Formatting for PyPI

Author: rtlingg

README.md

@@ -1,32 +1,35 @@
 ## The Sagitta Pipeline
 Sagitta is a deep neural network based python3 pipeline that relies on Gaia DR2 and 2MASS photometry to identify pre-main sequence (PMS) stars and derive their age estimates.
 
+# Installation:
+```pip install sagitta``` (requires Python3)
+
 ## Description
-Sagitta is a python3 script that takes a Flexible Image Transport System (FITS) file as input. The only required column that must be specified for predictions to be generated is the Gaia DR2 source ID column with the "--source_id" flag. The values for the source id column must be unique for each star. All other missing required fields can/will be automatically downloaded when the pipeline is run. If a file is given that contains stars with and without Gaia source IDs, only the stars with values for the source ID will be run through the pipeline. In its default configuration, the pipeline will produce three predictions for each star: 1) a estimation of stellar extinction (Av), 2) the probablilty that a star is PMS (with 0 being 0% probablity and 1 being a 100% probablity), and 3) the estimated age of each star. Once the pipeline has been run and the output table has been automatically saved, the user should look at the output to determine an appropriate PMS output probablity cutoff to create their predicted PMS subset (ie. select pms > 0.8). Due to the nature of how the age model in the pipeline was trained only stars with significantly high PMS model probability output should be considered to have accurate age predictions.
+Sagitta is a python3 script that takes a Flexible Image Transport System (FITS) file as input. The only required column that must be specified for predictions to be generated is the Gaia DR2 source ID column with the ```--source_id``` flag. The values for the source id column must be unique for each star. All other missing required fields can/will be automatically downloaded when the pipeline is run. If a file is given that contains stars with and without Gaia source IDs, only the stars with values for the source ID will be run through the pipeline. In its default configuration, the pipeline will produce three predictions for each star: 1) a estimation of stellar extinction (Av), 2) the probablilty that a star is PMS (with 0 being 0% probablity and 1 being a 100% probablity), and 3) the estimated age of each star. Once the pipeline has been run and the output table has been automatically saved, the user should look at the output to determine an appropriate PMS output probablity cutoff to create their predicted PMS subset (ie. select pms > 0.8). Due to the nature of how the age model in the pipeline was trained only stars with significantly high PMS model probability output should be considered to have accurate age predictions.
 
 Behing the scenes, Sagitta uses three seperate convolutional neural networks (CNNs) to make its predictions. The first model, denoted as the Av model, is used for generating stellar extcintion (Av) values for stars in the input table. The second model, denoted as the PMS model, is used for generating the probability that each star is pre-main sequence. The thrid model, denoted as the age model, is used for generating the predicted ages for the stars.
 
-## Pipeline Options
+## Pipeline Usage Options
 
 #### Flow Control Options
 
 ###### Turning off Av, PMS, or age predictions
-In the default configuration all three models will be run with their outputs saved as columns in a output FITS file. If specified, the user can choose to not produce outputs from any of these models using the "--no_av_prediction", "--no_pms_prediction", and "--no_age_prediction" flags. However, in order to make PMS or age predictions, Av values must have either been generated with the Av model or the input column's name that holds that Av values should be specified with the input naming option. It is important to note however that the Av values requred for use in the PMS and age models should be generated from the Av model to provide optimal predictions.
+In the default configuration all three models will be run with their outputs saved as columns in a output FITS file. If specified, the user can choose to not produce outputs from any of these models using the ```--no_av_prediction```, ```--no_pms_prediction```, and ```--no_age_prediction``` flags. However, in order to make PMS or age predictions, Av values must have either been generated with the Av model or the input column's name that holds that Av values should be specified with the input naming option. It is important to note however that the Av values requred for use in the PMS and age models should be generated from the Av model to provide optimal predictions.
 
 ###### Only Downloading Data
-If you want to only download all of the data required for the use of the pipeline but NOT run any of the models, than you can use the "--download_only" flag to perform this action. It will download all required Gaia and 2MASS fields along with their associated errors, parallax, PMRA, PMDEC, PMRA_error, and PMDEC_error for every star with Gaia source ID specified.
+If you want to only download all of the data required for the use of the pipeline but NOT run any of the models, than you can use the ```--download_only``` flag to perform this action. It will download all required Gaia and 2MASS fields along with their associated errors, parallax, PMRA, PMDEC, PMRA_error, and PMDEC_error for every star with Gaia source ID specified.
 
 ###### Prediction Uncertainty Statistic Generation
-Also included in the pipeline is a uncertainty statistics generator for each of the models predictions. The statistics are generated on a per-star basis by randomly varying the input parameters by their associated errors and analyzing the outputs. The number of times each star is sampled to create these output statistics is an option given to the user but it should be noted that computaional cost scales linearly with the number of times sampled. These uncertainty generators are turned off by default but can be turned on by specifying the "--av_uncertainty", "--pms_uncertainty", or "--age_uncertainy" flags where the number of times to sample each star follows the flag (ie using "--age_uncertainty 10" would generate the age model output statistics for each star by sampling each star 10 times, varying the outputs, and analying the predictions). The statistics produced for the model output includes mean, median, standard deviation, variance, minimum, and maximum.
+Also included in the pipeline is a uncertainty statistics generator for each of the models predictions. The statistics are generated on a per-star basis by randomly varying the input parameters by their associated errors and analyzing the outputs. The number of times each star is sampled to create these output statistics is an option given to the user but it should be noted that computaional cost scales linearly with the number of times sampled. These uncertainty generators are turned off by default but can be turned on by specifying the ```--av_uncertainty```, ```--pms_uncertainty```, or ```--age_uncertainy``` flags where the number of times to sample each star follows the flag (ie using ```--age_uncertainty 10``` would generate the age model output statistics for each star by sampling each star 10 times, varying the outputs, and analying the predictions). The statistics produced for the model output includes mean, median, standard deviation, variance, minimum, and maximum.
 
 ###### Uncertainty Av Scattering Range Option
-By default, because the Av values from the Av model don't contain a true uncertainty values, the amount by which they are varied in the PMS and age model uncertainty generation is performed by choosing a random value from a uniform distribution with range +/- 0.1 of the original Av. But because selecting +/- 0.1 was only done based off of current Av model output trends, the size of this range can be specified via the "--av_scatter_range" flag.
+By default, because the Av values from the Av model don't contain a true uncertainty values, the amount by which they are varied in the PMS and age model uncertainty generation is performed by choosing a random value from a uniform distribution with range +/- 0.1 of the original Av. But because selecting +/- 0.1 was only done based off of current Av model output trends, the size of this range can be specified via the ```--av_scatter_range``` flag.
 
 ###### Testing Mode
-It is recommended that before running the pipeline on a large set of data, that you first test that the pipeline will execute properly by using the "--test" flag. In this mode only the first 10000 stars of the input file will be processed with the pipeline. The output of the test run will be saved by default as "{tableIn}-test-sagitta.fits" so that you can look at the output to make sure that it is as desired.
+It is recommended that before running the pipeline on a large set of data, that you first test that the pipeline will execute properly by using the ```--test``` flag. In this mode only the first 10000 stars of the input file will be processed with the pipeline. The output of the test run will be saved by default as "{tableIn}-test-sagitta.fits" so that you can look at the output to make sure that it is as desired.
 
 ###### Specifying an Av Input Column
-Using the "--av" flag to specify an input Av column is ONLY recommended for situtaitons where you already have generated Av values with the pipeline and are specifing that previous output column. If this is the case, then you prevent redundant generation of Av values by using this flag. It should be known though, that in order for the pipeline to produce its best predictions the Av column used should always be generated by the Av model.
+Using the ```--av``` flag to specify an input Av column is ONLY recommended for situtaitons where you already have generated Av values with the pipeline and are specifing that previous output column. If this is the case, then you prevent redundant generation of Av values by using this flag. It should be known though, that in order for the pipeline to produce its best predictions the Av column used should always be generated by the Av model.
 
 #### Data Processing Options
 
@@ -70,24 +73,37 @@ It is recommended that in the the case where the input table already contains an
 If a column name is not specified but is in the required list of photometric fields then it will be downloaded and saved in the output table with its default name.
 
 ###### Output Fits File Naming Option
-The user can specify the name for the output file via the "--tableOut" flag. If this flag is not specified then by default the output table will be named {tableIn}-sagitta.fits if NOT in testing model, or {tableIn}-test-sagitta.fits if in testing mode.
+The user can specify the name for the output file via the ```--tableOut``` flag. If this flag is not specified then by default the output table will be named {tableIn}-sagitta.fits if NOT in testing model, or {tableIn}-test-sagitta.fits if in testing mode.
 
 ###### Output Column Naming Options
-There are three flags for output column naming specification. They are the "--av_out", "--pms_out", and "--age_out" flags with their default values being "av", "pms", and "age" respectivly. These names correspond to the output column names from each of the three models, and will also be used in the uncertainty statistic generation output column names as well.
+There are three flags for output column naming specification. They are the ```--av_out```, ```--pms_out```, and ```--age_out``` flags with their default values being "av", "pms", and "age" respectivly. These names correspond to the output column names from each of the three models, and will also be used in the uncertainty statistic generation output column names as well.
+
+## Examples
+Testing all three models in the pipeline on example.fits and renaming the Av and pms output columns:
+```sagitta example.fits --av_out av_sagitta --pms_out pms_sagitta  --test```
+
+Running all three models and specifying the output table name to be output.fits:
+```sagitta example.fits --tableOut output.fits```
+
+Only running the Av and PMS models:
+```sagitta example.fits --no_age_prediction```
+
+Running all three models AND generating the PMS output uncertainty statistics with the sampling rate to 5 times per star:
+```sagitta example.fits --pms_uncertainty 5```
+
+Specifying that the example.fits's source ID colum is named Gaia_DR2_ID:
+```sagitta example.fits --source_id Gaia_DR2_ID```
+
+Pulling up the terminal help:
+```sagitta --help```
 
 ## Required Packages
-1. [AstroPy](https://www.astropy.org/)
-2. [AstroQuery](https://astroquery.readthedocs.io/)
-3. [GalPy](https://docs.galpy.org/)
-4. [NumPy](https://numpy.org/)
-5. [Pandas](https://pandas.pydata.org/)
-6. [Pytorch](https://pytorch.org/)
-
-## Usage
-The Sagitta pipeline can be invoked by running the [sagitta.py](./Sagitta/sagitta.py) file directly or using command "sagitta" via the command line.
-
-(TODO: Build this into the setup.py functionality)
-(TODO: Make some TTYGIFs of the pipeline being run)
+* [AstroPy](https://www.astropy.org/)
+* [AstroQuery](https://astroquery.readthedocs.io/)
+* [GalPy](https://docs.galpy.org/)
+* [NumPy](https://numpy.org/)
+* [Pandas](https://pandas.pydata.org/)
+* [Pytorch](https://pytorch.org/)
 
 ## Paper Reference
 [Untangling the Galaxy III: Photometric Search for Pre-main Sequence Stars with Deep Learning](https://arxiv.org/abs/2012.10463)

requirements.txt

@@ -0,0 +1 @@
+#