astrotrack 0.1.0__tar.gz

astrotrack-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Gabriella Mariam Zahra Rajpoot
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

astrotrack-0.1.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: astrotrack
+Version: 0.1.0
+Summary: A tool for analysing and investigating LEO satellite flyover occurrences with contamination in radio astronomy observational data.
+Author-email: Gabriella Mariam Zahra Rajpoot <LetterToGabi@gmail.com>
+License: BSD 3-Clause License
+Keywords: astronomy,satellite,radio,signal,analysis,LEO,skyfield
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.25
+Requires-Dist: matplotlib>=3.5
+Requires-Dist: pandas>=2.0
+Requires-Dist: scipy>=1.10
+Requires-Dist: astropy>=7.0
+Requires-Dist: skyfield>=1.50
+Requires-Dist: h5py>=3.10
+Requires-Dist: tabulate>=0.9
+Requires-Dist: tqdm>=4.60
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=6.0; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Dynamic: license-file
+
+# astrotrack: Characterising LEO Satellite RFI in Wide-Field Radio Astronomy
+
+![CI](https://github.com/Gabriella8080/astrotrack/actions/workflows/CI.yml/badge.svg) ![License](https://img.shields.io/badge/license-BSD--3-blue)
+
+## Overview
+
+`astrotrack` is an open-source Python package for characterising potential Low Earth Orbit (LEO) satellite interference in wide-field radio astronomy observations. While interferometric arrays are able to spatially localise LEO satellite radiation, wide-beam radiometers like REACH (de Lera Acedo et al. 2022) integrate the total sky power into a frequency spectrum and therefore lack equivalent strategies for identifying satellite-generated contamination. To address this limitation, `astrotrack` provides tools for combining Two-Line Element (TLE) data with site-specific observational constraints to identify LEO satellite flyovers and investigate their potential association with radio frequency interference (RFI).
+
+> **Accompanying Paper**: *'astrotrack: Characterising LEO Satellite Interference in Wide-Field Radio Astronomy'*, in preparation.
+
+<br>
+<div align="center">
+  <img src="docs/images/animated_satellites.gif" width="600">
+  <p><em>3-D trajectory animation generated by AstroTrack's <code>satcon_animate</code> module of Eutelsat OneWeb satellite flyovers at the REACH site in the Karoo radio reserve, South Africa on 15 June 2025.</em></p>
+</div>
+<br>
+
+## Repository Structure
+
+| Paths | Description |
+| ----- | ------------|
+| [`data/`](data/) | CSV horizon profiles, including a [baseline](data/horizon-profiles/baseline-horizon.csv) and [REACH radiometer](data/horizon-profiles/REACH-horizon.csv) horizon profile. Alongside this, the [TLE catalogue](data/TLE-catalogues/TLEs.txt) used in exemplar and experimental analyses is provided. |
+| [`docs/`](docs/) | [Example usage](docs/examples/) of functionalities across `astrotrack` modules. |
+| [`astrotrack/`](astrotrack/) | `astrotrack` Python package source code.  |
+| [`notebooks/astrotrack_demo/`](/notebooks/astrotrack_demo/) | [Demonstration notebook](notebooks/astrotrack_demo/01_astrotrack_demo.ipynb) showing example `astrotrack` workflow. |
+| [`notebooks/astrotrack_results/`](notebooks/astrotrack_results/) | Notebooks documenting experimental results and analyses. |
+| [`tests`](tests/) | Unit tests validating `astrotrack` functionalities and edge case performance.|
+| [`environment.yml`](environment.yml) | Conda environment for `astrotrack` specifying required dependencies.|
+
+
+## Data Availability
+
+Raw HDF5 files containing PSD observations used for comparison are proprietary to the REACH collaboration and are therefore not made publicly available. The publicly available 12,270 TLEs used in this work are provided in a [CSV file](data/TLE-catalogues/TLEs.txt) downloaded from [Space-Track](https://www.space-track.org) on 17:10:37 UTC 14 June 2025.
+
+
+## `astrotrack` Installation
+
+To install `astrotrack` from source, follow the instructions below:
+
+```bash
+conda env create -f environment.yml
+conda activate astrotrack
+pip install -e .
+```
+
+The package can then be imported using:
+
+```bash
+import astrotrack
+```
+
+`astrotrack` is recommended to be used with the provided Conda [environment](environment.yml).
+
+
+## Quick Start
+
+The below example demonstrates how to initialise `astrotrack` using a provided TLE catalogue along with user-defined observational constraints, the satellite constellation of interest, and a target date:
+
+```python
+from datetime import datetime
+from astrotrack.preprocess import load_satellite_data
+
+data = load_satellite_data(
+    tle_file="LEO_TLE_file.txt",
+    target_date=datetime(2025, 1, 18, 12, 25, 8),
+    obs_len=3600, 
+    traj_res=60,
+    obs_lat=51.5,
+    obs_lon=-0.1,
+    R=2000,
+    horizon_data="Horizon-Profile.csv", 
+    satcon="STARLINK"
+)
+```
+
+> **Generating Epoch Times with Skyfield**: The following code can be used to initialise a time array for satellite propagation.
+>
+>```python
+>import numpy as np
+>from skyfield.api import load
+>
+># Create a timescale object:
+>ts = load.timescale()
+>
+># Define orbit duration:
+>orbit_duration = np.arange(0, 3600, 1)  # in seconds
+>
+># Generate time array:
+>epochs_of_orbit = ts.utc(2025, 1, 1, 10, 15, 0 + orbit_duration)
+>```
+>
+
+
+## Example Usage & Workflow
+
+`astrotrack` is organised into five modules. A typical workflow begins with initialising and structuring satellite Two-Line Element (TLE) data for analysis, after which the subsequent modules derive orbital properties, Doppler behaviour with respect to a ground-based experiment, animations, and enable spectral associations.
+
+<br>
+<div align="center">
+  <img src="docs/images/package-modules.png" width="600">
+</div>
+<br>
+
+- [`preprocess`](): Loads and filters satellite TLE data provided by the user.
+- [`satcon_properties`](): Filters, analyses, and visualises satellite trajectories as well as their metrics. 
+- [`doppler_analysis`](): Evaluates Doppler shifts and detectability relative to a user-defined instrument's specifications.
+- [`satcon_animate`](): Generates 3-D trajectory animations.
+- [`psd_analysis`](): Visualises satellite flyover properties alongside measured PSD data coincidential with satellite flyovers.
+
+A detailed overview of all five modules, their key functions, and example usage is provided in a supplementary [document](docs/examples/examples.md).
+
+
+A [demonstration notebook](notebooks/astrotrack_demo/01_astrotrack_demo.ipynb) is also provided, and includes usage of an example [horizon profile](data/horizon-profiles/REACH-horizon.csv) from the REACH experiment as well as a [TLE catalogue](data/TLE-catalogues/TLEs.txt) compiled from [Space-Track](https://www.space-track.org). A [baseline horizon profile](data/horizon-profiles/baseline-horizon.csv) corresponding to an idealised flat horizon is additionally available to be used directly, or modified by the user to incorporate site-specific observational constraints.
+
+## Testing \& Validation
+
+`astrotrack` is validated using unit tests covering the package's functionalities from [TLE preprocessing](tests/preprocess_test.py), deriving [satellite properties](tests/satcon_properties_test.py), performing [Doppler Analysis](tests/doppler_analysis_test.py), and analysis with [PSD observations](tests/psd_analysis_test.py).
+
+The entire test suite can be run using:
+```bash
+pytest
+```
+
+## License
+
+The `astrotrack` Python package source code is released under BSD 3-Clause License, with citation details provided in the [`CITATION.cff`](CITATION.cff) file.
+
+## Bibliography
+
+de Lera Acedo, E., de Villiers, D.I.L., Razavi-Ghods, N. et al. *The REACH radiometer for detecting the 21-cm hydrogen signal from redshift z ≈ 7.5–28*. Nat Astron 6, 984–998 (2022). https://doi.org/10.1038/s41550-022-01709-9

astrotrack-0.1.0/README.md

@@ -0,0 +1,130 @@
+# astrotrack: Characterising LEO Satellite RFI in Wide-Field Radio Astronomy
+
+![CI](https://github.com/Gabriella8080/astrotrack/actions/workflows/CI.yml/badge.svg) ![License](https://img.shields.io/badge/license-BSD--3-blue)
+
+## Overview
+
+`astrotrack` is an open-source Python package for characterising potential Low Earth Orbit (LEO) satellite interference in wide-field radio astronomy observations. While interferometric arrays are able to spatially localise LEO satellite radiation, wide-beam radiometers like REACH (de Lera Acedo et al. 2022) integrate the total sky power into a frequency spectrum and therefore lack equivalent strategies for identifying satellite-generated contamination. To address this limitation, `astrotrack` provides tools for combining Two-Line Element (TLE) data with site-specific observational constraints to identify LEO satellite flyovers and investigate their potential association with radio frequency interference (RFI).
+
+> **Accompanying Paper**: *'astrotrack: Characterising LEO Satellite Interference in Wide-Field Radio Astronomy'*, in preparation.
+
+<br>
+<div align="center">
+  <img src="docs/images/animated_satellites.gif" width="600">
+  <p><em>3-D trajectory animation generated by AstroTrack's <code>satcon_animate</code> module of Eutelsat OneWeb satellite flyovers at the REACH site in the Karoo radio reserve, South Africa on 15 June 2025.</em></p>
+</div>
+<br>
+
+## Repository Structure
+
+| Paths | Description |
+| ----- | ------------|
+| [`data/`](data/) | CSV horizon profiles, including a [baseline](data/horizon-profiles/baseline-horizon.csv) and [REACH radiometer](data/horizon-profiles/REACH-horizon.csv) horizon profile. Alongside this, the [TLE catalogue](data/TLE-catalogues/TLEs.txt) used in exemplar and experimental analyses is provided. |
+| [`docs/`](docs/) | [Example usage](docs/examples/) of functionalities across `astrotrack` modules. |
+| [`astrotrack/`](astrotrack/) | `astrotrack` Python package source code.  |
+| [`notebooks/astrotrack_demo/`](/notebooks/astrotrack_demo/) | [Demonstration notebook](notebooks/astrotrack_demo/01_astrotrack_demo.ipynb) showing example `astrotrack` workflow. |
+| [`notebooks/astrotrack_results/`](notebooks/astrotrack_results/) | Notebooks documenting experimental results and analyses. |
+| [`tests`](tests/) | Unit tests validating `astrotrack` functionalities and edge case performance.|
+| [`environment.yml`](environment.yml) | Conda environment for `astrotrack` specifying required dependencies.|
+
+
+## Data Availability
+
+Raw HDF5 files containing PSD observations used for comparison are proprietary to the REACH collaboration and are therefore not made publicly available. The publicly available 12,270 TLEs used in this work are provided in a [CSV file](data/TLE-catalogues/TLEs.txt) downloaded from [Space-Track](https://www.space-track.org) on 17:10:37 UTC 14 June 2025.
+
+
+## `astrotrack` Installation
+
+To install `astrotrack` from source, follow the instructions below:
+
+```bash
+conda env create -f environment.yml
+conda activate astrotrack
+pip install -e .
+```
+
+The package can then be imported using:
+
+```bash
+import astrotrack
+```
+
+`astrotrack` is recommended to be used with the provided Conda [environment](environment.yml).
+
+
+## Quick Start
+
+The below example demonstrates how to initialise `astrotrack` using a provided TLE catalogue along with user-defined observational constraints, the satellite constellation of interest, and a target date:
+
+```python
+from datetime import datetime
+from astrotrack.preprocess import load_satellite_data
+
+data = load_satellite_data(
+    tle_file="LEO_TLE_file.txt",
+    target_date=datetime(2025, 1, 18, 12, 25, 8),
+    obs_len=3600, 
+    traj_res=60,
+    obs_lat=51.5,
+    obs_lon=-0.1,
+    R=2000,
+    horizon_data="Horizon-Profile.csv", 
+    satcon="STARLINK"
+)
+```
+
+> **Generating Epoch Times with Skyfield**: The following code can be used to initialise a time array for satellite propagation.
+>
+>```python
+>import numpy as np
+>from skyfield.api import load
+>
+># Create a timescale object:
+>ts = load.timescale()
+>
+># Define orbit duration:
+>orbit_duration = np.arange(0, 3600, 1)  # in seconds
+>
+># Generate time array:
+>epochs_of_orbit = ts.utc(2025, 1, 1, 10, 15, 0 + orbit_duration)
+>```
+>
+
+
+## Example Usage & Workflow
+
+`astrotrack` is organised into five modules. A typical workflow begins with initialising and structuring satellite Two-Line Element (TLE) data for analysis, after which the subsequent modules derive orbital properties, Doppler behaviour with respect to a ground-based experiment, animations, and enable spectral associations.
+
+<br>
+<div align="center">
+  <img src="docs/images/package-modules.png" width="600">
+</div>
+<br>
+
+- [`preprocess`](): Loads and filters satellite TLE data provided by the user.
+- [`satcon_properties`](): Filters, analyses, and visualises satellite trajectories as well as their metrics. 
+- [`doppler_analysis`](): Evaluates Doppler shifts and detectability relative to a user-defined instrument's specifications.
+- [`satcon_animate`](): Generates 3-D trajectory animations.
+- [`psd_analysis`](): Visualises satellite flyover properties alongside measured PSD data coincidential with satellite flyovers.
+
+A detailed overview of all five modules, their key functions, and example usage is provided in a supplementary [document](docs/examples/examples.md).
+
+
+A [demonstration notebook](notebooks/astrotrack_demo/01_astrotrack_demo.ipynb) is also provided, and includes usage of an example [horizon profile](data/horizon-profiles/REACH-horizon.csv) from the REACH experiment as well as a [TLE catalogue](data/TLE-catalogues/TLEs.txt) compiled from [Space-Track](https://www.space-track.org). A [baseline horizon profile](data/horizon-profiles/baseline-horizon.csv) corresponding to an idealised flat horizon is additionally available to be used directly, or modified by the user to incorporate site-specific observational constraints.
+
+## Testing \& Validation
+
+`astrotrack` is validated using unit tests covering the package's functionalities from [TLE preprocessing](tests/preprocess_test.py), deriving [satellite properties](tests/satcon_properties_test.py), performing [Doppler Analysis](tests/doppler_analysis_test.py), and analysis with [PSD observations](tests/psd_analysis_test.py).
+
+The entire test suite can be run using:
+```bash
+pytest
+```
+
+## License
+
+The `astrotrack` Python package source code is released under BSD 3-Clause License, with citation details provided in the [`CITATION.cff`](CITATION.cff) file.
+
+## Bibliography
+
+de Lera Acedo, E., de Villiers, D.I.L., Razavi-Ghods, N. et al. *The REACH radiometer for detecting the 21-cm hydrogen signal from redshift z ≈ 7.5–28*. Nat Astron 6, 984–998 (2022). https://doi.org/10.1038/s41550-022-01709-9

astrotrack-0.1.0/astrotrack/__init__.py

@@ -0,0 +1,22 @@
+from .doppler_analysis import (  # noqa: F401
+    check_doppler_resolution,
+    plot_doppler_shifts,
+)
+from .preprocess import load_satellite_data  # noqa: F401
+from .psd_analysis import (  # noqa: F401
+    load_hdf5,
+    plot_psd_satellite_time_series,
+    plot_psd_with_satellite_metric,
+)
+from .satcon_animate import animate_trajectories  # noqa: F401
+from .satcon_properties import (  # noqa: F401
+    filter_by_norads,
+    filter_by_time,
+    filter_custom,
+    filter_nth,
+    get_norads,
+    plot_flyover_histogram_by_norad,
+    plot_max_elevation_histogram,
+    plot_satellite_metric,
+    plot_satellite_trajectory,
+)

astrotrack-0.1.0/astrotrack/doppler_analysis.py

@@ -0,0 +1,111 @@
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+from tabulate import tabulate
+
+default_font = "Times New Roman"
+
+
+def plot_doppler_shifts(
+    all_satellite_data,
+    f0,
+    font_family=default_font,
+    figsize=(8, 5),
+    marker_color="deeppink",
+    time_window=10,
+):
+    """
+    Plot the Doppler shifts for each satellite in separate subplots,
+    centered around visibility midpoint.
+
+    Parameters:
+    ----------
+    all_satellite_data : list[dict]
+        Satellite data dictionaries.
+    f0 : float
+        Transmission frequency [Hz].
+    font_family : str
+        Font family for plot text.
+    figsize : tuple
+        Figure size for each subplot.
+    marker_color : str
+        Color of scatter plot markers.
+    time_window : float
+        Half-width of x-axis around visibility [min].
+    """
+    c = 3.0e5  # speed of light in km/s
+    for satellite_data in all_satellite_data:
+        plt.rcParams["font.family"] = font_family
+        plt.figure(figsize=figsize)
+
+        epochs = satellite_data["Epochs"]
+        velocity_r = np.array(satellite_data["Velocities"])  # km/s
+        elevations = satellite_data["Elevations"]
+        tle_line_2 = satellite_data["TLE"][1]
+        norad_id = tle_line_2.split()[1]
+        theta_max = max(elevations)
+        epochs_np = np.array([np.datetime64(e) for e in epochs])
+        center_time = epochs_np[len(epochs_np) // 2]
+        relative_time = (epochs_np - center_time) / np.timedelta64(1, "m")  # mins
+        doppler_shift = (velocity_r / c) * f0
+
+        plt.scatter(
+            relative_time,
+            doppler_shift / 1e3,
+            s=3,
+            color=marker_color,
+            label=rf"$\theta_{{max}} \approx {theta_max:.0f}^\circ$",
+        )
+
+        print_time = (
+            center_time.astype("datetime64[s]").tolist().strftime("%Y-%m-%d %H:%M:%S")
+        )
+        plt.xlabel("Visibility Time (min)")
+        plt.ylabel("Doppler Shift (kHz)")
+        plt.title(f"NORAD {norad_id} Doppler Shift (Centered at {print_time}):")
+        plt.axhline(0, color="black", linestyle="--")
+        plt.xlim(-time_window, time_window)
+        plt.legend(loc="upper right", fontsize=10)
+        plt.grid(True)
+        plt.show()
+
+
+def check_doppler_resolution(
+    all_satellite_data, f0_array, resolution=12_000, experiment="REACH", return_df=False
+):
+    """
+    Check if Doppler shift can be resolved,
+    given experiment's frequency resolution.
+
+    Parameters:
+    ----------
+    all_satellite_data : list[dict]
+        Satellite data dictionaries.
+    f0_array : array
+        Frequencies to test [Hz].
+    resolution : float
+        Frequency resolution of experiment [Hz].
+    experiment_name : str
+        Name of experiment.
+    """
+    c = 3.0e5  # speed of light in km/s
+    rows = []
+
+    for satellite_data in all_satellite_data:
+        norad_id = satellite_data["TLE"][1].split()[1]
+        velocity_r = np.array(satellite_data["Velocities"])
+        f_max_needed = (resolution * c) / (np.max(np.abs(velocity_r)) * 1e6)
+
+        row = {"Satellite NORAD ID": norad_id}
+        for f0 in f0_array:
+            max_doppler_khz = np.max(np.abs((velocity_r / c) * f0)) / 1e3
+            row[f"{f0/1e6:.1f} MHz"] = f"""{max_doppler_khz:.2f} kHz | {
+                'YES' if max_doppler_khz > resolution/1e3 else 'NO'
+                }"""
+        row[f"Freq. to Resolve ({experiment})"] = f"{f_max_needed:.0f} MHz"
+        rows.append(row)
+
+    df = pd.DataFrame(rows)
+    print(tabulate(df, headers="keys", tablefmt="grid", showindex=False))
+    if return_df:
+        return df