Heart Rate Analysis¶

Heart rate analysis estimates a periodic heartbeat frequency from a velocity time series and reports it in beats-per-minute (bpm) and Hz (bpm = 60 × Hz).

Input data¶

Heart rate is a dependent analysis. It is seeded by a radon_velocity analysis on the same (channel, roi_id) and reads the parent velocity series through get_plot_data(). Run Velocity Analysis first.

Two estimators and quality control¶

Every run computes the dominant periodicity with two independent estimators:

Lomb-Scargle periodogram
Welch power spectral density

When the two estimates fall within agree_tol_bpm of each other the summary status is ok (accept); when they diverge the status becomes method_disagree (reject / review). Too few valid velocity samples yields insufficient_valid.

Programmatic use¶

from acqstore.acq_image import AcqImage
from acqstore.acq_image.analysis import HeartRateAnalysis, RadonVelocityAnalysis
from acqstore.sample_data import ensure_sample_file

acq = AcqImage(str(ensure_sample_file('kymograph-flow')))

channel = acq.images.channel_indices[0]
roi_ids = acq.rois.get_roi_ids()
roi_id = roi_ids[0] if roi_ids else acq.rois.create_rect_roi(name='hr').roi_id

acq.analysis_set.create_and_run(
    RadonVelocityAnalysis,
    channel=channel,
    roi_id=roi_id,
    detection_params={'window_width': 64},
    replace_existing=True,
    execution_options={'use_multiprocessing': False},
)

heart_rate = acq.analysis_set.create_and_run(
    HeartRateAnalysis,
    channel=channel,
    roi_id=roi_id,
    replace_existing=True,
)
print(heart_rate.result.summary)
acq.save()

Detection parameters¶

name	display_name	type	default	unit	editable	visible	description
bpm_min	Heart rate min	float	240	bpm	True	True	Lower heart-rate bound of the analysis band.
bpm_max	Heart rate max	float	600	bpm	True	True	Upper heart-rate bound of the analysis band.
use_abs	Use absolute velocity	bool	1	nan	True	True	Analyze absolute velocity instead of signed velocity.
outlier_k_mad	Outlier clip (MAD)	float	4	nan	True	True	MAD winsorization factor applied during preprocessing.
lomb_n_freq	Lomb frequencies	int	512	nan	True	True	Number of frequencies in the Lomb-Scargle grid.
interp_max_gap_sec	Max interp gap	float	0.05	s	True	True	Maximum NaN gap interpolated for the Welch path.
bandpass_order	Bandpass order	int	3	nan	True	True	Butterworth band-pass order for the Welch path.
nperseg_sec	Welch segment	float	2	s	True	True	Welch PSD segment duration.
edge_margin_hz	Edge margin	float	-1	Hz	True	True	Edge margin in Hz for edge flagging. Use -1.0 for auto.
peak_half_width_hz	Peak half width	float	0.5	Hz	True	True	Half-width around the peak used for band concentration.
agree_tol_bpm	Agreement tolerance	float	30	bpm	True	True	Maximum Lomb-vs-Welch bpm delta considered agreement.
do_segments	Compute segments	bool	0	nan	True	True	Compute a compact windowed segment summary.
seg_win_sec	Segment window	float	6	s	True	True	Segment window length when segments are computed.
seg_step_sec	Segment step	float	1	s	True	True	Segment window step when segments are computed.
seg_min_valid_frac	Segment min valid	float	0.5	nan	True	True	Minimum finite-sample fraction required per segment window.

Results¶

Heart rate stores a compact summary in the JSON sidecar. There is no CSV table for heart rate.

Typical summary content includes per-estimator results (lomb, welch), rollup status, and an agreement block (abs_delta_bpm, agree_ok).

See the Heart Rate Analysis API and the Heart Rate Analysis notebook. The notebook uses the folder sample velocity-sample-data so it can show both accept and reject outcomes on two files. For a one-file scripted demo, use ensure_sample_file('kymograph-flow') as above.