PFFP File Class

class data_classes.pffpFile.pffpFile(file_dir, calibration_params, sensor_units={'Time': 'min', 'accel': 'g', 'pressure': 'kPa'})

Bases: BinaryFile

Purpose: To store information and modify a PFFP binary file.

Inherits

BinaryFile

A base class for handling binary file operations.

calibration_params

Parameters for converting sensor readings from volts to engineering units.

Type:

DataFrame

sensor_units

Units used for different sensors. Defaults to {“accel”: “g”, “pressure”: “kPa”, “Time”: “min”}.

Type:

dict, optional

num_drops

Number of drops in the file. Defaults to “Not Checked”.

Type:

str

df_stored

Flag indicating whether the DataFrame has been stored.

Type:

bool

stored_concat_accel

Flag indicating whether concatenated acceleration data has been stored.

Type:

bool

analyze_file(use_pore_pressure=True, store_df=True, overide_water_drop=False, select_accel=['2g_accel', '18g_accel', '50g_accel', '250g_accel'])

Analyze the binary file to identify and process drops based on sensor data.

Parameters:

  • use_pore_pressure (bool, optional) – Whether to use pore pressure data to help identify drops. Defaults to True.

  • store_df (bool, optional) – Whether to store the DataFrame in the class attribute for later use. Defaults to True.

  • overide_water_drop (bool, optional) – Flag to override the default water drop detection. Defaults to False.

  • select_accel (list of str, optional) – List of accelerometer labels to use for drop analysis. Defaults to [“2g_accel”, “18g_accel”, “50g_accel”, “250g_accel”].

Notes

This method performs the following actions: - Loads and processes the binary file into a DataFrame. - Stitches accelerometer data together, excluding certain sensors if needed. - Identifies drop locations based on peak accelerations and optionally pore pressure data. - Creates Drop objects for each identified drop and stores them in the drops attribute. - Optionally stores the DataFrame if store_df is True.

TODO: - Add inputs for drop detection tolerances and sampling rate.

binary_2_sensor_df(size_byte=3, byte_order='big', signed=True, acceleration_unit='g', pressure_unit='kPa', time_unit='min')

Read a binary file and transform it into a Dataframe that has the sensor values converted to engineering units of interest.

Parameters:

  • size_byte (int, optional) – The size of each data element in bytes. Defaults to 3.

  • byte_order (str, optional) – The byte order of the binary file. Defaults to “big”.

  • signed (bool, optional) – Whether the data is signed. Defaults to True.

  • acceleration_unit (str, optional) – The unit to convert acceleration values to. Defaults to “g”.

  • pressure_unit (str, optional) – The unit to convert pressure values to. Defaults to “kPa”.

  • time_unit (str, optional) – The unit for time values. Defaults to “min”.

Returns:

The processed DataFrame with converted sensor readings and time steps.

Return type:

DataFrame

check_drop_in_file()

Check if there are any drops detected in the file.

Returns:

True if there are drops detected, False otherwise.

Return type:

bool

check_pore_pressure_4_drop(df, window=2500)

Use pore pressure data to check if there are drops in the file.

Parameters:

  • df (DataFrame) – DataFrame containing sensor data with columns ‘Time’ and ‘pore_pressure’.

  • window (int, optional) – Window size for smoothing the pressure data (default is 2500).

Returns:

  • numpy.ndarray: Array of times where pressure gradient peaks occur.

  • int: Number of drops detected based on pressure derivative.

Return type:

tuple

static get_tightest_sensor(row, resolutions, labels)

Determine the sensor with the closest resolution to the maximum value in the row.

Parameters:

  • row (Series) – The data row containing sensor values.

  • resolutions (list of float) – List of possible sensor resolutions.

  • labels (list of str) – List of sensor labels corresponding to the resolutions.

Returns:

The value from the row that corresponds to the closest resolution.

Return type:

float

insert_drop(drop, index=None)

Add a drop to the file object. This is useful for the automatic process and manually adding a drop

manual_indices_selection(drop, debug=False, interactive=True, figsize=[12, 8], legend=False, lag=0.1)

Manually select indices for drops. Allows users to enter time or index values.

Parameters:

  • drop (Drop) – The Drop object for which indices are to be manually selected.

  • debug (bool, optional) – Flag to enable debugging information (default is False).

  • interactive (bool, optional) – Flag to enable interactive plotting (default is True).

  • figsize (list of int, optional) – Figure size for plotting (default is [12, 8]).

  • legend (bool, optional) – Flag to show legend on the plot (default is False).

  • lag (float, optional) – Time delay before accepting user input (default is 0.1 seconds).

Notes

Prompts the user to specify time, index, or skip the drop. Provides options for impulse integration and updates the drop object accordingly.

manually_add_drop(peak_index, file_drop_index, peak_info, pressure_check)

Function to manually add a drop to the file object. This covers all the initialization steps that are necessary to make sure the drop has all of the information it needs to work

manually_integrate_drop(drop)

Integrate acceleration data for a drop that was manually processed.

Parameters:

drop (Drop) – The Drop object representing the manually processed drop.

Notes

This method performs the integration of acceleration data for a drop whose indices were selected manually. It assumes that the indices have been found and the drop has been marked as manually processed.

Raises:

  • IndexError – If the indices for the drop are not found.

  • ValueError – If the drop is not marked as manually processed.

manually_process_drops(interactive_plot=True, figsize=[6, 4])

Manually process drops by allowing the user to select drop indices and perform integration interactively.

Parameters:

  • interactive_plot (bool, optional) – Whether to use interactive plotting for manual index selection. Defaults to True.

  • figsize (list of int, optional) – The size of the figures for interactive plots. Defaults to [6, 4].

new_pffp_file_name(survey_id, num_char_from_end=8, use_default=True, other_name=None)

Update the name of the pffp file.

Parameters:

  • survey_id (str) – The survey identifier to include in the new file name.

  • num_char_from_end (int, optional) – Number of characters to keep from the end of the current file name. Defaults to 8.

  • use_default (bool, optional) – Whether to use the default naming format. Defaults to True.

  • other_name (str, optional) – A custom name to use instead of the default format. Not implemented yet.

Raises:

ValueError – If use_default is False and other_name is None.

plot_drop_impulses(figsize=[4, 6], save_figs=False, hold=False, legend=True, colors=['black', 'blue', 'green', 'orange', 'purple', 'brown'], units={'Time': 's', 'accel': 'g', 'displacement': 'cm', 'velocity': 'm/s'}, line_style=['solid', 'dashed'], return_figs=False)

Plot the standard velocity and acceleration versus displacement plots for all processed drops.

Parameters:

  • figsize (list of int, optional) – Size of the figure in inches (default is [4, 6]).

  • save_figs (bool, optional) – Flag to save the figures (default is False).

  • hold (bool, optional) – Flag to hold the figure open and plot on the same figure (default is False). If True, all drops will be plotted on the same figure.

  • legend (bool, optional) – Flag to show the legend on the plot (default is True).

  • colors (list of str, optional) – List of colors to use for plotting each drop (default is [“black”, “blue”, “green”, “orange”, “purple”, “brown”]).

  • units (dict, optional) – Dictionary specifying the units for time, acceleration, velocity, and displacement (default is {“Time”: “s”, “accel”: “g”, “velocity”: “m/s”, “displacement”: “cm”}).

  • line_style (list of str, optional) – List of line styles to use for plotting (default is [“solid”, “dashed”]).

Notes

  • If hold is True, all processed drops will be plotted on the same figure using the first color specified in the colors list.

  • Each processed drop will be plotted with acceleration and velocity versus displacement.

  • The units dictionary is used to convert the units of the data to match the specified units.

  • The save_figs flag is not implemented in this version of the method.

  • If legend is True, a legend will be added to the plot to differentiate between acceleration and velocity.

process_drops()

Process the identified drops in the file by integrating acceleration data.

Notes

This method processes each drop by: - Trimming the acceleration data around the drop events. - Integrating the trimmed acceleration data to obtain meaningful metrics. - Handling any errors that occur during processing, including moving files to a “funky” folder if errors are encountered.

Raises:

zeroLenError – If any error occurs during the processing of drops.

quick_view(fig=None, axs=None, interactive=False, figsize=[12, 8], legend=False, show=True, **kwargs)

Provide a quick view of the file data by plotting accelerometer, pore pressure, and tilt sensor data.

Parameters:

  • interactive (bool, optional) – Flag to enable interactive plotting with Plotly (default is False).

  • figsize (list of int, optional) – Figure size for plotting (default is [12, 8]).

  • legend (bool, optional) – Flag to show legend on the plot (default is False).

Notes

If interactive is True, plots are created using Plotly for interactive viewing. Otherwise, matplotlib is used for static plots.

reset_drop_index(reset_type='normal')

Loop over the drops and reset the file indices

stitch_accelerometers(accel_df, accel_labels)

Stitch accelerometer data together to get the most resolved accelerations.

Parameters:

  • accel_df (DataFrame) – DataFrame containing accelerometer data.

  • accel_labels (list of str) – List of accelerometer labels to be used for stitching.

Notes

Assumes that the accel labels and the max sensor values are in the same order.