tts_dtat

Subpackages

Submodules

tts_dtat.commonchartfuncs

Common functions for charts

tts_dtat.commonchartfuncs.elapsed_seconds_to_dt_str(es_flt) → str

Converts elapsed seconds since a reference epoch (2018-01-01) to a formatted string.

Args:

es_flt (float): The number of seconds elapsed since January 1, 2018.

Returns:

str: A datetime string formatted as ‘%Y-%jT%H:%M:%S’.

tts_dtat.commonchartfuncs.get_plotly_marker_values(customize_dict: CustomizedTrace) → CustomizedMarker

Extracts and defaults marker configuration values for a Plotly trace.

Args:
customize_dict (CustomizedTrace): A dictionary containing customization options

for the trace, such as color, symbol, size, and colorscale.

Returns:
CustomizedMarker: A dictionary formatted for use as a Plotly marker configuration,

containing keys for size, symbol, color, colorscale, showscale, and line properties.

tts_dtat.commonchartfuncs.make_colorbar_dict(data, z_var, z_vals, color) → dict

Creates a dictionary defining the properties of a Plotly colorbar.

Determines the appropriate tick values and text based on the data type of the Z-axis variable (time, discrete bins, or categorical strings).

Args:

data (pd.DataFrame): The DataFrame containing the data. z_var (str): The name of the column used for the Z-axis (color dimension). z_vals (str): The name of the column containing the numeric values for the Z-axis. color (list or str): The color configuration, which can be a list of bins or a single color.

Returns:

dict: A dictionary containing title, tickmode, tickvals, and ticktext for the colorbar.

tts_dtat.datachecker

Utility functions for verifying and identifying data

tts_dtat.datachecker.find_value_header(cols)

Returns the column name of the ‘value’ in the data, given the column names as a list

tts_dtat.datachecker.handle_mixed_time_formats(timestamp)

Tries to convert a string with subseconds first, if that fails, tries without subseconds, and otherwise returns an error if both fail

tts_dtat.datachecker.header()

The datacache header

tts_dtat.datachecker.is_time_type(state)

Returns true if the state is a known time type

tts_dtat.datachecker.make_datetime_column(time_data)

Returns a transformed column of strings to datetime objects

tts_dtat.datachecker.min_header()

The smallest valid header for imported information

tts_dtat.datachecker.valid_time_type_cols()

A list of all valid time type column names. This is the source of truth definition.

tts_dtat.datachecker.valid_value_col_names()

A list of all valid generic ‘value’ column names. This is the source of truth definition.

tts_dtat.datachecker.verify_header(data)

Verifies that the header of a dataframe has the necessary columns

tts_dtat.datainterpolator

Helper functions to create additional numeric scales for figure traces

class tts_dtat.datainterpolator.DefaultInterpolator(data)

Bases: object

Default interpolator logic module. See the documentation for details.

make_column_values(state, elapsed_seconds=False)

Interpolate data as necessary (pad then backfill) to provide a continuous set of color values for the “z-axis” of a data set. This method assumes data has been sorted by the primary time type used for the graph. :keyword state: apidName to make into a column of numeric values to use as a colorscale :keyword time_in_seconds: return a time type as a series of seconds elapsed since 1/1/2018

make_num_col_from_state(state)

Make a new column of non-empty numeric types based on the data from state. Interpolate data as necessary (pad then backfill). :keyword state: apidName to make into a column of numeric values to use as a colorscale

make_num_vals_from_strings(col)

Make a new column of non-empty numeric types from a column of string values. :keyword col: column of string values

tts_dtat.demo_data

tts_dtat.demo_data.drifting_off_nominal()
Simulates data for an instrument drifting off its nominal values.

Used for demo jupyter notebook, and has no operational purpose.

Generates synthetic data for Voltage and Current that drifts over time, along with Mode state changes.

Returns:
pd.DataFrame: A DataFrame containing columns for ‘scet’ (time), ‘name’,

and ‘value’.

tts_dtat.demo_data.instrument_turn_on()

Simulates data for an instrument turning on. Used for demo jupyter notebook, and has no operational purpose.

Generates synthetic data for Voltage, Current, and Mode states over time, simulating a startup sequence from TEST to INIT to OPERATIONAL.

Returns:
pd.DataFrame: A DataFrame containing columns for ‘scet’ (time), ‘name’,

‘value’, and ‘unit’.

tts_dtat.demo_data.make_time_col(length=1000)

Generates a list of timestamps starting from the current time.

Args:
length (int, optional): The number of minutes to generate timestamps for.

Defaults to 1000.

Returns:

list: A list of pandas Timestamps with minute frequency.

tts_dtat.dtatdata

Datacache object functions for a cache for data from one or more sources

tts_dtat.dtatdata.column_values_from_state(data, state, time='scet', elapsed_seconds=False)

Makes a column of values for the given state. Returns the data and column name.

Args:

data (pd.DataFrame): DataFrame containing the data state (str): The state/column to process time (str, optional): The time column to sort by. Defaults to “scet”. elapsed_seconds (bool, optional): Whether to convert time to elapsed seconds.

Defaults to False.

Returns:

tuple: A tuple containing (processed data, column name).

tts_dtat.dtatdata.get_data_from_state(data, state)

Returns only the data for the given state. Does not modify the cache. Returns empty if state is invalid.

Args:

data (pd.DataFrame): The DataFrame containing the data. state (str): The name of the state to filter by.

Returns:

pd.DataFrame: A subset of the data containing only rows for the specified state.

tts_dtat.dtatdata.get_data_from_states(data, filter_states)

Returns only data for the given list of states. Does not modify the cache. Returns empty if all states are invalid, otherwise skips invalid states.

Args:

data (pd.DataFrame): The DataFrame containing the data. filter_states (list): A list of state names to filter by.

Returns:

pd.DataFrame: A subset of the data containing only rows for the specified states.

tts_dtat.dtatdata.get_max_date(data)

Returns the maximum date of data in this cache.

Args:

data (pd.DataFrame): The DataFrame containing the data.

Returns:

datetime: The maximum datetime found in the ‘scet’ column, or None if empty.

tts_dtat.dtatdata.get_min_date(data)

Returns the minimum date of data in this cache.

Args:

data (pd.DataFrame): The DataFrame containing the data.

Returns:

datetime: The minimum datetime found in the ‘scet’ column, or None if empty.

tts_dtat.dtatdata.get_unit_from_state(data, state)

Retrieves the unit associated with a specific state.

Args:

data (pd.DataFrame): The DataFrame containing the data. state (str): The name of the state to find the unit for.

Returns:

str: The unit string (e.g., ‘Time’, ‘volts’), or ‘Unknown’ if not found.

tts_dtat.dtatdata.get_units_from_states(data, states)

Retrieves the units for a list of states or a single state.

Args:

data (pd.DataFrame): The DataFrame containing the data. states (Union[str, list]): A single state name or a list of state names.

Returns:
Union[str, list]: A unit string if the input was a single state,

or a list of unit strings if the input was a list.

tts_dtat.dtatdata.log_data(data)

Log the current data as a debug message.

Args:

data (pd.DataFrame): The DataFrame to log.

tts_dtat.dtatdata.make_doy_from_state(data, state)

Creates a ‘doy’ (Day of Year) formatted string column from a time state.

Args:

data (pd.DataFrame): The DataFrame containing the data. state (str): The name of the time column to convert.

Returns:

pd.DataFrame: The DataFrame with an added ‘doy’ column.

tts_dtat.dtatdata.make_pd_cache_from_data(data_lists)

Creates a pandas DataFrame cache from a list of data sources.

Args:

data_lists (list): A list of JSON strings or objects containing data to be loaded.

Returns:
pd.DataFrame: A consolidated DataFrame containing data from all sources,

with standardized headers and datetime conversions.

tts_dtat.dtatdata.print_data(data)

Print the current data to console.

Args:

data (pd.DataFrame): The DataFrame to print.

tts_dtat.dtatdata.sort_by(data, col, ascending=True)

Sorts the data by the given column name.

Args:

data (pd.DataFrame): The DataFrame to sort. col (str): The name of the column to sort by. ascending (bool, optional): Whether to sort in ascending order. Defaults to True.

Returns:

pd.DataFrame: The sorted DataFrame.

tts_dtat.mouseover_maker

Functions to create a properly formatted hovertemplate string for plotly charts

tts_dtat.mouseover_maker.default_hovertemplate()

Return a hovertemplate string for a generic graph. This is the only hovertemplate method in this module that can used without setting meta to the output of make_meta()

Returns:

str: A generic hovertemplate string displaying X and Y values.

tts_dtat.mouseover_maker.ht_X_Y_Z_names(xaxis='X', yaxis='Y', zaxis='Z')

Return a hovertemplate that uses the x and y axis names to label the values. The meta field should be set to the output of make_meta() for this hovertemplate to work properly.

Args:

xaxis (str, optional): The label for the X-axis. Defaults to “X”. yaxis (str, optional): The label for the Y-axis. Defaults to “Y”. zaxis (str, optional): The label for the Z-axis (color). Defaults to “Z”.

Returns:

str: A formatted plotly hovertemplate string.

tts_dtat.mouseover_maker.ht_X_Y_Z_time_names(xaxis='X', yaxis='Y', zaxis='Z')

Return a hovertemplate that uses the x and y axis names to label the values. The meta field should be set to the output of make_meta() for this hovertemplate to work properly.

Args:

xaxis (str, optional): The label for the X-axis. Defaults to “X”. yaxis (str, optional): The label for the Y-axis. Defaults to “Y”. zaxis (str, optional): The label for the Z-axis (color). Defaults to “Z”.

Returns:

str: A formatted plotly hovertemplate string that includes a dedicated Time field.

tts_dtat.mouseover_maker.make_meta(zvar, data)

Returns the meta value for a chart which should be set to allow the Z and time values to be reflected in hovertext tooltips made by this module. This method should be run on the data and set to meta before using any of the below ‘ht’ hovertemplate methods in this module.

Args:
zvar (str): The name of the column containing the Z-axis (color) data.

Can be None if no Z-axis is used.

data (pd.DataFrame): The pandas DataFrame containing the chart data,

including ‘scet’ and the zvar column.

Returns:
list: A list of lists, where each inner list contains [z_value, scet_time]

corresponding to a row in the dataframe.

tts_dtat.palette

Default color palette for charts

tts_dtat.palette.clean_and_sort_colorscale(color_set: list, custom_divisions: list, data_min=0, data_max=1)

Cleans, sorts, and normalizes the colorscale bins based on data ranges.

Args:

color_set (list): The list of colors. custom_divisions (list): The list of raw start values for the bins. data_min (float, optional): The minimum value of the dataset. Defaults to 0. data_max (float, optional): The maximum value of the dataset. Defaults to 1.

Returns:
tuple: A tuple containing the processed (color_set, custom_divisions) lists,

where divisions are normalized to 0-1.

tts_dtat.palette.get_default_color_options()

Creates properly formatted dropdown labels for the default color options.

Returns:
list: A list of dictionaries, where each dictionary represents an option

containing ‘label’, ‘value’, ‘className’, and ‘title’.

tts_dtat.palette.get_default_colors()

Returns a list of the hex values with default colors

Returns:

list: A list of string hex color codes available in the default palette.

tts_dtat.palette.get_default_shape_options()

Creates properly formatted dropdown labels for the default shape options.

Returns:
list: A list of dictionaries, where each dictionary represents a shape option

containing ‘label’, ‘value’, ‘className’, and ‘title’.

tts_dtat.palette.get_line_color(color)

Tries to return a related line color. If not found, returns the color again.

Args:

color (str): The hex code of the fill color.

Returns:
str: The hex code of the corresponding line color, or the original color

if no mapping is found.

tts_dtat.palette.make_discrete_colorscale(color_set: list, custom_divisions: list, data_min=0, data_max=1)

Creates a discrete Plotly colorscale based on specified colors and division points.

Args:

color_set (list): A list of color codes. custom_divisions (list): A list of values where each color bin starts. data_min (float, optional): The minimum value in the data range. Defaults to 0. data_max (float, optional): The maximum value in the data range. Defaults to 1.

Returns:
list: A list of tuples compatible with Plotly’s colorscale format, or “jet”

if no colors are provided.

tts_dtat.palette.make_discrete_colorscale_from_data(color_set: list, bin_lower_bounds: list, color_data)

Generates a discrete colorscale by deriving min/max values directly from the data.

Args:

color_set (list): A list of color codes. bin_lower_bounds (list): A list of values where each color bin starts. color_data (pd.DataFrame): The dataframe containing the ‘value’ column to determine range.

Returns:

list: A discrete Plotly colorscale.

tts_dtat.palette.pop_next_color(unassigned_colors=None) → Tuple[str, list]

Retrieves the next available color from the unassigned list. If the list is empty or None, it resets with default colors.

Args:

unassigned_colors (list, optional): The current list of available color hex codes.

Returns:
Tuple[str, list]: A tuple containing the popped color (str) and the

updated list of unassigned colors.

tts_dtat.palette.remove_unseen_bins(color_set: list, custom_divisions: list)

Removes bins (colors and divisions) that fall outside the normalized 0-1 range. Ensures that the lowest remaining bin starts at 0.

Args:

color_set (list): A list of colors assigned to bins. custom_divisions (list): A list of normalized starting points (0-1) for each bin.

Returns:

tuple: A tuple containing the filtered (color_set, custom_divisions).

tts_dtat.plot

Plotly and other functions for a stacked plot graph

This version makes an arrow for each event

tts_dtat.plot.make_bar_graph(data: DataFrame, y1: str, y2: str, y_axis_units: Sequence[str] = [], x_var: str = 'scet', figure_title: str = None, unassigned_colors: List | None = None, background_color: str = '#fcfcfc', axis_line_color: str = '#555555', figure_margins: dict = None, figure_height: int = None, figure_width: int = None, bar_width: int = 1, plot_lines: bool = False, bar_color: str = '#005500')
tts_dtat.plot.make_diff_graph(data: DataFrame, y1: str, y2: str, y_axis_units: Sequence[str] = [], x_var: str = 'scet', figure_title: str = None, unassigned_colors: List | None = None, background_color: str = '#fcfcfc', axis_line_color: str = '#555555', figure_margins: dict = None, figure_height: int = None, figure_width: int = None)
tts_dtat.plot.make_stacked_graph(data: DataFrame, y_vars: Sequence[Sequence[str]], x_var: str = 'scet', z_var: str | None = None, multi_axis: bool = False, plot_lines: bool = True, figure_title: str = None, y_axis_title: str | List[str] = None, customize_dict: CustomizationOptions | None = None, unassigned_colors: List | None = None, background_color: str = '#fcfcfc', axis_line_color: str = '#555555', figure_margins: dict = None, figure_height: int = None, figure_width: int = None, events: Dict[str, List[Tuple]] = {}, event_line: bool = None, doy: bool = True, global_y_label: bool = False)

Creates a stacked graph with multiple subplots using Plotly.

Args:

data (pd.DataFrame): The pandas DataFrame containing the data to plot. y_vars (Sequence[Sequence[str]]): A list of lists of variable names to plot. x_var (str, optional): The name of the column to use for the X-axis. Defaults to “scet”. z_var (Optional[str], optional): The name of the column to use for the Z-axis (color scale). multi_axis (bool, optional): If True, creates multiple Y-axes for traces within the same subplot. plot_lines (bool, optional): If True, plots lines and markers. If False, plots markers only. figure_title (str, optional): The title of the figure. y_axis_title (Union[str, List[str]], optional): The title(s) for the Y-axis. Can be a single string (applied to all or used globally), or a list of strings (one per subplot). customize_dict (Optional[CustomizationOptions], optional): Customization options for specific traces. unassigned_colors (Optional[List], optional): A list of colors to use for traces without assignments. background_color (str, optional): The background color of the plot. axis_line_color (str, optional): The color of the axis lines. figure_margins (dict, optional): Margins for the figure (l, r, t, b). figure_height (int, optional): The height of the figure in pixels. figure_width (int, optional): The width of the figure in pixels. events (Dict[str, List[Tuple]], optional): A dictionary of events to annotate. event_line (bool, optional): If True, draws a vertical line at the event time. doy (bool, optional): If True and x_var is a time type, formats the X-axis ticks using dates. global_y_label (bool, optional): If True, treats y_axis_title as a single label for the whole figure.

Returns:

tuple: (graph, unassigned_colors, marker_values, visible_traces)

tts_dtat.types

Module containing type definitions

class tts_dtat.types.CustomizationOptions

Bases: MutableMapping[str, CustomizedTrace]

A mutable mapping that associates trace names (str) with their corresponding CustomizedTrace configuration dictionaries.

class tts_dtat.types.CustomizedMarker

Bases: TypedDict

Defines the properties of a marker in a plot.

Attributes:

size (int): The size of the marker. symbol (str): The shape of the marker (e.g., ‘circle’). color (str): The color of the marker. colorscale (str): The color scale applied to the marker. showscale (bool): Whether to show the color scale associated with the marker. line (Line): The outline properties of the marker.

color: str
colorscale: str
line: Line
showscale: bool
size: int
symbol: str
class tts_dtat.types.CustomizedTrace

Bases: TypedDict

Defines customization options for a specific trace in a plot.

Attributes:

size (int): The size of the markers in the trace. symbol (str): The symbol used for markers (e.g., ‘circle’, ‘square’). color (str): The color of the markers or line. colorscale (str): The name of the color scale to use (e.g., ‘Viridis’). showscale (bool): Whether to display the color scale bar. line (Line): A dictionary defining the properties of the trace’s line. z_var (Optional[str]): The name of the variable determining the Z-axis or color dimension. mode (str): The drawing mode for the trace (e.g., ‘lines’, ‘markers’, ‘lines+markers’). marker_line_width (float): Specific width for the marker border/stroke. Overrides line[‘width’] for markers.

color: str
colorscale: str
line: Line
marker_line_width: float
mode: str
showscale: bool
size: int
symbol: str
z_var: str | None
class tts_dtat.types.Line

Bases: TypedDict

Defines the properties of a line in a plot.

Attributes:

width (float): The width of the line in pixels. color (str): The color of the line (hex code or name). shape (Optional[str]): The shape of the line (e.g., ‘linear’, ‘hv’, ‘vh’, ‘spline’).

color: str
shape: str | None
width: float