ecallistolib 0.2.1__py3-none-any.whl

ecallistolib/__init__.py

@@ -0,0 +1,110 @@
+
+"""
+e-callistolib: Tools for e-CALLISTO FITS dynamic spectra.
+Version 0.2.1
+Sahan S Liyanage (sahanslst@gmail.com)
+Astronomical and Space Science Unit, University of Colombo, Sri Lanka.
+"""
+
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .exceptions import (
+    CombineError,
+    CropError,
+    DownloadError,
+    ECallistoError,
+    InvalidFilenameError,
+    InvalidFITSError,
+)
+from .io import CallistoFileParts, parse_callisto_filename, read_fits
+from .models import DynamicSpectrum
+from .processing import noise_reduce_mean_clip
+from .crop import crop, crop_frequency, crop_time, slice_by_index
+
+try:
+    __version__ = version("ecallistolib")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    # Version
+    "__version__",
+    # Core
+    "DynamicSpectrum",
+    "CallistoFileParts",
+    # I/O
+    "parse_callisto_filename",
+    "read_fits",
+    # Processing
+    "noise_reduce_mean_clip",
+    # Cropping
+    "crop",
+    "crop_frequency",
+    "crop_time",
+    "slice_by_index",
+    # Exceptions
+    "ECallistoError",
+    "InvalidFITSError",
+    "InvalidFilenameError",
+    "DownloadError",
+    "CombineError",
+    "CropError",
+]
+
+
+def __getattr__(name: str):
+    """Lazy imports for optional dependencies."""
+    if name in {
+        "combine_time",
+        "combine_frequency",
+        "can_combine_time",
+        "can_combine_frequency",
+    }:
+        from .combine import (
+            can_combine_frequency,
+            can_combine_time,
+            combine_frequency,
+            combine_time,
+        )
+
+        return {
+            "can_combine_frequency": can_combine_frequency,
+            "combine_frequency": combine_frequency,
+            "can_combine_time": can_combine_time,
+            "combine_time": combine_time,
+        }[name]
+
+    if name in {"list_remote_fits", "download_files"}:
+        from .download import download_files, list_remote_fits
+
+        return {"list_remote_fits": list_remote_fits, "download_files": download_files}[
+            name
+        ]
+
+    if name in {
+        "plot_dynamic_spectrum",
+        "plot_raw_spectrum",
+        "plot_background_subtracted",
+        "TimeAxisConverter",
+    }:
+        from .plotting import (
+            TimeAxisConverter,
+            plot_background_subtracted,
+            plot_dynamic_spectrum,
+            plot_raw_spectrum,
+        )
+
+        return {
+            "plot_dynamic_spectrum": plot_dynamic_spectrum,
+            "plot_raw_spectrum": plot_raw_spectrum,
+            "plot_background_subtracted": plot_background_subtracted,
+            "TimeAxisConverter": TimeAxisConverter,
+        }[name]
+
+    if name == "background_subtract":
+        from .processing import background_subtract
+
+        return background_subtract
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

ecallistolib/combine.py

@@ -0,0 +1,110 @@
+"""
+e-callistolib: Tools for e-CALLISTO FITS dynamic spectra.
+Version 0.2.1
+Sahan S Liyanage (sahanslst@gmail.com)
+Astronomical and Space Science Unit, University of Colombo, Sri Lanka.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterable
+
+import numpy as np
+
+from .io import parse_callisto_filename, read_fits
+from .models import DynamicSpectrum
+
+
+def can_combine_frequency(path1: str | Path, path2: str | Path, time_atol: float = 0.01) -> bool:
+    """
+    True if:
+      - same station/date/time
+      - different focus (01 vs 02)
+      - time axes match within tolerance
+    """
+    p1 = parse_callisto_filename(path1)
+    p2 = parse_callisto_filename(path2)
+
+    if (p1.station != p2.station) or (p1.date_yyyymmdd != p2.date_yyyymmdd) or (p1.time_hhmmss != p2.time_hhmmss):
+        return False
+    if p1.focus == p2.focus:
+        return False
+
+    ds1 = read_fits(path1)
+    ds2 = read_fits(path2)
+    return np.allclose(ds1.time_s, ds2.time_s, atol=time_atol)
+
+
+def combine_frequency(path1: str | Path, path2: str | Path) -> DynamicSpectrum:
+    """
+    Stack two spectra along frequency axis (vertical stacking).
+    """
+    ds1 = read_fits(path1)
+    ds2 = read_fits(path2)
+
+    data = np.vstack([ds1.data, ds2.data])
+    freqs = np.concatenate([ds1.freqs_mhz, ds2.freqs_mhz])
+
+    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)
+
+
+def can_combine_time(paths: Iterable[str | Path], freq_atol: float = 0.01) -> bool:
+    """
+    True if all files:
+      - same station/date/focus
+      - same frequency axis within tolerance
+    """
+    paths = list(paths)
+    if len(paths) < 2:
+        return False
+
+    parts = [parse_callisto_filename(p) for p in paths]
+    stations = {p.station for p in parts}
+    dates = {p.date_yyyymmdd for p in parts}
+    focuses = {p.focus for p in parts}
+
+    if len(stations) != 1 or len(dates) != 1 or len(focuses) != 1:
+        return False
+
+    ref = read_fits(paths[0]).freqs_mhz
+    for p in paths[1:]:
+        freqs = read_fits(p).freqs_mhz
+        if not np.allclose(freqs, ref, atol=freq_atol):
+            return False
+
+    return True
+
+
+def combine_time(paths: Iterable[str | Path]) -> DynamicSpectrum:
+    """
+    Concatenate spectra along time axis (horizontal concatenation).
+    Assumes all have identical frequency axis.
+    """
+    paths = sorted(list(paths), key=lambda p: parse_callisto_filename(p).time_hhmmss)
+
+    ds0 = read_fits(paths[0])
+    combined_data = ds0.data
+    combined_time = ds0.time_s
+    freqs = ds0.freqs_mhz
+
+    for p in paths[1:]:
+        ds = read_fits(p)
+
+        if ds.time_s.size > 1:
+            dt = float(ds.time_s[1] - ds.time_s[0])
+        else:
+            dt = 1.0
+
+        shift = float(combined_time[-1] + dt)
+        adjusted_time = ds.time_s + shift
+
+        combined_data = np.concatenate([combined_data, ds.data], axis=1)
+        combined_time = np.concatenate([combined_time, adjusted_time])
+
+    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)
+

ecallistolib/crop.py

@@ -0,0 +1,225 @@
+"""
+e-callistolib: Tools for e-CALLISTO FITS dynamic spectra.
+Version 0.2.1
+Sahan S Liyanage (sahanslst@gmail.com)
+Astronomical and Space Science Unit, University of Colombo, Sri Lanka.
+"""
+
+from __future__ import annotations
+
+from typing import Optional, Tuple, Union
+
+import numpy as np
+
+from .exceptions import CropError
+from .models import DynamicSpectrum
+
+
+def crop_frequency(
+    ds: DynamicSpectrum,
+    freq_min: Optional[float] = None,
+    freq_max: Optional[float] = None,
+) -> DynamicSpectrum:
+    """
+    Crop a DynamicSpectrum to a frequency range.
+
+    Parameters
+    ----------
+    ds : DynamicSpectrum
+        Input spectrum to crop.
+    freq_min : float, optional
+        Minimum frequency in MHz (inclusive). If None, uses the minimum frequency in the data.
+    freq_max : float, optional
+        Maximum frequency in MHz (inclusive). If None, uses the maximum frequency in the data.
+
+    Returns
+    -------
+    DynamicSpectrum
+        Cropped spectrum containing only frequencies in [freq_min, freq_max].
+
+    Raises
+    ------
+    CropError
+        If the frequency range is invalid or results in empty data.
+    """
+    freqs = ds.freqs_mhz
+    actual_min, actual_max = float(freqs.min()), float(freqs.max())
+
+    if freq_min is None:
+        freq_min = actual_min
+    if freq_max is None:
+        freq_max = actual_max
+
+    if freq_min > freq_max:
+        raise CropError(f"freq_min ({freq_min}) must be <= freq_max ({freq_max})")
+
+    # Find indices within range
+    mask = (freqs >= freq_min) & (freqs <= freq_max)
+
+    if not mask.any():
+        raise CropError(
+            f"No frequencies in range [{freq_min}, {freq_max}] MHz. "
+            f"Data range is [{actual_min}, {actual_max}] MHz."
+        )
+
+    indices = np.where(mask)[0]
+    cropped_data = ds.data[indices, :]
+    cropped_freqs = freqs[indices]
+
+    meta = dict(ds.meta)
+    meta["cropped"] = meta.get("cropped", {})
+    meta["cropped"]["frequency"] = {"min": freq_min, "max": freq_max}
+
+    return ds.copy_with(data=cropped_data, freqs_mhz=cropped_freqs, meta=meta)
+
+
+def crop_time(
+    ds: DynamicSpectrum,
+    time_min: Optional[float] = None,
+    time_max: Optional[float] = None,
+) -> DynamicSpectrum:
+    """
+    Crop a DynamicSpectrum to a time range.
+
+    Parameters
+    ----------
+    ds : DynamicSpectrum
+        Input spectrum to crop.
+    time_min : float, optional
+        Minimum time in seconds (inclusive). If None, uses the minimum time in the data.
+    time_max : float, optional
+        Maximum time in seconds (inclusive). If None, uses the maximum time in the data.
+
+    Returns
+    -------
+    DynamicSpectrum
+        Cropped spectrum containing only times in [time_min, time_max].
+
+    Raises
+    ------
+    CropError
+        If the time range is invalid or results in empty data.
+    """
+    times = ds.time_s
+    actual_min, actual_max = float(times.min()), float(times.max())
+
+    if time_min is None:
+        time_min = actual_min
+    if time_max is None:
+        time_max = actual_max
+
+    if time_min > time_max:
+        raise CropError(f"time_min ({time_min}) must be <= time_max ({time_max})")
+
+    # Find indices within range
+    mask = (times >= time_min) & (times <= time_max)
+
+    if not mask.any():
+        raise CropError(
+            f"No times in range [{time_min}, {time_max}] s. "
+            f"Data range is [{actual_min}, {actual_max}] s."
+        )
+
+    indices = np.where(mask)[0]
+    cropped_data = ds.data[:, indices]
+    cropped_times = times[indices]
+
+    meta = dict(ds.meta)
+    meta["cropped"] = meta.get("cropped", {})
+    meta["cropped"]["time"] = {"min": time_min, "max": time_max}
+
+    return ds.copy_with(data=cropped_data, time_s=cropped_times, meta=meta)
+
+
+def crop(
+    ds: DynamicSpectrum,
+    freq_range: Optional[Tuple[Optional[float], Optional[float]]] = None,
+    time_range: Optional[Tuple[Optional[float], Optional[float]]] = None,
+) -> DynamicSpectrum:
+    """
+    Crop a DynamicSpectrum to specified frequency and/or time ranges.
+
+    Parameters
+    ----------
+    ds : DynamicSpectrum
+        Input spectrum to crop.
+    freq_range : tuple of (min, max), optional
+        Frequency range in MHz. Use None for either bound to keep original.
+    time_range : tuple of (min, max), optional
+        Time range in seconds. Use None for either bound to keep original.
+
+    Returns
+    -------
+    DynamicSpectrum
+        Cropped spectrum.
+
+    Examples
+    --------
+    >>> # Crop to 100-200 MHz
+    >>> cropped = crop(ds, freq_range=(100, 200))
+
+    >>> # Crop to first 60 seconds
+    >>> cropped = crop(ds, time_range=(0, 60))
+
+    >>> # Crop both axes
+    >>> cropped = crop(ds, freq_range=(100, 200), time_range=(0, 60))
+    """
+    result = ds
+
+    if freq_range is not None:
+        freq_min, freq_max = freq_range
+        result = crop_frequency(result, freq_min, freq_max)
+
+    if time_range is not None:
+        time_min, time_max = time_range
+        result = crop_time(result, time_min, time_max)
+
+    return result
+
+
+def slice_by_index(
+    ds: DynamicSpectrum,
+    freq_slice: Optional[slice] = None,
+    time_slice: Optional[slice] = None,
+) -> DynamicSpectrum:
+    """
+    Slice a DynamicSpectrum by array indices.
+
+    Parameters
+    ----------
+    ds : DynamicSpectrum
+        Input spectrum to slice.
+    freq_slice : slice, optional
+        Slice object for frequency axis. E.g., slice(0, 100) for first 100 channels.
+    time_slice : slice, optional
+        Slice object for time axis. E.g., slice(0, 500) for first 500 samples.
+
+    Returns
+    -------
+    DynamicSpectrum
+        Sliced spectrum.
+
+    Examples
+    --------
+    >>> # Get first 100 frequency channels
+    >>> sliced = slice_by_index(ds, freq_slice=slice(0, 100))
+
+    >>> # Get every other time sample
+    >>> sliced = slice_by_index(ds, time_slice=slice(None, None, 2))
+    """
+    if freq_slice is None:
+        freq_slice = slice(None)
+    if time_slice is None:
+        time_slice = slice(None)
+
+    sliced_data = ds.data[freq_slice, time_slice]
+    sliced_freqs = ds.freqs_mhz[freq_slice]
+    sliced_times = ds.time_s[time_slice]
+
+    if sliced_data.size == 0:
+        raise CropError("Slice resulted in empty data array")
+
+    meta = dict(ds.meta)
+    meta["sliced"] = {"freq_slice": str(freq_slice), "time_slice": str(time_slice)}
+
+    return ds.copy_with(data=sliced_data, freqs_mhz=sliced_freqs, time_s=sliced_times, meta=meta)

ecallistolib/download.py

@@ -0,0 +1,147 @@
+"""
+e-callistolib: Tools for e-CALLISTO FITS dynamic spectra.
+Version 0.2.1
+Sahan S Liyanage (sahanslst@gmail.com)
+Astronomical and Space Science Unit, University of Colombo, Sri Lanka.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date
+from pathlib import Path
+from typing import Iterable, List, Optional
+
+import requests
+from bs4 import BeautifulSoup
+
+from .exceptions import DownloadError
+
+DEFAULT_BASE_URL = "http://soleil80.cs.technik.fhnw.ch/solarradio/data/2002-20yy_Callisto/"
+
+
+@dataclass(frozen=True)
+class RemoteFITS:
+    """Represents a remote FITS file available for download."""
+    name: str
+    url: str
+
+
+def list_remote_fits(
+    day: date,
+    hour: int,
+    station_substring: str,
+    base_url: str = DEFAULT_BASE_URL,
+    timeout_s: float = 10.0,
+) -> List[RemoteFITS]:
+    """
+    Return RemoteFITS entries for a given day/hour and station substring.
+
+    Parameters
+    ----------
+    day : date
+        The date to search for files.
+    hour : int
+        UTC hour (0-23) to filter files.
+    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]
+        List of available remote FITS files matching the criteria.
+
+    Raises
+    ------
+    ValueError
+        If hour is not in [0, 23].
+    DownloadError
+        If the remote server cannot be reached or returns an error.
+    """
+    if not (0 <= hour <= 23):
+        raise ValueError("hour must be in [0, 23]")
+
+    url_day = f"{base_url.rstrip('/')}/{day.year}/{day.month:02}/{day.day:02}/"
+
+    try:
+        r = requests.get(url_day, timeout=timeout_s)
+        r.raise_for_status()
+    except requests.exceptions.Timeout:
+        raise DownloadError(f"Timeout while connecting to {url_day}")
+    except requests.exceptions.ConnectionError as e:
+        raise DownloadError(f"Failed to connect to {url_day}: {e}")
+    except requests.exceptions.HTTPError as e:
+        raise DownloadError(f"HTTP error accessing {url_day}: {e}")
+
+    soup = BeautifulSoup(r.content, "html.parser")
+    fits_files = [a.get("href") for a in soup.find_all("a") if a.get("href", "").endswith(".fit.gz")]
+
+    out: List[RemoteFITS] = []
+    station_substring = station_substring.lower().strip()
+
+    for fn in fits_files:
+        if station_substring and (station_substring not in fn.lower()):
+            continue
+        parts = fn.split("_")
+        if len(parts) >= 3:
+            try:
+                hh = int(parts[2][:2])
+                if hh == hour:
+                    out.append(RemoteFITS(name=fn, url=url_day + fn))
+            except ValueError:
+                # Skip files with invalid time format
+                continue
+
+    return out
+
+
+def download_files(
+    items: Iterable[RemoteFITS],
+    out_dir: str | Path,
+    timeout_s: float = 30.0,
+) -> List[Path]:
+    """
+    Download FITS files to a local directory.
+
+    Parameters
+    ----------
+    items : Iterable[RemoteFITS]
+        Remote FITS files to download.
+    out_dir : str or Path
+        Output directory for downloaded files.
+    timeout_s : float
+        HTTP request timeout per file in seconds.
+
+    Returns
+    -------
+    List[Path]
+        List of paths to saved files.
+
+    Raises
+    ------
+    DownloadError
+        If a file cannot be downloaded.
+    """
+    out_dir = Path(out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    saved: List[Path] = []
+    with requests.Session() as s:
+        for it in items:
+            try:
+                r = s.get(it.url, timeout=timeout_s)
+                r.raise_for_status()
+            except requests.exceptions.Timeout:
+                raise DownloadError(f"Timeout downloading {it.name}")
+            except requests.exceptions.RequestException as e:
+                raise DownloadError(f"Failed to download {it.name}: {e}")
+
+            target = out_dir / it.name
+            target.write_bytes(r.content)
+            saved.append(target)
+
+    return saved

ecallistolib/exceptions.py

@@ -0,0 +1,38 @@
+"""
+e-callistolib: Tools for e-CALLISTO FITS dynamic spectra.
+Version 0.2.1
+Sahan S Liyanage (sahanslst@gmail.com)
+Astronomical and Space Science Unit, University of Colombo, Sri Lanka.
+"""
+
+from __future__ import annotations
+
+
+class ECallistoError(Exception):
+    """Base exception for all ecallistolib errors."""
+    pass
+
+
+class InvalidFITSError(ECallistoError):
+    """Raised when a FITS file is invalid or cannot be read."""
+    pass
+
+
+class InvalidFilenameError(ECallistoError):
+    """Raised when a filename doesn't match e-CALLISTO naming convention."""
+    pass
+
+
+class DownloadError(ECallistoError):
+    """Raised when downloading files from the archive fails."""
+    pass
+
+
+class CombineError(ECallistoError):
+    """Raised when spectra cannot be combined."""
+    pass
+
+
+class CropError(ECallistoError):
+    """Raised when cropping parameters are invalid."""
+    pass