Metadata-Version: 2.1
Name: leosatpy
Version: 0.1.0
Summary: LEOSatpy is a highly-automated end-to-end pipeline for the reduction, calibration, and analysis of Low Earth Orbit Satellite observations from various telescopes.
Home-page: http://leosatpy.readthedocs.io/
Download-URL: https://github.com/CLEOsat-group/leosatpy/archive/master.zip
Author: Christian Adam
Author-email: christian.adam84@gmail.com
License: GNU General Public License v3.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Requires-Python: >=3.9
Description-Content-Type: text/x-rst
License-File: LICENSE

.. Define variables

.. _ckoir: https://www.astro.uantof.cl/research/observatorios/ckoirama-observatory/

.. |ckoir| replace:: Ckoirama Observatory

.. _ctio: http://www.astro.yale.edu/smarts/0.9m.html

.. |ctio| replace:: Small and Moderate Aperture Research Telescope System

.. _dk154: https://www.eso.org/public/teles-instr/lasilla/danish154/

.. |dk154| replace:: 1.54-metre Danish telescope

.. _spm: https://www.astrossp.unam.mx/es/

.. |spm| replace:: Observatorio Astronómico Nacional

.. _ouka: https://moss-observatory.org/

.. |ouka| replace:: MOSS telescope

.. _cbnuo: https://www.chungbuk.ac.kr/site/english/main.do

.. |cbnuo| replace:: Chungbuk National University Observatory

.. _ca123: https://www.caha.es/CAHA/Telescopes/1.2m.html

.. |ca123| replace:: 1.23-metre telescope


LEOSatpy
========

**LEOSatpy** (Low Earth Orbit satellite python) is an end-to-end pipeline to process and analyse
satellite trail observations from different telescopes.

The programs in the LEOSatpy package are written for python 3.9 (recommended) and 3.10.
To run LEOSatpy on a machine with a different version of python, it is recommended to use
LEOSatpy with a Conda environment.
This allows to run the package without interfering with the system.

To install Conda follow the instructions
`linked here <https://conda.io/projects/conda/en/latest/user-guide/install/linux.html>`_.
Once installed, a conda environment running a specific version of Python can be created and activated with:

.. code-block:: sh

    $ conda create -n myenv python=3.9
    $ conda activate myenv


The full documentation for **LEOSatpy** can be found `here <https://docs.readthedocs.io/en/stable/tutorial/>`_.


LEOSatpy is distributed under the GNU General Public License v3. See the
`LICENSE <https://github.com/CLEOsat-group/leosatpy/blob/master/LICENSE>`_ file for the precise terms and conditions.

Package Functionalities
-----------------------


Content
^^^^^^^

The important files for the process in this directory:

===========================  ==========================================================================
Program                      Function
===========================  ==========================================================================
``reduceSatObs.py``          Perform reduction of satellite observations.
``calibrateSatObs.py``       Perform astrometric calibration using GAIA DR3 positions.
``analyseSatObs.py``         Detect satellite trail(s) and perform aperture photometry using
                             comparison stars from the GSC 2.4.3 catalog.
===========================  ==========================================================================


Supported Telescopes
^^^^^^^^^^^^^^^^^^^^

Observations from the following telescopes are currently supported:

* 0.6-metre Chakana telescope at the |ckoir|_ of the Universidad de Antofagasta, Antofagasta, Chile.
* 0.9-metre |ctio|_ (SMARTS)
  at Cerro Tololo Inter-american Observatory (CTIO), Chile.
* |dk154|_ at the La Silla Observatory, Chile.
* 0.28-metre DDOTI (Deca-Degree Optical Transient Imager) telescopes at the |spm|_ (OAN) in Sierra San Pedro Martír (SPM), Baja California, México.
* 0.5-metre |ouka|_ at the Oukaïmeden Observatory, Morocco.
* 0.6-metre telescope of the |cbnuo|_ in Jincheon, South Korea.
* |ca123|_ at the Calar Alto Observatory, Spain.


.. note::

    If you want your telescope added to the list, please contact
    `Jeremy Tregloan-Reed <jeremy.tregloan-reed@uda.cl>`_.

The positions of reference stars for astrometric calibration where obtained from the GAIA DR3 catalog via
`astroquery <https://astroquery.readthedocs.io/en/latest/#>`_

The positions and magnitudes of the comparison stars are collected using the
`WebServices for Catalog Access <https://outerspace.stsci.edu/display/GC/WebServices+for+Catalog+Access>`_
to the Guide Star Catalog(s) v2.4.3.


How to use LEOSatpy
-------------------


Installation
^^^^^^^^^^^^

To run the `leosatpy` programs, download or clone the repository to your local machine

.. code-block:: sh

    $ (myenv) git clone https://github.com/CLEOsat-group/leosatpy.git

and navigate to the folder location of the cloned package files:

.. code-block:: sh

    $ (myenv) cd path/to/cloned/github

**INSTALLATION: To be implemented/written**


Requirements
""""""""""""

The LEOSatpy programs are written with python 3.9 and tested with python 3.9 and 3.10.

Alongside the standard python modules such as numpy, pandas, scipy, or matplotlib,
LEOSatpy also requires a number of additional modules to work, e.g. ccdproc, astropy, or photutils.

All packages required to run LEOSatpy can be install at once with:

.. code-block:: sh

    $ (myenv) pip install -r requirements.txt



Running LEOSatpy
^^^^^^^^^^^^^^^^


Prerequisites
"""""""""""""

**1. Configuration**

The LEOSatpy package comes with a configuration file, called `leosatpy_config.ini`.

..    This file allows to change a number of parameter used during the reduction, calibration and analysis.
    Among these are the location and name of the result table holding all collected information and analysis results.

By default the results are saved in the ``/home/user`` directory.
To change the location and name open the configuration file and change the following lines:

::

    RESULT_TABLE_PATH = '~'
    RESULT_TABLE_NAME = 'results_LEOSat.csv'

**2. Folder structure**

Although there is some degree of freedom in the nomenclature and structuring of the folder,
it is recommended to follow the folder layout given below:

.. code-block::

    .
    └── 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-DD

The 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``, or ``YYYYMMDD``.

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.

.. note::

    The 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 from the science observation files
and place them into separate folder.

Once all programs have been executed, the directory should look like this:

.. code-block::

    .
    └── Telescope-Identifier
        ├── YYYY-MM-DD
        │   ├── bias
        │   ├── flats
        │   ├── darks
        │   ├── master_calibs
        │   └── science_data
        │       ├── auxiliary
        │       ├── calibrated
        │       ├── catalogs
        │       ├── figures
        │       │   └── Sat-ID
        │       ├── raw
        │       └── reduced
        ├── YYYY-MM-DD
        └── YYYY-MM-DD

.. attention::

    To prevent unexpected behaviour during execution, please also check that:

    * the raw FITS-files contain data
    * FITS-header keywords (e.g., `IMAGETYP` of bias, flats, or science files) are correctly labeled
    * corresponding raw FITS calibration images are available (e.g., binning, exposure time, filter)


We are now ready to run LEOSatpy.


Reduction
"""""""""

The reduction of all raw FITS-files in a folder can be performed via the following line:

.. code-block:: sh

    $ (myenv) python reduceSatObs.py [path_to_data]

For example:

.. code-block:: sh

    $ (myenv) python reduceSatObs.py ../Telescope-Identifier/YYYY-MM-DD/

To reduce data from multiple nights for example type:

.. code-block:: sh

    $ (myenv) python reduceSatObs.py [path_to_data_night_1] [path_to_data_night_2]

It is also possible to reduce all epochs of a telescope at once with:

.. code-block:: sh

    $ (myenv) python reduceSatObs.py [path_to_telescope_data]

.. note::

    The usage of partial and multiple inputs as shown above also works for the other programs in the package.


..    During the reduction the following steps are performed:

        * Image registration and validation
        * Master calibration file creation
        * Removal of instrumental signatures to create and save the reduced FITS-image(s)
        * Save results to result table.


Astrometric calibration
"""""""""""""""""""""""

To apply the astrometric calibration type:

.. code-block:: sh

    $ (myenv) python calibrateSatObs.py [path_to_data]

..    During the astrometric calibration the following steps are performed:

        * Registration and validation of the reduced FITS-files
        * 2D background estimation and source detection
        * Determination of the pixel scale and detector rotation angle by comparing the detected sources with precise positions from the GAIA eDR3 catalog
        * Update the FITS-files World Coordinate System (WCS) with found transformation.
        * Save results to result table


Satellite trail detection and analysis
""""""""""""""""""""""""""""""""""""""

To run the satellite detection and analysis on all files in the input type:

.. code-block:: sh

    $ (myenv) python analyseSatObs.py [path_to_data]

..  During the analysis the following steps are performed:

    * Registration and validation of the calibrated FITS-files
    * `Xu et al. (2015) <https://ui.adsabs.harvard.edu/abs/2015PatRe..48.4012X/abstract>`_
    * Save results to result table



Citing LEOSatpy
---------------

When publishing data processed and analysed with LEOSatpy, please cite:

::

    Adam, C. et al., 2023 (in preparation). "Estimating the impact to astronomy from the Oneweb satellite constellation using multicolour observations".
    Software pipeline available at https://github.com/CLEOsat-group/leosatpy.

Acknowledgements
----------------

Alongside the packages listed in the ``requirements.txt``, this project uses workflows and code adopted from the following packages:

* `Astrometry <https://github.com/lukaswenzl/astrometry>`_ under the GPLv3 License, Lukas Wenzl (2022), `Zenodo <https://doi.org/10.5281/zenodo.6462441>`_
* `AutoPhOT <https://github.com/Astro-Sean/autophot>`_ under the GPLv3 License, Brennan & Fraser (2022), `NASA ADS <https://ui.adsabs.harvard.edu/abs/2022A%26A...667A..62B/abstract>`_

.. * `reduceccd <https://github.com/rgbIAA/reduceccd/tree/master>`_ under the BSD-3-Clause license

.. * `wht_reduction_scripts <https://github.com/crawfordsm/wht_reduction_scripts>`_ under the BSD-3-Clause license


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 <jeremy.tregloan-reed@uda.cl>`_, Universidad de Atacama
* `Eduardo Unda-Sanzana <eduardo.unda@uamail.cl>`_, Universidad de Antofagasta
* `Edgar Ortiz <ed.ortizm@gmail.com>`_, Universidad de Antofagasta
* `Maria Isabel Romero Colmenares <maria.romero.21@alumnos.uda.cl>`_, Universidad de Atacama
* `Sangeetha Nandakumar <an.sangeetha@gmail.coml>`_, Universidad de Atacama

The 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 the
`GitHub repository <https://github.com/CLEOsat-group/leosatpy>`_ and to create a pull request.

If you encounter a bug or problem, please `submit a new issue on the GitHub repository
<https://github.com/CLEOsat-group/leosatpy/issues>`_ providing 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 to
`Jeremy Tregloan-Reed <jeremy.tregloan-reed@uda.cl>`_, or `Christian Adam <christian.adam84@gmail.com>`_.


Author
------

`Christian Adam <christian.adam84@gmail.com>`_,
Centro de Investigación, Tecnología, Educación y Vinculación Astronómica (CITEVA), Universidad de Antofagasta,
Antofagasta, Chile
