pyfli.io.spad_folding#

Detect and fold periodic SPAD gate sequences into one excitation period.

This module belongs to pyfli.io and provides signal-aware temporal alignment and folding for gated SPAD acquisitions. Detection is performed on a spatially integrated trace, while all shifts and sums are applied to the original data cube.

Functions

`_circular_autocorrelation`(trace)	Return normalized circular autocorrelation for a one-dimensional trace.
`_cycle_similarity`(trace, period_bins, ...)	Return mean pairwise correlation between circularly aligned periods.
`_period_score`(correlation, period_bins)	Score one candidate period using all repeated circular-autocorrelation lags.
`_smooth_circular_trace`(trace, smoothing_sigma)	Return a circularly smoothed float64 temporal trace.
`_valid_period_divisors`(n_bins)	Return period lengths that divide n_bins into at least two full periods.
`analyze_fold_layout`(data[, ...])	Detect the periodic layout and circular phase required to fold SPAD data.
`apply_fold_layout`(data, layout)	Circularly align and sum repeated periods using a validated fold layout.
`build_temporal_trace`(data)	Build a high-SNR one-dimensional trace by summing over the spatial dimensions.
`circular_align`(data, phase_shift)	Circularly shift a SPAD cube along its temporal axis.
`detect_signal_onset`(folded_trace[, ...])	Detect the circular onset of the dominant fluorescence response in one period.
`estimate_period_bins`(trace[, ...])	Estimate the excitation-period length from circular temporal autocorrelation.
`make_phase_folded_trace`(trace, period_bins)	Sum repeated periods of a temporal trace without changing its circular phase.

Classes

SpadFoldLayout(original_bins, period_bins, ...)

Store the detected or user-specified layout of a periodic SPAD acquisition.

class SpadFoldLayout(original_bins, period_bins, repeat_count, phase_origin, phase_shift, onset_index, onset_lead_bins, pulse_positions, period_score, cycle_similarity, signal_score, confidence, manual_period, manual_phase)[source]#

Bases: object

Store the detected or user-specified layout of a periodic SPAD acquisition.

Parameters:

original_bins (int) – Number of temporal gates before folding.
period_bins (int) – Number of gates in one excitation period.
repeat_count (int) – Number of repeated excitation periods contained in the acquisition.
phase_origin (int) – Gate index inside one period that is treated as the start of the decay.
phase_shift (int) – Circular shift applied on the time axis before folding.
onset_index (int) – Detected or implied gate index of the signal onset inside one period.
onset_lead_bins (int) – Number of gates the folded period starts before the signal onset.
pulse_positions (tuple[int, ]) – Expected pulse-onset positions in the original acquisition.
period_score (float) – Circular-autocorrelation score for the selected temporal period.
cycle_similarity (float) – Mean pairwise similarity between aligned repeated periods.
signal_score (float) – Signal-to-baseline confidence score used during onset detection.
confidence (float) – Combined confidence score for automatic folding.
manual_period (bool) – Whether period_bins was supplied explicitly by the user.
manual_phase (bool) – Whether phase_shift was supplied explicitly by the user.

original_bins: int#

period_bins: int#

repeat_count: int#

phase_origin: int#

phase_shift: int#

onset_index: int#

onset_lead_bins: int#

pulse_positions: tuple[int, ...]#

period_score: float#

cycle_similarity: float#

signal_score: float#

confidence: float#

manual_period: bool#

manual_phase: bool#

to_metadata()[source]#

Convert the fold layout to serializable metadata.

Returns:: Dictionary containing the fold-detection and alignment metadata.
Return type:: dict[str, object]

build_temporal_trace(data)[source]#

Build a high-SNR one-dimensional trace by summing over the spatial dimensions.

Parameters:: data (np.ndarray) – Three-dimensional SPAD data cube with shape (H, W, T).
Returns:: Spatially integrated temporal trace with shape (T,) and float64 dtype.
Return type:: np.ndarray

estimate_period_bins(trace, expected_repeats=None, search_radius=0.15)[source]#

Estimate the excitation-period length from circular temporal autocorrelation.

Parameters:

trace (np.ndarray) – One-dimensional temporal trace.
expected_repeats (int | None) – Expected number of repeated excitation periods. When provided, the search is constrained around len(trace) / expected_repeats.
search_radius (float) – Fractional search radius around the expected period when expected_repeats is provided.

Returns:

Detected period length in bins and its normalized autocorrelation score.

Return type:

tuple[int, float]

make_phase_folded_trace(trace, period_bins)[source]#

Sum repeated periods of a temporal trace without changing its circular phase.

Parameters:

trace (np.ndarray) – One-dimensional temporal trace.
period_bins (int) – Number of gates in one excitation period.

Returns:

Phase-folded trace with shape (period_bins,).

Return type:

np.ndarray

detect_signal_onset(folded_trace, smoothing_sigma=1.0, threshold_fraction=0.10)[source]#

Detect the circular onset of the dominant fluorescence response in one period.

Parameters:

folded_trace (np.ndarray) – One-period temporal trace. The signal may wrap across the first/last gate.
smoothing_sigma (float) – Gaussian smoothing sigma used only for onset detection.
threshold_fraction (float) – Fraction of peak-to-baseline amplitude used for the rising-edge crossing.

Returns:

Detected onset index and a signal-to-baseline confidence score in [0, 1].

Return type:

tuple[int, float]

circular_align(data, phase_shift)[source]#

Circularly shift a SPAD cube along its temporal axis.

Parameters:

data (np.ndarray) – Three-dimensional SPAD data cube with shape (H, W, T).
phase_shift (int) – Integer shift applied along the temporal axis. A negative value moves later gates toward the beginning of the temporal sequence.

Returns:

Shifted data cube with the same shape and dtype as the input.

Return type:

np.ndarray

analyze_fold_layout(data, expected_repeats=None, period_bins=None, phase_shift=None, min_confidence=0.60, validate=True, search_radius=0.15, smoothing_sigma=1.0, threshold_fraction=0.10, onset_lead_bins=None)[source]#

Detect the periodic layout and circular phase required to fold SPAD data.

Parameters:

data (np.ndarray) – Three-dimensional SPAD data cube with shape (H, W, T).
expected_repeats (int | None) – Expected number of repeated excitation periods.
period_bins (int | None) – Explicit period length. When None, the period is detected automatically.
phase_shift (int | None) – Explicit circular shift. When None, signal onset is detected automatically.
min_confidence (float) – Minimum accepted combined confidence for automatic folding validation.
validate (bool) – Whether to reject a detected layout whose confidence is below min_confidence.
search_radius (float) – Fractional period-search radius around an expected period.
smoothing_sigma (float) – Circular Gaussian smoothing sigma used only on the detection trace.
threshold_fraction (float) – Peak-to-baseline fraction used to locate the fluorescence onset.
onset_lead_bins (int | None) – Number of gates the folded period starts before the detected onset so the complete rising edge and pre-pulse baseline are kept at the start of the period. None selects 5 % of the period, with a minimum of two gates. Ignored when phase_shift is supplied explicitly.

Returns:

Validated folding layout and detection diagnostics.

Return type:

SpadFoldLayout

apply_fold_layout(data, layout)[source]#

Circularly align and sum repeated periods using a validated fold layout.

Parameters:

data (np.ndarray) – Three-dimensional SPAD data cube with shape (H, W, T).
layout (SpadFoldLayout) – Folding layout returned by analyze_fold_layout.

Returns:

Folded data cube with shape (H, W, period_bins).

Return type:

np.ndarray