ecallistolib 0.2.1__tar.gz → 0.2.3__tar.gz

{ecallistolib-0.2.1/src/ecallistolib.egg-info → ecallistolib-0.2.3}/PKG-INFO

@@ -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')}")
 ```