endaq.plot

endaq.plot

endaq.plot.animate_quaternion(df, rate=6.0, scale=1.0)

A function to animate orientation as a set of axis markers derived from quaternion data.

Parameters:
  • df – A dataframe of quaternion data indexed by seconds. Columns must be ‘X’, ‘Y’, ‘Z’, and ‘W’. The order of the columns does not matter.

  • rate – The number of frames per second to animate.

  • scale – Time-scaling to adjust how quickly data is parsed. Higher speeds will make the file run faster, lower speeds will make the file run slower.

Returns:

A Plotly figure containing the plot

endaq.plot.around_peak(df, num=1000, leading_ratio=0.5)

A function to plot the data surrounding the largest peak (or valley) in the given data. The “peak” is defined by the point in the absolute value of the given data with the largest value.

Parameters:
  • df (DataFrame) – A dataframe indexed by time stamps

  • num (int) – The number of points to plot

  • leading_ratio (float) – The ratio of the data to be viewed that will come before the peak

Returns:

A Plotly figure containing the plot

endaq.plot.gen_map(df_map, mapbox_access_token=None, lat='Latitude', lon='Longitude', color_by_column=None, filter_positive_color_vals=False, hover_data=[], size_max=15.0, zoom_offset=-2.0)
Plots GPS data on a map from a single recording, shading the points based on one of several characteristics

(defaults to ground speed).

Parameters:
  • df_map (pd.DataFrame) – The pandas dataframe containing the recording data.

  • mapbox_access_token (str) –

    The access token (or API key) needed to be able to plot against a map using Mapbox, create a free account here

  • lat (str) – The dataframe column title to use for latitude

  • lon (str) – The dataframe column title to use for longitude

  • color_by_column (str) – The dataframe column title to color the plotted points by. If None is provided (the default), all the points will be the same color

  • filter_positive_color_vals (bool) – A boolean variable, which will filter which points are plotted by if they have corresponding positive values, default is False

  • hover_data (list[str]) – The list of dataframe column titles with data to display when the mouse hovers over a datapoint

  • size_max (float) – The size of the scatter points in the map, default 15

  • zoom_offset (float) – The offset to apply to the zoom, default -2, this is influenced by the final figure size

Here is an example map of a drive from Boston Logan Airport to Mide Technology

import endaq
endaq.plot.utilities.set_theme()
import pandas as pd

# Get GPS Data
gps = pd.read_csv('https://info.endaq.com/hubfs/data/mide-map-gps-data.csv')

# Generate & Show Map
fig = endaq.plot.gen_map(
    gps,
    lat="Latitude",
    lon="Longitude",
    color_by_column="Ground Speed",
    hover_data=["Date"]
)
fig.show()

(Source code, html)

endaq.plot.general_get_correlation_figure(merged_df, color_col='serial_number_id', color_discrete_map=None, hover_names=None, characteristics_to_show_on_hover=[], starting_cols=None)

A function to create a plot with two drop-down menus, each populated with a set of options corresponding to the scalar quantities contained in the given dataframe. The data points will then be plotted with the X and Y axis corresponding to the selected attributes from the drop-down menu.

Parameters:
  • merged_df (DataFrame) – A Pandas DataFrame of data to use for producing the plot

  • color_col (str) – The column name in the given dataframe (as merged_df) that is used to color data points with. This is used in combination with the color_discrete_map parameter

  • color_discrete_map (dict | None) – A dictionary which maps the values given to color data points based on (see the color_col parameter description) to the colors that these data points should be

  • hover_names (Container | None) – The names of the points to display when they are hovered on

  • characteristics_to_show_on_hover (list) – The set of characteristics of the data to display when hovered over

  • starting_cols (Container | None) – The two starting columns for the dropdown menus (will be the first two available if None is given)

Returns:

The interactive Plotly figure

Return type:

Figure

endaq.plot.get_pure_numpy_2d_pca(df, color_col='serial_number_id', color_discrete_map=None)

Get a Plotly figure of the 2D PCA for the given DataFrame. This will have dropdown menus to select which components are being used for the X and Y axis.

Parameters:
  • df (DataFrame) – The dataframe of points to compute the PCA with

  • color_col (str) – The column name in the given dataframe (as df) that is used to color data points with. This is used in combination with the color_discrete_map parameter

  • color_discrete_map (dict | None) – A dictionary which maps the values given to color data points based on (see the color_col parameter description) to the colors that these data points should be

Returns:

A plotly figure as described in the main function description

Return type:

Figure

endaq.plot.get_tsne_plot(df, perplexity=20, random_seed=0, num_iterations=1000, learning_rate=500, color_col='serial_number_id', color_discrete_map=None, momentum=0)

Estimates a SNE model, and plots the visualization of the given data.

More information about t-SNE visualizations and how to use them effectively can be found here: https://distill.pub/2016/misread-tsne/

(Implementation based around the following: https://nlml.github.io/in-raw-numpy/in-raw-numpy-t-sne/)

Parameters:
  • df (DataFrame) – A Pandas Dataframe of the the data to be visualized (e.g. a recording attribute DataFrame)

  • perplexity (int) – A value which can be thought of as determining how many neighbors of a point will be used to update its position in the visualization.

  • random_seed (int) – Integer value to set the seed value for the random

  • num_iterations (int) – The number of iterations to train for

  • learning_rate (int) – The rate at which to update the values in the model

  • color_col (str) – The column name in the given dataframe (as merged_df) that is used to color data points with. This is used in combination with the color_discrete_map parameter

  • color_discrete_map (dict | None) – A dictionary which maps the values given to color data points based on (see the color_col parameter description) to the colors that these data points should be

  • momentum (int) – The momentum to be used when applying updates to the model

Returns:

Plotly figure of the, low-dimensional representation of the given data

Return type:

Figure

endaq.plot.multi_file_plot_attributes(multi_file_db, attribs_to_plot=array(['accelerationPeakFull', 'accelerationRMSFull', 'velocityRMSFull', 'psuedoVelocityPeakFull', 'displacementRMSFull', 'gpsSpeedFull', 'gyroscopeRMSFull', 'microphonoeRMSFull', 'temperatureMeanFull', 'pressureMeanFull'], dtype='<U22'), recording_colors=None, width_per_subplot=400)

Creates a Plotly figure plotting all the desired attributes from the given DataFrame.

Parameters:
  • multi_file_db (DataFrame) – The Pandas DataFrame of data to plot attributes from

  • attribs_to_plot (ndarray) – A numpy ndarray of strings with the names of the attributes to plot

  • recording_colors (Container | None) – The colors to make each of the points (All will be the same color if None is given)

  • width_per_subplot (int) – The width to make every subplot

Returns:

A Plotly figure of all the subplots desired to be plotted

Return type:

Figure

endaq.plot.octave_psd_bar_plot(df, bins_per_octave=3, f_start=20.0, yaxis_title='', log_scale_y_axis=True)

Produces a bar plot of an octave psd.

Parameters:
  • df (DataFrame) – The dataframe of sensor data

  • bins_per_octave (int) – The number of frequency bins per octave

  • f_start (float) – The center of the first frequency bin

  • yaxis_title (str) – The text to label the y-axis

  • log_scale_y_axis (bool) – If the y-axis should be log scaled

endaq.plot.octave_spectrogram(df, window, bins_per_octave=3, freq_start=20.0, max_freq=inf, db_scale=True, log_scale_y_axis=True)

Produces an octave spectrogram of the given data, this is a wrapper around rolling_psd() and spectrum_over_time()

Parameters:
  • df (pd.DataFrame) – The dataframe of sensor data. This must only have 1 column.

  • window (float) – The time window for each of the columns in the spectrogram

  • bins_per_octave (int) – The number of frequency bins per octave

  • freq_start (float) – The center of the first frequency bin

  • max_freq (float) – The maximum frequency to plot

  • db_scale (bool) – If the spectrogram should be log-scaled for visibility (with 10*log10(x))

  • log_scale_y_axis (bool) – If the y-axis of the plot should be log scaled

Returns:

a tuple containing: - dataframe of the spectrogram data - the corresponding plotly figure

Return type:

tuple[pd.DataFrame, go.Figure]

endaq.plot.pvss_on_4cp(df, mode='srs', accel_units='gravity', disp_units='in', tick_spacing='medium', include_text=True, size=None)

Given a shock response as a SRS or PVSS (see shock_spectrum()) return a plot of the pseudo velocity on a four coordinate plot (4CP or tripartite) that includes diagonal lines and hover labels to also signify the displacement and acceleration levels as a function of natural frequency.

Parameters:
  • df (DataFrame) – the input dataframe of shock response data, each column is plotted separately

  • mode (Literal['srs', 'pvss']) –

    the type of spectrum of the input dataframe, options are:

    • srs: default, shock response spectrum (SRS) which assumes has units of accel_units

    • pvss: pseudo-velocity shock spectrum (PVSS) which assumes has units of accel_units * s

  • accel_units (str) – the units to display acceleration as, default is “gravity” which will be shortened to ‘g’ in labels, the unit conversion is handled using convert_units()

  • disp_units (str) – the units to display displacement as and velocity (divided by seconds), default is “in”, the unit conversion is handled using convert_units()

  • tick_spacing (Literal['fine', 'medium', 'coarse']) –

    the spacing of each tick and corresponding diagonal line:

    • fine: order of magnitude, and linearly spaced ticks between each order of magnitude

    • medium: default, order of magnitude, and then 2x and 5x between each order of magnitude, typical for Plotly,

    • coarse: only the order of magnitude

  • include_text (bool) – if True (default) add text labels to the diagonal lines

  • size (int | None) – the number of pixels to set the width and height of the figure to force it to be square, default is None

Returns:

a Plotly figure of the PVSS on 4CP paper with hover information for acceleration and displacement

Return type:

Figure

Here’s a few examples from a dataset recorded with an enDAQ sensor on a motorcycle as it revved the engine which resulted in changing frequency content

import endaq
endaq.plot.utilities.set_theme()
import pandas as pd

# Get crash data
df_crash = pd.read_csv('https://info.endaq.com/hubfs/data/motorcycle-crash.csv',index_col=0)

# Calculate SRS
srs = endaq.calc.shock.shock_spectrum(df_crash, mode='srs', damp=0.05)

# Generate 4CP Plot
imp = endaq.plot.plots.pvss_on_4cp(srs, disp_units='in')
imp.show()

# Change Plot Theme
endaq.plot.utilities.set_theme('endaq_light')

# Generate 4CP Plot with Different Units
met = endaq.plot.plots.pvss_on_4cp(srs, disp_units='mm', tick_spacing='coarse', size=500)
met.show()

(Source code, html, html)

(html)

(html)

endaq.plot.rolling_min_max_envelope(df, desired_num_points=2000, plot_as_bars=True, plot_title='', opacity=0.7, colors_to_use=None)

A function to create a Plotly Figure to plot the data for each of the available data sub-channels, designed to reduce the number of points/data being plotted without minimizing the insight available from the plots. It will plot either an envelope for rolling windows of the data (plotting the max and the min as line plots), or a bar based plot where the top of the bar (rectangle) is the highest value in the time window that bar spans, and the bottom of the bar is the lowest point in that time window (choosing between them is done with the plot_as_bars parameter).

Parameters:
  • df (DataFrame) – The dataframe of sub-channel data indexed by time stamps

  • desired_num_points (int) – The desired number of points to be plotted for each subchannel. The number of points will be reduced from its original sampling rate by applying metrics (e.g. min, max) over sliding windows and then using that information to represent/visualize the data contained within the original data. If less than the desired number of points are present, then a sliding window will NOT be used, and instead the points will be plotted as they were originally recorded (also the subchannel will NOT be plotted as a bar based plot even if plot_as_bars was set to true).

  • plot_as_bars (bool) – A boolean value indicating if the data should be visualized as a set of rectangles, where a shaded rectangle is used to represent the maximum and minimum values of the data during the time window covered by the rectangle. These maximum and minimum values are visualized by the locations of the top and bottom edges of the rectangle respectively, unless the height of the rectangle would be 0, in which case a line segment will be displayed in its place. If this parameter is False, two lines will be plotted for each of the sub-channels in the figure being created, creating an ‘envelope’ around the data. An ‘envelope’ around the data consists of a line plotted for the maximum values contained in each of the time windows, and another line plotted for the minimum values. Together these lines create a boundary which contains all the data points recorded in the originally recorded data.

  • plot_title (str) – The title for the plot

  • opacity (float) – The opacity to use for plotting bars/lines

  • colors_to_use (Container | None) – An “array-like” object of strings containing colors to be cycled through for the sub-channels. If None is given (which is the default), then the colorway variable in Plotly’s current theme/template will be used to color the data on each of the sub-channels uniquely, repeating from the start of the colorway if all colors have been used.

Returns:

The Plotly Figure with the data plotted

Return type:

Figure

Here’s an example plotting a dataset with over 6 million points per channel

import endaq
endaq.plot.utilities.set_theme()
import plotly.graph_objects as go

# Get Accel, 6M datapoints per axis
accel = endaq.ide.get_primary_sensor_data('https://info.endaq.com/hubfs/ford_f150.ide',
    measurement_type='accel',
    time_mode='datetime')

# Apply Highpass Filter
accel = endaq.calc.filters.butterworth(accel, low_cutoff=2)

# Generate Shaded Bar Plot of All Data
fig = endaq.plot.rolling_min_max_envelope(accel)
fig.show()

(Source code, html)

endaq.plot.spectrum_over_time(df, plot_type='Heatmap', var_column='variable', var_to_process=None, time_column='timestamp', freq_column='frequency (Hz)', val_column='value', freq_min=None, freq_max=None, log_freq=False, log_val=False, round_time=True, round_freq=2, waterfall_line_sequence=True, zsmooth='best', waterfall_line_color='#EE7F27', min_median_max_line_color='#6914F0')

Generate a 3D Plotly figure from a stacked spectrum to visualize how the frequency content changes over time

Parameters:
  • df (DataFrame) –

    the input dataframe with columns defining the frequency content, timestamps, values, and variables, see the following functions which provides outputs that would then be passed into this function as an input:

  • plot_type (Literal['Heatmap', 'Surface', 'Waterfall', 'Animation', 'Peak', 'Lines']) –

    the type of plot to display the spectrum, options are:

    • Heatmap: a 2D visualization with the color defining the z value (the default)

    • Surface: similar to Heatmap but the z value is also projected “off the page”

    • Waterfall: distinct lines are plotted per time slice in a 3D view

    • Animation: a 2D display of the waterfall but the spectrum changes with animation frames

    • Peak: per timestamp the peak frequency is determined and plotted against time

    • Lines: the value in each frequency bin is plotted against time

  • var_column (str) – the column name in the dataframe that defines the different variables, default is “variable”

  • var_to_process (str | None) – the variable value in the var_column to filter the input df down to, if none is provided (the default) this function will filter to the first value

  • time_column (str) – the column name in the dataframe that defines the timestamps, default is “timestamp”

  • freq_column (str) – the column name in the dataframe that defines the frequency, default is “frequency (Hz)”

  • val_column (str) – the column name in the dataframe that defines the values, default is “value”

  • freq_min (float | None) – the minimum of the y axis (frequency) to include in the figure, default is None meaning it will display all content

  • freq_max (float | None) – the maximum of the y axis (frequency) to include in the figure, default is None meaning it will display all content

  • log_freq (bool) – if True the frequency will be in a log scale, default is False

  • log_val (bool) – if True the values will be in a log scale, default is False

  • round_time (bool) – if True (default) the time values will be rounded to the nearest second for datetimes and hundredths of a second for floats

  • round_freq (int) – number of decimals to round the frequency bins to, default is 3

  • waterfall_line_sequence (bool) – if True the waterfall line colors are defined with a color scale, if False all lines will have the same color, default is True

  • zsmooth (str) – the Plotly smooth algorithm to use in the heatmap, default is “best” which looks ideal but “fast” will be more responsive, or False will attempt no smoothing

  • waterfall_line_color (str) – the color to use for all lines in the Waterfall plot if waterfall_line_sequence is False

  • min_median_max_line_color (str) – the color to use for the min, max, and median lines in the Animation, if set to None these lines won’t be added, default is ‘#6914F0’

Returns:

a Plotly figure visualizing the spectrum over time

Return type:

Figure

Here’s a few examples from a dataset recorded with an enDAQ sensor on a motorcycle as it revved the engine which resulted in changing frequency content

import pandas as pd
import endaq

# Set Theme
endaq.plot.utilities.set_theme()

# Get Vibration Data
df_vibe = pd.read_csv('https://info.endaq.com/hubfs/data/motorcycle-vibration-moving-frequency.csv', index_col=0)

# Calculate a Rolling FFT
fft = endaq.calc.fft.rolling_fft(df_vibe, num_slices=200, add_resultant=True)

# Visualize the Rolling FFT as a Heatmap
heatmap = endaq.plot.plots.spectrum_over_time(fft, plot_type='Heatmap', freq_max=200, var_to_process='Resultant')
heatmap.show()

# Plot the Peak Frequency vs Time
peak = endaq.plot.plots.spectrum_over_time(fft, plot_type='Peak', freq_max=200, var_to_process='Resultant')
peak.show()

# Visualize as a Surface Plot
surface = endaq.plot.plots.spectrum_over_time(fft, plot_type='Surface', freq_max=200, var_to_process='Resultant')
surface.show()

# Visualize as a Waterfall
waterfall = endaq.plot.plots.spectrum_over_time(fft, plot_type='Waterfall', freq_max=200, var_to_process='Resultant')
waterfall.show()

(Source code, html, html, html, html)

(html)

(html)

(html)

(html)

Here’s another few examples with a longer dataset with DatetimeIndex of a car engine during a morning commute

import pandas as pd
import endaq

# Set Theme
endaq.plot.utilities.set_theme()

# Get a Longer Dataset with DatetimeIndex
engine = endaq.ide.get_primary_sensor_data('https://info.endaq.com/hubfs/data/Commute.ide', measurement_type='accel',
                                           time_mode='datetime')

# Compute PSD
psd = endaq.calc.psd.rolling_psd(engine, num_slices=500, add_resultant=True, octave_bins=12, fstart=4)

# Visualize as a Heatmap
heatmap2 = endaq.plot.plots.spectrum_over_time(psd, plot_type='Heatmap', var_to_process='Resultant', zsmooth='best',
                                               log_freq=True, log_val=True)
heatmap2.show()

# Visualize as an Animation
animation = endaq.plot.plots.spectrum_over_time(psd, plot_type='Animation', var_to_process='Resultant',
                                                log_freq=True, log_val=True)
animation.show()

# Use Rolling PSD to Calculate RMS in Certain Frequency Bins
rms = endaq.calc.psd.rolling_psd(engine, num_slices=500, scaling='rms', add_resultant=True,
                                 freq_splits=[1, 20, 60, 300, 3000])

# Plot the RMS per Frequency Bin Over Time
lines = endaq.plot.plots.spectrum_over_time(rms, plot_type='Lines', log_val=False, var_to_process='Resultant')
lines.show()

# Compute Pseudo Velocity at Specific Times
pvss = endaq.calc.shock.rolling_shock_spectrum(engine, slice_width=2.0, add_resultant=True,
                                               mode='pvss', init_freq=4, damp=0.05,
                                               index_values=pd.DatetimeIndex(['2016-08-02 12:07:15',
                                                                              '2016-08-02 12:08:01',
                                                                              '2016-08-02 12:10:06'], tz='UTC'))

# Visualize as a Waterfall
waterfall2 = endaq.plot.plots.spectrum_over_time(pvss, plot_type='Waterfall', log_freq=True, log_val=True,
                                                 var_to_process='Resultant', waterfall_line_sequence=False)
waterfall2.show()

(Source code, html, html, html, html)

(html)

(html)

(html)

(html)

endaq.plot.table_plot(table, num_round=2, row_size=None, font_color=None, bg_color=None, line_color=None)

Generate a Plotly figure from a Pandas dataframe that is styled consistent with the current Plotly template

Parameters:
  • table (DataFrame) – the input dataframe to generate the plot from

  • num_round (int | None) – the precision to round all numbers (if any) in table before displaying

  • row_size (int | None) – the size for each row, if None it will set this to 2 times the default Plotly template font size

  • font_color (str | None) – the color of all cell’s text and the background color for the header, if None it will set this to the default Plotly font color

  • bg_color (str | None) – the color of all cell’s background color and the text for the header, if None it will set this to the default Plotly background color

  • line_color (str | None) – the color for the lines in the table, if None it will set this to the default Plotly grid color

Returns:

a Plotly table figure with all content from the dataframe

Return type:

Figure

Here’s an example to generate a table from the metrics calculated with shock_vibe_metrics()

import endaq
endaq.plot.utilities.set_theme('endaq_light')
import pandas as pd

# Get Acceleration Data
accel = pd.read_csv('https://info.endaq.com/hubfs/Plots/bearing_data.csv', index_col=0)

# Calculate Metrics
metrics = endaq.calc.stats.shock_vibe_metrics(accel, include_resultant=False, freq_splits=[0, 65, 300, None])

# Generate Plot to Show Metrics as a Table
light_table = endaq.plot.table_plot(metrics)
light_table.show()

# Change Theme
endaq.plot.utilities.set_theme('endaq')

# Regenerate Plot to Show Metrics as a Table
dark_table = endaq.plot.table_plot(metrics, num_round=4)
dark_table.show()

(Source code, html, html)

(html)

(html)

endaq.plot.table_plot_from_ide(doc=None, name=None, **kwargs)

Generate a Plotly figure from a .IDE file using table_plot() and get_channel_table() while also displaying the device serial number, part number, and the date of the recording

Parameters:
  • doc (Dataset | None) – A idelib.dataset.Dataset

  • name (str | None) – The plot title to add, if None then no title is added

  • kwargs – Other parameters to pass directly to table_plot()

Returns:

a Plotly table figure with all content from the dataframe

Return type:

Figure

Here’s an example to generate a table from the metrics calculated with shock_vibe_metrics()

import endaq
endaq.plot.utilities.set_theme()

doc = endaq.ide.get_doc('https://info.endaq.com/hubfs/data/All-Channels.ide')
fig = endaq.plot.table_plot_from_ide(doc=doc, name='Example File')
fig.show()

(Source code, html)

endaq.plot.dashboards

endaq.plot.dashboards.rolling_enveloped_dashboard(channel_df_dict, desired_num_points=250, num_rows=None, num_cols=3, width_for_subplot_row=400, height_for_subplot_row=400, subplot_colors=None, min_points_to_plot=1, plot_as_bars=False, plot_full_single_channel=False, opacity=1.0, y_axis_bar_plot_padding=0.06)

A function to create a Plotly Figure with sub-plots for each of the available data sub-channels, designed to reduce the number of points/data being plotted without minimizing the insight available from the plots. It will plot either an envelope for rolling windows of the data (plotting the max and the min as line plots), or a bar based plot where the top of the bar (rectangle) is the highest value in the time window that bar spans, and the bottom of the bar is the lowest point in that time window (choosing between them is done with the plot_as_bars parameter).

Parameters:
  • channel_df_dict (dict) – A dictionary mapping channel names to Pandas DataFrames of that channels data

  • desired_num_points (int) – The desired number of points to be plotted in each subplot. The number of points will be reduced from its original sampling rate by applying metrics (e.g. min, max) over sliding windows and then using that information to represent/visualize the data contained within the original data. If less than the desired number of points are present, then a sliding window will NOT be used, and instead the points will be plotted as they were originally recorded (also the subplot will NOT be plotted as a bar based plot even if plot_as_bars was set to true).

  • num_rows (int | None) – The number of columns of subplots to be created inside the Plotly figure. If None is given, (then num_cols must not be None), then this number will automatically be determined by what’s needed. If more rows are specified than are needed, the number of rows will be reduced to the minimum needed to contain all the subplots

  • num_cols (int | None) – The number of columns of subplots to be created inside the Plotly figure. See the description of the num_rows parameter for more details on this parameter, and how the two interact. This also follows the same approach to handling None when given

  • width_for_subplot_row (int) – The width of the area used for a single subplot (in pixels).

  • height_for_subplot_row (int) – The height of the area used for a single subplot (in pixels).

  • subplot_colors (Container | None) – An “array-like” object of strings containing colors to be cycled through for the subplots. If None is given (which is the default), then the colorway variable in Plotly’s current theme/template will be used to color the data on each of the subplots uniquely, repeating from the start of the colorway if all colors have been used.

  • min_points_to_plot (int) – The minimum number of data points required to be present to create a subplot for a channel/subchannel (NOT including NaN values).

  • plot_as_bars (bool) – A boolean value indicating if the plot should be visualized as a set of rectangles, where a shaded rectangle is used to represent the maximum and minimum values of the data during the time window covered by the rectangle. These maximum and minimum values are visualized by the locations of the top and bottom edges of the rectangle respectively, unless the height of the rectangle would be 0, in which case a line segment will be displayed in its place. If this parameter is False, two lines will be plotted for each of the subplots in the figure being created, creating an “envelope” around the data. An “envelope” around the data consists of a line plotted for the maximum values contained in each of the time windows, and another line plotted for the minimum values. Together these lines create a boundary which contains all the data points recorded in the originally recorded data.

  • plot_full_single_channel (bool) – If instead of a dashboard of subplots a single plot with multiple sub-channels should be created. If this is True, only one (key, value) pair can be given for the channel_df_dict parameter

  • opacity (float) – The opacity to use for plotting bars/lines

  • y_axis_bar_plot_padding (float) – Due to some unknown reason the bar subplots aren’t having their y axis ranges automatically scaled so this is the ratio of the total y-axis data range to pad both the top and bottom of the y axis with. The default value is the one it appears Plotly uses as well.

Returns:

The Plotly Figure containing the subplots of sensor data (the ‘dashboard’)

Return type:

Figure

Here’s an example plotting a dashboard of all channels recorded on a commercial aircraft seat base

import endaq
endaq.plot.utilities.set_theme('endaq_light')

# Get IDE Object
doc = endaq.ide.get_doc('https://info.endaq.com/hubfs/data/Seat-Base_21.ide')

# Get All Data
data = {doc.channels[ch].name: endaq.ide.to_pandas(doc.channels[ch], time_mode='datetime') for ch in doc.channels}

# Get Dashboard of All Channels
dashboard = endaq.plot.dashboards.rolling_enveloped_dashboard(
    data,
    num_rows=1,
    num_cols=None
)
dashboard.show()

(Source code, html)

endaq.plot.dashboards.rolling_metric_dashboard(channel_df_dict, desired_num_points=250, num_rows=None, num_cols=3, rolling_metrics_to_plot=('mean', 'std'), metric_colors=None, width_for_subplot_row=400, height_for_subplot_row=400)

A function to create a dashboard of subplots of the given data, plotting a set of rolling metrics.

Parameters:
  • channel_df_dict (dict) – A dictionary mapping channel names to Pandas DataFrames of that channels data

  • desired_num_points (int) – The desired number of points to be plotted in each subplot. The number of points will be reduced from its original sampling rate by applying metrics (e.g. min, max) over sliding windows and then using that information to represent/visualize the data contained within the original data. If less than the desired number of points are present, then a sliding window will NOT be used, and instead the points will be plotted as they were originally recorded (also the subplot will NOT be plotted as a bar based plot even if plot_as_bars was set to true).

  • num_rows (int | None) – The number of columns of subplots to be created inside the Plotly figure. If None is given, (then num_cols must not be None), then this number will automatically be determined by what’s needed. If more rows are specified than are needed, the number of rows will be reduced to the minimum needed to contain all the subplots

  • num_cols (int | None) – The number of columns of subplots to be created inside the Plotly figure. See the description of the num_rows parameter for more details on this parameter, and how the two interact. This also follows the same approach to handling None when given

  • rolling_metrics_to_plot (tuple) – A tuple of strings which indicate what rolling metrics to plot for each subchannel. The options are ['mean', 'std', 'absolute max', 'rms'] which correspond to the mean, standard deviation, maximum of the absolute value, and root-mean-square.

  • metric_colors (Container | None) – An “array-like” object of strings containing colors to be cycled through for the metrics. If None is given (which is the default), then the colorway variable in Plotly’s current theme/template will be used to color the metric data, repeating from the start of the colorway if all colors have been used. The first value corresponds to the color if not enough points of data exist for a rolling metric, and the others correspond to the metric in rolling_metrics_to_plot in the same order they are given

  • width_for_subplot_row (int) – The width of the area used for a single subplot (in pixels).

  • height_for_subplot_row (int) – The height of the area used for a single subplot (in pixels).

Returns:

The Plotly Figure containing the subplots of sensor data (the ‘dashboard’)

Return type:

Figure

endaq.plot.utilities

endaq.plot.utilities.define_theme(template_name='endaq_cloud', default_plotly_template='plotly_dark', text_color='#DAD9D8', font_family='Open Sans', title_font_family='Open Sans SemiBold', graph_line_color='#DAD9D8', grid_line_color='#404041', background_color='#262626', plot_background_color='#0F0F0F')

Define a Plotly theme (template), allowing completely custom aesthetics

Parameters:
  • template_name (str) – The name for the Plotly template being created

  • default_plotly_template (str) – The default Plotly Template (aspects of this will be used if a characteristic isn’t set elsewhere)

  • text_color (str) – The color of the text

  • font_family (str) – The font family to use for text (not including the title)

  • title_font_family (str) – The font family to use for the title

  • graph_line_color (str) – The line color used when plotting line plots

  • grid_line_color (str) – The color of the grid lines on the plot

  • background_color (str) – The background color of the figure

  • plot_background_color (str) – The background color of the plot

Returns:

The plotly template which was just created

Return type:

Template

endaq.plot.utilities.determine_plotly_map_zoom(lons=None, lats=None, lonlats=None, projection='mercator', width_to_height=2.0, margin=1.2)

Finds optimal zoom for a plotly mapbox. Must be passed (lons & lats) or lonlats.

Originally based on the following post: https://stackoverflow.com/questions/63787612/plotly-automatic-zooming-for-mapbox-maps

This is a temporary solution awaiting an official implementation: https://github.com/plotly/plotly.js/issues/3434

Parameters:
  • lons (tuple | None) – tuple, optional, longitude component of each location

  • lats (tuple | None) – tuple, optional, latitude component of each location

  • lonlats (tuple | None) – tuple, optional, gps locations

  • projection (str) – str, only accepting ‘mercator’ at the moment, raises NotImplementedError if other is passed

  • width_to_height (float) – float, expected ratio of final graph’s with to height, used to select the constrained axis.

  • margin (float) – The desired margin around the plotted points (where 1 would be no-margin)

Returns:

The zoom scaling for the Plotly map

Return type:

float

Note

This implementation could be potentially problematic. By simply averaging min/max coordinates you end up with situations such as the longitude lines -179.99 and 179.99 being almost right next to each other, but their center is calculated at 0, the other side of the earth.

endaq.plot.utilities.get_center_of_coordinates(lats, lons, as_list=False, as_degrees=True)

Inputs and outputs are measured in degrees.

Parameters:
  • lats (ndarray) – An ndarray of latitude points

  • lons (ndarray) – An ndarray of longitude points

  • as_list (bool) – If True, return a length 2 list of the latitude and longitude coordinates. If not return a dictionary of format {"lon": lon_center, "lat": lat_center}

  • as_degrees (bool) – A boolean value representing if the lats and lons parameters are given in degrees (as opposed to radians). These units will be used for the returned values as well.

Returns:

The latitude and longitude values as either a dictionary or a list, which is determined by the value of the as_list parameter (see the as_list docstring for details on the formatting of this return value

Return type:

list | dict

endaq.plot.utilities.set_theme(theme='endaq')

Set the plot appearances based on a known ‘theme’.

Parameters:

theme (Literal['endaq', 'endaq_light', 'endaq_arial', 'endaq_light_arial']) – A string denoting which plot appearance color scheme to use. Current options are ‘endaq’, ‘endaq_light’, ‘endaq_arial’ and ‘endaq_light_arial’.

Returns:

The plotly template which was set

Return type:

Template