feat: Implement GenericSpectrogram.join_many

[Omiii-215]

PR Description

Adds GenericSpectrogram.join_many() to reintroduce time-axis concatenation functionality from the old Spectrogram API, addressing part of Issue #82.

The method:

Sorts spectrograms by start_time.

Validates frequency axis compatibility.

Handles overlaps by trimming.

Handles gaps using maxgap and optional fill_gaps logic.

Returns a new spectrogram while preserving the subclass type.

Includes a new test file covering contiguous joins, gap handling, overlap trimming, sorting, subclass preservation, and frequency mismatch cases.

This restores one of the legacy methods still used by downstream users (e.g., e-CALLISTO), with the remaining methods planned for follow-up PRs.

[Omiii-215]

Summary

This PR reintroduces GenericSpectrogram.join_many to restore time-axis concatenation functionality from the legacy Spectrogram API, addressing part of Issue #82 by taking the help of #5 .

Implementation

A new class method join_many was added to radiospectra/spectrogram/spectrogrambase.py.
It takes a sequence of spectrogram objects and returns a single combined spectrogram along the time axis.

Key behaviors:

• Sorting: Input spectrograms are sorted by start_time to ensure correct chronological stitching.
• Frequency validation: All inputs must share compatible frequency axes; otherwise a ValueError is raised.
• Cadence inference: The method computes the median time difference between samples to determine the expected cadence.

Gap and Overlap Handling

The method handles real-world data discontinuities:

• Overlap trimming: Overlapping time ranges are automatically trimmed to maintain monotonic time order.

• Gap detection: The gap between consecutive spectrograms is computed.

• maxgap parameter: If a gap exceeds the user-defined threshold, a ValueError is raised.

• Optional gap filling (fill_gaps=True):

  • Missing time steps are inferred from the cadence.
  • Filler columns are inserted by repeating the last valid data column.
  • This preserves a continuous time axis for plotting and analysis.

Metadata handling

A new metadata dictionary is created for the output:

• Preserves the base spectrogram metadata.

• Updates:

  • times
  • start_time
  • end_time

Tests

A new test file test_join_many.py was added covering:

• Contiguous joins
• Gap filling
• Gap rejection via maxgap
• Overlap trimming
• Input sorting
• Subclass preservation
• Frequency mismatch handling

All CI checks are passing.