visualization.py#

Functions to support data visualization.

class seabirdscientific.visualization.ChartConfig(title: str, x_names: List[str], y_names: List[str], z_names: List[str], chart_type: Literal['overlay', 'subplots'], bounds: Dict[Literal['x', 'y', 'z'], Dict[int, List[int]]] | None = None, x_titles: List[str] | None = None, y_titles: List[str] | None = None, z_titles: List[str] | None = None, plot_loop_edit_flags=False, lift_pen_over_bad_data=False, flag_value=-9.99e-29)#

Dataclass to contain chart information and plotly settings

class seabirdscientific.visualization.ChartData(data_source: str | DataFrame, config: ChartConfig)#

Class to contain chart data and helper functions

seabirdscientific.visualization.apply_overlay_config(figure: Figure, config: ChartConfig)#

Updates various chart settings for charts with multiple y axes.

Config parameters may contain upto 4 arguments per axis, and must be in the same order as the data. Hence all of the magic number indexing below

Parameters:

  • figure – The figure being updated

  • config – The user defined config being applied to the figure

seabirdscientific.visualization.apply_single_config(figure: Figure, config: ChartConfig)#

Updates various chart settings for single plots.

Parameters:

  • figure – The figure being updated

  • config – The user defined config being applied to the figure

seabirdscientific.visualization.apply_subplots_x_config(figure: Figure, config: ChartConfig)#

Updates various chart settings for charts with multiple x axes.

Config parameters may contain upto 4 arguments per axis, and must be in the same order as the data. Hence all of the magic number indexing below

Parameters:

  • figure – The figure being updated

  • config – The user defined config being applied to the figure

seabirdscientific.visualization.apply_subplots_y_config(figure: Figure, config: ChartConfig)#

Updates various chart settings for charts with multiple y axes.

Config parameters may contain upto 4 arguments per axis, and must be in the same order as the data. Hence all of the magic number indexing below

Parameters:

  • figure – The figure being updated

  • config – The user defined config being applied to the figure

seabirdscientific.visualization.create_overlay(x: DataFrame, y: DataFrame, config: ChartConfig) → Figure#

Creates a chart with multiple datasets overlayed on one axis.

Parameters:

  • x – Pandas DataFrame of data for the x axis

  • y – Pandas DataFrame of data for the y axis

  • config – Dataclass with settings for the plotly chart

Returns:

A plotly.graph_objects.Figure

seabirdscientific.visualization.create_single_plot(x: DataFrame, y: DataFrame, config: ChartConfig) → Figure#

Creates a single XY plot, with one or more data sets.

If there are multiple datasets for the x or y axis, an overlay plot will be generated

Parameters:

  • x – Numpy array of data for the x axis

  • y – Numpy array of data for the y axis

  • config – Dataclass with settings for the plotly chart

Returns:

A plotly.graph_objects.Figure displaying the provided x y data

seabirdscientific.visualization.create_subplots(x: DataFrame, y: DataFrame, config: ChartConfig) → Figure#

Creates a chart with multiple subplots.

Parameters:

  • x – Pandas DataFrame of data for the x axis

  • y – Pandas DataFrame of data for the y axis

  • config – Dataclass with settings for the plotly chart

Returns:

A plotly.graph_objects.Figure with multiple subplots

seabirdscientific.visualization.parse_instrument_data(source: str | Path | DataFrame) → DataFrame#

Top level function for converting instrument data to numpy array.

Currently supports pandas dataframes, json strings, or a Path to the following file types: .csv, .asc (comma separated only), .json.

Parameters:

source – A JSON string, file path (.csv, .asc, .json), or pandas DataFrame

Returns:

pandas dataframe containing field names and data

seabirdscientific.visualization.plot_ts_chart(x: ndarray, y: ndarray, z: ndarray, x_vec: ndarray, y_vec: ndarray, z_mat: ndarray, config: ChartConfig) → Figure#

Overlays a scatter plot onto a contour plot to create a TS plot. Takes as args the xyz properties on a Contour object. In a future version these will be replaced with a single contour object

Parameters:

  • x – absolute salinity

  • y – conservative temperature

  • z – potential density

  • x_vec – absolute salinity vector

  • y_vec – conservative temperature vector

  • z_mat – potential density matrix

  • config – Config object with key/values required by conversion function

Returns:

A plotly.graph_objects.Figure

seabirdscientific.visualization.plot_xy_chart(data: ChartData, config: ChartConfig) → Figure#

Takes instrument data and a config and plots an XY chart with one or more data sets.

Parameters:

  • data – Data object with x, y, z, data selected according to the config

  • config – Config object with various plotly settings

Returns:

A plotly.graph_objects.Figure

seabirdscientific.visualization.select_subset(axis_names: list[str], data: DataFrame) → DataFrame#

Takes a list of axis names and returns a data set for each name in the list.

If axis_names is empty the function will return a DataFrame of integers representing the sample count of the data. This could be used in a single series chart for example.

Otherwise, the function will return a DataFrame for each name in the list. This would be for a single xy chart or an overlay/subplot chart.

Example:

data = read_data(“./example.csv”)

subset = select_subset([“T090C”, “C0Sm”], data)

Parameters:

  • axis_names – List of axis names corresponding to the data

  • data – The numpy DataFrame returned from read_data()

Returns:

A tuple with the axis name and data