Transforms

This section provides detailed documentation for the available transforms in the hermes_rheo.transforms module.

Rheological Analysis

class hermes_rheo.transforms.rheo_analysis.RheoAnalysis(owchirp_waiting_time='before_signal', cutoff_points=0, *args, **kwargs)

Bases: MeasurementTransform

The RheoAnalysis class, a subclass of MeasurementTransform, is designed for analyzing rheological data, particularly focusing on the transformation and analysis of data collected from rheological experiments involving Arbitrary Waves (e.g. OWChirp).

prepare_chirp_data()

Prepares chirp data by adjusting units and switching coordinates.

average_until_tw()

Applies a filter to the signal by averaging until a specified waiting time.

average_over_chirp()

Filters the signal by averaging over the length of the chirp only.

average_over_all()

Filters the signal by averaging over the entire duration, including waiting time.

filter_signal()

Applies a selected filtering method to the signal.

select_best_filter_method()

Determines the best filtering method based on the symmetry of the corrected signal.

calculate_wave_parameters()

Calculates various wave parameters from the wave data used to generate the chirp.

moduli_ofr_chirp()

Computes viscoelastic properties by applying fast fourier transform from strain and stress

data collected during chirp experiments.

_apply()

Applies transformations to the target dataset based on the specified method.

List

alias of List

Optional = typing.Optional

Tuple

alias of Tuple

static average_over_all(t_w: float, time: List[float], signal: List[float]) → ndarray

Average over all: This subtracts the time-averaged value of the signal before and after the waiting time (t_w).

Parameters:

• t_w (float) – The waiting time before the chirp starts.

• time (List[float]) – A list of time values corresponding to the signal.

• signal (List[float]) – A list of signal values that need to be corrected.

Returns:

A NumPy array representing the corrected signal after subtracting the average values

before and after t_w from the entire signal.

Return type:

np.ndarray

Raises:

IndexError – If the time list does not contain values less than or equal to t_w.

static average_over_chirp(t_w: float, time: List[float], signal: List[float]) → ndarray

Average over chirp only: this subtracts the average of the signal over the length of the signal alone, excluding the initial waiting time. It can be the best option for the stress signal since the stress can be settling to zero during the initial waiting time.

Parameters:

• t_w (float) – The waiting time before the chirp starts.

• time (List[float]) – A list of time values corresponding to the signal.

• signal (List[float]) – A list of signal values that need to be corrected.

Returns:

A NumPy array representing the corrected signal after subtracting the average value post t_w.

Return type:

np.ndarray

Raises:

IndexError – If the time list does not contain values less than or equal to t_w.

static average_until_tw(t_w: float, time: List[float], signal: List[float]) → ndarray

Average until waiting time (t_w): This function subtracts the initial value of the strain/stress during the waiting time. It is usually the best option to correct the strain signal.

Parameters:

• t_w (float) – The waiting time before the chirp starts.

• time (List[float]) – A list of time values corresponding to the signal.

• signal (List[float]) – A list of signal values that need to be corrected.

Returns:

An array representing the corrected signal after subtracting the initial average value.

Return type:

np.ndarray

Raises:

IndexError – If the time list does not contain values less than or equal to t_w.

static calculate_wave_parameters(wave_data: Dict[str, dict]) → Tuple[float, float, float, float, float]

Calculates wave parameters from the provided wave data. Depending on the number of waves present, it calculates the waiting time (tw), duration of the signal (T), tapering parameter (r), initial frequency (w0), and final frequency (w1) of the wave.

Parameters:

wave_data (dict) – A dictionary containing wave information. The dictionary is expected to contain keys such as: - ‘duration (s)’: The duration of each wave in seconds. - ‘coef’: Coefficients corresponding to the wave parameters.

Returns:

A tuple containing:

• tw (float): The waiting time before the wave starts.

• T (float): The total duration of the signal.

• r (float): The tapering parameter

• w0 (float): The initial frequency (low frequency) of the wave.

• w1 (float): The final frequency (high frequency) of the wave.

Return type:

Tuple[float, float, float, float, float]

filter_signal(t_w: float, time: List[float], signal: List[float], method: str = 'tw') → ndarray | None

Filters the signal based on the specified method and a time threshold.

Parameters:

• t_w (float) – The time threshold used for filtering.

• time (List[float]) – A list of time values corresponding to the signal.

• signal (List[float]) – A list of signal values that need to be filtered.

• method (str, optional) – The method of filtering. Options are ‘tw’, ‘chirp’, ‘all’, or ‘none’. Defaults to ‘tw’.

Returns:

A NumPy array representing the filtered signal.

Returns None if an invalid method is selected.

Return type:

Optional[np.ndarray]

Raises:

IndexError – If the time list does not contain values less than or equal to t_w.

static moduli_owchirp_strain_controlled(strain: ndarray, stress: ndarray, fs: float, om1: float, om2: float) → Tuple[ndarray, ...]

Computes the elastic modulus (G’), loss modulus (G’’), and complex modulus from strain and stress in the time domain. The Fourier Transform is applied to the strain and stress, and the results are filtered between frequencies om1 and om2.

Note

This code is adapted from the MITOWCh MATLAB code by Alessandro Perego (aperego@mmm.com), with specific Python replacements for MATLAB functions like padarray, pow2, nextpow2, and isrow.

Parameters:

• strain (np.ndarray) – The strain data as a NumPy array.

• stress (np.ndarray) – The stress data as a NumPy array.

• fs (float) – The sampling frequency.

• om1 (float) – The lower angular frequency bound.

• om2 (float) – The upper angular frequency bound.

Returns:

A tuple containing:

• frequency (np.ndarray): The frequency array.

• strain_final (np.ndarray): The corrected strain array.

• stress_final (np.ndarray): The corrected stress array.

• elastic_modulus_final (np.ndarray): The elastic modulus array (G’).

• loss_modulus_final (np.ndarray): The loss modulus array (G’’).

• complex_modulus (np.ndarray): The complex modulus array.

Return type:

Tuple[np.ndarray, …]

static moduli_owchirp_stress_controlled(strain_rate: ndarray, stress: ndarray, fs: float, om1: float, om2: float) → Tuple[ndarray, ...]

Computes the elastic modulus (G’), loss modulus (G’’), and complex modulus from strain and stress in the time domain. The Fourier Transform is applied to the strain rate and stress, and the results are filtered between frequencies om1 and om2.

Note

This code is adapted from the MITOWCh MATLAB code by Alessandro Perego (aperego@mmm.com), with specific Python replacements for MATLAB functions like padarray, pow2, nextpow2, and isrow.

Important

For stress-controlled instruments, it’s preferable to use strain rate instead of strain for calculating the moduli due to the inertia of the instrument. However, the current implementation does not perform inertia correction, and users should be aware of potential bias in the results.

Parameters:

• strain_rate (np.ndarray) – The strain rate data as a NumPy array.

• stress (np.ndarray) – The stress data as a NumPy array.

• fs (float) – The sampling frequency.

• om1 (float) – The lower angular frequency bound.

• om2 (float) – The upper angular frequency bound.

Returns:

A tuple containing:

• frequency (np.ndarray): The frequency array.

• strain_final (np.ndarray): The corrected strain array.

• stress_final (np.ndarray): The corrected stress array.

• elastic_modulus_final (np.ndarray): The elastic modulus array (G’).

• loss_modulus_final (np.ndarray): The loss modulus array (G’’).

• complex_modulus (np.ndarray): The complex modulus array.

Return type:

Tuple[np.ndarray, …]

np = <module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/hermes-rheo/envs/latest/lib/python3.10/site-packages/numpy/__init__.py'>

static prepare_owchirp_data(dataset: <module 'piblin.data.datasets.abc.split_datasets.one_dimensional_composite_dataset' from '/home/docs/checkouts/readthedocs.org/user_builds/hermes-rheo/envs/latest/lib/python3.10/site-packages/piblin/data/datasets/abc/split_datasets/one_dimensional_composite_dataset.py'>, time: str, strain: str, stress: str, temperature: str, cutoff_points: float) → Tuple[ndarray, ndarray, ndarray, ndarray]

Prepares and processes Arbitrary Wave (e.g. chirp) data by switching coordinates and adjusting the units of stress and strain for Fast Fourier Transform (FFT) analysis. It also discards data before a specified cutoff time.

Parameters:

• dataset (one_d_composite_dataset) – The dataset to process containing time, strain, stress, and temperature data.

• time (str) – The name of the time coordinate in the dataset.

• strain (str) – The name of the strain coordinate in the dataset.

• stress (str) – The name of the stress coordinate in the dataset.

• temperature (str) – The name of the temperature coordinate in the dataset.

• cutoff_points (float) – Time (in seconds) to discard data before the cutoff.

Returns:

A tuple containing the processed arrays:

• time values (np.ndarray): The time values starting from the cutoff point onward.

• strain values (np.ndarray): The corresponding strain values, converted to unitless if originally in %.

• stress values (np.ndarray): The corresponding stress values, converted to Pa if originally in MPa.

• temperature values (np.ndarray): The temperature values starting from the cutoff point.

Return type:

Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]

Raises:

ValueError –

• If cutoff_points is greater than the maximum value of the dataset time values. - If strain_values are not set after switching coordinates to strain. - If stress_values are not set after switching coordinates to stress. - If an unsupported unit is found in the stress values.

select_best_filter_method(t_w: float, time: List[float], signal: List[float]) → Tuple[ndarray, str]

Iterates over different filtering methods, applies each to the signal, and evaluates the corrected signal. The best filtering method is selected based on the lowest sum of absolute values of the corrected signal, indicating the most symmetrical signal around zero.

Parameters:

• t_w (float) – The time threshold used for filtering.

• time (List[float]) – A list of time values corresponding to the signal.

• signal (List[float]) – A list of signal values to be filtered.

Returns:

A tuple containing the best corrected signal as a NumPy array

and the name of the best method as a string.

Return type:

Tuple[np.ndarray, str]

select_best_filter_method_DMA(t_w: float, time: List[float], signal: List[float]) → Tuple[ndarray, str]

Iterates over different filtering methods and selects the best one for DMA instruments. The method with the best metric, calculated by combining the average of the start and end signal values and the standard deviation, is selected to correct the bias in the signal.

Note: For DMA (Dynamic Mechanical Analysis) instruments, a slightly different algorithm was implemented to correct bias. In this method, we focus on minimizing bias by combining two metrics: 1. The average of the absolute values of the corrected signal at the start and end. 2. The standard deviation of the corrected signal across the entire time range. The method with the smallest combined metric is considered the best.

Parameters:

• t_w (float) – The time threshold used for filtering.

• time (List[float]) – A list of time values corresponding to the signal.

• signal (List[float]) – A list of signal values to be filtered.

Returns:

A tuple containing the best corrected signal as a NumPy array

and the name of the best method as a string.

Return type:

Tuple[np.ndarray, str]

Automated Mastercurve

Mutation Number

class hermes_rheo.transforms.mutation_number.MutationNumber(state='time', state_sampling='first point', dependent_variable='complex modulus', *args, **kwargs)

Bases: MeasurementSetTransform

A transform class to calculate and visualize the mutation number from measurement sets.

Args:

statestr

The state variable to be used (default is ‘time’).

state_samplingstr

The method to determine the state value (‘average’, ‘first point’, ‘last point’).

dependent_variablestr

The dependent variable to be used for mutation number calculation (default is ‘complex modulus’).

Methods:

_state_to_condition(self, target):

Computes the specified state’s value using the defined method and adds it as a condition in the dataset.

_apply(self, target, **kwargs):

Applies the mutation number calculation to the dataset and returns a MutationNumberMeasurementSet object.

OWChirp Design

class hermes_rheo.transforms.owchirp_generation.OWChirpGeneration(output_file_name: str, waiting_time: float, signal_duration: float, strain_amplitude: float, initial_frequency: float, final_frequency: float, tapering_parameter: float, initial_phase_shift: float)

Bases: object

Class to generate and visualize an Optimal Window Chirp (OWChirp) signal.

output_file_name

The name of the file to save the signal data.

Type:

str

waiting_time

The waiting time in seconds.

Type:

float

signal_duration

The chirp signal length in seconds.

Type:

float

strain_amplitude

The strain amplitude as a percentage.

Type:

float

initial_frequency

The initial frequency in rad/s.

Type:

float

final_frequency

The final frequency in rad/s.

Type:

float

tapering_parameter

The tapering parameter as a percentage.

Type:

float

initial_phase_shift

The initial phase angle in degrees.

Type:

float

print_parameters()

Print the parameters and equations for the chirp signal.

to_txt(filepath)

Save the parameters and equations to a text file in the specified folder.

visualize(display_r0=False, filepath=None)

Plot the chirp waveform and save data and plot to user-specified folder.

States to Conditions

class hermes_rheo.transforms.states_to_conditions.StatesToConditions(state: str = 'temperature', method: str = 'average', *args, **kwargs)

Bases: MeasurementTransform