data analysis package

time series

towbintools.data_analysis.time_series.aggregate_interpolated_series(all_points_interpolated_series: ndarray, all_points_interpolated_time: ndarray, larval_stage_durations: ndarray, aggregation: str = 'mean') → tuple[ndarray, ndarray, ndarray, ndarray]

Aggregates the interpolated series and time information.

Parameters:

• all_points_interpolated_series (np.ndarray) – Array of shape (nb_of_worms / points, 4, n_points) containing the interpolated series.

• all_points_interpolated_time (np.ndarray) – Array of shape (nb_of_worms / points, 4, n_points) containing the interpolated time information.

• larval_stage_durations (np.ndarray) – Array of shape (nb_of_worms / points, 4) containing the larval stage durations.

• aggregation (str) – Aggregation method to use. Can be ‘mean’ or ‘median’.

Returns:

Array of shape (4*n_points) containing the rescaled time information. aggregated_series (np.ndarray) : Array of shape (4*n_points) containing the aggregated series. std_series (np.ndarray) : Array of shape (4*n_points) containing the standard deviation of the series. ste_series (np.ndarray) : Array of shape (4*n_points) containing the standard error of the series.

Return type:

rescaled_time (np.ndarray)

towbintools.data_analysis.time_series.compute_exponential_series_at_time_classified(series: ndarray, time: ndarray, qc: ndarray, fit_width: int = 10) → ndarray

Evaluate a time series at given time indices using exponential (log-linear) regression.

For each requested time index, fits a linear regression to the log-transformed series within a window of fit_width points on each side, using only points classified as "worm". Returns the back-transformed (exponential) predicted value at each requested time.

Parameters:

• series (np.ndarray) – 1D array of measured values (e.g. volume).

• time (np.ndarray) – 1D array of time indices at which to evaluate the series.

• qc (np.ndarray) – Classification array with values "worm", "egg", or "error"; only "worm" points are used for fitting.

• fit_width (int, optional) – Half-width of the fitting window around each requested time index. (default: 10)

Returns:

Predicted series values at each element of time. NaN is

returned for time indices that are non-finite or where no "worm" points fall within the fitting window.

Return type:

np.ndarray

towbintools.data_analysis.time_series.compute_series_at_time_classified(series: ndarray, time: ndarray, series_time: ndarray | None, qc: ndarray, lmbda: float = 0.0075, medfilt_window: int = 5, bspline_order: int = 3) → ndarray

Evaluate a time series at arbitrary time points after smoothing and classification-based masking.

Non-worm points are masked and interpolated, then the series is smoothed with a median filter and Whittaker-Eilers smoothing, and finally evaluated at the requested time values using a b-spline interpolant.

Parameters:

• series (np.ndarray) – 1D array of measured values.

• time (np.ndarray) – Time points at which the smoothed series is to be evaluated.

• series_time (np.ndarray) – 1D array of time points corresponding to series. Pass None to use integer indices.

• qc (np.ndarray) – Classification array with values "worm", "egg", or "error"; non-worm points are masked before smoothing.

• lmbda (float, optional) – Smoothing parameter for the Whittaker-Eilers smoother. (default: 0.0075)

• medfilt_window (int, optional) – Kernel size for the median filter. (default: 5)

• bspline_order (int, optional) – The order of the b-spline interpolation. (default: 3)

Returns:

The series at the given time(s).

Return type:

np.ndarray

towbintools.data_analysis.time_series.correct_series_with_classification(series: ndarray, qc: ndarray) → ndarray

Remove the points of non-worms from the time series and interpolate them back.

Parameters:

• series (np.ndarray) – The time series of values.

• qc (np.ndarray) – The classification of the points as either ‘worm’ or ‘egg’ or ‘error’.

Returns:

The corrected time series.

Return type:

np.ndarray

towbintools.data_analysis.time_series.crop_series_to_length(series: ndarray, new_length: int) → ndarray

Crop a 1D or 2D series to a new length.

Parameters:

• series (np.ndarray) – The time series to crop.

• new_length (int) – The desired length of the cropped series.

Returns:

The cropped series of the specified length.

Return type:

np.ndarray

Raises:

ValueError – If the input series is not 1D or 2D.

towbintools.data_analysis.time_series.filter_series_with_classification(series: ndarray, qc: ndarray) → ndarray

Remove the points of non-worms from the time series.

Parameters:

• series (np.ndarray) – The time series of values.

• qc (np.ndarray) – The classification of the points as either ‘worm’ or ‘egg’ or ‘error’.

Returns:

The filtered time series.

Return type:

np.ndarray

towbintools.data_analysis.time_series.interpolate_entire_development(series: ndarray, time: ndarray, ecdysis: ndarray, qc: ndarray | None = None, n_points: int = 100) → tuple[ndarray, ndarray]

Interpolate a time series over all four larval stages.

Calls interpolate_larval_stage() for each stage and stacks the results.

Parameters:

• series (np.ndarray) – 1D array of measured values.

• time (np.ndarray) – 1D array of time points corresponding to series.

• ecdysis (array-like) – 5-element sequence [hatch_time, M1, M2, M3, M4] of ecdysis indices.

• qc (np.ndarray, optional) – Classification array with values "worm", "egg", or "error"; non-worm points are masked before interpolation. (default: None)

• n_points (int, optional) – Number of evenly-spaced output points per stage. (default: 100)

Returns:

(interpolated_time, interpolated_series)

both of shape (4, n_points). Rows correspond to larval stages L1–L4; stages with invalid ecdysis events are filled with NaN.

Return type:

tuple[np.ndarray, np.ndarray]

towbintools.data_analysis.time_series.interpolate_larval_stage(series: ndarray, time: ndarray, ecdysis: ndarray, larval_stage: int, qc: ndarray | None = None, n_points: int = 100) → tuple[ndarray, ndarray]

Interpolate a time series over a single larval stage to a fixed number of points.

Uses a linear b-spline to resample the series between the ecdysis events bounding the requested larval stage. Non-worm time points are excluded when qc is provided.

Parameters:

• series (np.ndarray) – 1D array of measured values.

• time (np.ndarray) – 1D array of time points corresponding to series.

• ecdysis (array-like) – 5-element sequence [hatch_time, M1, M2, M3, M4] of ecdysis indices.

• larval_stage (int) – Larval stage to interpolate (1–4).

• qc (np.ndarray, optional) – Classification array with values "worm", "egg", or "error"; non-worm points are masked before interpolation. (default: None)

• n_points (int, optional) – Number of evenly-spaced output points. (default: 100)

Returns:

(interpolated_time, interpolated_series)

each of length n_points. Both arrays are filled with NaN when the bounding ecdysis events are invalid.

Return type:

tuple[np.ndarray, np.ndarray]

Raises:

ValueError – If larval_stage is not in the range [1, 4].

towbintools.data_analysis.time_series.pad_series_to_length(series: ndarray, new_length: int, pad_value: float = 0) → ndarray

Pad a 1D or 2D series to a new length with a specified pad value.

Parameters:

• series (np.ndarray) – The time series to pad.

• new_length (int) – The desired length of the padded series.

• pad_value (int, optional) – The value to use for padding. Default is 0

Returns:

The padded series of the specified length.

Return type:

np.ndarray

Raises:

ValueError – If the input series is not 1D or 2D.

towbintools.data_analysis.time_series.random_crop_series_to_length(series: ndarray, new_length: int) → ndarray

Randomly crop a 1D or 2D series to a new length.

Parameters:

• series (np.ndarray) – The time series to crop.

• new_length (int) – The desired length of the cropped series.

Returns:

The cropped series of the specified length.

Return type:

np.ndarray

Raises:

ValueError – If the input series is not 1D or 2D.

towbintools.data_analysis.time_series.rescale_and_aggregate(series: ndarray, time: ndarray, ecdysis: ndarray, larval_stage_durations: ndarray, qc: ndarray, points: list[int] | None = None, aggregation: str = 'mean', n_points: int = 100) → tuple[ndarray, ndarray, ndarray, ndarray]

Rescales and aggregates the series and time information.

Parameters:

• series (np.ndarray) – Array of shape (nb_of_worms, length of series) containing the series to interpolate.

• time (np.ndarray) – Array of shape (nb_of_worms, length of series) containing the time information.

• ecdysis (np.ndarray) – Array of shape (nb_of_worms, 5) containing the ecdysis times.

• qc (np.ndarray) – Array of shape (nb_of_worms, length of series) containing the worm type classification

• points (list) – List of points to consider for the interpolation. If None, all points are considered.

• aggregation (str) – Aggregation method to use. Can be ‘mean’ or ‘median’.

• n_points (int) – Number of points to interpolate the series to.

Returns:

Array of shape (4*n_points) containing the rescaled time information. aggregated_series (np.ndarray) : Array of shape (4*n_points) containing the aggregated series. std_series (np.ndarray) : Array of shape (4*n_points) containing the standard deviation of the series. ste_series (np.ndarray) : Array of shape (4*n_points) containing the standard error of the series.

Return type:

rescaled_time (np.ndarray)

towbintools.data_analysis.time_series.rescale_series(series: ndarray, time: ndarray, ecdysis: ndarray, qc: ndarray, points: list[int] | None = None, n_points: int = 100) → tuple[ndarray, ndarray]

Interpolates one or multiple series and the time to have n_points points in total per larval stages.

Parameters:

• series (np.ndarray) – Array of shape (nb_of_worms / points, length of series) containing the series to interpolate.

• time (np.ndarray) – Array of shape (nb_of_worms / points, length of series) containing the time information.

• ecdysis (np.ndarray) – Array of shape (nb_of_worms / points, 5) containing the ecdysis times.

• qc (np.ndarray) – Array of shape (nb_of_worms / points, length of series) containing the worm type classification

• points (list) – List of points to consider for the interpolation. If None, all points are considered.

• n_points (int) – Number of points to interpolate the series to.

Returns:

Array of shape (nb_of_worms / points, 4, n_points) containing the interpolated time information. all_points_interpolated_series (np.ndarray) : Array of shape (nb_of_worms / points, 4, n_points) containing the interpolated series.

Return type:

all_points_interpolated_time (np.ndarray)

towbintools.data_analysis.time_series.resize_series_to_length(series: ndarray, new_length: int, kind: str = 'linear') → ndarray

Resize a 1D or 2D series to a new length using interpolation.

Parameters:

• series (np.ndarray) – The time series to resize.

• new_length (int) – The desired length of the resized series.

• kind (str, optional) – The type of interpolation to use. (default: “linear”)

Returns:

The resized series of the specified length.

Return type:

np.ndarray

Raises:

ValueError – If the input series is not 1D or 2D.

towbintools.data_analysis.time_series.smooth_series(series: ndarray, series_time: ndarray | None, lmbda: float = 0.0075, order: int = 2, medfilt_window: int = 5) → ndarray

Smooth a time series without classification-based masking.

Applies a median filter followed by Whittaker-Eilers smoothing. Unlike smooth_series_classified(), non-worm points are not masked first.

Parameters:

• series (np.ndarray) – 1D array of measured values.

• series_time (np.ndarray) – 1D array of time points corresponding to series. Pass None to use integer indices.

• lmbda (float, optional) – Smoothing parameter for the Whittaker-Eilers smoother. (default: 0.0075)

• order (int, optional) – Penalty order for the Whittaker-Eilers smoother. (default: 2)

• medfilt_window (int, optional) – Kernel size for the median filter applied before Whittaker-Eilers smoothing. (default: 5)

Returns:

Smoothed series of the same length as series. Returns an

all-NaN array when all input values are NaN.

Return type:

np.ndarray

towbintools.data_analysis.time_series.smooth_series_classified(series: ndarray, series_time: ndarray | None, qc: ndarray, lmbda: float = 0.0075, order: int = 2, medfilt_window: int = 5) → ndarray

Smooth a time series after masking non-worm points.

Non-worm points (according to qc) are replaced by interpolated values, then a median filter is applied followed by Whittaker-Eilers smoothing.

Parameters:

• series (np.ndarray) – 1D array of measured values.

• series_time (np.ndarray) – 1D array of time points corresponding to series. Pass None to use integer indices.

• qc (np.ndarray) – Classification array with values "worm", "egg", or "error"; non-worm points are interpolated before smoothing.

• lmbda (float, optional) – Smoothing parameter for the Whittaker-Eilers smoother. (default: 0.0075)

• order (int, optional) – Penalty order for the Whittaker-Eilers smoother. (default: 2)

• medfilt_window (int, optional) – Kernel size for the median filter applied before Whittaker-Eilers smoothing. (default: 5)

Returns:

Smoothed series of the same length as series. Returns an

all-NaN array when all input values are NaN.

Return type:

np.ndarray

growth rate

towbintools.data_analysis.growth_rate.compute_growth_rate_classified(series: ndarray, time: ndarray, qc: ndarray, method: str = 'exponential', ignore_start_fraction: float = 0.0, ignore_end_fraction: float = 0.0, savgol_filter_window: int = 5, savgol_filter_order: int = 3) → float

Compute the growth rate of a time series after correcting non-worm timepoints.

Non-worm points (classified as "egg" or "error") are removed and interpolated before fitting.

Parameters:

• series (np.ndarray) – The time series of values.

• time (np.ndarray) – The time data corresponding to the series.

• qc (np.ndarray) – Per-point classification ("worm", "egg", or "error").

• method (str, optional) – Regression method; "exponential" or "linear". (default: "exponential")

• ignore_start_fraction (float, optional) – Fraction of points to ignore at the start. (default: 0.0)

• ignore_end_fraction (float, optional) – Fraction of points to ignore at the end. (default: 0.0)

• savgol_filter_window (int, optional) – Window size of the Savitzky-Golay filter. (default: 5)

• savgol_filter_order (int, optional) – Polynomial order of the Savitzky-Golay filter. (default: 3)

Returns:

The growth rate of the time series.

Return type:

float

towbintools.data_analysis.growth_rate.compute_growth_rate_exponential(series: ndarray, time: ndarray, ignore_start_fraction: float = 0.0, ignore_end_fraction: float = 0.0, savgol_filter_window: int = 5, savgol_filter_order: int = 3) → float

Compute the growth rate of a time series using exponential regression.

Parameters:

• series (np.ndarray) – The series of values to compute the growth rate of.

• time (np.ndarray) – The time data corresponding to the series.

• ignore_start_fraction (float, optional) – Fraction of points to ignore at the start. (default: 0.0)

• ignore_end_fraction (float, optional) – Fraction of points to ignore at the end. (default: 0.0)

• savgol_filter_window (int, optional) – Window size of the Savitzky-Golay filter. (default: 5)

• savgol_filter_order (int, optional) – Polynomial order of the Savitzky-Golay filter. (default: 3)

Returns:

The exponential growth rate of the time series.

Return type:

float

towbintools.data_analysis.growth_rate.compute_growth_rate_linear(series: ndarray, time: ndarray, ignore_start_fraction: float = 0.0, ignore_end_fraction: float = 0.0, savgol_filter_window: int = 5, savgol_filter_order: int = 3) → float

Compute the growth rate of a time series using linear regression.

Parameters:

• series (np.ndarray) – The series of values to compute the growth rate of.

• time (np.ndarray) – The time data corresponding to the series.

• ignore_start_fraction (float, optional) – Fraction of points to ignore at the start. (default: 0.0)

• ignore_end_fraction (float, optional) – Fraction of points to ignore at the end. (default: 0.0)

• savgol_filter_window (int, optional) – Window size of the Savitzky-Golay filter. (default: 5)

• savgol_filter_order (int, optional) – Polynomial order of the Savitzky-Golay filter. (default: 3)

Returns:

The linear growth rate of the time series.

Return type:

float

towbintools.data_analysis.growth_rate.compute_growth_rate_per_larval_stage(series: ndarray, time: ndarray, qc: ndarray, ecdysis: dict, method: str = 'exponential', ignore_start_fraction: float = 0.0, ignore_end_fraction: float = 0.0, savgol_filter_window: int = 5, savgol_filter_order: int = 3) → dict

Compute the growth rate of a time series for each larval stage.

Non-worm timepoints are removed and interpolated before fitting. Growth rates are computed for L1–L4 using the ecdysis boundary indices.

Parameters:

• series (np.ndarray) – The time series of values.

• time (np.ndarray) – The time data corresponding to the series.

• qc (np.ndarray) – Per-point classification ("worm", "egg", or "error").

• ecdysis (dict) – Ecdysis boundary dict with keys "HatchTime", "M1", "M2", "M3", "M4" as integer indices.

• method (str, optional) – Regression method; "exponential" or "linear". (default: "exponential")

• ignore_start_fraction (float, optional) – Fraction of points to ignore at the start of each stage. (default: 0.0)

• ignore_end_fraction (float, optional) – Fraction of points to ignore at the end of each stage. (default: 0.0)

• savgol_filter_window (int, optional) – Window size of the Savitzky-Golay filter. (default: 5)

• savgol_filter_order (int, optional) – Polynomial order of the Savitzky-Golay filter. (default: 3)

Returns:

Growth rate for each larval stage, keyed "L1"–"L4".

Stages with NaN ecdysis boundaries return np.nan.

Return type:

dict

towbintools.data_analysis.growth_rate.compute_instantaneous_growth_rate(series: ndarray, time: ndarray, lmbda: float = 0.0075, order: int = 2, medfilt_window: int = 5) → ndarray

Compute the instantaneous growth rate of a time series.

Parameters:

• series (np.ndarray) – The series of values to compute the growth rate of.

• time (np.ndarray) – The time data corresponding to the series.

• lmbda (float, optional) – The smoothing parameter for the Whittaker-Eilers smoothing. Default provides good results for our volume curves when series_time is in hours. (default: 0.0075)

• order (int, optional) – The order of the penalty of the Whittaker-Eilers smoother. (default: 2)

• medfilt_window (int, optional) – The window size for the median filter. (default: 5)

Returns:

The instantaneous growth rate of the time series.

Return type:

np.ndarray

towbintools.data_analysis.growth_rate.compute_instantaneous_growth_rate_classified(series: ndarray, time: ndarray, qc: ndarray, lmbda: float = 0.0075, order: int = 2, medfilt_window: int = 5) → ndarray

Compute the instantaneous growth rate of a time series after correcting the non-worm points by removing them and interpolating them back.

Parameters:

• series (np.ndarray) – The time series of values.

• time (np.ndarray) – The time data corresponding to the series.

• qc (np.ndarray) – The classification of the points as either ‘worm’ or ‘egg’ or ‘error’.

• lmbda (float, optional) – The smoothing parameter for the Whittaker-Eilers smoothing. Default provides good results for our volume curves when series_time is in hours. (default: 0.0075)

• order (int, optional) – The order of the penalty of the Whittaker-Eilers smoother. (default: 2)

• medfilt_window (int, optional) – The window size for the median filter. (default: 5)

Returns:

The instantaneous growth rate of the time series.

Return type:

np.ndarray

towbintools.data_analysis.growth_rate.compute_larval_stage_duration(ecdysis: dict) → dict

Compute the duration of each larval stage.

Parameters:

ecdysis (dict) – The ecdysis events of the worm.

Returns:

The duration of each larval stage.

Return type:

dict