Package: leosatpy
LEOSatpy(Low Earth Orbit satellite python) is an end-to-end pipeline to process and analyse
satellite trail observations from various telescopes.The pipeline is written in Python 3 and provides the following functionalities:ModuleFunctionreduceSatObsFull reduction of raw-FITS images including bias, dark, and flat reduction.calibrateSatObsWCS calibration, i.e. plate solving, usingGAIA DR3positions, obtained via theAstroquerytool.analyseSatObsSatellite trail(s) detection and aperture photometry using
comparison stars from theGSC v2.4.3catalog.The full documentation for LEOSatpy can be foundhere.LEOSatpy is distributed under the GNU General Public License v3. See theLICENSEfile for the precise terms and conditions.Currently supported telescopes:0.6-metre Chakana telescope at theCkoirama Observatoryof the Universidad de Antofagasta, Antofagasta, Chile.0.9-metreSmall and Moderate Aperture Research Telescope System(SMARTS)
at the Cerro Tololo Inter-american Observatory (CTIO), Chile.Víctor M. Blanco 4-meter Telescopeat the Cerro Tololo Inter-american Observatory (CTIO), Chile.1.54-metre Danish telescopeat the La Silla Observatory, Chile.0.28-metre DDOTI (Deca-Degree Optical Transient Imager) telescopes at theObservatorio Astronómico Nacional(OAN) in Sierra San Pedro Martír (SPM), Baja California, México.0.5-metreMOSS telescopeat the Oukaïmeden Observatory, Morocco.0.6-metre telescope of theChungbuk National University Observatoryin Jincheon, South Korea.1.23-metre telescopeat the Calar Alto Observatory, Spain.NoteIf you want your telescope added to the list, please contactJeremy Tregloan-Reed.How to use LEOSatpyThe LEOSatpy pipeline is written for use with Python >=3.9.
To avoid unnecessary interference with the Python installed on the system, it is recommended to create a new Python environment
to run LEOSatpy, using for exampleconda.A new conda environment can be created and activated with:$condacreate-nleosatpy_envpython=3.9$condaactivateleosatpy_envInstallationLEOSatpy is available onPyPI, and can be installed using pip:$(leosatpy_env)pipinstallleosatpyAlternatively, the latest release of LEOSatpy is also available from theGitHub repository.Clone the repository using git:$(leosatpy_env)gitclonehttps://github.com/CLEOsat-group/leosatpy.gitDownload the zip file from the GitHub repository:Navigate to the main page of the repository. Click on the “Code” button, then click “Download ZIP”.Once cloned or downloaded and extracted, LEOSatpy can be installed from anywhere by typing:$(leosatpy_env)pipinstall-ePATH/TO/CLONED/GITHUBor by navigating to the downloaded folder:$(leosatpy_env)cdPATH/TO/CLONED/GITHUBand using the following command in the terminal:$(leosatpy_env)pythonsetup.pyinstallThe successful installation of LEOSatpy can be tested by trying to access the help or the version of LEOSatpy via:$(leosatpy_env)reduceSatObs--help$(leosatpy_env)reduceSatObs--versionIf no error messages are shown, LEOSatpy is most likely installed correctly.Running LEOSatpyPrerequisites1. ConfigurationLEOSatpy comes with a configuration file, calledleosatpy_config.ini, containing an extensive list of parameter
that can be adjusted to modify the behaviour of LEOSatpy.ImportantUpon the first execution, a copy of the leosatpy configuration file is placed in the/home/userdirectory.
Please modify the file as required and re-run the program.By default, information and results for each dataset are stored in a .csv file located in the/home/userdirectory.
The location and name of this file can be changed by modifying the following lines in theleosatpy_config.ini:RESULT_TABLE_PATH = '~'
RESULT_TABLE_NAME = 'results_leosatpy.csv'2. Folder structureAlthough there is some degree of freedom in the nomenclature and structuring of the folder,
it is highly recommended to adopt the following folder layout:.
└── Telescope-Identifier <- free naming
    ├── YYYY-MM-DD <- recommended format
    │   ├── bias
    │   ├── flats
    │   ├── darks
    │   └── science_data <- free naming
    │       └── raw <- optional, but recommended
    ├── YYYY-MM-DD
    └── YYYY-MM-DDThe only requirement with regard to the name of the main folder is
that the folder name should contain the date of observation either in the format:YYYY-MM-DD, orYYYYMMDD.The program will select the search path for the calibration data based on the obs date from the science data header
and the names of folder in the given path.
Possible formats are, e.g., 20221110, 2022-11-20, tel_20221011_satxy, 2022-11-26_satxy_obs1, etc.NoteThe program can detect and handle if the name of the folder does not corresponds to the observation date.
However, the difference in date should not exceed 7 days. For example, data observed on 2022-11-11 UTC
might be located in a folder named 2022-11-10. <– This is detected.It is also recommended to separate the raw calibration files, i.e., bias, darks, and flats from the science observation files
and place them into separate folder, named accordingly/bias,/darks,/flats, andscience/raw, respectively.Once all programs have been executed, the final folder structure should look like this:.
└── Telescope-Identifier
    ├── YYYY-MM-DD
    │   ├── bias
    │   ├── flats
    │   ├── darks
    │   ├── master_calibs
    │   └── science_data (e.g., STARLINK)
    │       ├── auxiliary
    │       ├── calibrated
    │       ├── catalogs
    │       ├── figures
    │       │   └── Sat-ID (e.g., STARLINK-3568)
    │       ├── raw
    │       ├── reduced
    │       └── tle_predictions
    ├── YYYY-MM-DD
    └── YYYY-MM-DDAttention!To prevent unexpected behaviour during the program execution, please also check and make sure that:the raw FITS-files contain dataFITS-header keywords (e.g.,IMAGETYPof bias, flats, or science files) are correctly labeledcorresponding raw FITS calibration images are available (e.g., binning, exposure time, filter)LEOSatpy is now ready for use.ReductionThe reduction of all raw FITS-files in a folder can be performed via the following line:$(leosatpy_env)reduceSatObsPATH/TO/DATALEOSatpy also accepts relative paths and multiple inputs, for example:$(leosatpy_env)reduceSatObs../Telescope-Identifier/YYYY-MM-DD/$(leosatpy_env)reduceSatObsPATH/TO/DATA/NIGHT_1PATH/TO/DATA/NIGHT_2To reduce all data from a telescope at once with:$(leosatpy_env)reduceSatObsPATH/TO/TELESCOPE/DATAHintThe usage of partial and multiple inputs as shown above also works for the other programs in the package.Astrometric calibrationTo apply the astrometric calibration type:$(leosatpy_env)calibrateSatObsPATH/TO/DATASatellite trail detection and analysisTo run the satellite detection and analysis on all files in the input type:$(leosatpy_env)analyseSatObsPATH/TO/DATACiting LEOSatpyWhen publishing data processed and analysed with LEOSatpy, please cite:Adam et al. (2023) (in preparation). "Estimating the impact to astronomy from the Oneweb satellite constellation using multicolour observations". https://doi.org/10.5281/zenodo.8012131
Software pipeline available at https://github.com/CLEOsat-group/leosatpy.AcknowledgementsAlongside the packages listed in therequirements.txt, this project uses workflows and code adopted from the following packages:Astrometryunder the GPLv3 License, Lukas Wenzl (2022),ZenodoAutoPhOTunder the GPLv3 License, Brennan & Fraser (2022),NASA ADSCcdproc, an Astropy package for image reduction (Craig et al. 2023).The authors of these packages and code are gratefully acknowledged.Special thanks go out to the following people for their ideas and contributions to the development
of the LEOSat Python package:Jeremy Tregloan-Reed, Universidad de AtacamaEduardo Unda-Sanzana, Universidad de AntofagastaEdgar Ortiz, Universidad de AntofagastaMaria Isabel Romero Colmenares, Universidad de AtacamaSangeetha Nandakumar, Universidad de AtacamaThe project would not have been possible without the help of everyone who contributed.Feedback, questions, comments?LEOSatpy is under active development and help with the development of new functionalities
and fixing bugs is very much appreciated.
In case you would like to contribute, feel free to fork theGitHub repositoryand to create a pull request.If you encounter a bug or problem, pleasesubmit a new issue on the GitHub repositoryproviding as much
detail as possible (error message, operating system, Python version, etc.).If you have further feedback, questions or comments you can also send an e-mail toJeremy Tregloan-Reed, orChristian Adam.AuthorChristian Adam,
Centro de Investigación, Tecnología, Educación y Vinculación Astronómica (CITEVA), Universidad de Antofagasta,
Antofagasta, Chile