Event Detection Functions#

massphoto.detection.detect_on_map(maps, thresholds=(0.0,), threshold_absolute=False, position_map=0, contrast_map=None, threshold_distance_temp=1, threshold_distance_spat=3, min_distance_temp=10, min_distance_spat=5, output_map_values=False)[source]#

Detects peaks in a multi-dimensional array of maps.

Note

Available as both massphoto.detect_on_map and massphoto.detection.detect_on_map.

Parameters:

  • maps (list or np.ndarray) – The multi-dimensional array/list of maps [map1, map2, …].

  • thresholds (list or np.ndarray, optional) – The thresholds for peak detection. It can be a single value or a list of the same length as the number of maps. Defaults to 0.0.

  • threshold_absolute (bool, optional) – If True, the absolute value of the maps will be used for thresholding. Defaults to False.

  • position_map (int, optional) – The index of the map to use for peak position determination. Defaults to 0 (first map).

  • contrast_map (int or None, optional) – The index of the map to use for peak contrast determination. If None, no contrast estimate will be returned. Defaults to None.

  • threshold_distance_temp (int, optional) – Temporal extent of the area in which the map has to peak above the threshold. Defaults to 1.

  • threshold_distance_spat (int, optional) – Spatial extent of the area in which the map has to peak above the threshold. Defaults to 3.

  • min_distance_temp (int, optional) – The minimum distance between peaks in the temporal dimension. Defaults to 10.

  • min_distance_spat (int, optional) – The minimum distance between peaks in the spatial dimensions. Defaults to 5.

  • output_map_values (bool, optional) – If True, include map_i columns in the output DataFrame. Each value is the local maximum of map i within the threshold-distance neighborhood around the detected event, i.e. the largest value in the support region that would still have detected that event. Defaults to False.

Returns:

A DataFrame containing the peak positions and optionally the map values.

Return type:

pd.DataFrame

massphoto.detection.event_correlation(movie, correlation_args=None, thresholds=(0.4, 0.001), threshold_absolute=True, min_distance_temp=10, contrast_map=1, **detection_args)[source]#

Detect events in a ratiometric movie using spatial correlation maps.

This is a convenience wrapper around correlation_map() followed by detect_on_map().

See also

detect_on_map, detect

Parameters:
massphoto.detection.event_correlation_step(movie, movie_r, correlation_args=None, correlation_native_args=False, correlation_step_args=False, thresholds=(0.6, 0.5, 0.001), threshold_absolute=True, threshold_distance_spat=3, min_distance_temp=10, position_map=2, contrast_map=2, **detection_args)[source]#

Detect events using a normalised correlation with a step function in the native movie and a normalised correlation with a PSF template in the ratiometric movie.

This function computes three maps and then calls detect_on_map():

  1. Step correlation on the (optionally pre-filtered) native movie. (default threshold: 0.6)

  2. Normalised spatial correlation on the ratiometric movie. (default threshold: 0.5)

  3. Raw spatial correlation (contrast) on the ratiometric movie. (default threshold: 0.001)

Defaults are chosen for typical mass photometry data and can be overridden explicitly or via massphoto.defaults (this function is decorated with sync_apply_defaults()), e.g.: massphoto.defaults.set(‘event_correlation_step.thresholds’, [0.25, 0.35, 0.0005])

Parameters:

  • movie (NativeMovie) – Native movie, used for the step-correlation map.

  • movie_r (RatiometricMovie) – Ratiometric movie, used for the spatial correlation maps.

  • correlation_args (dict | None, default=None) – Keyword arguments forwarded to correlation_map().

  • correlation_native_args (dict | bool, default=False) – If truthy, pre-filter movie with correlation_map_kern_norm() before the step correlation. If True, a shallow copy of correlation_args is used. If a dict, it is used as the kwargs for the native correlation.

  • correlation_step_args (dict | bool, default=False) – Keyword arguments forwarded to step_correlation(). If False, defaults of that function are used.

  • thresholds (list | np.ndarray, default=[0.6, 0.5, 0.001]) – Per-map detection thresholds [step_corr, norm_corr, contrast].

  • threshold_absolute (bool | list[bool], default=True) – Whether to threshold on absolute map values.

  • threshold_distance_spat (int, default=3) – Spatial window (pixels) that must exceed the threshold for a detection.

  • min_distance_temp (int, default=10) – Minimum temporal separation (frames) between detections.

  • position_map (int, default=2) – Map index used to determine peak positions (default uses the raw correlation map).

  • contrast_map (int | None, default=2) – Map index used to report contrast estimates in the output (c column).

  • **detection_args (dict) – Forwarded to detect_on_map() (e.g. min_distance_spat, threshold_distance_temp, output_map_values).

Returns:

Detected event positions with columns frame, y, x and optionally c (when contrast_map is not None).

Return type:

pd.DataFrame

See also

detect_on_map, detect

massphoto.detection.detect(movie, movie_template=None, movie_normalize_frame_means=False, movie_correct_drift=False, return_ratiometric=False, ratiometric_args=None, ratiometric_func=<function calc_ratiometric>, detection_func=<function event_correlation_step>, detection_args=None, chunk_overlap=-1, chunk_size=1000, postprocess=(), scheduler=None, progress_bar=True, attach_record=True)[source]#

Detect events in a movie with chunked (Dask) processing.

Note

Available as both massphoto.detect and massphoto.detection.detect.

This is a thin wrapper over process() that can optionally apply drift correction and ratiometric conversion before calling detection_func on each chunk.

Parameters:

  • movie (da.Array | np.ndarray | os.PathLike) – Movie array of shape (frames, y, x), or a path readable by read_movie().

  • movie_template (np.ndarray | None, default=None) – Global native reference image used for frame-mean normalization and drift correction. If needed and not supplied, it is computed as the mean image of the input movie.

  • movie_normalize_frame_means (bool) – If True, scale each native frame so its mean matches the global frame mean before drift correction and ratiometric conversion.

  • movie_correct_drift (bool) – If True, apply correct_drift() first.

  • return_ratiometric (bool) – If True, also return the ratiometric movie.

  • ratiometric_args (dict | None, default=None) – Passed to ratiometric_func.

  • ratiometric_func (Callable | None) – Ratiometric conversion (default: calc_ratiometric()).

  • detection_func (Callable) – Detection function applied to each chunk (default: event_correlation_step()).

  • detection_args (dict | None) – Passed to detection_func.

  • chunk_overlap (int, default=-1) – Chunk overlap in frames; -1 chooses a value based on processing args.

  • chunk_size (int, default=1000) – Chunk size in frames; default is 1000.

  • postprocess (Sequence[Callable[[pd.DataFrame], pd.DataFrame]]) – Post-processing callbacks applied to the final DataFrame.

  • scheduler (str | None, default=None) – Dask scheduler name (e.g. 'threads'/'processes').

  • progress_bar (bool, default=True) – If True, display a tqdm progress bar during Dask computation.

  • attach_record (bool, default=True) – If True, attach an analysis_record dictionary to DataFrame.attrs containing the effective defaults state, origin function, and origin kwargs for reproducible replay with massphoto.resolve_record().

Returns:

Detected event table, and optionally the ratiometric movie.

Return type:

pd.DataFrame | tuple[pd.DataFrame, np.ndarray]

See also

massphoto.pipeline.process