ecallistolib 0.2.3__py3-none-any.whl → 0.3.0__py3-none-any.whl

ecallistolib/__init__.py

@@ -20,7 +20,7 @@ from .exceptions import (
 )
 from .io import CallistoFileParts, parse_callisto_filename, read_fits
 from .models import DynamicSpectrum
-from .processing import noise_reduce_mean_clip
+from .processing import noise_reduce_mean_clip, noise_reduce_median_clip
 from .crop import crop, crop_frequency, crop_time, slice_by_index
 
 try:
@@ -39,6 +39,7 @@ __all__ = [
     "read_fits",
     # Processing
     "noise_reduce_mean_clip",
+    "noise_reduce_median_clip",
     # Cropping
     "crop",
     "crop_frequency",
@@ -77,12 +78,14 @@ def __getattr__(name: str):
             "combine_time": combine_time,
         }[name]
 
-    if name in {"list_remote_fits", "download_files"}:
-        from .download import download_files, list_remote_fits
+    if name in {"list_remote_fits", "list_remote_fits_range", "download_files"}:
+        from .download import download_files, list_remote_fits, list_remote_fits_range
 
-        return {"list_remote_fits": list_remote_fits, "download_files": download_files}[
-            name
-        ]
+        return {
+            "list_remote_fits": list_remote_fits,
+            "list_remote_fits_range": list_remote_fits_range,
+            "download_files": download_files,
+        }[name]
 
     if name in {
         "plot_dynamic_spectrum",

ecallistolib/combine.py

@@ -48,7 +48,7 @@ def combine_frequency(path1: str | Path, path2: str | Path) -> DynamicSpectrum:
 
     meta = dict(ds1.meta)
     meta["combined"] = {"mode": "frequency", "sources": [str(ds1.source), str(ds2.source)]}
-    return DynamicSpectrum(data=data, freqs_mhz=freqs, time_s=ds1.time_s, source=None, meta=meta)
+    return DynamicSpectrum(data=data, freqs_mhz=freqs, time_s=ds1.time_s, source=ds1.source, meta=meta)
 
 
 def can_combine_time(paths: Iterable[str | Path], freq_atol: float = 0.01) -> bool:
@@ -106,5 +106,5 @@ def combine_time(paths: Iterable[str | Path]) -> DynamicSpectrum:
 
     meta = dict(ds0.meta)
     meta["combined"] = {"mode": "time", "sources": [str(Path(p)) for p in paths]}
-    return DynamicSpectrum(data=combined_data, freqs_mhz=freqs, time_s=combined_time, source=None, meta=meta)
+    return DynamicSpectrum(data=combined_data, freqs_mhz=freqs, time_s=combined_time, source=ds0.source, meta=meta)
 

ecallistolib/download.py

@@ -99,6 +99,81 @@ def list_remote_fits(
     return out
 
 
+def list_remote_fits_range(
+    start_date: date,
+    end_date: date,
+    hours: Iterable[int] | None = None,
+    station_substring: str = "",
+    base_url: str = DEFAULT_BASE_URL,
+    timeout_s: float = 10.0,
+) -> List[RemoteFITS]:
+    """
+    List available FITS files over a date range.
+
+    Parameters
+    ----------
+    start_date : date
+        Start date (inclusive).
+    end_date : date
+        End date (inclusive).
+    hours : Iterable[int] | None
+        UTC hours to include (0-23). If None, includes all hours (0-23).
+    station_substring : str
+        Case-insensitive substring to match station names.
+    base_url : str
+        Base URL of the e-CALLISTO archive.
+    timeout_s : float
+        HTTP request timeout in seconds.
+
+    Returns
+    -------
+    List[RemoteFITS]
+        All matching remote FITS files across the date range.
+
+    Raises
+    ------
+    ValueError
+        If start_date > end_date.
+
+    Example
+    -------
+    >>> from datetime import date
+    >>> files = list_remote_fits_range(
+    ...     start_date=date(2023, 6, 1),
+    ...     end_date=date(2023, 6, 3),
+    ...     hours=[12, 13, 14],
+    ...     station_substring="alaska"
+    ... )
+    """
+    from datetime import timedelta
+
+    if start_date > end_date:
+        raise ValueError("start_date must be <= end_date")
+
+    hours_to_check = list(hours) if hours is not None else list(range(24))
+
+    results: List[RemoteFITS] = []
+    current = start_date
+
+    while current <= end_date:
+        for hour in hours_to_check:
+            try:
+                found = list_remote_fits(
+                    day=current,
+                    hour=hour,
+                    station_substring=station_substring,
+                    base_url=base_url,
+                    timeout_s=timeout_s,
+                )
+                results.extend(found)
+            except DownloadError:
+                # Skip days/hours with no data or connection issues
+                continue
+        current += timedelta(days=1)
+
+    return results
+
+
 def download_files(
     items: Iterable[RemoteFITS],
     out_dir: str | Path,

ecallistolib/models.py

@@ -42,3 +42,23 @@ class DynamicSpectrum:
     @property
     def shape(self) -> tuple[int, int]:
         return int(self.data.shape[0]), int(self.data.shape[1])
+
+    @property
+    def n_freq(self) -> int:
+        """Number of frequency channels."""
+        return self.data.shape[0]
+
+    @property
+    def n_time(self) -> int:
+        """Number of time samples."""
+        return self.data.shape[1]
+
+    @property
+    def duration_s(self) -> float:
+        """Total observation duration in seconds."""
+        return float(self.time_s[-1] - self.time_s[0])
+
+    @property
+    def freq_range_mhz(self) -> tuple[float, float]:
+        """Frequency range as (min, max) in MHz."""
+        return float(self.freqs_mhz.min()), float(self.freqs_mhz.max())

ecallistolib/processing.py

@@ -68,3 +68,54 @@ def background_subtract(ds: DynamicSpectrum) -> DynamicSpectrum:
     meta = dict(ds.meta)
     meta["processing"] = {"method": "background_subtract"}
     return ds.copy_with(data=data, meta=meta)
+
+
+def noise_reduce_median_clip(
+    ds: DynamicSpectrum,
+    clip_low: float,
+    clip_high: float,
+    scale: float | None = (2500.0 / 255.0 / 25.4),
+) -> DynamicSpectrum:
+    """
+    Noise reduction using median subtraction and clipping.
+
+    More robust to outliers than mean-based subtraction. Uses the same
+    algorithm as noise_reduce_mean_clip but substitutes the median for
+    the mean when computing the background level.
+
+    Algorithm:
+    1) Subtract median over time for each frequency channel
+    2) Clip to [clip_low, clip_high]
+    3) Apply optional scaling
+
+    Parameters
+    ----------
+    ds : DynamicSpectrum
+        Input dynamic spectrum.
+    clip_low : float
+        Lower clipping threshold.
+    clip_high : float
+        Upper clipping threshold.
+    scale : float | None
+        Scaling factor. Default is ~3.88 (2500/255/25.4).
+        Set to None to disable scaling.
+
+    Returns
+    -------
+    DynamicSpectrum
+        New spectrum with noise reduced.
+    """
+    data = np.array(ds.data, copy=True, dtype=float)
+    data = data - np.median(data, axis=1, keepdims=True)
+    data = np.clip(data, clip_low, clip_high)
+    if scale is not None:
+        data = data * float(scale)
+
+    meta = dict(ds.meta)
+    meta["noise_reduction"] = {
+        "method": "median_subtract_clip",
+        "clip_low": clip_low,
+        "clip_high": clip_high,
+        "scale": scale,
+    }
+    return ds.copy_with(data=data, meta=meta)

{ecallistolib-0.2.3.dist-info → ecallistolib-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ecallistolib
-Version: 0.2.3
+Version: 0.3.0
 Summary: Tools to download, read, process, and plot e-CALLISTO FITS dynamic spectra.
 Author: Sahan S. Liyanage
 License: MIT
@@ -29,6 +29,14 @@ A Python library to **download**, **read**, **process**, and **plot** e-CALLISTO
 
 ---
 
+## 🆕 What's New in v0.3.0
+
+- **`DynamicSpectrum` convenience properties** — `n_freq`, `n_time`, `duration_s`, `freq_range_mhz` for quick data inspection
+- **`list_remote_fits_range()`** — Query the e-CALLISTO archive across multiple days with optional hour filtering
+- **`noise_reduce_median_clip()`** — Median-based noise reduction, more robust to outliers than mean-based method
+
+---
+
 ## Table of Contents
 
 - [Features](#features)
@@ -147,6 +155,12 @@ print(f"Frequencies: {spectrum.freqs_mhz}")     # Frequency axis in MHz
 print(f"Time samples: {spectrum.time_s}")       # Time axis in seconds
 print(f"Source file: {spectrum.source}")        # Original file path
 print(f"Metadata: {spectrum.meta}")             # Station, date, etc.
+
+# New in v0.3.0: Convenience properties
+print(f"Num frequencies: {spectrum.n_freq}")    # Number of frequency channels
+print(f"Num time samples: {spectrum.n_time}")   # Number of time samples
+print(f"Duration: {spectrum.duration_s} s")     # Total observation duration
+print(f"Freq range: {spectrum.freq_range_mhz}") # (min, max) frequency in MHz
 ```
 
 #### Parsing Filenames
@@ -190,6 +204,25 @@ for path in saved_paths:
     print(f"Downloaded: {path}")
 ```
 
+#### Querying Multiple Days
+
+List files over a date range with `list_remote_fits_range` (new in v0.3.0):
+
+```python
+from datetime import date
+import ecallistolib as ecl
+
+# List files from June 1-3, 2023, during hours 12-14 UTC
+remote_files = ecl.list_remote_fits_range(
+    start_date=date(2023, 6, 1),
+    end_date=date(2023, 6, 3),
+    hours=[12, 13, 14],          # Optional: specific UTC hours
+    station_substring="alaska"
+)
+
+print(f"Found {len(remote_files)} files across 3 days")
+```
+
 ---
 
 ### Processing Data
@@ -237,6 +270,26 @@ bg_subtracted = ecl.background_subtract(spectrum)
 # Each frequency channel now has zero mean
 ```
 
+#### Median-Based Noise Reduction (v0.3.0)
+
+For data with outliers, use median-based subtraction which is more robust:
+
+```python
+import ecallistolib as ecl
+
+spectrum = ecl.read_fits("my_spectrum.fit.gz")
+
+# Use median instead of mean (more robust to outliers)
+cleaned = ecl.noise_reduce_median_clip(
+    spectrum,
+    clip_low=-5.0,
+    clip_high=20.0
+)
+
+# Metadata shows the method used
+print(cleaned.meta["noise_reduction"]["method"])  # 'median_subtract_clip'
+```
+
 ---
 
 ### Cropping & Slicing
@@ -545,6 +598,10 @@ class DynamicSpectrum:
 | Property | Type | Description |
 |----------|------|-------------|
 | `shape` | `tuple[int, int]` | Returns `(n_freq, n_time)` |
+| `n_freq` | `int` | Number of frequency channels |
+| `n_time` | `int` | Number of time samples |
+| `duration_s` | `float` | Total observation duration in seconds |
+| `freq_range_mhz` | `tuple[float, float]` | Frequency range as `(min, max)` in MHz |
 
 #### Methods
 
@@ -612,6 +669,21 @@ Download FITS files to a local directory.
 
 ---
 
+#### `list_remote_fits_range(start_date, end_date, hours=None, station_substring="", ...) -> List[RemoteFITS]`
+
+List available FITS files over a date range (new in v0.3.0).
+
+| Parameter | Type | Description |
+|-----------|------|--------------|
+| `start_date` | `date` | Start date (inclusive) |
+| `end_date` | `date` | End date (inclusive) |
+| `hours` | `Iterable[int] \| None` | UTC hours to include (0–23), or None for all |
+| `station_substring` | `str` | Case-insensitive station filter |
+
+**Returns:** List of `RemoteFITS` objects across the date range.
+
+---
+
 ### Processing Functions
 
 #### `noise_reduce_mean_clip(ds, clip_low=-5.0, clip_high=20.0, scale=...) -> DynamicSpectrum`
@@ -641,6 +713,21 @@ Subtract mean over time for each frequency channel (background subtraction only,
 
 ---
 
+#### `noise_reduce_median_clip(ds, clip_low, clip_high, scale=...) -> DynamicSpectrum`
+
+Apply noise reduction via median subtraction and clipping (new in v0.3.0). More robust to outliers than mean-based method.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `ds` | `DynamicSpectrum` | — | Input spectrum |
+| `clip_low` | `float` | — | Lower clipping threshold |
+| `clip_high` | `float` | — | Upper clipping threshold |
+| `scale` | `float \| None` | `~3.88` | Scaling factor (`None` to disable) |
+
+**Returns:** New `DynamicSpectrum` with processed data and updated metadata.
+
+---
+
 ### Cropping Functions
 
 #### `crop_frequency(ds, freq_min=None, freq_max=None) -> DynamicSpectrum`

ecallistolib-0.3.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+ecallistolib/__init__.py,sha256=ufhvqfgjgW4oymwZJF8TsycDXjgCBbjOSG4VXFBY7BI,3186
+ecallistolib/combine.py,sha256=G1ySitPAFbKVNL3u_-Fva4prdYXzq4glIpf8YC8aF5g,3327
+ecallistolib/crop.py,sha256=DactJZ9DtZ50zj7Cp6Ii0F6sCieVloGyzWqMY7HmJ9I,6383
+ecallistolib/download.py,sha256=cT1wWvpOUrbbsX-H4IxC_KiebTS-6L5VywHd2LxPVeo,6138
+ecallistolib/exceptions.py,sha256=e993ColPiVOyOP7Dh7RY4GlRoClwFCPABLiWaS5cLuk,1027
+ecallistolib/io.py,sha256=_uSw6L6Bm1t5GjpVMGtdoF_5NmgEVVDzCXW2nRVFbV8,3686
+ecallistolib/models.py,sha256=XyPqIo-yDfuRHY2p6MkXovHkmQUV2ltSaGKXzoXzzDA,1887
+ecallistolib/plotting.py,sha256=rEItUrxAXfMj76_MPmoycgfxcbsuWztc3cduWKppkSU,20616
+ecallistolib/processing.py,sha256=0Flsj9wQfu17oZtxkC4A2c90HhU5aMp3iVWhVGKl_Mg,3409
+ecallistolib-0.3.0.dist-info/licenses/LICENSE,sha256=WunjkzsBGyy9vIQxfNe_GDV1yKBQJ-0WbFt4AXZ5Rvc,1073
+ecallistolib-0.3.0.dist-info/METADATA,sha256=dbplIiwUva-SL_Dd3_21uZnKWVgusOMOC2h0M5vQWu8,29447
+ecallistolib-0.3.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+ecallistolib-0.3.0.dist-info/top_level.txt,sha256=DmLjR5jlE2i2mQXou5gyCpaHOOlNs4DIQyCPoGXhsbc,13
+ecallistolib-0.3.0.dist-info/RECORD,,

ecallistolib-0.2.3.dist-info/RECORD

@@ -1,14 +0,0 @@
-ecallistolib/__init__.py,sha256=MOEjuYi132aHYdFNN8ReRcu95eXOVWFsyRvX2zPb6Os,3003
-ecallistolib/combine.py,sha256=wYDh1pzh4DMZTLD2KRQOCtRbtt2y-PC8xmQvC5xl1LA,3315
-ecallistolib/crop.py,sha256=DactJZ9DtZ50zj7Cp6Ii0F6sCieVloGyzWqMY7HmJ9I,6383
-ecallistolib/download.py,sha256=XbqcLqptKS16D8MP9bWZZprFviQdw1hbt9ctsW1N91s,4114
-ecallistolib/exceptions.py,sha256=e993ColPiVOyOP7Dh7RY4GlRoClwFCPABLiWaS5cLuk,1027
-ecallistolib/io.py,sha256=_uSw6L6Bm1t5GjpVMGtdoF_5NmgEVVDzCXW2nRVFbV8,3686
-ecallistolib/models.py,sha256=Mv8fRWKsbNlMQi20_6oxUz9UX6wkckZAcS9Tj0kH-b4,1299
-ecallistolib/plotting.py,sha256=rEItUrxAXfMj76_MPmoycgfxcbsuWztc3cduWKppkSU,20616
-ecallistolib/processing.py,sha256=enwu8KSome09u4Iv5zjhY80t1HbnGFz3xXf2Wr3Lp7k,1962
-ecallistolib-0.2.3.dist-info/licenses/LICENSE,sha256=WunjkzsBGyy9vIQxfNe_GDV1yKBQJ-0WbFt4AXZ5Rvc,1073
-ecallistolib-0.2.3.dist-info/METADATA,sha256=vqzLuqmPGXxIKwF2HABGorRI6YusKD15p_XAQ3kQEmg,26290
-ecallistolib-0.2.3.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-ecallistolib-0.2.3.dist-info/top_level.txt,sha256=DmLjR5jlE2i2mQXou5gyCpaHOOlNs4DIQyCPoGXhsbc,13
-ecallistolib-0.2.3.dist-info/RECORD,,