endaq.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 (pandas.core.frame.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, filter_points_by_positive_groud_speed=True, color_by_column='GNSS Speed: Ground Speed')¶

Plots GPS data on a map from a single recording, shading the points based some characteristic (defaults to ground speed).

Parameters

df_map (pandas.core.frame.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.
filter_points_by_positive_groud_speed (bool) – A boolean variable, which will filter which points are plotted by if they have corresponding positive ground speeds. This helps remove points which didn’t actually have a GPS location found (was created by a bug in the hardware I believe).
color_by_column (str) – The dataframe column title to color the plotted points by.

endaq.plot.general_get_correlation_figure(merged_df, recording_colors=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 (pandas.core.frame.DataFrame) – A Pandas DataFrame of data to use for producing the plot
recording_colors (Optional[collections.abc.Container]) – The colors of each of the points to be plotted
hover_names (Optional[collections.abc.Container]) – 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 (Optional[collections.abc.Container]) – 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

plotly.graph_objs._figure.Figure

endaq.plot.get_pure_numpy_2d_pca(df, recording_colors=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 (pandas.core.frame.DataFrame) – The dataframe of points to compute the PCA with
recording_colors (Optional[collections.abc.Container]) – See the same parameter in the general_get_correlation_figure function

Returns

A plotly figure as described in the main function description

Return type

plotly.graph_objs._figure.Figure

endaq.plot.multi_file_plot_attributes(multi_file_db, rows_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 (pandas.core.frame.DataFrame) – The Pandas DataFrame of data to plot attributes from
rows_to_plot (numpy.ndarray) – A numpy ndarray of strings with the names of the attributes to plot
recording_colors (Optional[collections.abc.Container]) – 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

plotly.graph_objs._figure.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 (pandas.core.frame.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.

Parameters

df (pandas.core.frame.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: - the frequency bins - the time bins - the spectrogram data - the corresponding plotly figure

Return type

plotly.graph_objs._figure.Figure

endaq.plot.rolling_min_max_envelope(df, desired_num_points=250, plot_as_bars=False, plot_title='', opacity=1, 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 (pandas.core.frame.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 it’s 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 it’s 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 (Optional[collections.abc.Container]) – 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

plotly.graph_objs._figure.Figure

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, 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 it’s 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 (Optional[int]) – 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 (Optional[int]) – 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 (Optional[collections.abc.Container]) – 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 it’s 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

plotly.graph_objs._figure.Figure

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 it’s 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 (Optional[int]) – 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 (Optional[int]) – 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’] which correspond to the mean, standard deviation, and maximum of the absolute value.
metric_colors (Optional[collections.abc.Container]) – 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

plotly.graph_objs._figure.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

go.layout._template.Template

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

Originally based on the following post: https://stackoverflow.com/questions/63787612/plotly-automatic-zooming-for-mapbox-maps Finds optimal zoom for a plotly mapbox. Must be passed (lons & lats) or lonlats.

Temporary solution awaiting official implementation, see: https://github.com/plotly/plotly.js/issues/3434

Parameters

lons (Optional[tuple]) – tuple, optional, longitude component of each location
lats (Optional[tuple]) – tuple, optional, latitude component of each location
lonlats (Optional[tuple]) – 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 coorindates 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 (numpy.ndarray) – An ndarray of latitude points
lons (numpy.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

Union[list, dict]

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

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

Parameters: theme (str) – 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: go.layout._template.Template

endaq.cloud

endaq.cloud API Wrapper