galstar
=======


Setup and Build
===============

  ./configure --with-libpeyton=../libpeyton/optimized --optimized --prefix=`pwd`/staging
  make -j install

This will configure and build an optimized version of galstar in
./optimized and install it in directory ./staging linking against 
an optimized version of libpeyton from ../libpeyton/optimized


Quick Test
==========

  greg@greg-G53JW:~/projects/galstar/build$ ./galstar --help
  Usage: ./galstar <outfile1.txt:X1[,Y1]> [outfile2.txt:X2[,Y2] [...]]
  
  Options:
    --help                produce this help message
    --pdfs arg            marginalized PDF to produce (can be given as the 
                          command line argument)
    --lf arg              luminosity function file
    --seds arg            SEDs file
    --thindisk arg        Thin disk model parameters (l1 h1)
    --thickdisk arg       Thick disk model parameters, (f_thin l2 h2)
    --halo arg            Halo model parameters, (f_halo q n_inner R_br n_outer)
    --test                Assume the input contains (l b Ar DM Mr FeH uErr gErr 
                          rErr iErr zErr) and generate test data
    --range-M arg         Range of absolute magnitudes to sample
    --range-FeH arg       Range of Fe/H to consider
    --range-DM arg        DM grid to sample
    --range-Ar arg        Ar grid to sample
    --datafile arg        Stellar magnitudes and errors file
    --statsfile arg       Base filename for statistics output


Quick Demo
==========

Running galstar on a pencil-beam catalog (test.in):

  greg@greg-G53JW:~/projects/galstar/build$ ./galstar ../output/test/DM_Ar:DM,Ar --datafile ../test_input/test.in --statsfile ../output/test/stats
  # Outputting P(DM, Ar) into file ../output/test/DM_Ar
  # Loaded Phi(-1 <= Mr <= 28) LF from /home/greg/projects/galstar/staging/share/galstar/MrLF.MSandRGB_v1.0.dat
  # Loaded 147951 SEDs from /home/greg/projects/galstar/staging/share/galstar/MSandRGBcolors_v1.3.dat
  # Galactic structure: 8000 25 | 2150 245 | 0.13 3261 743 | 0.0051 0.7 -2.62
  # Loading stellar magnitudes from ../test_input/test.in ...
  # Sampler: DM=[5..20..0.02] Ar=[0..5..0.02] Mr=[ALL] FeH=[ALL]
  =========================================
  Calculating posterior for star #0
  
  Mean:
  	13.7	+-	0.517
  	0.206	+-	0.093
  	3.8	+-	0.493
  	-1.32	+-	0.214
  
  Covariance:
  	0.268	-0.0157	-0.251	-0.0295
  	-0.0157	0.00866	0.00719	-0.00353
  	-0.251	0.00719	0.243	0.0325
  	-0.0295	-0.00353	0.0325	0.0458
  
  Gelman-Rubin diagnostic:
  1.037	1.0459	1.049	1.0886
  Acceptance rate: 18.4% 4.2% 4.04% 3.99%
  
  Time elapsed for 2000000 steps (20 rounds) on 4 threads: 4.14 s
  
  =========================================
  Calculating posterior for star #1
  
  Mean:
	14.9	+-	0.549
	0.185	+-	0.1
	4.53	+-	0.584
	-1.67	+-	0.265

  Covariance:
  	0.302	0.0166	-0.317	0.0208
  	0.0166	0.0101	-0.0263	-0.00546
  	-0.317	-0.0263	0.341	-0.0158
  	0.0208	-0.00546	-0.0158	0.0703
  
  Gelman-Rubin diagnostic:
  1.0003	1.0001	1.0003	1.0001
  Acceptance rate: 19.7% 19.6% 15.9% 17.6%
  
  Time elapsed for 100000 steps (1 rounds) on 4 threads: 0.286 s
  
  =========================================
  Calculating posterior for star #2
  
  Mean:
  	11.3	+-	0.712
  	0.25	+-	0.112
  	4.08	+-	0.691
  	-0.741	+-	0.15
  
  Covariance:
  	0.506	-0.0186	-0.486	0.00625
  	-0.0186	0.0125	0.00631	0.00229
  	-0.486	0.00631	0.477	-0.00855
  	0.00625	0.00229	-0.00855	0.0225
  
  Gelman-Rubin diagnostic:
  1.1898	1.0141	1.1918	1.045
  Acceptance rate: 4.02% 3.92% 4.05% 4.04%
  
  Did not converge.
  
  Time elapsed for 2000000 steps (20 rounds) on 4 threads: 3.56 s
  
  =========================================
  Calculating posterior for star #3
  
  Mean:
  	15.2	+-	0.445
  	0.152	+-	0.076
  	3.96	+-	0.442
  	-1.48	+-	0.261
  
  Covariance:
  	0.198	-0.00362	-0.194	0.00939
  	-0.00362	0.00578	-0.00203	-0.00731
  	-0.194	-0.00203	0.195	-0.00253
  	0.00939	-0.00731	-0.00253	0.0679
  
  Gelman-Rubin diagnostic:
  1.0002	1	1.0002	1.0001
  Acceptance rate: 20.4% 19.5% 20.6% 18.6%
  
  Time elapsed for 100000 steps (1 rounds) on 4 threads: 0.302 s
  
  =========================================
  Calculating posterior for star #4
  
  Mean:
  	15.3	+-	0.614
  	0.225	+-	0.116
  	4.59	+-	0.642
  	-1.7	+-	0.274
  
  Covariance:
  	0.377	0.0131	-0.388	0.0286
  	0.0131	0.0135	-0.0261	-0.00548
  	-0.388	-0.0261	0.412	-0.0235
  	0.0286	-0.00548	-0.0235	0.0753
  
  Gelman-Rubin diagnostic:
  1.0002	1.0003	1.0001	1.0001
  Acceptance rate: 19.5% 19.2% 18.2% 18.7%
  
  Time elapsed for 100000 steps (1 rounds) on 4 threads: 0.318 s
  
  
  # Did not converge 1 times.


Create an input file from an SDSS fits file using the script read_sdss.py:

  greg@greg-G53JW:~/projects/galstar/build$ ../scripts/read_sdss.py --help
  usage: read_sdss [-h] [--filter FILT] [--toscreen] inputs [inputs ...]
  
  Translate FITS files of SDSS objects to ASCII input for galstar
  
  positional arguments:
    inputs         FITS files
  
  optional arguments:
    -h, --help     show this help message and exit
    --filter FILT  Filter objects with errors greater than the specified amount
    --toscreen     Print results to screen, rather than outputting to ASCII
                   files

Another useful script is plotpdf.py:

  greg@greg-G53JW:~/projects/galstar/build$ ../scripts/plotpdf.py --help
  usage: plotpdf [-h] --output OUTPUT [--imgtype {png,pdf,eps}]
                 [--shape SHAPE SHAPE] [--xname XNAME] [--yname YNAME]
                 [--xmin XMIN] [--xmax XMAX] [--ymin YMIN] [--ymax YMAX]
                 files [files ...]
  
  Plots posterior distributions produced by galstar
  
  positional arguments:
    files                 Input posterior distributions
  
  optional arguments:
    -h, --help            show this help message and exit
    --output OUTPUT       Output image filename base (without extension)
    --imgtype {png,pdf,eps}
                          Output image filetype
    --shape SHAPE SHAPE   # of rows and columns in figure
    --xname XNAME         Name of x-axis
    --yname YNAME         Name of y-axis
    --xmin XMIN           Lower bound of x in plots
    --xmax XMAX           Upper bound of x in plots
    --ymin YMIN           Lower bound of y in plots
    --ymax YMAX           Upper bound of y in plots


  greg@greg-G53JW:~/projects/galstar/build$ ../scripts/plotpdf_greg.py ../output/test/DM_Ar_*.txt --output ../output/test/DM_Ar --shape 3 2 --xname '\mu' --yname 'A_r'
  Plotting files 1 through 5...
  Done.


To plot the stacked posteriors of the output marginalized along all but one dimension, run plot_hist.py:

  greg@greg-G53JW:~/projects/galstar/build$ ../scripts/plot_hist.py --help
  usage: plot_hist [-h] --xname XNAME --output OUTPUT [--xaxis {0,1}]
                   [--subtract-background SUBTRACT_BACKGROUND SUBTRACT_BACKGROUND SUBTRACT_BACKGROUND]
                   [--MLonly | --Pxonly]
                   files [files ...]
  
  Plot stacked pdfs marginalized over one dimension and binned Maximum
  Likelihoods
  
  positional arguments:
    files                 Input posterior distributions
  
  optional arguments:
    -h, --help            show this help message and exit
    --xname XNAME         Name of x-axis
    --output OUTPUT       Output image filename (with extension)
    --xaxis {0,1}         Column to use as x-axis
    --subtract-background SUBTRACT_BACKGROUND SUBTRACT_BACKGROUND SUBTRACT_BACKGROUND
                          Remove background, assuming line-of-sight (l, b,
                          radius), in degrees
    --MLonly              Only plot histogram of binned Maximum Likelihoods
    --Pxonly              Only plot stacked pdfs
  
  greg@greg-G53JW:~/projects/galstar/build$ ../scripts/plot_hist.py ../output/test/DM_Ar_*.txt --output ../output/test/DM_hist.png --xname '\mu'
  25th percentile: 13.62
  Median: 14.53
  75th percentile: 14.97


By the end of this demo, the following output has been produced:

  greg@greg-G53JW:~/projects/galstar/build$ ls ../output/test/
  DM_Ar_0.png  DM_Ar_1.txt  DM_Ar_3.txt  DM_hist.png  stats_1.dat  stats_3.dat
  DM_Ar_0.txt  DM_Ar_2.txt  DM_Ar_4.txt  stats_0.dat  stats_2.dat  stats_4.dat


Input Files
==========

The --datafile option is used to pass a pencil-beam catalog of stellar magnitudes and errors. The format is:
  l	b
  u	g	r	i	z	u_err	g_err	r_err	i_err	z_err
  u	g	r	i	z	u_err	g_err	r_err	i_err	z_err
  ...

In the above demo, the following input file was given:

  greg@greg-G53JW:~/projects/galstar/build$ cat ../test_input/test.in
  60.169	40.978
  19.163	18.067	17.743	17.557	17.564	0.033	0.016	0.013	0.015	0.033
  20.834	20.016	19.653	19.471	19.539	0.115	0.031	0.022	0.025	0.069
  17.290	16.043	15.605	15.410	15.395	0.017	0.014	0.012	0.014	0.030
  20.664	19.623	19.356	19.190	19.168	0.099	0.025	0.019	0.022	0.054
  21.195	20.540	20.097	19.962	19.844	0.155	0.046	0.030	0.034	0.086