Release v2.5.5: The Extras Extravaganza

What's New

This release introduces soft_extras.py as a companion module to SoFT, providing two independent sets of post-tracking analysis tools: Level 2 Enrichment and Feature Maps.

🔬 Level 2 Enrichment (build_level2)

• Trajectory Angles: Computes EMD-based dominant drift direction from X/Y time-series, fully parallelized via ProcessPoolExecutor for performance.
• Feature Cancellation (compute_cancellation): Utilizes a KD-tree search to efficiently find the k closest co-dying, opposite-polarity neighbors within the same last frame.
• Death Cause Classification (compute_death_cause): Introduces mutually exclusive classification of dying features as either "cancelled" (co-dying neighbor) or "subsumed" (surviving, larger opposite-polarity host within 15 px and ≥2× area). In tie-breaker scenarios, the closer candidate wins.
• Expanded Schema: Exposes new tracking columns: cancelled, cancelled_by, subsumed, subsumed_by, and death_cause.
• Coronal Hole Masking (get_ch_mask): Automatically downloads AIA 193Å and HMI 45s from JSOC, reprojects AIA onto the HMI grid, and returns a binary coronal hole mask via SoFT detection.
• Coronal Hole Flagging (flag_coronal_hole): Stamps each feature with an in_coronal_hole boolean based on its mean pixel position against the generated CH mask.
• Modular Execution: All pipeline steps are individually togglable via run_* flags. Skipped steps cleanly populate their output columns with NaN to maintain strict schema consistency.
• Stateless Configuration: All configuration parameters now live directly in function signatures, entirely eliminating module-level constants.

🗺️ Feature Maps (build_feature_maps)

• Oscillation & Velocity Analysis: Filters features by a lifetime threshold, then computes per-feature peak oscillation frequency (mHz) and velocity MAD from Vx/Vy periodograms.
• Visual Data Generation: Paints area-sized circular blobs onto the reference image canvas, creating two distinct maps: one colored by frequency and one by MAD.
• FITS Export: Automatically saves both output maps as FITS files while preserving the original WCS header.
• Optimized Rendering: The _paint_disk function has been heavily optimized to operate exclusively over a per-blob bounding box, bypassing the expensive full-image ogrid memory allocation on every iteration.

📦 Housekeeping

• Dependencies: Added a requirements.txt covering all non-SoFT dependencies.

Hotfix — watershed_routine over-segmentation (v2.5.2)

Fixed

• Over-segmentation of large/elongated features: when separation=False, watershed_routine now enforces a single seed per low-threshold connected component. Previously, peak_local_max could return multiple high-threshold seeds within the same blob, causing the watershed to draw spurious internal boundaries and split one feature into several labelled regions.
• Bug in detection: sign="neg" was incorrectly passing "pos" to watershed_routine, meaning negative features were being processed as positive ones. The call now correctly passes "neg".

Behaviour

• separation=False (default): one seed per connected component — large features are kept whole.
• separation=True: original multi-seed behaviour is preserved so that the watershed line can correctly separate touching features.

Notes

• Change is confined to watershed_routine. No other functions were modified and no call-site changes are required — separation was already forwarded through the full call chain (track_all → process_image → detection → watershed_routine).

Hotfix — watershed_routine out-of-mask seed placement (v2.5.5)

Fixed

Out-of-mask seed placement (watershed_routine)
Seeds were previously derived from high-threshold centroids (floating-point
averages of pixel positions), which can land on pixels where img_low == 0.
With compactness=0, the watershed could not grow these seeds and only labelled
the few pixels immediately adjacent, causing large features to appear almost
entirely unlabelled. Seeds are now placed at the distance-transform maximum of
each low-threshold component, guaranteeing they always lie inside the mask.

Notes

• peak_local_max is now bypassed entirely when separation=False — seeds are
  derived solely from the low-threshold connected components.
• No call-site changes required.