@@ -66,12 +66,14 @@ The velocity estimator is product-specific and therefore remains in
6666` velocity/estimation.py ` rather than ` calculations ` . It processes `(frame, y,
6767x)` volumes in bounded temporal chunks, uses moments or calibrated frequency
6868bands as its active source, applies the shared local-background difference, and
69- returns physical velocity in ` mm/s ` . Exact-zero LF samples map to zero in band
70- mode; finite/non-negative validation and calibration provenance are part of the
69+ returns physical velocity in ` mm/s ` . In band mode, finite negative samples in
70+ both HF and LF are replaced with zero during chunk validation, with a warning
71+ naming the dataset and frame interval. Zero LF denominators map to ratio zero
72+ without division. Both bands must remain finite; validation and calibration provenance are part of the
7173pipeline contract.
7274
7375` low_freq_spectra/spectrograms.py ` reads HD frequency-bin spectra once per frame for
74- full-frame ` SpatialAverage ` /` SpatialMedian ` reductions and optional gap median
76+ full-frame ` Global/ SpatialAverage` /` Global/ SpatialMedian` reductions and optional gap median
7577power. ` low_freq_spectra/preprocessing.py ` interpolates Boolean gap support with
7678nearest neighbors to the spectrogram video's last two dimensions. The low-frequency spectral
7779runner publishes ` /ProcessingSpectrograms/Gaps/SpatialMedian ` with ` (time, freq) `
@@ -101,28 +103,41 @@ frequency order, window endpoints, and selected/valid sample counts.
101103over beats after each beat's whole/early/late phase median, reusing ` PerBeat/Raw ` .
102104Ignore NaNs; one valid beat gives zero, none gives NaN. Persist raw power units,
103105` ddof=0 ` , reduction order, windows, and valid beat counts per frequency.
104- Positive-frequency PNG/EPS overlays use these STD envelopes and normalize each
105- curve by its own maximum over bins 0 through 31. Their frequency grid is fixed
106- at ` linspace(0, fs/4, 33) ` in Hz, independent of source length. All three figures
107- report the same stored ` Metrics/index_max1 ` through bin 31 inclusive. Keep power
108- linear, scale STD by the same per-curve maximum, and do not save the grid to HDF5.
109- Missing/invalid stored peaks or fewer than 32 bins omit these figures.
106+ Positive-frequency PNG/EPS overlays use the actual positive/DC half of the
107+ source: ` P=floor(N/2) ` bins at spacing ` fs/N ` . Normalize each curve by the
108+ Hv, the same NaN-aware central-quarter median of the full spectrum used by A0
109+ (64 source bins use bins 24 through 39), before cropping from stored ` Metrics/index_max1 `
110+ through bin ` P-1 ` inclusive. Scale STD by the same per-curve divisor, retain
111+ linear power. The runner publishes the full signed frequency mapping once at
112+ ` /ProcessingSpectrograms/FrequencyBinTable ` , as a ` (freq,) ` array in ` kHz ` where
113+ each zero-based array index identifies the source bin. Use the
114+ shared conversions in ` calculations/math/frequency.py ` for tables, metrics, and
115+ plots. Table publication requires valid sampling calibration, independently of
116+ gap support, cardiac timing, and figure export. Missing/invalid stored peaks,
117+ all-NaN neighborhoods, or nonpositive divisors omit the affected figures.
110118Median/early/late use solid/dashed/dotted signals and envelope patterns.
111- The full-domain heatmap/median frequency axes use spacing ` fs/(2*N) ` with DC zero,
119+ The full-domain heatmap/median frequency axes use full-spectrum spacing ` fs/N ` with DC zero,
112120positive-then-negative order, and kHz labels. Resolve ` fs ` from shared
113121` Meta/SamplingFrequencyHz/value ` ; publish it from HD timing parameters/config
114122before export if absent, since velocity analysis may run later. Missing/invalid
115123sampling metadata skips frequency figures while keeping other products.
116124The spectrum figure and pooled scalar metrics consume ` MedianPhaseBeat ` .
117125All gap metrics live directly under ` /ProcessingSpectrograms/Gaps/Metrics ` .
118- Phase curves ` A0_t ` , ` A1_t ` , ` A2_t ` , ` R1_t ` , and ` R2_t ` use ` MedianBeat ` with
119- the pooled peak indices fixed at every phase. Retain the original pooled scalar
120- names ` A0 ` /` A1 ` /` A2 ` /` R1 ` /` R2 ` ; remove output heights ` h0 ` /` h1 ` /` hv ` and ` rho_h ` .
126+ Phase curves ` A0_t ` , ` A1_t ` , ` A2_t ` , ` R1_t ` , ` R2_t ` , ` Z1_t ` , and ` Z2_t ` use
127+ ` MedianBeat ` with the pooled peak indices fixed at every phase. Pooled scalar
128+ metrics use the same seven names without ` _t ` ; output heights ` h0 ` /` h1 ` /` hv `
129+ and ` rho_h ` are absent.
121130Each curve also has ` _early ` and ` _late ` scalar medians over closed phase
122- intervals ` [0,1/3] ` and ` [1/3,1] ` , and a signed ` delta_<metric> ` early-minus-late
123- scalar. Ignore NaNs within each window; missing windows/differences remain NaN.
131+ intervals (default ` [0,1/3] ` and ` [1/3,1] ` ), and a signed ` delta_<metric> ` scalar.
132+ All seven deltas are late-minus-early. Generic helpers in
133+ ` calculations/math/phase_windows.py ` own closed interval masks, NaN-aware medians,
134+ and subtraction. ` run_gap_analysis ` and ` pack_spectrum_metrics ` accept
135+ ` early_interval ` /` late_interval ` cycle-fraction bounds in ` [0,1] ` ; use the same
136+ windows for early/late spectra, STD envelopes, and metric summaries/deltas.
137+ Keep subtraction order explicit in definitions, source paths, and calculation
138+ metadata. Ignore NaNs within each window; missing windows/differences remain NaN.
124139Keep the source's excluded endpoint and include a one-third boundary sample in
125- both windows when present. Curves retain phase/timing/peak provenance and also
140+ both default windows when present. Curves retain phase/timing/peak provenance and also
126141produce shared ` gaps_<metric> ` PNG/EPS plots.
127142The valley height ` hv ` uses a NaN-aware median over a neighborhood centered on
128143the two central bins. Its default length is one quarter of the actual domain
@@ -132,8 +147,22 @@ with at least two bins is supported; an explicit even `valley_neighborhood_lengt
132147overrides the default. Peak halves and central valley bins scale with the domain,
133148splitting at ` floor(bin_count/2) ` for odd lengths. All-NaN peak halves retain NaN
134149indexes, log a warning, and are identified by per-half valid-bin counts in metadata.
135- ` A2 ` uses the same inclusive peak-to-peak width as ` A0 ` .
136- ` R1=A1/A0 ` replaces ` rho_A ` ; ` R2=A2/A0 ` . Metric metadata records the neighborhood.
150+ ` A0 ` is valley-median height times peak-to-peak width in kHz; ` A2 ` is the
151+ peak-height mean times the same width. These swap the former A0/A2 meanings.
152+ Use ` df_khz=fs/(N*1000) ` and width ` (index_max2-index_max1)*df_khz ` , with no
153+ extra bin. ` A1 ` is the trapezoidal integral between those peak bins with positive
154+ ` df_khz ` spacing in stored HD order (unwrapped kHz, no signed-axis sorting).
155+ Areas and their phase summaries/deltas have source-power-times-kHz units;
156+ peak/valley heights retain power units. Preserve calibration, spacing, integration
157+ method, and units in metadata. Artifact axis labels abbreviate ` a.u.*kHz ` to
158+ ` a.u. ` . Resolve calibration from shared
159+ ` Meta/SamplingFrequencyHz/value ` ; missing/invalid calibration warns and skips
160+ the Metrics family while retaining raw/aggregate spectra and filters.
161+ ` R1=A1/A0 ` , ` R2=A2/A0 ` ,
162+ ` Z1=(A1-A0)/A0 ` , and ` Z2=(A2-A0)/A0 ` are dimensionless; zero/missing A0 gives
163+ NaN. All seven metrics have pooled scalars, phase curves, early/late medians,
164+ signed late-minus-early deltas, and matching PNG/EPS phase plots.
165+ Metric metadata records the neighborhood.
137166Independent ` PerBeat/BandLimited ` keeps DC plus the configured non-DC harmonics
138167(default 12) via the shared bandlimiting API in signed mode, using
139168periodic phase boundaries. Original durations define each effective Hz cutoff.
0 commit comments