# galclassify
Perform stellar classifications using a synthetic population generated by Galaxia

**EPIC classification results for K2 targets can be found in galclassifyk2/output/.**

### Documentation:
- Huber et al. (2016), ApJS 224, 2: http://adsabs.harvard.edu/abs/2016ApJS..224....2H
- Sharma et al. (2011): http://adsabs.harvard.edu/abs/2011ApJ...730....3S


### Dependencies:
* Galaxia: http://galaxia.sourceforge.net/ (the galaxia executable needs to be in your path; NB galaxia is only needed if you're generating new catalogs) <br/>
* IDL/GDL: ASTROLIB, Coyote Library, and EBF (http://ebfformat.sourceforge.net/build/intro.html) <br/> 
* Code is tested and functional with GDL 0.9.5 (open source implementation of IDL; using GDL additionally requires installation of the CMSVLIB library: https://www.physics.wisc.edu/~craigm/idl/cmsave.html to restore IDL save files)


## galclassifyk2:

Code used to classify stellar sources targeted by the K2 mission for the Ecliptic Plane Input Catalog (EPIC). This can be used to e.g. extract posteriors for any given EPIC target or derive classifications for a new campaign. 

#### Prerequisites:

galclassifyk2 uses databases which need be generated/downloaded before classifications can be done. Assuming you're starting from scratch, the procedure is as follows:

1) Download and unzip astrometric and spectroscopic input catalogs (LAMOST DR1, APOGEE DR12, RAVE DR4, TGAS) here:
https://drive.google.com/drive/folders/15FWKqCen2z1qwSuEAgZQVViKbav-WbUE?usp=sharing
and place them in the catalogs/ directory. 

2) Download and unzip an EPIC from MAST:
http://archive.stsci.edu/missions/k2/catalogs/
You want catalogs without 'missing' in the filename, i.e. the original EPIC for a given campaign. For C1, for example, this will be d1435_02_epic_field1_dmc.mrg (see epicfiles.txt for the filenames for other campaigns). Place the EPIC file in the epics/ directory.
Update: Since sometime in late 2016 this is now one massive csv file.

3) Run the readepic.pro script, which creates a data structure from the EPIC file downloaded in step 2:
```	
.compile main
readepic
```	
This will create the file epics/epic.ebf.


4) Download and unzip the Galaxia synthetic population for a given campaign here:
https://drive.google.com/drive/folders/13Hniwt-hqa_ehKINIwOiiw76K-npCbpH?usp=sharing
and place it in the galaxia/ directory. 

Now everything should be ready to run classifications. 


#### Examples:

Example calling sequences from IDL/GDL for C1:

Check result for EPIC201121245 only:
```	
classifyk2,epicin=201121245
```	

The result should be something like: <br />
[parameter median +1sig -1sig originalstep adjustedstep] <br />
Teff       4899.1720       78.495985       78.495985       49.059991       19.623996 <br />
log(g)       2.9718189      0.46199999      0.53899999   0.00500000     0.076999998 <br />
[Fe/H]     -0.39738958      0.29999995      0.35999994    0.0500000     0.059999990 <br />
Rad       4.8207513       4.5357750       1.6357121   0.00100000     0.035999990 <br />
mass       1.0046383      0.22135916      0.10061780    0.0091470726     0.020123560 <br />
rho    0.0063197528     0.022567087    0.0054866470   0.00500000      0.10999999 <br />
distance       601.48027       445.69961       196.69803   0.00100000     0.034399986 <br />
E(B-V)     0.031316837     0.017600000     0.011000000   0.00100000    0.0022000000


Run the whole C1 target sample and plot the output for each star (you'll be prompted after each star):
```	
classifyk2,cam=1,/pl
```	

Check result for EPIC201121245 & EPIC201122521, and plot result:
```	
classifyk2,epicin=[201122521,201121245],/pl
```	

Check result for EPIC201121245, plot result, and output 10000 posterior samples:
```	
classifyk2,epicin=201121245,/pl,sample=10000
```	

Run the whole C1 target sample without plotting:
```	
classifyk2,cam=1
```	

#### Random and important notes:

- The directory location of the files in step 1, 2 and 3 as well as the output directory can be modified the "paths.txt" file.
- If you change the names of EPIC input files downloaded from MAST, make sure to edit the epicfiles.txt file which links each campaign number to the file name.
- The spectroscopic catalog cross-matching routine is crude, and might throw a memory allocation error depending on your setup. If that's the case, try to increase the search radius parameter in classifyk2.pro (search for range = 3./60./60.). The catalog matching also takes some time, so if you're running multiple stars make sure to pass arrays of EPIC IDs as input.


#### Generating new catalogs:

If you want to generate new classifications (i.e. for campaigns not covered in the paper), the procedure is as follows:

- Repeat steps 2 and 3 above for the desired campaign.
- Update coords.txt with the coordinates for the field.
- Generate a Galaxia synthetic population for the field. To do this, run:

```	
makegalaxiasim,cam=x
```	

where x is the desired campaign number. This will create the file galaxia/cx_model.ebf.

- Run classifyk2 on all stars:
```	
classifyk2,cam=x
```	
This generates a file named k2cx_stparas_raw.idl in the output directory. 

- Run the consolidation routine:
```	
consolidate,cam=x
```
This generates a files named k2cx_stparas.idl and k2cx_stparas.txt in the output directory. 





## galclassify:

Stand-alone version of the Galaxia classification code to classify any given star (not necessarily observed by K2) given some input observables. Unlike galclassifyk2 this code generates a synthetic population for each star given some radius, rather than using a precomputed population over a large field. Suitable for individual stellar classifications, but slow if you want to classify large samples of stars.

#### Usage:

Calling sequence from IDL/GDL:
```
galclassify,input=input
```

**Required input parameters:**	<br/>
input ... plain ascii file containing observables in a fixed format; see tychostar.txt for an example <br/>

**Optional input parameters:**	<br/>
sample	... specifies how many posterior samples should be saved in a text file  <br/>
pl      ... set if you want to see plots

**Output:**	<br/>
If sample is not set, the default output will be the median and 1-sigma confidence interval for each parameter (printed in the terminal) and graphical output of posteriors and observables. If sample is set, the text files containing the posteriors (both discrete and sampled) will be written to the output/ directory

**Example:** <br/>
Classify some random Tycho star:
```	
galclassify,input="tychostar.txt"
```

Classify some random Tycho star and save posteriors with 10000 samples:
```	
galclassify,input="tychostar.txt",sample=10000
```

Classify the Sun at J=10mag and plot result:
```	
galclassify,input="sun_at_J10.txt",/pl
```

#### Random and important notes:
* For bright stars Galaxia will take a very long time to run, and most likely the population will still be too sparse for meaningful inference - in this case it's better to use traditional isochrone modeling.
* The posterior sampling is still very crude, and for stars with poor model coverage the samples will be dominated by a few distinct models