Remove a slow trend¶

Question¶

What rhythm remains after removing the baseline drift?

See every package-generated example · Read the complete analysis pipeline

When to use¶

Use this when slow baseline drift interferes with circadian interpretation.

Example figure¶

Remove a slow trend output generated by Circadian Workbench

This deterministic example is calculated by the detrend action and drawn by render_detrend_svg, the same renderer used for publication export. Empty or withheld elements are therefore visible exactly as they are in a real result.

import circadian_workbench as cw

cw.call("detrend", recording={"path": "mouse01.awd"})

Required inputs and controls¶

The public function is the registered action below. settings= is accepted as a friendlier alias for config= by cw.call; the calculation stores the complete normalized config in provenance.

Function reference¶

cw.call("detrend", recording, config=None, detrend_method='running_mean', window_hours=24.0, polynomial_degree=3, min_valid_fraction=0.5, bandwidth_hours=None, low_cut_hours=45.0, high_cut_hours=4.0, filter_order=2, lowess_fraction=None, lowess_iterations=3, asls_smoothness=1000000.0, asls_asymmetry=0.01, asls_iterations=10, smooth_window_hours=0.0, exclude_hours=None)

Arguments and parameters¶

Name	Type	Required	Default	Units	Meaning
`recording`	recording spec	yes	—	-	The record to analyse: {'path': 'data/m01.awd'} (a bare path string also works), {'demo': true} for the built-in deterministic record, {'inline': {'filename': ..., 'text': ...}} for tabular text, {'trace': {'hours': [...], 'values': [...], 'name': ...}} for one elapsed-time trace, or {'channels': {'hours': [...], 'values': {'reporter_a': [...], 'reporter_b': [...]}}} for several measurements from one subject. A returned processed_trace spec retains transformed values, their original clock, source identity and explicit processing history. Versioned recording_snapshot specs are self-contained numeric inputs for replaying in-memory Recording objects; they do not invoke a raw-activity importer.
`config`	object	no	`null`	-	Partial scientific settings. Omitted or None values use the shared installed defaults; invalid fresh values are rejected. Run describe_config for names, meanings, units, bounds and choices. Explicitly load old saved mappings with load_saved_settings to report compatibility conversions.
`detrend_method`	string	no	`"running_mean"`	-	Baseline removal method: none, linear, robust_linear/Huber, first_difference, running_mean, moving_median, lowess/loess, savitzky_golay, polynomial (including cubic/bicubic and poly6), kernel/baseline, amp_baseline, asymmetric_least_squares/asls, hodrick_prescott/HP, or frequency.
`window_hours`	float	no	`24.0`	hours	Baseline window.
`polynomial_degree`	integer	no	`3`	count	Polynomial baseline degree; poly6/degree6 force 6 and cubic/poly3/bicubic force 3.
`min_valid_fraction`	float	no	`0.5`	dimensionless	Minimum finite share of a local smoothing window.
`bandwidth_hours`	float	no	`null`	hours	Gaussian kernel standard deviation; omitted uses one quarter of window_hours.
`low_cut_hours`	float	no	`45.0`	hours	Longest period retained by frequency detrending.
`high_cut_hours`	float	no	`4.0`	hours	Shortest period retained by frequency detrending.
`filter_order`	integer	no	`2`	count	Butterworth frequency-filter order.
`lowess_fraction`	float	no	`null`	dimensionless	Fraction of finite samples in each LOWESS local fit; omitted derives it from window_hours.
`lowess_iterations`	integer	no	`3`	count	LOWESS robust residual-reweighting passes after the initial local fit; 0 disables reweighting.
`asls_smoothness`	float	no	`1000000.0`	dimensionless	Positive second-difference penalty for asymmetric least squares; larger is smoother.
`asls_asymmetry`	float	no	`0.01`	dimensionless	Weight in (0, 0.5) for points above the asymmetric baseline; smaller excludes positive peaks more strongly.
`asls_iterations`	integer	no	`10`	count	Asymmetric least-squares reweighting passes, from 1 to 100.
`smooth_window_hours`	float	no	`0.0`	hours	Centred smoothing window; zero disables smoothing.
`exclude_hours`	float	no	`null`	hours	Leading hours to discard before fitting.

Every nested config key, default, allowed value, and purpose is listed in the complete configuration reference.

How it works¶

The declared baseline estimator is subtracted from the sampled trace.

$$ y_{\mathrm{detrended}}=y-b(t) $$

Implementation: analysis.py::detrend.

Outputs and interpretation¶

The result includes original values, estimated baseline, detrended values and fit details.

cw.call returns a Result: use .data for calculated values, .warnings for scientific qualifications, .provenance for version and input identity, .script for an equivalent replay script, and .files for saved outputs.

Limitations¶

Window and edge choices change the resulting trace; inspect the original alongside the processed signal.

Example¶

The figure above is a real package result from a seeded, redistributable synthetic dataset. The flat gallery bundle retains figure_data_detrend.csv, a standalone plot_detrend.py, source hashes, an editable SVG, and a rendered preview.

Methods text¶

The declared baseline estimator was applied and its estimate subtracted from the trace.