fino2py package

Subpackages

• fino2py.cleaning package
  • Submodules
  • fino2py.cleaning.merge_split_data module
    • merge_split_data()
  • Module contents
• fino2py.ingesting package
  • Submodules
  • fino2py.ingesting.read_nova_demographics module
    • read_nova_demographics()
  • fino2py.ingesting.read_raw_demographics module
    • read_raw_demographics()
  • fino2py.ingesting.read_raw_finometer_data module
    • read_raw_finometer_data()
  • fino2py.ingesting.read_raw_nova_data module
    • read_raw_nova_data()
  • Module contents
• fino2py.reshaping package
  • Submodules
  • fino2py.reshaping.create_chunk module
    • create_chunk()
  • fino2py.reshaping.generate_protocol_averages module
    • generate_protocol_averages()
  • fino2py.reshaping.minute_by_minute module
    • Functions
    • minute_by_minute()
  • fino2py.reshaping.minute_by_minute_from_folder module
    • minute_by_minute_from_folder()
  • fino2py.reshaping.nova_concat module
    • nova_concat()
  • fino2py.reshaping.nova_minute_by_minute module
    • Functions
    • nova_minute_by_minute()
  • Module contents
• fino2py.times package
  • Submodules
  • fino2py.times.convert_fino_time module
    • convert_fino_time()
  • fino2py.times.convert_partial_time module
    • convert_partial_time()
  • fino2py.times.convert_timestamp_time module
    • convert_timestamp_time()
  • fino2py.times.import_protocol_times module
    • import_protocol_times()
  • Module contents

Submodules

fino2py.dependencies module

This script is just housing the dependencies for the other scripts in the src folder. It is not intended to be run as a script. The dependencies are:

• pathlib

• pandas

possible future dependencies:

• csv

Module contents

fino2py.read_raw_finometer_data(folder_path: str | Path, interval: str | None = None, save_csv: bool = False) → Tuple[pandas.DataFrame, str]

Imports the raw finometer data and calculates the average of each measure over the selected time period.

This function imports the raw finometer data from the specified folder path or file and calculates the average of each measure over a selected time period. The default time period is 1 minute, but it can be changed by setting the interval parameter to a different value. This function is a convenient way to preprocess the data before further analysis.

Parameters:

• folder_path (Union[str, pathlib.Path]) – The path to the folder containing the .txt file.

• interval (str, optional) – If provided, the data is resampled to the given interval. Defaults to None.

• save_csv (bool, optional) – If True, the imported data (or the resampled data if interval is provided) is saved as a CSV file in the same folder as the data file. Defaults to False.

Raises:

• TypeError – If folder_path is not a pathlib.Path object or a string.

• ValueError – If folder_path does not exist or is not a directory. If there is not exactly one .txt file in the folder.

Returns:

A tuple containing the following:

• A DataFrame with the raw finometer data resampled to the given interval.

• The Participant ID of the participant whose data is being imported.

Return type:

Tuple[pd.DataFrame, str]

Notes

• The function expects the finometer data to be stored in a single .txt file within the specified folder.

• The function reads the data from the .txt file, performs preprocessing steps (such as dropping unnecessary columns and converting timestamps), and calculates the average of each measure over the selected time period.

• If interval is provided, the data is resampled to the given interval using the mean value for each resampled interval.

• If save_csv is True, the imported data (or the resampled data if interval is provided) is saved as a CSV file in the same folder as the data file.

Example

df, id = read_raw_finometer_data(‘/path/to/folder’, interval=’1T’, save_csv=True)

fino2py.read_raw_demographics(folder_path: str) → pandas.DataFrame

Reads in the demographics from the .txt file and returns a DataFrame row containing the data.

Parameters: file_path (str): Path to the demographics file.

Returns: demographics_df (pd.DataFrame): DataFrame containing the demographics data.

fino2py.read_raw_nova_data(folder_path: str | Path, interval: str | None = '1s', save_csv: bool = False, required_files: list = ['Basic Nova', 'Advanced_Hemodynamics']) → Tuple[str, pandas.DataFrame]

Imports the raw NovaPress data, processes it, and calculates the average of each measure over the selected time period.

This function imports the raw NovaPress data from the specified folder path or file and calculates the average of each measure over a selected time period. The default time period is 1 minute, but it can be changed by setting the interval parameter to a different value. This function is a convenient way to preprocess the data before further analysis. It combines data from the ‘Basic Nova’ and ‘Advanced_Hemodynamics’ CSV files by matching on the ‘Time(sec)’ column.

Parameters:

• folder_path (Union[str, pathlib.Path]) – The path to the folder containing the .csv files.

• file_prefix (str, optional) – If provided, only files with names starting with this prefix will be considered. Defaults to None.

• interval (str, optional) – The interval over which the average of each measure is calculated. Defaults to ‘1s’.

• save_csv (bool, optional) – If True, the imported data (or the resampled data if interval is provided) is saved as a CSV file in the same folder as the data file. Defaults to False.

• required_files (list, optional) – A list of strings specifying the names of the CSV files to be imported and processed. Defaults to [‘Basic Nova’, ‘Advanced_Hemodynamics’].

Raises:

• TypeError – If folder_path is not a pathlib.Path object or a string.

• ValueError – If folder_path does not exist or is not a directory, or if no matching CSV files are found.

Returns:

A tuple containing the following:

• A string representing the Participant ID of the participant whose data is being imported.

• A pandas DataFrame with the raw NovaPress data resampled to the given interval (if provided).

Return type:

Tuple[str, pd.DataFrame]

Notes

• The function expects the data to be stored in one or more .csv files in the specified folder.

• If file_prefix is provided, only files with names starting with the specified prefix will be considered.

• The function reads the data from the CSV files, performs preprocessing steps (such as dropping unnecessary columns and converting timestamps), and calculates the average of each measure over the selected time period.

• If interval is provided, the data is resampled to the given interval using the mean value for each resampled interval.

• If save_csv is True, the imported data (or the resampled data if interval is provided) is saved as a CSV file in the same folder as the data file.

Example

df, id = read_raw_nova_data(‘/path/to/folder’, interval=’1T’, save_csv=True)

fino2py.read_nova_demographics(folder_path: str) → pandas.DataFrame

Reads in the demographics from the nova press .csv file and returns a DataFrame row containing the data.

Parameters: file_path (str): Path to the demographics file.

Returns: demographics_df (pd.DataFrame): DataFrame containing the demographics data.

fino2py.generate_protocol_averages(frame, id, times=None, save_csv=None)

A function that imports the finometer dataframes (which have already been processed from the raw data) to produce averages for each section of the experimental protocol concatenated into a single row so that participants can then be merged into a single dataframe.

Parameters:

• frame (pandas.DataFrame) – The DataFrame containing the averaged finometer data

• id (str) – The participant ID

• save_csv (bool, optional) – If True, the imported data will be saved as a .csv file in the same folder as the .csv file, this is not always needed and should be used sparingly

• times (dict, optional) – A dictionary of tuples of times, with the keys being the names of the time periods.

Returns:

A DataFrame with the mean values of the given columns during each time period of the study.

Return type:

pandas.DataFrame

Raises:

• TypeError – If frame is not a pandas.DataFrame object If id is not a string

• ValueError – If times is not provided as a dictionary with at least one key-value pair If there are not enough times provided for a given time period If there are too many times provided for a given time period

fino2py.create_chunk(df: pandas.DataFrame, ID: str, tag: str, start: str | None, end: str | None) → pandas.DataFrame

Create a chunk of data from a dataframe between specified start and end times and return a new dataframe containing the mean values for each cardiovascular measure during that chunk.

Parameters:

dfpandas DataFrame

The dataframe containing the data to extract a chunk from.

IDstr

The participant ID to include in the output dataframe.

tagstr

The tag to include in the column names of the output dataframe.

startstr or None

The start time of the chunk in the format ‘HH:MM:SS’ or ‘HH:MM:SS.mmm’. If None, the chunk starts at the beginning of the dataframe.

endstr or None

The end time of the chunk in the format ‘HH:MM:SS’ or ‘HH:MM:SS.mmm’. If None, the chunk ends at the end of the dataframe.

Returns:

pandas DataFrame

A new dataframe containing the mean values for each column in the specified chunk of the input dataframe. The output dataframe has a row for the specified participant ID and columns with names that include the specified tag.

fino2py.merge_split_data(part1_file: str | Path, part2_file: str | Path, part2_start_line: str = 9, output_file: str | Path | None = None) → List[str]

Appends cardiovascular data from part 2 file to part 1 file and optionally writes the combined data to an output file.

Parameters:

• part1_file (Union[str, Path]) – File path of the part 1 file.

• part2_file (Union[str, Path]) – File path of the part 2 file.

• part2_start_line (int, optional) – The line number in the part 2 file from which to start appending the data (default is 9). Use this parameter to skip lines in the part 2 file, for example, to account for recalibration.

• output_file (Union[str, Path], optional) – File path of the output file to write the combined data (default is None).

Returns:

List of combined cardiovascular data.

Return type:

List[str]

fino2py.minute_by_minute(df: pandas.DataFrame, df_id: str) → pandas.DataFrame

Reshape the participant’s minute by minute data into a single row

This function takes a DataFrame containing finometer data (df). It converts the index of the DataFrame into a column named “Time (s)” to preserve the original time information.

The DataFrame is then flattened to create a new DataFrame (flat_frame) with each minute’s data in a separate column. The column names are generated by appending “_minute_i” to the original column names, where “i” represents the minute index.

The Participant ID (df_id) is added as a column at the beginning of the flat_frame DataFrame. This allows for participant data to be easily concatenated into a single DataFrame for sample level analysis.

Parameters:

• df (pandas DataFrame) – The DataFrame containing the finometer data.

• df_id (str) – The Participant ID associated with the data.

Returns:

The minute-by-minute analysis DataFrame.

The flat_frame DataFrame contains each minute’s data in separate columns, with column names reflecting the original column names and minute indices. The Participant ID column is included at the beginning.

Return type:

pandas DataFrame

fino2py.nova_minute_by_minute(df: pandas.DataFrame, df_id: str) → pandas.DataFrame

Reshape the participant’s minute by minute data into a single row

This function takes a DataFrame containing finometer data (df). It converts the index of the DataFrame into a column named “Time (s)” to preserve the original time information.

The DataFrame is then flattened to create a new DataFrame (flat_frame) with each minute’s data in a separate column. The column names are generated by appending “_minute_i” to the original column names, where “i” represents the minute index.

The Participant ID (df_id) is added as a column at the beginning of the flat_frame DataFrame. This allows for participant data to be easily concatenated into a single DataFrame for sample level analysis.

Parameters:

• df (pandas DataFrame) – The DataFrame containing the finometer data.

• df_id (str) – The Participant ID associated with the data.

Returns:

The minute-by-minute analysis DataFrame.

The flat_frame DataFrame contains each minute’s data in separate columns, with column names reflecting the original column names and minute indices. The Participant ID column is included at the beginning.

Return type:

pandas DataFrame

fino2py.nova_concat(data_dict: Dict) → pandas.DataFrame

Concatenate the minute-by-minute data for each participant into a single DataFrame.

This function takes a dictionary of minute-by-minute dataframes (data_dict) and concatenates them into a single DataFrame. The dictionary should be created using the read_raw_nova_data function. The Participant ID column is added at the beginning of the DataFrame to allow for sample-level analysis.

Parameters:

data_dict (Dict) – A dictionary containing Participant ID as keys and minute-by-minute dataframes as values.

Returns:

A concatenated DataFrame containing minute-by-minute data for all participants.

Return type:

pd.DataFrame

Example

# Import minute-by-minute data for each participant with a dictionary comprehension data_dict

concatenated_df = nova_concat(data_dict)

fino2py.minute_by_minute_from_folder(path: str, save_raw: bool = False, save: bool = False) → Tuple[pandas.DataFrame, str]

This function reads the raw finometer data from the specified folder path and ‘reshapes’ the data into a minute-by-minute format. It uses the read_raw_finometer_data function to import the data and calculate the average of each measure over the selected time interval (1 minute in this case). Then, the minute_by_minute function is applied to reshape the data into a single row, with each column representing the average of a particular measure over each minute of the data collection.

Parameters:

• path (str) – The path to the folder containing the finometer data files.

• save_raw (bool, optional) – Specifies whether to save the imported raw data as a CSV file. The default is False.

• save (bool, optional) – Specifies whether to save the minute-by-minute analysis result as a CSV file. The default is False.

Returns:

A tuple containing the minute-by-minute analysis DataFrame and the Participant ID associated with the data.

Return type:

Tuple[pd.DataFrame, str]

Notes

• The read_raw_finometer_data function is used to import the raw finometer data and calculate the average over the selected time interval.

• The minute_by_minute function is applied to reshape the data into a single row for each minute.

• If save_raw is True, the imported raw data is saved as a CSV file in the same folder as the data files.

• If save is True, the minute-by-minute analysis result is saved as a CSV file in the same folder as the data files.

Example

frame, id = minute_by_minute_from_folder(‘/path/to/folder’, int=’1T’, save_raw=True, save=True)

fino2py.convert_partial_time(partial_time: str) → time

Convert the partial time in the format ‘09:02’ to a datetime.time object with 0 seconds.

Parameters:

partial_timestr

The partial time in the format ‘09:02’

Returns:

datetime.time

The time as a datetime.time object with 0 seconds.

fino2py.convert_fino_time(fino_time: str) → time

Converts the string times produced by the Finometer to datime objects in the ‘%H:%M:%S.%f’ format.

Parameters:

fino_timestr

The Finometer time in the format ‘%H:%M:%S.%f’

Returns:

datetime.time

The time as a datetime.time object.

fino2py.convert_timestamp_time(timestamp_time: str) → str

Convert the timestamp string in the format ‘09:02:12’ to ‘%H:%M:%S’ datetime format.

Parameters:

timestamp_timestr

The timestamp time in the format ‘09:02:12’

Returns:

str

The time in the ‘%H:%M:%S’ format.

fino2py.import_protocol_times(times_file_path: Path, add_seconds: bool = False, flatten_seconds: bool = False, save_csv: bool = False) → pandas.DataFrame

This function imports the protocol times from a .csv or excel file file and returns a cleaned pandas dataframe with the protocol times for each participant.

Parameters:

• times_file_path (pathlib.Path or str) – The path to the .csv/.xlsx file containing the protocol times.

• add_seconds (bool, optional) – If True, seconds will be added to the time values (if missing).

• flatten_seconds (bool, optional) – If True, seconds will be set to 00 for all time values.

• save_csv (bool, optional) – If True, the imported data will be saved as a .csv file in the same folder as the .csv file.

Raises:

• TypeError: – If times_file_path is not a pathlib.Path object.

• ValueError: – If times_file_path does not exist or is not a file. If times_file_path does not have a .csv extension. If add_seconds and flatten_seconds are both True. If the function is unable to add seconds to time values or set seconds to 00.

Returns:

A cleaned pandas dataframe with the protocol times for each participant.

Return type:

pandas.DataFrame