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

ecallistolib/__init__.py

@@ -1,7 +1,7 @@
 
 """
 e-callistolib: Tools for e-CALLISTO FITS dynamic spectra.
-Version 0.2.1
+Version 0.2.3
 Sahan S Liyanage (sahanslst@gmail.com)
 Astronomical and Space Science Unit, University of Colombo, Sri Lanka.
 """
@@ -14,6 +14,7 @@ from .exceptions import (
     CropError,
     DownloadError,
     ECallistoError,
+    FrequencyOutOfRangeError,
     InvalidFilenameError,
     InvalidFITSError,
 )
@@ -50,6 +51,7 @@ __all__ = [
     "DownloadError",
     "CombineError",
     "CropError",
+    "FrequencyOutOfRangeError",
 ]
 
 
@@ -86,12 +88,14 @@ def __getattr__(name: str):
         "plot_dynamic_spectrum",
         "plot_raw_spectrum",
         "plot_background_subtracted",
+        "plot_light_curve",
         "TimeAxisConverter",
     }:
         from .plotting import (
             TimeAxisConverter,
             plot_background_subtracted,
             plot_dynamic_spectrum,
+            plot_light_curve,
             plot_raw_spectrum,
         )
 
@@ -99,6 +103,7 @@ def __getattr__(name: str):
             "plot_dynamic_spectrum": plot_dynamic_spectrum,
             "plot_raw_spectrum": plot_raw_spectrum,
             "plot_background_subtracted": plot_background_subtracted,
+            "plot_light_curve": plot_light_curve,
             "TimeAxisConverter": TimeAxisConverter,
         }[name]
 

ecallistolib/combine.py

@@ -1,6 +1,6 @@
 """
 e-callistolib: Tools for e-CALLISTO FITS dynamic spectra.
-Version 0.2.1
+Version 0.2.3
 Sahan S Liyanage (sahanslst@gmail.com)
 Astronomical and Space Science Unit, University of Colombo, Sri Lanka.
 """

ecallistolib/crop.py

@@ -1,6 +1,6 @@
 """
 e-callistolib: Tools for e-CALLISTO FITS dynamic spectra.
-Version 0.2.1
+Version 0.2.3
 Sahan S Liyanage (sahanslst@gmail.com)
 Astronomical and Space Science Unit, University of Colombo, Sri Lanka.
 """

ecallistolib/download.py

@@ -1,6 +1,6 @@
 """
 e-callistolib: Tools for e-CALLISTO FITS dynamic spectra.
-Version 0.2.1
+Version 0.2.3
 Sahan S Liyanage (sahanslst@gmail.com)
 Astronomical and Space Science Unit, University of Colombo, Sri Lanka.
 """

ecallistolib/exceptions.py

@@ -1,6 +1,6 @@
 """
 e-callistolib: Tools for e-CALLISTO FITS dynamic spectra.
-Version 0.2.1
+Version 0.2.3
 Sahan S Liyanage (sahanslst@gmail.com)
 Astronomical and Space Science Unit, University of Colombo, Sri Lanka.
 """
@@ -36,3 +36,8 @@ class CombineError(ECallistoError):
 class CropError(ECallistoError):
     """Raised when cropping parameters are invalid."""
     pass
+
+
+class FrequencyOutOfRangeError(ECallistoError):
+    """Raised when the requested frequency is outside the spectrum's frequency range."""
+    pass

ecallistolib/io.py

@@ -1,6 +1,6 @@
 """
 e-callistolib: Tools for e-CALLISTO FITS dynamic spectra.
-Version 0.2.1
+Version 0.2.3
 Sahan S Liyanage (sahanslst@gmail.com)
 Astronomical and Space Science Unit, University of Colombo, Sri Lanka.
 """

ecallistolib/models.py

@@ -1,6 +1,6 @@
 """
 e-callistolib: Tools for e-CALLISTO FITS dynamic spectra.
-Version 0.2.1
+Version 0.2.3
 Sahan S Liyanage (sahanslst@gmail.com)
 Astronomical and Space Science Unit, University of Colombo, Sri Lanka.
 """

ecallistolib/plotting.py

@@ -1,6 +1,6 @@
 """
 e-callistolib: Tools for e-CALLISTO FITS dynamic spectra.
-Version 0.2.1
+Version 0.2.3
 Sahan S Liyanage (sahanslst@gmail.com)
 Astronomical and Space Science Unit, University of Colombo, Sri Lanka.
 """
@@ -155,39 +155,60 @@ def _get_filename_title(ds: DynamicSpectrum, suffix: str) -> str:
     """Generate plot title from DynamicSpectrum source filename."""
     if ds.source is not None:
         filename = ds.source.stem  # Get filename without extension
+        # Also strip .fit if it's a double extension like .fit.gz
+        if filename.endswith(".fit"):
+            filename = filename[:-4]
         return f"{filename}_{suffix}"
     return suffix
 
 
-def plot_raw_spectrum(
+# Conversion factor for Digits to dB (pseudo-calibration)
+# dB = Digits * 2500 / 256 / 25.4 = Digits * 0.384
+DIGITS_TO_DB_FACTOR = 2500.0 / 256.0 / 25.4  # ~0.384
+
+
+def plot_dynamic_spectrum(
     ds: DynamicSpectrum,
+    process: Literal["raw", "background_subtracted", "noise_reduced"] = "raw",
+    clip_low: float | None = None,
+    clip_high: float | None = None,
     title: str | None = None,
-    cmap: str = "viridis",
+    cmap: str = "inferno",
     figsize: tuple[float, float] | None = None,
-    vmin: float | None = None,
-    vmax: float | None = None,
     ax: Optional[plt.Axes] = None,
     show_colorbar: bool = True,
     time_format: Literal["seconds", "ut"] = "seconds",
+    intensity_units: Literal["digits", "dB"] = "digits",
     **imshow_kwargs,
 ) -> tuple["Figure", "Axes", "AxesImage"]:
     """
-    Plot a raw DynamicSpectrum without any processing.
+    Plot a DynamicSpectrum with selectable processing mode.
+
+    This is the main plotting function that supports raw, background-subtracted,
+    and noise-reduced visualization modes with full matplotlib customization.
 
     Parameters
     ----------
     ds : DynamicSpectrum
         The dynamic spectrum to plot.
-    title : str
-        Plot title.
+    process : {"raw", "background_subtracted", "noise_reduced"}
+        Processing mode to apply before plotting:
+        - "raw": Plot the original data without any processing.
+        - "background_subtracted": Subtract mean over time for each frequency.
+        - "noise_reduced": Apply background subtraction and clipping (requires 
+          clip_low and clip_high).
+    clip_low : float | None
+        Lower clipping threshold. Required when process="noise_reduced".
+        Also used for colormap normalization in all modes if provided.
+    clip_high : float | None
+        Upper clipping threshold. Required when process="noise_reduced".
+        Also used for colormap normalization in all modes if provided.
+    title : str | None
+        Plot title. If None, auto-generates from filename and process mode.
     cmap : str
-        Matplotlib colormap name.
+        Matplotlib colormap name (e.g., "inferno", "viridis", "jet").
     figsize : tuple[float, float] | None
         Figure size as (width, height) in inches. Ignored if ax is provided.
-    vmin : float | None
-        Minimum value for colormap normalization.
-    vmax : float | None
-        Maximum value for colormap normalization.
     ax : plt.Axes | None
         Existing axes to plot on. If None, creates a new figure.
     show_colorbar : bool
@@ -195,19 +216,60 @@ def plot_raw_spectrum(
     time_format : {"seconds", "ut"}
         Format for the time axis. "seconds" shows elapsed seconds,
         "ut" shows Universal Time (requires ut_start_sec in metadata).
+    intensity_units : {"digits", "dB"}
+        Units for the intensity axis. "digits" shows raw ADU values,
+        "dB" converts using dB = Digits * 0.384 (pseudo-calibration).
     **imshow_kwargs
         Additional keyword arguments passed to matplotlib's imshow().
+        Common options include:
+        - interpolation: str ("nearest", "bilinear", "bicubic", etc.)
+        - origin: str ("upper", "lower")
+        - alpha: float (transparency)
 
     Returns
     -------
     tuple[Figure, Axes, AxesImage]
         The figure, axes, and image objects.
 
+    Raises
+    ------
+    ValueError
+        If process="noise_reduced" but clip_low or clip_high is not provided.
+
     Example
     -------
     >>> ds = read_fits("spectrum.fit.gz")
-    >>> fig, ax, im = plot_raw_spectrum(ds, figsize=(12, 6), cmap="plasma")
+    >>> # Plot raw spectrum
+    >>> fig, ax, im = plot_dynamic_spectrum(ds, process="raw")
+    >>> # Plot noise-reduced spectrum
+    >>> fig, ax, im = plot_dynamic_spectrum(
+    ...     ds, process="noise_reduced",
+    ...     clip_low=-5, clip_high=20,
+    ...     cmap="jet"
+    ... )
     """
+    from .processing import background_subtract, noise_reduce_mean_clip
+
+    # Validate parameters for noise_reduced mode
+    if process == "noise_reduced":
+        if clip_low is None or clip_high is None:
+            raise ValueError(
+                "When process='noise_reduced', both clip_low and clip_high must be provided."
+            )
+
+    # Apply processing
+    if process == "background_subtracted":
+        ds_plot = background_subtract(ds)
+        title_suffix = "background_subtracted"
+    elif process == "noise_reduced":
+        ds_plot = noise_reduce_mean_clip(
+            ds, clip_low=clip_low, clip_high=clip_high, scale=None
+        )
+        title_suffix = "noise_clipped"
+    else:  # raw
+        ds_plot = ds
+        title_suffix = "raw"
+
     if ax is None:
         fig, ax = plt.subplots(figsize=figsize)
     else:
@@ -215,8 +277,18 @@ def plot_raw_spectrum(
 
     extent, converter = _compute_extent(ds, time_format)
 
+    # Convert to dB if requested
+    plot_data = ds_plot.data
+    vmin, vmax = clip_low, clip_high
+    if intensity_units == "dB":
+        plot_data = plot_data * DIGITS_TO_DB_FACTOR
+        if vmin is not None:
+            vmin = vmin * DIGITS_TO_DB_FACTOR
+        if vmax is not None:
+            vmax = vmax * DIGITS_TO_DB_FACTOR
+
     im = ax.imshow(
-        ds.data,
+        plot_data,
         aspect="auto",
         extent=extent,
         cmap=cmap,
@@ -226,65 +298,64 @@ def plot_raw_spectrum(
     )
     # Use filename-based title if not provided
     if title is None:
-        title = _get_filename_title(ds, "raw")
+        title = _get_filename_title(ds, title_suffix)
     ax.set_title(title)
     _format_time_axis(ax, converter, time_format)
     ax.set_ylabel("Frequency [MHz]")
 
     if show_colorbar:
         cbar = fig.colorbar(im, ax=ax)
-        cbar.set_label("Intensity [DN]")
+        if intensity_units == "dB":
+            cbar.set_label("Intensity [dB]")
+        else:
+            cbar.set_label("Intensity [Digits]")
 
     return fig, ax, im
 
 
-def plot_dynamic_spectrum(
+def plot_raw_spectrum(
     ds: DynamicSpectrum,
     title: str | None = None,
-    cmap: str = "inferno",
+    cmap: str = "viridis",
     figsize: tuple[float, float] | None = None,
-    vmin: float | None = None,
-    vmax: float | None = None,
+    clip_low: float | None = None,
+    clip_high: float | None = None,
     ax: Optional[plt.Axes] = None,
     show_colorbar: bool = True,
     time_format: Literal["seconds", "ut"] = "seconds",
+    intensity_units: Literal["digits", "dB"] = "digits",
     **imshow_kwargs,
 ) -> tuple["Figure", "Axes", "AxesImage"]:
     """
-    Plot a DynamicSpectrum using matplotlib with full customization.
+    Plot a raw DynamicSpectrum without any processing.
 
-    This is the main plotting function with support for all matplotlib
-    imshow parameters including colormap clipping (vmin/vmax), figure size,
-    and custom time axis formats.
+    This is a convenience function that calls plot_dynamic_spectrum with 
+    process="raw" and a default colormap suitable for raw data.
 
     Parameters
     ----------
     ds : DynamicSpectrum
         The dynamic spectrum to plot.
-    title : str
+    title : str | None
         Plot title.
     cmap : str
-        Matplotlib colormap name (e.g., "inferno", "viridis", "magma", "plasma").
+        Matplotlib colormap name. Default is "viridis".
     figsize : tuple[float, float] | None
-        Figure size as (width, height) in inches. Ignored if ax is provided.
-    vmin : float | None
-        Minimum value for colormap normalization (clipping lower bound).
-    vmax : float | None
-        Maximum value for colormap normalization (clipping upper bound).
+        Figure size as (width, height) in inches.
+    clip_low : float | None
+        Minimum value for colormap normalization.
+    clip_high : float | None
+        Maximum value for colormap normalization.
     ax : plt.Axes | None
         Existing axes to plot on. If None, creates a new figure.
     show_colorbar : bool
         Whether to show a colorbar.
     time_format : {"seconds", "ut"}
-        Format for the time axis. "seconds" shows elapsed seconds,
-        "ut" shows Universal Time (requires ut_start_sec in metadata).
+        Format for the time axis.
+    intensity_units : {"digits", "dB"}
+        Units for the intensity axis.
     **imshow_kwargs
         Additional keyword arguments passed to matplotlib's imshow().
-        Common options include:
-        - interpolation: str ("nearest", "bilinear", "bicubic", etc.)
-        - origin: str ("upper", "lower")
-        - alpha: float (transparency)
-        - norm: matplotlib.colors.Normalize (custom normalization)
 
     Returns
     -------
@@ -294,43 +365,22 @@ def plot_dynamic_spectrum(
     Example
     -------
     >>> ds = read_fits("spectrum.fit.gz")
-    >>> ds_reduced = noise_reduce_mean_clip(ds)
-    >>> fig, ax, im = plot_dynamic_spectrum(
-    ...     ds_reduced,
-    ...     title="Noise Reduced",
-    ...     vmin=-5, vmax=20,
-    ...     figsize=(12, 6),
-    ...     cmap="magma"
-    ... )
+    >>> fig, ax, im = plot_raw_spectrum(ds, figsize=(12, 6), cmap="plasma")
     """
-    if ax is None:
-        fig, ax = plt.subplots(figsize=figsize)
-    else:
-        fig = ax.figure
-
-    extent, converter = _compute_extent(ds, time_format)
-
-    im = ax.imshow(
-        ds.data,
-        aspect="auto",
-        extent=extent,
+    return plot_dynamic_spectrum(
+        ds,
+        process="raw",
+        clip_low=clip_low,
+        clip_high=clip_high,
+        title=title,
         cmap=cmap,
-        vmin=vmin,
-        vmax=vmax,
+        figsize=figsize,
+        ax=ax,
+        show_colorbar=show_colorbar,
+        time_format=time_format,
+        intensity_units=intensity_units,
         **imshow_kwargs,
     )
-    # Use filename-based title if not provided
-    if title is None:
-        title = _get_filename_title(ds, "dynamic_spectrum")
-    ax.set_title(title)
-    _format_time_axis(ax, converter, time_format)
-    ax.set_ylabel("Frequency [MHz]")
-
-    if show_colorbar:
-        cbar = fig.colorbar(im, ax=ax)
-        cbar.set_label("Intensity [DN]")
-
-    return fig, ax, im
 
 
 def plot_background_subtracted(
@@ -338,34 +388,34 @@ def plot_background_subtracted(
     title: str | None = None,
     cmap: str = "jet",
     figsize: tuple[float, float] | None = None,
-    vmin: float | None = None,
-    vmax: float | None = None,
+    clip_low: float | None = None,
+    clip_high: float | None = None,
     ax: Optional[plt.Axes] = None,
     show_colorbar: bool = True,
     time_format: Literal["seconds", "ut"] = "seconds",
+    intensity_units: Literal["digits", "dB"] = "digits",
     **imshow_kwargs,
 ) -> tuple["Figure", "Axes", "AxesImage"]:
     """
     Plot a DynamicSpectrum after background subtraction (before clipping).
 
-    This is a convenience function that applies background subtraction
-    (mean removal per frequency channel) and plots the result. This shows
-    the intermediate step before clipping is applied in noise reduction.
+    This is a convenience function that calls plot_dynamic_spectrum with
+    process="background_subtracted".
 
     Parameters
     ----------
     ds : DynamicSpectrum
         The raw dynamic spectrum (will be background-subtracted internally).
-    title : str
+    title : str | None
         Plot title.
     cmap : str
-        Matplotlib colormap name. Default is "RdBu_r" (diverging colormap)
-        which works well for showing positive/negative deviations.
+        Matplotlib colormap name. Default is "jet" which works well for
+        showing positive/negative deviations.
     figsize : tuple[float, float] | None
         Figure size as (width, height) in inches.
-    vmin : float | None
+    clip_low : float | None
         Minimum value for colormap normalization.
-    vmax : float | None
+    clip_high : float | None
         Maximum value for colormap normalization.
     ax : plt.Axes | None
         Existing axes to plot on. If None, creates a new figure.
@@ -373,6 +423,8 @@ def plot_background_subtracted(
         Whether to show a colorbar.
     time_format : {"seconds", "ut"}
         Format for the time axis.
+    intensity_units : {"digits", "dB"}
+        Units for the intensity axis.
     **imshow_kwargs
         Additional keyword arguments passed to matplotlib's imshow().
 
@@ -384,23 +436,183 @@ def plot_background_subtracted(
     Example
     -------
     >>> ds = read_fits("spectrum.fit.gz")
-    >>> fig, ax, im = plot_background_subtracted(ds, vmin=-10, vmax=30)
+    >>> fig, ax, im = plot_background_subtracted(ds, clip_low=-10, clip_high=30)
     """
-    from .processing import background_subtract
-
-    ds_bg = background_subtract(ds)
-    # Use filename-based title if not provided
-    if title is None:
-        title = _get_filename_title(ds, "background_subtracted")
     return plot_dynamic_spectrum(
-        ds_bg,
+        ds,
+        process="background_subtracted",
+        clip_low=clip_low,
+        clip_high=clip_high,
         title=title,
         cmap=cmap,
         figsize=figsize,
-        vmin=vmin,
-        vmax=vmax,
         ax=ax,
         show_colorbar=show_colorbar,
         time_format=time_format,
+        intensity_units=intensity_units,
         **imshow_kwargs,
     )
+
+
+def plot_light_curve(
+    ds: DynamicSpectrum,
+    frequency_mhz: float,
+    process: Literal["raw", "background_subtracted", "noise_reduced"] = "raw",
+    title: str | None = None,
+    figsize: tuple[float, float] | None = None,
+    ax: Optional[plt.Axes] = None,
+    time_format: Literal["seconds", "ut"] = "seconds",
+    clip_low: float | None = None,
+    clip_high: float | None = None,
+    intensity_units: Literal["digits", "dB"] = "digits",
+    **plot_kwargs,
+) -> tuple["Figure", "Axes", "plt.Line2D"]:
+    """
+    Plot a light curve (intensity vs time) at a specific frequency.
+
+    This function extracts the intensity values at the frequency channel closest
+    to the specified frequency and plots them against time. The data can be
+    plotted raw, after background subtraction, or after full noise reduction.
+
+    Parameters
+    ----------
+    ds : DynamicSpectrum
+        The dynamic spectrum to extract the light curve from.
+    frequency_mhz : float
+        The target frequency in MHz. The function will use the closest
+        available frequency channel in the spectrum.
+    process : {"raw", "background_subtracted", "noise_reduced"}
+        Processing to apply before plotting:
+        - "raw": Use the original data without any processing.
+        - "background_subtracted": Subtract mean over time for each frequency.
+        - "noise_reduced": Apply full noise reduction (requires clip_low/clip_high).
+    title : str | None
+        Plot title. If None, generates title from filename and frequency.
+    figsize : tuple[float, float] | None
+        Figure size as (width, height) in inches. Ignored if ax is provided.
+    ax : plt.Axes | None
+        Existing axes to plot on. If None, creates a new figure.
+    time_format : {"seconds", "ut"}
+        Format for the time axis. "seconds" shows elapsed seconds,
+        "ut" shows Universal Time (requires ut_start_sec in metadata).
+    clip_low : float | None
+        Lower clipping threshold for noise reduction. Required if process="noise_reduced".
+    clip_high : float | None
+        Upper clipping threshold for noise reduction. Required if process="noise_reduced".
+    intensity_units : {"digits", "dB"}
+        Units for the intensity axis. "digits" shows raw ADU values,
+        "dB" converts using dB = Digits * 0.384 (pseudo-calibration).
+    **plot_kwargs
+        Additional keyword arguments passed to matplotlib's plot().
+
+    Returns
+    -------
+    tuple[Figure, Axes, Line2D]
+        The figure, axes, and line objects.
+
+    Raises
+    ------
+    FrequencyOutOfRangeError
+        If the requested frequency is outside the spectrum's frequency range.
+    ValueError
+        If process="noise_reduced" but clip_low or clip_high is not provided.
+
+    Example
+    -------
+    >>> ds = read_fits("spectrum.fit.gz")
+    >>> # Plot raw light curve at 60 MHz
+    >>> fig, ax, line = plot_light_curve(ds, frequency_mhz=60, process="raw")
+    >>> # Plot noise-reduced light curve with custom clipping
+    >>> fig, ax, line = plot_light_curve(
+    ...     ds, frequency_mhz=60, process="noise_reduced",
+    ...     clip_low=-5, clip_high=20
+    ... )
+    """
+    from .exceptions import FrequencyOutOfRangeError
+    from .processing import background_subtract, noise_reduce_mean_clip
+
+    # Validate frequency is within range
+    freq_min = float(ds.freqs_mhz.min())
+    freq_max = float(ds.freqs_mhz.max())
+
+    if frequency_mhz < freq_min or frequency_mhz > freq_max:
+        raise FrequencyOutOfRangeError(
+            f"Requested frequency {frequency_mhz} MHz is outside the spectrum's "
+            f"frequency range [{freq_min:.2f}, {freq_max:.2f}] MHz."
+        )
+
+    # Validate clip parameters for noise_reduced
+    if process == "noise_reduced":
+        if clip_low is None or clip_high is None:
+            raise ValueError(
+                "When process='noise_reduced', both clip_low and clip_high must be provided."
+            )
+
+    # Find the closest frequency channel
+    freq_idx = int(np.argmin(np.abs(ds.freqs_mhz - frequency_mhz)))
+    actual_freq = float(ds.freqs_mhz[freq_idx])
+
+    # Apply processing
+    if process == "background_subtracted":
+        ds_processed = background_subtract(ds)
+    elif process == "noise_reduced":
+        ds_processed = noise_reduce_mean_clip(
+            ds, clip_low=clip_low, clip_high=clip_high, scale=None
+        )
+    else:  # raw
+        ds_processed = ds
+
+    # Extract light curve data
+    light_curve = ds_processed.data[freq_idx, :]
+
+    # Convert to dB if requested
+    if intensity_units == "dB":
+        light_curve = light_curve * DIGITS_TO_DB_FACTOR
+
+    # Create figure and axes
+    if ax is None:
+        fig, ax = plt.subplots(figsize=figsize)
+    else:
+        fig = ax.figure
+
+    # Prepare time axis
+    if time_format == "ut":
+        converter = TimeAxisConverter.from_dynamic_spectrum(ds)
+        time_values = ds.time_s + converter.ut_start_sec
+        ax.set_xlabel("Time [UT]")
+        # Format x-tick labels as UT times
+        from matplotlib.ticker import FuncFormatter
+
+        def fmt(x, pos):
+            return converter.seconds_to_ut(x - converter.ut_start_sec)
+
+        ax.xaxis.set_major_formatter(FuncFormatter(fmt))
+    else:
+        time_values = ds.time_s
+        ax.set_xlabel("Time [s]")
+
+    # Plot the light curve
+    (line,) = ax.plot(time_values, light_curve, **plot_kwargs)
+
+    # Set title
+    if title is None:
+        # Map process name to title suffix
+        title_suffix = "noise_clipped" if process == "noise_reduced" else process
+        if ds.source is not None:
+            filename = ds.source.stem
+            # Strip .fit if it's a double extension like .fit.gz
+            if filename.endswith(".fit"):
+                filename = filename[:-4]
+            title = f"{filename}_light_curve_{actual_freq:.1f}MHz_{title_suffix}"
+        else:
+            title = f"Light Curve @ {actual_freq:.1f} MHz ({title_suffix})"
+
+    ax.set_title(title)
+
+    if intensity_units == "dB":
+        ax.set_ylabel("Intensity [dB]")
+    else:
+        ax.set_ylabel("Intensity [Digits]")
+
+    return fig, ax, line
+

ecallistolib/processing.py

@@ -1,6 +1,6 @@
 """
 e-callistolib: Tools for e-CALLISTO FITS dynamic spectra.
-Version 0.2.1
+Version 0.2.3
 Sahan S Liyanage (sahanslst@gmail.com)
 Astronomical and Space Science Unit, University of Colombo, Sri Lanka.
 """
@@ -14,8 +14,8 @@ from .models import DynamicSpectrum
 
 def noise_reduce_mean_clip(
     ds: DynamicSpectrum,
-    clip_low: float = -5.0,
-    clip_high: float = 20.0,
+    clip_low: float,
+    clip_high: float,
     scale: float | None = (2500.0 / 255.0 / 25.4),
 ) -> DynamicSpectrum:
     """

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ecallistolib
-Version: 0.2.1
+Version: 0.2.3
 Summary: Tools to download, read, process, and plot e-CALLISTO FITS dynamic spectra.
 Author: Sahan S. Liyanage
 License: MIT
@@ -70,6 +70,20 @@ A Python library to **download**, **read**, **process**, and **plot** e-CALLISTO
 
 ## Installation
 
+
+### From PyPI (Stable)
+
+```bash
+pip install ecallistolib
+```
+
+### Optional Dependencies
+
+Install optional features as needed:
+
+```bash
+pip install ecallistolib"[download,plot]"
+```
 ### From Source (Development)
 
 ```bash
@@ -103,11 +117,14 @@ import ecallistolib as ecl
 # Read a FITS file
 spectrum = ecl.read_fits("ALASKA_20230101_120000_01.fit.gz")
 
-# Apply noise reduction
-cleaned = ecl.noise_reduce_mean_clip(spectrum)
-
-# Plot the result
-fig, ax, im = ecl.plot_dynamic_spectrum(cleaned, title="Solar Radio Burst")
+# Plot with different processing modes
+fig, ax, im = ecl.plot_dynamic_spectrum(
+    spectrum, 
+    process="noise_reduced",
+    clip_low=-5, 
+    clip_high=20,
+    title="Solar Radio Burst"
+)
 ```
 
 ---
@@ -186,14 +203,11 @@ import ecallistolib as ecl
 
 spectrum = ecl.read_fits("my_spectrum.fit.gz")
 
-# Apply noise reduction with default parameters
-cleaned = ecl.noise_reduce_mean_clip(spectrum)
-
-# Or customize the parameters
+# Apply noise reduction with required clipping values
 cleaned = ecl.noise_reduce_mean_clip(
     spectrum,
-    clip_low=-5.0,              # Lower clipping threshold
-    clip_high=20.0,             # Upper clipping threshold
+    clip_low=-5.0,              # Lower clipping threshold (required)
+    clip_high=20.0,             # Upper clipping threshold (required)
     scale=2500.0 / 255.0 / 25.4 # Scaling factor (None to disable)
 )
 
@@ -240,7 +254,7 @@ spectrum = ecl.read_fits("my_spectrum.fit.gz")
 cropped = ecl.crop_frequency(spectrum, freq_min=100, freq_max=300)
 
 # Crop to specific time range (in seconds)
-cropped = ecf.crop_time(spectrum, time_min=10, time_max=60)
+cropped = ecl.crop_time(spectrum, time_min=10, time_max=60)
 
 # Crop both axes at once
 cropped = ecl.crop(spectrum, freq_range=(100, 300), time_range=(10, 60))
@@ -319,28 +333,28 @@ if ecl.can_combine_time(files):
 
 ### Plotting
 
-Create dynamic spectrum visualizations with full customization:
+Create dynamic spectrum visualizations with selectable processing modes:
 
 ```python
 import ecallistolib as ecl
 import matplotlib.pyplot as plt
 
-spectrum = ecf.read_fits("my_spectrum.fit.gz")
-cleaned = ecf.noise_reduce_mean_clip(spectrum)
+spectrum = ecl.read_fits("my_spectrum.fit.gz")
 
-# Basic plot
-fig, ax, im = ecf.plot_dynamic_spectrum(cleaned, title="Solar Radio Observation")
+# Plot raw spectrum
+fig, ax, im = ecl.plot_dynamic_spectrum(spectrum, process="raw")
 plt.show()
 
-# Customized plot with clipping values, colormap, and figure size
-fig, ax, im = ecf.plot_dynamic_spectrum(
-    cleaned,
+# Plot noise-reduced spectrum with required clipping values
+fig, ax, im = ecl.plot_dynamic_spectrum(
+    spectrum,
+    process="noise_reduced",     # Apply noise reduction
+    clip_low=-5,                  # Lower clipping bound (required)
+    clip_high=20,                 # Upper clipping bound (required)
     title="Type III Solar Burst",
-    cmap="magma",            # Matplotlib colormap
-    vmin=-5,                  # Colormap lower bound
-    vmax=20,                  # Colormap upper bound
-    figsize=(12, 6),          # Figure size in inches
-    interpolation="bilinear"  # Any matplotlib imshow kwarg
+    cmap="magma",
+    figsize=(12, 6),
+    interpolation="bilinear"
 )
 plt.savefig("spectrum.png", dpi=150, bbox_inches="tight")
 ```
@@ -348,12 +362,12 @@ plt.savefig("spectrum.png", dpi=150, bbox_inches="tight")
 #### Plotting Raw Data
 
 ```python
-import ecallistolib as ecf
+import ecallistolib as ecl
 
-spectrum = ecf.read_fits("my_spectrum.fit.gz")
+spectrum = ecl.read_fits("my_spectrum.fit.gz")
 
 # Plot raw spectrum without any processing
-fig, ax, im = ecf.plot_raw_spectrum(
+fig, ax, im = ecl.plot_raw_spectrum(
     spectrum,
     title="Raw Spectrum",
     cmap="viridis",
@@ -364,15 +378,15 @@ fig, ax, im = ecf.plot_raw_spectrum(
 #### Plotting Background Subtracted (Before Clipping)
 
 ```python
-import ecallistolib as ecf
+import ecallistolib as ecl
 
-spectrum = ecf.read_fits("my_spectrum.fit.gz")
+spectrum = ecl.read_fits("my_spectrum.fit.gz")
 
 # Plot after background subtraction but before clipping
-fig, ax, im = ecf.plot_background_subtracted(
+fig, ax, im = ecl.plot_background_subtracted(
     spectrum,
-    vmin=-10,
-    vmax=30,
+    clip_low=-10,
+    clip_high=30,
     cmap="RdBu_r"  # Diverging colormap for +/- values
 )
 ```
@@ -382,28 +396,46 @@ fig, ax, im = ecf.plot_background_subtracted(
 Display time in seconds or Universal Time (UT):
 
 ```python
-import ecallistolib as ecf
+import ecallistolib as ecl
 
-spectrum = ecf.read_fits("my_spectrum.fit.gz")
+spectrum = ecl.read_fits("my_spectrum.fit.gz")
 
 # Default: time in seconds
-ecf.plot_dynamic_spectrum(spectrum, time_format="seconds")
+ecl.plot_dynamic_spectrum(spectrum, time_format="seconds")
 
 # Time in UT format (HH:MM:SS)
-ecf.plot_dynamic_spectrum(spectrum, time_format="ut")
+ecl.plot_dynamic_spectrum(spectrum, time_format="ut")
+```
+
+#### Intensity Units
+
+Choose between raw digital values (Digits/ADU) or pseudo-calibrated dB:
+
+```python
+import ecallistolib as ecl
+
+spectrum = ecl.read_fits("my_spectrum.fit.gz")
+
+# Default: intensity in Digits (raw ADU values)
+ecl.plot_dynamic_spectrum(spectrum, intensity_units="digits")
+
+# Convert to dB using: dB = Digits * 0.384 (pseudo-calibration)
+ecl.plot_dynamic_spectrum(spectrum, intensity_units="dB")
 ```
 
+> **Note:** The dB conversion uses the formula: dB = Digits × 2500 / 256 / 25.4 ≈ Digits × 0.384
+
 #### Time Axis Converter
 
 Convert between elapsed seconds and UT time programmatically:
 
 ```python
-import ecallistolib as ecf
+import ecallistolib as ecl
 
-spectrum = ecf.read_fits("my_spectrum.fit.gz")
+spectrum = ecl.read_fits("my_spectrum.fit.gz")
 
 # Create converter from spectrum metadata
-converter = ecf.TimeAxisConverter.from_dynamic_spectrum(spectrum)
+converter = ecl.TimeAxisConverter.from_dynamic_spectrum(spectrum)
 
 # Convert seconds to UT
 print(converter.seconds_to_ut(100))    # "12:01:40"
@@ -418,19 +450,72 @@ print(converter.ut_to_seconds("13:00:00"))  # 3600.0
 
 ```python
 import matplotlib.pyplot as plt
-import ecallistolib as ecf
+import ecallistolib as ecl
 
 fig, axes = plt.subplots(1, 2, figsize=(14, 5))
 
-spectrum1 = ecf.read_fits("file1.fit.gz")
-spectrum2 = ecf.read_fits("file2.fit.gz")
+spectrum1 = ecl.read_fits("file1.fit.gz")
+spectrum2 = ecl.read_fits("file2.fit.gz")
 
-ecf.plot_raw_spectrum(spectrum1, ax=axes[0], title="Raw")
-ecf.plot_dynamic_spectrum(
-    ecf.noise_reduce_mean_clip(spectrum2), 
+ecl.plot_dynamic_spectrum(spectrum1, process="raw", ax=axes[0], title="Raw")
+ecl.plot_dynamic_spectrum(
+    spectrum2, 
+    process="noise_reduced",
     ax=axes[1], 
     title="Noise Reduced",
-    vmin=-5, vmax=20
+    clip_low=-5, clip_high=20
+)
+
+plt.tight_layout()
+plt.show()
+```
+
+#### Light Curve Plotting
+
+Plot intensity vs time at a specific frequency:
+
+```python
+import ecallistolib as ecl
+import matplotlib.pyplot as plt
+
+spectrum = ecl.read_fits("my_spectrum.fit.gz")
+
+# Plot raw light curve at 60 MHz
+fig, ax, line = ecl.plot_light_curve(spectrum, frequency_mhz=60, process="raw")
+plt.show()
+
+# Plot background-subtracted light curve
+fig, ax, line = ecl.plot_light_curve(
+    spectrum, frequency_mhz=60, process="background_subtracted"
+)
+plt.show()
+
+# Plot noise-reduced light curve (must provide clip values)
+fig, ax, line = ecl.plot_light_curve(
+    spectrum,
+    frequency_mhz=60,
+    process="noise_reduced",
+    clip_low=-5,
+    clip_high=20
+)
+plt.show()
+```
+
+Compare all three processing modes:
+
+```python
+import ecallistolib as ecl
+import matplotlib.pyplot as plt
+
+spectrum = ecl.read_fits("my_spectrum.fit.gz")
+
+fig, axes = plt.subplots(3, 1, figsize=(12, 10))
+
+ecl.plot_light_curve(spectrum, 60, process="raw", ax=axes[0], title="Raw")
+ecl.plot_light_curve(spectrum, 60, process="background_subtracted", ax=axes[1], title="BG Sub")
+ecl.plot_light_curve(
+    spectrum, 60, process="noise_reduced", ax=axes[2], title="Noise Reduced",
+    clip_low=-5, clip_high=20
 )
 
 plt.tight_layout()
@@ -638,36 +723,65 @@ Concatenate spectra horizontally (time concatenation).
 
 ### Plotting Functions
 
-#### `plot_dynamic_spectrum(ds, title="...", cmap="inferno", figsize=None, vmin=None, vmax=None, ax=None, show_colorbar=True, time_format="seconds", **imshow_kwargs)`
+#### `plot_dynamic_spectrum(ds, process="raw", clip_low=None, clip_high=None, title=None, cmap="inferno", figsize=None, ax=None, show_colorbar=True, time_format="seconds", intensity_units="digits", **imshow_kwargs)`
 
-Plot a dynamic spectrum with full customization.
+Plot a dynamic spectrum with selectable processing mode.
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `ds` | `DynamicSpectrum` | — | Spectrum to plot |
-| `title` | `str` | `"Dynamic Spectrum"` | Plot title |
+| `process` | `str` | `"raw"` | Processing mode: `"raw"`, `"background_subtracted"`, or `"noise_reduced"` |
+| `clip_low` | `float \| None` | `None` | Lower clipping bound (required for `"noise_reduced"`) |
+| `clip_high` | `float \| None` | `None` | Upper clipping bound (required for `"noise_reduced"`) |
+| `title` | `str \| None` | `None` | Plot title (auto-generated if `None`) |
 | `cmap` | `str` | `"inferno"` | Matplotlib colormap |
 | `figsize` | `tuple \| None` | `None` | Figure size as `(width, height)` in inches |
-| `vmin` | `float \| None` | `None` | Colormap lower bound (clipping) |
-| `vmax` | `float \| None` | `None` | Colormap upper bound (clipping) |
 | `ax` | `Axes \| None` | `None` | Existing axes (creates new if `None`) |
 | `show_colorbar` | `bool` | `True` | Whether to display colorbar |
 | `time_format` | `str` | `"seconds"` | `"seconds"` or `"ut"` for time axis format |
+| `intensity_units` | `str` | `"digits"` | `"digits"` (raw ADU) or `"dB"` (pseudo-calibrated) |
 | `**imshow_kwargs` | — | — | Additional kwargs passed to `matplotlib.imshow()` |
 
 **Returns:** Tuple of `(fig, ax, im)`.
 
+**Raises:** `ValueError` if `process="noise_reduced"` without `clip_low` and `clip_high`.
+
 ---
 
-#### `plot_raw_spectrum(ds, title="Raw Spectrum", cmap="viridis", ...)`
+#### `plot_raw_spectrum(ds, clip_low=None, clip_high=None, title=None, cmap="viridis", ...)`
 
-Plot raw spectrum data without any processing. Accepts the same parameters as `plot_dynamic_spectrum`.
+Convenience function that calls `plot_dynamic_spectrum` with `process="raw"`.
 
 ---
 
-#### `plot_background_subtracted(ds, title="Background Subtracted", cmap="RdBu_r", ...)`
+#### `plot_background_subtracted(ds, clip_low=None, clip_high=None, title=None, cmap="jet", ...)`
+
+Convenience function that calls `plot_dynamic_spectrum` with `process="background_subtracted"`.
+
+---
+
+#### `plot_light_curve(ds, frequency_mhz, process="raw", title=None, figsize=None, ax=None, time_format="seconds", clip_low=None, clip_high=None, **plot_kwargs)`
+
+Plot a light curve (intensity vs time) at a specific frequency.
 
-Plot spectrum after background subtraction (before clipping). Automatically applies `background_subtract()` and plots the result. Accepts the same parameters as `plot_dynamic_spectrum`.
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `ds` | `DynamicSpectrum` | — | Spectrum to extract light curve from |
+| `frequency_mhz` | `float` | — | Target frequency in MHz |
+| `process` | `str` | `"raw"` | Processing mode: `"raw"`, `"background_subtracted"`, or `"noise_reduced"` |
+| `title` | `str \| None` | `None` | Plot title (auto-generated if `None`) |
+| `figsize` | `tuple \| None` | `None` | Figure size as `(width, height)` in inches |
+| `ax` | `Axes \| None` | `None` | Existing axes (creates new if `None`) |
+| `time_format` | `str` | `"seconds"` | `"seconds"` or `"ut"` for time axis format |
+| `clip_low` | `float \| None` | `None` | Lower clip threshold (required for `"noise_reduced"`) |
+| `clip_high` | `float \| None` | `None` | Upper clip threshold (required for `"noise_reduced"`) |
+| `**plot_kwargs` | — | — | Additional kwargs passed to `matplotlib.plot()` |
+
+**Returns:** Tuple of `(fig, ax, line)`.
+
+**Raises:**
+- `FrequencyOutOfRangeError` if frequency is outside spectrum's range.
+- `ValueError` if `process="noise_reduced"` without `clip_low` and `clip_high`.
 
 ---
 
@@ -701,22 +815,23 @@ The library provides a hierarchy of custom exceptions for robust error handling:
 | `DownloadError` | Raised when downloading files from the archive fails |
 | `CombineError` | Raised when spectra cannot be combined |
 | `CropError` | Raised when cropping parameters are invalid |
+| `FrequencyOutOfRangeError` | Raised when the requested frequency is outside the spectrum's range |
 
 #### Error Handling Example
 
 ```python
-import ecallistolib as ecf
+import ecallistolib as ecl
 from ecallistolib import InvalidFITSError, CropError
 
 try:
-    spectrum = ecf.read_fits("corrupted_file.fit")
+    spectrum = ecl.read_fits("corrupted_file.fit")
 except FileNotFoundError:
     print("File not found")
 except InvalidFITSError as e:
     print(f"Invalid FITS file: {e}")
 
 try:
-    cropped = ecf.crop(spectrum, freq_range=(1000, 2000))  # Out of range
+    cropped = ecl.crop(spectrum, freq_range=(1000, 2000))  # Out of range
 except CropError as e:
     print(f"Cropping failed: {e}")
 ```
@@ -729,24 +844,24 @@ except CropError as e:
 
 ```python
 from datetime import date
-import ecallistolib as ecf
+import ecallistolib as ecl
 import matplotlib.pyplot as plt
 
 # 1. Download data
-remote = ecf.list_remote_fits(date(2023, 6, 15), hour=12, station_substring="alaska")
-paths = ecf.download_files(remote[:2], out_dir="./data")
+remote = ecl.list_remote_fits(date(2023, 6, 15), hour=12, station_substring="alaska")
+paths = ecl.download_files(remote[:2], out_dir="./data")
 
 # 2. Read and combine
-if ecf.can_combine_time(paths):
-    spectrum = ecf.combine_time(paths)
+if ecl.can_combine_time(paths):
+    spectrum = ecl.combine_time(paths)
 else:
-    spectrum = ecf.read_fits(paths[0])
+    spectrum = ecl.read_fits(paths[0])
 
 # 3. Process
-cleaned = ecf.noise_reduce_mean_clip(spectrum)
+cleaned = ecl.noise_reduce_mean_clip(spectrum)
 
 # 4. Plot
-fig, ax, im = ecf.plot_dynamic_spectrum(
+fig, ax, im = ecl.plot_dynamic_spectrum(
     cleaned,
     title=f"e-CALLISTO Observation - {spectrum.meta.get('station', 'Unknown')}",
     cmap="plasma"
@@ -758,9 +873,9 @@ plt.show()
 ### Working with Metadata
 
 ```python
-import ecallistolib as ecf
+import ecallistolib as ecl
 
-spectrum = ecf.read_fits("my_file.fit.gz")
+spectrum = ecl.read_fits("my_file.fit.gz")
 
 # Access metadata
 print(f"Station: {spectrum.meta.get('station')}")
@@ -768,7 +883,7 @@ print(f"Date: {spectrum.meta.get('date')}")
 print(f"UT Start: {spectrum.meta.get('ut_start_sec')} seconds")
 
 # After processing, metadata is preserved and extended
-processed = ecf.noise_reduce_mean_clip(spectrum)
+processed = ecl.noise_reduce_mean_clip(spectrum)
 print(f"Processing applied: {processed.meta.get('noise_reduction')}")
 ```
 

ecallistolib-0.2.3.dist-info/RECORD

@@ -0,0 +1,14 @@
+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,,

{ecallistolib-0.2.1.dist-info → ecallistolib-0.2.3.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.10.1)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

ecallistolib-0.2.1.dist-info/RECORD

@@ -1,14 +0,0 @@
-ecallistolib/__init__.py,sha256=9O277WBX99gg3MqWcv-tiaQxB6IKeMfHM91uDJP_9O0,2833
-ecallistolib/combine.py,sha256=79LuR2HngpTbaM2xBg7aqUGK_1xkK3RomKmomWG2FpE,3315
-ecallistolib/crop.py,sha256=zcAsd5XP-_lG9exBPUFYt4PJslzxLabjSLvbdSADhDk,6383
-ecallistolib/download.py,sha256=gUmDLZDjyVIElzqZnGoAREkpOaxYNsAUDeujlGwd_o4,4114
-ecallistolib/exceptions.py,sha256=F0EdRCi54ut8qQDtDVZxhGn3P_JbsoQ8hNVxKCFpO5s,879
-ecallistolib/io.py,sha256=e-BMtWvILsqs2ua89Ysa2vwZ9s4mDukDGVPYDA3ed-E,3686
-ecallistolib/models.py,sha256=v8bl1fN3jKHVbQmpfVSv3ZusFrkWZJ1ciZkuufygmjE,1299
-ecallistolib/plotting.py,sha256=RhTJK5qGwCcBRRJP-mDNyGoWzd5diHCbx1IyXK8PraU,12296
-ecallistolib/processing.py,sha256=eBH3uGt3RmGM1NRdH_wJ7AAcVeadk9te-pHc9pWy2Lo,1976
-ecallistolib-0.2.1.dist-info/licenses/LICENSE,sha256=WunjkzsBGyy9vIQxfNe_GDV1yKBQJ-0WbFt4AXZ5Rvc,1073
-ecallistolib-0.2.1.dist-info/METADATA,sha256=LPysk03p7kqiyr311C2R-CKwYWnq_yVgyK4n8eLSlMM,22583
-ecallistolib-0.2.1.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
-ecallistolib-0.2.1.dist-info/top_level.txt,sha256=DmLjR5jlE2i2mQXou5gyCpaHOOlNs4DIQyCPoGXhsbc,13
-ecallistolib-0.2.1.dist-info/RECORD,,