tfmindi.pp.extract_seqlets

tfmindi.pp.extract_seqlets#

tfmindi.pp.extract_seqlets(contrib, oh, method='recursive_q99_abs_smooth', **method_kwargs)#

Extract, scale, and process seqlets from saliency maps.

Seqlets are called from the projected 1D attribution track (contrib * oh).sum(1) using the selected method, then each seqlet’s contribution matrix is normalized by its maximum absolute contribution value and sign-corrected.

Parameters:

  • contrib (ndarray) – Contribution scores array with shape (n_examples, 4, length)

  • oh (ndarray) – One-hot encoded sequences array with shape (n_examples, 4, length)

  • method (str (default: 'recursive_q99_abs_smooth')) –

    Seqlet-calling algorithm to use. One of:

    • "recursive_q99_abs_smooth" (default): triangular-smooth, per-example q99 normalisation, then the recursive caller on abs(track). Accepts smooth_window, threshold (0.05), min_seqlet_len, max_seqlet_len, additional_flanks (3).

    • "recursive_raw": recursive caller on the raw signed track (reproduces the previous TF-MInDi default behaviour). Same knobs as above.

    • "hysteresis": two-threshold local caller. Accepts smooth_window, seed_z (2.5), grow_z (1.0), min_seqlet_len, max_seqlet_len, merge_gap.

    • "local_contrast": multi-scale sliding-window contrast caller. Accepts windows, smooth_window, seed_z (4.0), expand_z, …

    • "wavelet_otsu": wavelet-denoise + Otsu-threshold caller (needs PyWavelets). Accepts wavelet, threshold_scale (1.7), otsu_weight, min_seqlet_len, …

  • **method_kwargs – Method-specific hyperparameters forwarded to the selected caller, overriding its defaults, e.g. threshold=0.1 for the recursive methods, seed_z=3.0 for hysteresis, threshold_scale=2.0 for wavelet_otsu. Passing a keyword the chosen caller does not accept raises a TypeError. See the per-method caller functions for the full parameter lists (rec_q99_smooth_abs, recursive_raw, hysteresis, local_contrast, wavelet_otsu).

Return type:

tuple[DataFrame, list[ndarray]]

Returns:

  • DataFrame with seqlet coordinates and scores [example_idx, start, end, attribution, score]

  • List of processed seqlet contribution matrices

Examples

>>> seqlets_df, seqlet_matrices = extract_seqlets(contrib, oh)
>>> print(seqlets_df.columns.tolist())
['example_idx', 'start', 'end', 'attribution', 'score']
>>> # switch caller and tune it in one call
>>> seqlets_df, seqlet_matrices = extract_seqlets(contrib, oh, method="hysteresis", seed_z=3.0)