Metadata-Version: 2.1
Name: dran
Version: 0.0.3.dev0
Summary: Data reduction and analysis of HartRAO 26m telescope drift scans
Home-page: https://github.com/Pfesi/dran
Author: Pfesesani van Zyl
Author-email: pfesi24@gmail.com
Project-URL: Documentation, https://dran.readthedocs.io/
Project-URL: Changelog, https://dran.readthedocs.io/en/latest/changelog.html
Project-URL: Issue Tracker, https://github.com/Pfesi/dran/issues
Keywords: dran,single-dish
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3.8
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS.rst
Requires-Dist: alabaster (==0.7.13)
Requires-Dist: astropy (==5.2.2)
Requires-Dist: attrs (==23.1.0)
Requires-Dist: Babel (==2.12.1)
Requires-Dist: beautifulsoup4 (==4.12.2)
Requires-Dist: bleach (==6.0.0)
Requires-Dist: certifi (==2023.7.22)
Requires-Dist: charset-normalizer (==3.2.0)
Requires-Dist: commonmark (==0.9.1)
Requires-Dist: contourpy (==1.1.0)
Requires-Dist: cycler (==0.11.0)
Requires-Dist: defusedxml (==0.7.1)
Requires-Dist: docutils (==0.18.1)
Requires-Dist: fastjsonschema (==2.18.0)
Requires-Dist: fonttools (==4.42.0)
Requires-Dist: furo (==2023.7.26)
Requires-Dist: idna (==3.4)
Requires-Dist: imagesize (==1.4.1)
Requires-Dist: importlib-metadata (==6.8.0)
Requires-Dist: importlib-resources (==6.0.1)
Requires-Dist: Jinja2 (==3.1.2)
Requires-Dist: joblib (==1.3.2)
Requires-Dist: jsonschema (==4.19.0)
Requires-Dist: jsonschema-specifications (==2023.7.1)
Requires-Dist: jupyter-client (==8.3.0)
Requires-Dist: jupyter-core (==5.3.1)
Requires-Dist: jupyterlab-pygments (==0.2.2)
Requires-Dist: kiwisolver (==1.4.4)
Requires-Dist: markdown-it-py (==3.0.0)
Requires-Dist: MarkupSafe (==2.1.3)
Requires-Dist: matplotlib (==3.7.2)
Requires-Dist: mdit-py-plugins (==0.4.0)
Requires-Dist: mdurl (==0.1.2)
Requires-Dist: mistune (==3.0.1)
Requires-Dist: myst-parser (==2.0.0)
Requires-Dist: nbclient (==0.8.0)
Requires-Dist: nbconvert (==7.7.3)
Requires-Dist: nbformat (==5.9.2)
Requires-Dist: numpy (==1.24.4)
Requires-Dist: pandas (==2.0.3)
Requires-Dist: pandocfilters (==1.5.0)
Requires-Dist: Pillow (==10.0.0)
Requires-Dist: pkgutil-resolve-name (==1.3.10)
Requires-Dist: platformdirs (==3.10.0)
Requires-Dist: ply (==3.11)
Requires-Dist: pyerfa (==2.0.0.3)
Requires-Dist: Pygments (==2.16.1)
Requires-Dist: pyparsing (==3.0.9)
Requires-Dist: PyQt-builder (==1.15.2)
Requires-Dist: PyQt5-sip (==12.11.0)
Requires-Dist: python-dateutil (==2.8.2)
Requires-Dist: pytz (==2023.3)
Requires-Dist: PyYAML (==6.0.1)
Requires-Dist: pyzmq (==25.1.1)
Requires-Dist: QtPy (==2.3.1)
Requires-Dist: referencing (==0.30.2)
Requires-Dist: requests (==2.31.0)
Requires-Dist: rpds-py (==0.9.2)
Requires-Dist: scikit-learn (==1.3.0)
Requires-Dist: scipy (==1.10.1)
Requires-Dist: six (==1.16.0)
Requires-Dist: snowballstemmer (==2.2.0)
Requires-Dist: soupsieve (==2.4.1)
Requires-Dist: Sphinx (==6.2.1)
Requires-Dist: sphinx-basic-ng (==1.0.0b2)
Requires-Dist: sphinx-rtd-theme (==1.2.2)
Requires-Dist: sphinxcontrib-applehelp (==1.0.4)
Requires-Dist: sphinxcontrib-devhelp (==1.0.2)
Requires-Dist: sphinxcontrib-htmlhelp (==2.0.1)
Requires-Dist: sphinxcontrib-jquery (==4.1)
Requires-Dist: sphinxcontrib-jsmath (==1.0.1)
Requires-Dist: sphinxcontrib-qthelp (==1.0.3)
Requires-Dist: sphinxcontrib-serializinghtml (==1.1.5)
Requires-Dist: threadpoolctl (==3.2.0)
Requires-Dist: tinycss2 (==1.2.1)
Requires-Dist: tomli (==2.0.1)
Requires-Dist: tornado (==6.3.2)
Requires-Dist: traitlets (==5.9.0)
Requires-Dist: tzdata (==2023.3)
Requires-Dist: urllib3 (==2.0.4)
Requires-Dist: webencodings (==0.5.1)
Requires-Dist: zipp (==3.16.2)
Provides-Extra: dev
Requires-Dist: pytest (>=3.7) ; extra == 'dev'

DRAN README
===========

**DRAN** is a data reduction and analysis software pipeline developed to systematically reduce and analyze 
`HartRAO's <http://www.hartrao.ac.za>`_ `26m telescope <http://www.hartrao.ac.za/hh26m_factsfile.html>`_ drift scan data. The software is a new development intended to replace the old LINES continuum data reduction and analysis program previously used at HartRAO. The program began
as part of the PhD projects for Pfesesani Van Zyl and is now mantained by the author 
who is currently a postdoc at `SARAO (the South African Radio AStronomy Observatory) <http://www.sarao.ac.za/>`_.

Program structure 
------------------

This program is built using `Python <http://www.python.org>`_ 3.8 and consists of two interfaces: 

* CLI - A command-line interface and, 
* GUI - A graphical user interface.

The CLI handles the automated and semi-automated data reduction and analysis of drift scan files, 
whereas the GUI is more aligned with handling single file inspection and fitting. 
The GUI also has features that allow for simple data analysis of timeseries data generated by the 
CLI.

Requirements
-------------

All required packages are in the requirements.txt file supplied with the software.

.. note::
  There is an issue with the installation of pyqt5 (the library required to run the GUI) on some machines while 
  loading the requirements file during program installation. Thus it is highly 
  recommended that the user utilizes an anaconda installation or a virtual environment of their choice
  when installing the program.
  Please also note that the software has only been tested on anaconda so using a different virtual 
  enviroment server might not work.  

Installation 
-------------

The DRAN program was developed using the anaconda virtual environment.
Running the code on a virtual environment is highly recommended to avoid 
package clashes, 
and the following installation shows how to do this using 
`anaconda <https://www.anaconda.com/products/individual>`_. 
Anaconda is a data science toolkit with a wide variety of open-source packages and 
and libraries under one hub for building powerful projects.

First you will need to `download anaconda <https://www.anaconda.com/products/individual>`_ and install it on your machine.
Once installed you will create the dran virtual environment and activate it
using the following commands 

.. code:: bash
 
   $ mkdir dran
   $ cd dran
   $ conda create --name dran --file requests.txt
   $ conda activate dran

Alternatively, you can use the pypi package manager 

.. code:: bash
 
   $ pip install dran


.. note:: 
   The program has not been tested on pyenv or env yet. This is planned for future releases.


Data files
----------

- File format
The program assumes that all raw files to be processed are strictly in `FITS <https://fits.gsfc.nasa.gov/fits_documentation.html>` 
file format. After processing the results are then stored in an SQLite database.

- File reading
A file can be read in through 2 main ways

1. The user explicilty gives the full path of the file / folder they want to process.
2. The user selects the file / folder using the available options through the use of a dialog box (e.g. in the GUI).


Quickstart
----------

After the successful installation of all the required libraries you can now start with processing the data. 
To dive right in you can type the following command

.. code:: bash

  $ dran -h

The above command prints out the set of options listed below,

.. code-block:: python

  usage: dran [-h] [-db DB] [-f F] [-force FORCE] [-c C] [-b B] [-delete_db DELETE_DB] [-mfp MFP]
  [-keep KEEP] [-delete_from DELETE_FROM] [-conv  CONV]

  Begin processing HartRAO drift scan data

  optional arguments:
    -h, --help            show this help message and exit
    -db DB                turn debugging on or off. e.g. -db on, by default
                        debug is off
    -f F                  process file or folder at given path e.g. -f data/Hydr
                        aA_13NB/2019d133_16h12m15s_Cont_mike_HYDRA_A.fits or
                        -f data/HydraA_13NB or -f data/
    -force FORCE          force fit all drift scans y/n e.g. -force y. Default
                        is set to n
    -c C                  initiate the command to run program. e.g. -c gui or -c
                        run_auto_analysis or -c cmdl
    -b B                  initiate browser. e.g. -b docs or -b dash
    -delete_db DELETE_DB  delete database on program run. e.g. -delete_db y
    -mfp MFP              multi-file processing of data between two dates. e.g.
                        -mfp fileList.txt
    -keep KEEP            keep original plots while processing data. e.g. -keep y
    -delete_from DELETE_FROM in coordination eith the filename, use delete_from to delete a row from a database
                          e.g. delete_from CALDB
    -conv  CONV           convert the database tables to csv. e.g. conv CALDB.db
    -saveLocs SAVELOCS    Save fit locations. e.g. -saveLocs y , default is no
    -fitTheoretical FITTHEORETICAL
                        Fit theoretical locations of the baseline, i.e. the
                        FNBW locs. e.g. -fitTheoretical y , default is no.
    -applyRFIremoval APPLYRFIREMOVAL
                        Apply or don't apply RFI removal e.g. -applyRFIremoval
                        n, default is yes.
    -fitLocs FITLOCS      Fit data at sepcified locations e.g. -fitLocs
                        pathToFile
    -analyze ANALYZE ANALYZE ANALYZE
                        Analyze results from database e.g. -analyze CALDB.db
                        Jupiter_22ghz all/no
    -quickview QUICKVIEW  get quickview of data e.g. -quickview y
    -db_rows DB_ROWS      use all rows in the database, including special case
                        data, for analysis., e.g. -db_rows all
    --version             show program's version number and exit  


Depending on the process you want to run, you can select one or more of the available options. 
If there are more options you would like implemented please email the author, details are listed below.

Data processing examples
------------------------


to perform an automated data reduction process on a single file, use the following command

.. code:: bash

  $ dran-auto -f path-to-file/filename.fits

if you want to set debuggin on

.. code:: bash

  $ dran-auto -f path-to-file/filename.fits -db on

to delete both a database

.. code:: bash

  $ dran-auto -f path-to-file/filename.fits -delete_db y

to process multiple chunks of data within seperate periods of the year you use the following command

.. code:: bash

  $ dran -mfp file_list.txt

**NB** Please note that this assumes that there exists a file called 
fileList.txt in the current directory that has the full path to the 
folder containing the source fits files you want to process. This 
file also has a start and end date in "YYYYdDDD" format stipulating 
the data range you want to process.  

to process all the data located in your directory, **NB** this is 
the directory that 
contains all the folders containing your fits files. For example

Jupiter_22GHz 2020d139 2020d139

processes files located in the Jupiter_22GHz directory starting with 
the 2020d139 to 2020d139 dates.

To view the web documentation guide of the software

.. code:: bash

  $ dran-docs 

To delete an entry made in a database

.. code:: bash

  $ dran-docs -delete_from CALDB

To keep the plots of the raw data 

.. code:: bash

  $ dran-auto -f path-to-file/filename.fits -keep y

To convert the database tables to csv

.. code:: bash

  $ dran-auto -conv y


Starting the program will bring up the menu shown below with options to 
select how you want to proceeed with your data reduction or analysis. 

.. code-block:: bash


##################################################################
# 								                                 #
# 		 ######  ######  ###### #    #  		                 #
# 		 #     # #    #  #    # # #  #  		                 #
# 		 #     # #####   ###### #  # #  		                 #
# 		 #     # #    #  #    # #   ##  		                 #
# 		 ######  #    #  #    # #    #  		                 #
# 								                                 #
##################################################################

 #	 PROGRAM STARTED


## SELECT OPTION:
----------------------------------- 

 1. Data reduction
 2. Open GUI
 3. Run command line analysis
 4. Open documentation
 5. Open dashboard
 0. Exit program

 Please select an option

 Option Selected: 




To get a quick view of the source file

.. code:: bash

  $ dran-auto -quickview y


Caveats
-------

Although the program tries to fit the data appropriately there 
are a few things the user needs to be aware of. The program tries 
its best to fit all the data (good/bad). However the onus is still 
on the user to check/insure the scans have been fit in a satisfactory 
manner by checking the results in the plots folder.


Report bugs
-----------

Please report any buggy behavior to the author.


Author contacts
---------------

If you have any problems, questions, ideas or suggestions, please 
open an issue
