Collection

class Collection(name: str, columns: list[str], types: list[Type])[source]

Bases: EventBase

Manages a collection of data entries stored in a CSV file and a pandas DataFrame.

name

Name of the collection.

Type:: str

columns

List of column names.

Type:: list[str]

types

List of column data types.

Type:: list[Type]

dict

Dictionary mapping columns to types.

Type:: dict

path

Path to the CSV file.

Type:: Path

df

The pandas DataFrame holding the data.

Type:: pd.DataFrame

__init__(name: str, columns: list[str], types: list[Type]) → None[source]

Initializes the Collection.

Parameters:

name (str) – The name of the collection (and the file base name).
columns (list[str]) – The column names.
types (list[Type]) – The data types for each column.

Methods

`__init__`(name, columns, types)	Initializes the Collection.
`add_entry`(entry)	Adds a new entry to the collection.
`change_last_entry`(column, value)	Updates a value in the last entry of the DataFrame and saves.
`check_split_csv`()	Checks if the CSV file is too large and splits it if necessary.
`convert_df_to_types`(df)	Converts DataFrame columns to the specified types.
`convert_with_default`(value, target_type)	Converts a value to a target type, using defaults for failures.
`df_from_df`(df, training)	Processes a DataFrame for saving (formatting dates, enums, etc).
`get_first_entry`(column, value)	Gets the first entry matching a specific value in a column.
`get_last_entry`(column, value)	Gets the last entry matching a specific value in a column.
`get_last_entry_name`(column, value)	Gets the 'name' field of the last entry matching a condition.
`get_last_sound_df`()	Returns the latest sound calibration entries for each speaker/sound.
`get_last_water_df`()	Returns the latest water calibration entries for each port.
`get_sound_gain`(speaker, dB, sound_name)	Calculates sound gain for a target dB based on calibration.
`get_valve_time`(port, volume)	Calculates valve open time for a given volume based on calibration.
`log`(date, type, subject, description)	Logs an event if the collection schema matches standard logging fields.
`log_temp`(date, temperature, humidity)	Logs temperature if the collection schema matches temperature fields.
`save_from_df`([training])	Saves values from the current DataFrame to the CSV file, processing formatting.

add_entry(entry: list) → None[source]

Adds a new entry to the collection.

Parameters:: entry (list) – The list of values for the new row.

static convert_with_default(value, target_type: Any) → Any[source]

Converts a value to a target type, using defaults for failures.

Parameters:

value – The value to convert.
target_type (Any) – The target type.

Returns:

The converted value or a default.

Return type:

Any

convert_df_to_types(df: pandas.DataFrame) → pandas.DataFrame[source]

Converts DataFrame columns to the specified types.

Parameters:: df (pd.DataFrame) – The DataFrame to convert.
Returns:: The converted DataFrame.
Return type:: pd.DataFrame

check_split_csv() → None[source]: Checks if the CSV file is too large and splits it if necessary.

get_last_entry(column: str, value: str) → pandas.Series | None[source]

Gets the last entry matching a specific value in a column.

Parameters:

column (str) – The column to search.
value (str) – The value to match.

Returns:

The last matching row, or None.

Return type:

Union[pd.Series, None]

get_last_entry_name(column: str, value: str) → str | None[source]

Gets the ‘name’ field of the last entry matching a condition.

Parameters:

column (str) – The column to search.
value (str) – The value to match.

Returns:

The name, or None.

Return type:

str | None

get_first_entry(column: str, value: str) → pandas.Series | None[source]

Gets the first entry matching a specific value in a column.

Parameters:

column (str) – The column to search.
value (str) – The value to match.

Returns:

The first matching row, or None.

Return type:

Union[pd.Series, None]

change_last_entry(column: str, value: Any) → None[source]

Updates a value in the last entry of the DataFrame and saves.

Parameters:

column (str) – The column to update.
value (Any) – The new value.

log(date: str, type: str, subject: str, description: str) → None[source]

Logs an event if the collection schema matches standard logging fields.

Parameters:

date (str) – Date string.
type (str) – Event type.
subject (str) – Subject name.
description (str) – Description.

log_temp(date: str, temperature: float, humidity: float) → None[source]

Logs temperature if the collection schema matches temperature fields.

Parameters:

date (str) – Date string.
temperature (float) – Temperature value.
humidity (float) – Humidity value.

get_last_water_df() → pandas.DataFrame[source]

Returns the latest water calibration entries for each port.

Returns:: Filtered DataFrame with max calibration numbers per port.
Return type:: pd.DataFrame

get_last_sound_df() → pandas.DataFrame[source]

Returns the latest sound calibration entries for each speaker/sound.

Returns:: Filtered DataFrame with max calibration numbers per sound.
Return type:: pd.DataFrame

get_valve_time(port: int, volume: float) → float[source]

Calculates valve open time for a given volume based on calibration.

Parameters:

port (int) – The port number.
volume (float) – The target volume in ul.

Returns:

The time in seconds.

Return type:

float

Raises:

ValueError – If calibration data is invalid or missing.

get_sound_gain(speaker: int, dB: float, sound_name: str) → float[source]

Calculates sound gain for a target dB based on calibration.

Parameters:

speaker (int) – The speaker ID.
dB (float) – The target decibels.
sound_name (str) – The name of the sound.

Returns:

The gain factor.

Return type:

float

Raises:

ValueError – If calibration data is invalid or missing.

save_from_df(training: TrainingProtocolBase = TrainingProtocolBase()) → None[source]

Saves values from the current DataFrame to the CSV file, processing formatting.

Parameters:: training (TrainingProtocolBase) – Protocol for formatting specific fields.

df_from_df(df: pandas.DataFrame, training: TrainingProtocolBase) → pandas.DataFrame[source]

Processes a DataFrame for saving (formatting dates, enums, etc).

Parameters:

df (pd.DataFrame) – The input DataFrame.
training (TrainingProtocolBase) – The training protocol for custom formatting.

Returns:

The processed DataFrame.

Return type:

pd.DataFrame