goldpan.quantities

Derived quantities: pulses in, one real number (or one array) per pulse out.

Every function here takes an array shaped (..., n_samples) – a single pulse (n_samples,) or a batch (n_pulses, n_samples) both work unchanged, since all reductions run along axis=-1. Output shape is one dimension smaller ((...,)) for scalar-per-pulse quantities, or (..., n_freq) for spectra.

These are the primitives: cuts in goldpan.cuts are built by thresholding the quantities defined here.

Functions

bline(pulses, config[, n_samples])

Baseline level ("bline"): mean of the first n_samples samples (default 500), skipping config.glitch_samples leading samples.

bline_1000(pulses, config)

bline over the first 1000 samples (skipping config.glitch_samples).

bstd(pulses, config[, n_samples])

Baseline scatter ("bstd"): std of the first n_samples samples (default 500), skipping config.glitch_samples leading samples.

bstd_1000(pulses, config)

bstd over the first 1000 samples (skipping config.glitch_samples): the baseline scatter of the 1000-sample window used by Branch 1 of 07221203_2025_dump1_noise.ipynb.

excursion_duration(pulses, config[, fraction])

excursion_ratio(pulses, config)

max_deviation / pretrigger_std ("ratio" in the notebooks).

frequencies_hz(n_samples, config)

Frequency bins (Hz) matching power_spectrum's / np.fft.rfft's output for a pulse of length n_samples.

half_max_time_us(pulses, config)

log_excursion_ratio(pulses, config)

log10(excursion_ratio) -- the quantity actually thresholded by the notebooks' Branch 2 exploration (07221203_2025_dump1_noise.ipynb), since the ratio's dynamic range spans orders of magnitude between the contaminated and quiet populations.

max_deviation(pulses, config)

Largest absolute deviation of a post-pretrigger sample from the pretrigger mean, per pulse ("dev" in the notebooks).

power_spectrum(pulses, config)

Real part of rfft(pulse) * conj(rfft(pulse)) (the squared magnitude of the FFT, "complex square") per pulse.

pretrigger_mean(pulses, config)

Mean of the pretrigger window, skipping config.glitch_samples leading samples.

pretrigger_std(pulses, config)

Std of the pretrigger window, skipping config.glitch_samples leading samples.

rise_sample(pulses, config[, fraction])

goldpan.quantities.pretrigger_mean(pulses, config)[source]

Mean of the pretrigger window, skipping config.glitch_samples leading samples.

Parameters:

config (PulseConfig)

goldpan.quantities.pretrigger_std(pulses, config)[source]

Std of the pretrigger window, skipping config.glitch_samples leading samples.

Parameters:

config (PulseConfig)

goldpan.quantities.bstd(pulses, config, n_samples=500)[source]

Baseline scatter (“bstd”): std of the first n_samples samples (default 500), skipping config.glitch_samples leading samples.

Unlike pretrigger_std, the window is set by n_samples, not by config.pretrigger_samples, so it is the same 500-sample quantity whatever config is passed (only glitch_samples is read from it). It matches the “bstd” of the Branch 2 cuts in 07221203_2025_dump1_noise.ipynb. For the 1000-sample window use bstd_1000.

Parameters:
goldpan.quantities.bstd_1000(pulses, config)[source]

bstd over the first 1000 samples (skipping config.glitch_samples): the baseline scatter of the 1000-sample window used by Branch 1 of 07221203_2025_dump1_noise.ipynb.

Parameters:

config (PulseConfig)

goldpan.quantities.bline(pulses, config, n_samples=500)[source]

Baseline level (“bline”): mean of the first n_samples samples (default 500), skipping config.glitch_samples leading samples. The companion of bstd.

Computed with pretrigger_mean on a copy of config whose window is n_samples, so the window is fixed by n_samples rather than by config.pretrigger_samples: it is the same 500-sample quantity whatever config is passed (only glitch_samples is read from it). For the 1000-sample window use bline_1000.

Parameters:
goldpan.quantities.bline_1000(pulses, config)[source]

bline over the first 1000 samples (skipping config.glitch_samples).

Parameters:

config (PulseConfig)

goldpan.quantities.max_deviation(pulses, config)[source]

Largest absolute deviation of a post-pretrigger sample from the pretrigger mean, per pulse (“dev” in the notebooks).

Measured only in the post-pretrigger region (samples pretrigger_samples:). Measuring it over the whole trace instead (including the samples used to compute the pretrigger mean) puts an artificial floor around excursion_ratio ~ 1 regardless of any threshold, by basic extreme-value statistics – see 07221203_2025_dump1_noise.ipynb for the full explanation.

Parameters:

config (PulseConfig)

goldpan.quantities.excursion_ratio(pulses, config)[source]

max_deviation / pretrigger_std (“ratio” in the notebooks).

For pure noise, extreme-value statistics put this around 3-8 (the max of ~3000 samples is expected to be several sigma out), not near 1 – traces that land near 1 usually have a contaminated (inflated) pretrigger std instead of being unusually quiet. See the “inverts the naive expectation” finding in 07221203_2025_dump1_noise.ipynb before using this as a “smaller = quieter” cut.

Parameters:

config (PulseConfig)

goldpan.quantities.log_excursion_ratio(pulses, config)[source]

log10(excursion_ratio) – the quantity actually thresholded by the notebooks’ Branch 2 exploration (07221203_2025_dump1_noise.ipynb), since the ratio’s dynamic range spans orders of magnitude between the contaminated and quiet populations.

Parameters:

config (PulseConfig)

goldpan.quantities.excursion_duration(pulses, config, fraction=0.5)[source]

Warning

Under development: devised specifically to tell a sustained real pulse (rises and stays elevated for many consecutive samples while it decays) apart from noise, for use by goldpan.cuts.looks_like_pulse / excursion_band_AI. Deliberately uses the longest contiguous run, not a total count – with ~2500 post-pretrigger samples, a plain count of samples above half-max is dominated by ordinary Gaussian tail hits (checked against real 07221203_2025_F0001 data: an early total-count version flagged every trace in the tight excursion_band as ‘pulse-like’). Not independently validated beyond that one check.

Longest run of consecutive post-pretrigger samples with |sample - pretrigger_mean| >= fraction * max_deviation – how long the trace stays near its own peak without dropping back down.

Parameters:
goldpan.quantities.rise_sample(pulses, config, fraction=0.5)[source]

Warning

Under development: fraction=0.5 half-max crossing heuristic; only validated on one exploratory analysis (07221203_2025_dump1_noise.ipynb’s Cut A rise-time check) – not yet checked against noisy/multi-peak traces

First post-pretrigger sample index (absolute, not relative to the window) where the pulse crosses fraction of its own max_deviation.

Guaranteed to find a crossing (the sample achieving the max deviation itself always satisfies >= fraction * max_deviation for fraction <= 1), so this never silently falls back to index 0 for “no crossing found”.

Parameters:
goldpan.quantities.half_max_time_us(pulses, config)[source]

Warning

Under development: built on rise_sample, which is still under development; meaningless for a trace with no pulse (it just finds the largest noise excursion)

Time (microseconds from the first sample of the trace) at which the pulse first reaches 50% of its own max_deviation: rise_sample(fraction=0.5) * sample_period_s.

Only samples after config.pretrigger_samples are searched, so the window must end before the pulse starts: with a 1000-sample window a pulse rising at sample 505 is not seen. Use replace(config, pretrigger_samples=500) for triggers near sample 500. Raises if config.sample_period_s is unset.

Parameters:

config (PulseConfig)

goldpan.quantities.power_spectrum(pulses, config)[source]

Real part of rfft(pulse) * conj(rfft(pulse)) (the squared magnitude of the FFT, “complex square”) per pulse.

Does not baseline-subtract for you – pass already-baseline-subtracted pulses (see goldpan.operations.baseline_subtract) or the DC bin will dominate every spectrum.

Parameters:

config (PulseConfig)

goldpan.quantities.frequencies_hz(n_samples, config)[source]

Frequency bins (Hz) matching power_spectrum’s / np.fft.rfft’s output for a pulse of length n_samples. Raises if config.sample_period_s is unset.

Parameters: