Scale a recording¶

Question¶

How does this trace look on a declared common scale?

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

When to use¶

Use this when traces need a declared common value scale.

Example figure¶

Scale a recording output generated by Circadian Workbench

This deterministic example is calculated by the normalize action and drawn by render_normalize_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("normalize", 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("normalize", recording, config=None, normalization_method='minmax', target_min=-1.0, target_max=1.0, reference_value=None, reference_start_hours=None, reference_end_hours=None, reference_statistic='mean', standard_deviation_ddof=0, detrended=False, envelope_floor_fraction=0.1)

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.
`normalization_method`	string	no	`"minmax"`	-	Transformation to apply. Canonical choices are none, mean_center, median_center, zscore, robust_zscore, robust_scale, own_mean, own_daily_total, minmax, max_abs, reference_delta, fold_change, delta_over_reference, log2_fold_change, percent_of_reference, percent_change, envelope and pre_treatment_cycle. Aliases include range for minmax, extreme or to_extreme for max_abs, z for zscore, dff for delta_over_reference, and fold for fold_change.
`target_min`	float	no	`-1.0`	normalised units	Lower output bound for minmax range scaling; ignored by other methods.
`target_max`	float	no	`1.0`	normalised units	Upper output bound for minmax range scaling; must exceed target_min.
`reference_value`	float	no	`null`	recording units	Explicit baseline for reference_delta, fold_change, delta_over_reference, log2_fold_change, percent_of_reference, percent_change or pre_treatment_cycle. Use this or a reference time window, never both.
`reference_start_hours`	float	no	`null`	hours	Inclusive start of the baseline window, in hours from the selected recording start. Must be paired with reference_end_hours.
`reference_end_hours`	float	no	`null`	hours	Inclusive end of the baseline window used to calculate the reference. Must exceed and be paired with reference_start_hours.
`reference_statistic`	string	no	`"mean"`	-	How a reference time window is reduced: mean or median.
`standard_deviation_ddof`	integer	no	`0`	-	Degrees of freedom removed from the z-score standard-deviation divisor: 0 for a population, 1 for a sample.
`detrended`	boolean	no	`false`	-	Whether inputs are already baseline-subtracted.
`envelope_floor_fraction`	float	no	`0.1`	fraction	For envelope normalisation, return missing values after the fitted oscillation envelope falls below this fraction of its starting amplitude. Must lie from 0 inclusive to 1 exclusive.

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

How it works¶

Values are transformed by the selected normalization rule and its recorded denominator or range.

$$ y_{\mathrm{scaled}}=N(y;\theta) $$

Implementation: analysis.py::normalize.

Outputs and interpretation¶

The result contains scaled values, scaling parameters and the processed trace.

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¶

Scaling changes amplitude units and does not repair missing data or poor measurement quality.

Example¶

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

Methods text¶

The trace was scaled with the declared normalization method and parameters.