Galaxy Builder - Basic Operation Manual


Galaxy Builder (galbuilder) is an IDL-based population synthesis SED-fitting and synthetic-photometry code.  It is designed for ease of use, for handy plotting of small numbers of galaxy SEDs, and for direct fitting of a small number of key physical parameters.  It is NOT numerically optimized (it's slow), so it's not ideal for large surveys. It is also not as extensively tested as other available SED fitters and makes more assumptions.

This manual is a first draft and is in a somewhat minimal state.  Eventually it will be filled in with more detail.

Last updated 2016-11-03 by Daniel Perley (dperley@dark-cosmology.dk)


INSTALLATION:

   1. Create the subdirectory 'galbuilder' somewhere on your hard drive (probably
      in your IDL directory), and unpack the contents of this installation file
      there (e.g.,  tar -xvf galbuilder.tar.gz).

   2. You will need to tell IDL about the existence of this new directory by 
      editing your idl_startup file (which in turn is specified by .idlenv or 
      in your .bashrc or .cshrc file) to add the string 
      ":+/path/to/galbuilder:+/path/to/galbuilder/dependencies/"
      to the IDL_PATH argument.  The GSFC IDLastro routines must also be
      installed (and visible within IDL_PATH); see http://idlastro.gsfc.nasa.gov/
      for programs and instructions.

  3. Test that the code is working by typing the following in IDL:
       IDL> galsedfit, '', ['u','g','r','i','z'],[3.6,4.7,5.7,5.7,5.7],[0.3,0.4,0.5,0.5,0.5], z=0.15
     It should produce no errors, output a listing of fitted parameters, and write several output files.

BASIC PROCEDURE:

  1. First create a photometry file containing photometry of your galaxy or galaxies.  It should look like this:
       * galaxy1  z=0.20  E(B-V)=0.05
       u    22.54  0.07  std no KeckI/LRIS     2014-01-10  Author+2015
       g    22.10  0.14  std no SDSS          
       r    21.85  0.14  std no SDSS          
       R    21.75  0.02  std no
       * galaxy2  z=0.15  E(B-V)=0.023
       B    22.10  0.12  std no           
       i    21.80  0.04  std no SDSS
       J    21.01  0.11  AB  no P200/WIRC
       H    20.31  0.15  AB  no P200/WIRC
       Ks  >20.00  -     AB  no P200/WIRC     # note: cloudy run
       
    The columns are: 
      (1) standard filter name   
      (2) magnitude
      (3) magnitude 1-sigma uncertainty (note error bars are nonlinear in mag space; this is the uncertainty towards higher flux)
      (4) calibration system: either "std" for the most common of the relevant filter, or "AB" for AB magnitude.
          You should use "std" for SDSS mags (although they are assumed to be logarithmic, pogson mags), 2MASS mags, etc.
      (5) is this magnitude corrected for foreground extinction?  "yes" means it is corrected already.  
          "no" means that we still need to correct it ourselves, using the E(B-V) value above.
      (6,7,8) - The telescope, date, and reference.  They are optional and can be omitted.
   They can be delimited by spaces or tabs.  Use a # to comment out lines.


  2. Next create a model file containing your initial guesses and/or parameter constraints for the fit.  It looks like this:
 #galaxy   z    SFR  age    age2     tau mass    Av dust Avembed fembed Tdust metal gasmetal q
 galaxy1  0.20* 0.25 1e+08  1.12e+10* -1 4.6e+08 0  calz 50*     0*     45*   0.2*  0.375*   1e+08*
 galaxy2  0.15* 0.18 1e+08* 1.11e+10* -1 3.2e+08 0* calz 50*     0*     40*   1*    1*       1e+07*
 The columns should be largely self-explanatory (mass units are solar, time units are yr, dust units in mag, temperature in K, metallicity in solar)
 An asterisk (*) denotes a FIXED parameter.
 A parameter set to -1 will be set to its default, or be tied to other parameters.  In particular if the age parameters are both set to -1,
 then the SFH will default to a simple continuous SFH in which SFR*age==mass.

 Note that the redshift in the photometry file controls the plot only.  The redshift in the model file affects the actual SED model.


  3. Run the code:
    IDL> galsedfit, 'galaxy1', phot='photometryfile.dat', model='modelfile.dat'

  If all goes well, it should finish successfully and write out a number of files:
      outmodelpar.dat - Contains output parameters in the same format as input parameters.  You can copy these back into the model file to rerun from the new best-fit point.
      modelphot.dat - Contains a table of residual information, useful for identifying outliers.
      modelsed.txt  - Contains an ASCII table of the best-fit SED.  (???)
      outsol.dat  - Ignore this for now
      sav/ - Directory with saved IDL structures storing various information about the fit
      trials/ - Directory with saved information about bootstrap trials
      plots/ - Directory with saved plots

FURTHER INFORMATION:

  4. Advanced usage:
      See buildgalaxy.pro for more options.  Note that you can control the output plot in great detail.
      If the SFH plot is in the way you can set inset=0 or inset=[1,2,3,4] to get rid of it or move it around.
      Use the /replot flag if you just want to change plotting without refitting everything.

  5. Uncertainties and derived parameters:
      The uncertainties in the output text aren't very reliable.  But you can do a lot better with a Monte Carlo run: 
        set trials=50 (or ideally some larger number) to randomly generate noise and repeatedly refit.
        However this can still underestimate the uncertainty if you run into discontinuities in parameter space, such
        as against regions where one of the two SFH components is being zeroed.  Try simplifying the model if this happens.
      You can also use this method to calculate uncertainties on "derived" parameters such as luminosity, but I haven't
        documented that yet.

  6. Troubleshooting
      The fitter may crash on occasion.  The most common causes are one of the following:
        * The photometry underconstrains the number of free parameters being fit.
          (if that's the case try fixing parameters: set A_V=0*, age=-1, etc... 
          or maybe you shouldn't be fitting SEDs on such sparse data?)
        * The initial variables set are physically impossible in combination: if SFR*age1 > mass, for example.
          If this looks like the case, try increasing the mass.
       Sometimes you may just get an inexplicably terrible fit.  Usually this is because the fitter has fallen into some
          local (but non-global) optimum of parameter space.   Try guesstimating the initial mass(/SFR/A_V) better.  
          Reducing the SFR may also help, it might be in a local optimum where everything is with nebular emission(!)
          If that doesn't work, try fixing some parameters, fitting the others, and then loosening the fixed parameters.
       In other scenarios the fit can get into a mode where it is ramming up against a wall in parameter space and gets stuck,
          typically when you fit 2 populations but one of them is being driven towards zero.
          Again, just try fixing/loosening/changing parameters, or use a 1-component model (mass and age only, set SFR, age2 to -1).  
          Double-check your photometry also (any typos?)
          Looking at the SFH subplot can be helpful.

  The code always assumes H=70 km/s/Mpc, Omega_M=0.3, Omega_Lambda=0.7 (the default cosmology in the GSFC cosmology routines).