Merge branch 'master' of https://github.com/sweverett/Balrog-GalSim

README.md

@@ -20,19 +20,20 @@ git clone [email protected]:sweverett/Balrog-GalSim.git
 
 ## Running Balrog
 
-Balrog is run with a python call to the script `balrog_injection.py`, with a few extra (required and optional) input arguments:
+(Updated as of 4/5/18) Balrog is run with a python call to the script `balrog_injection.py`, with a few extra (required and optional) input arguments that can either be passed by command line:
 
 ```
-python balrog_injection.py [config_file] [tile_list] [geom_file] [-t tile_dir] [-c config_dir] \
+python balrog_injection.py [config_file] [-l tile_list] [-g geom_file] [-t tile_dir] [-c config_dir] \
                            [-p psf_dir] [-o output_dir] [-v --verbose]
 
 ```
+or explicitly in the `config_file` described below:
 
-* `config_file`: A GalSim config file (for now .yaml, but more types in future) that defines universal parameters for all injections. Chip-specific config parameters are appended to this file during processing. Each DES tile will produce a separate yaml config that handles all injections for all chips in all bands that overlap with the tile ([see GalSim's Demo 6](https://github.com/GalSim-developers/GalSim/blob/master/examples/demo6.yaml) to see how appended configs work / look). An example balrog config file is given in `configs/bal_config.yaml`.
+* `config_file`: A GalSim config file (for now .yaml, but more types in future) that defines universal parameters for all injections. Chip-specific config parameters are appended to this file during processing. Each DES tile will produce a separate yaml config that handles all injections for all chips in all bands that overlap with the tile ([see GalSim's Demo 6](https://github.com/GalSim-developers/GalSim/blob/master/examples/demo6.yaml) to see how appended configs work / look). An example balrog config file is given in `configs/bal_config.yaml`. It also includes a description of how to pass these command-line input arguments in the config itself.
 * `tile_list`: A txt or csv file that contains a list of all tiles that are to be processed. Delimiter can be commas or newlines.
 * `geom_file`: The fits file containing tile geometry (e.g. `Y3A2_COADDTILE_GEOM.fits`).
 * `tile_dir`: Directory location that contains all desired DES tile files/folders (i.e. for N tiles, the location would contain at least the N directories `/DES0001-0001`, `/DES0001-0002`, etc.). Set to `.` by default.
-* `config_dir`: Directory location of the global GalSim config file. tile list file, and geometry file if not given in inputted filenames (the files only must be in the same directory if this is passed). Set to `.` by default.
+* `config_dir`: Directory location of the global GalSim config file. tile list file, and geometry file if not given in inputted filenames (the files only must be in the same directory if this is passed). Set to `.` by default. Cannot be set in `config_file` (for obvious reasons).
 * `psf_dir`: Relative directory path of a tile's psf *from* a given tile location (e.g. `{tile_dir}/{TILE}/{psf_dir}`). Set to `psfs` by default.
 * `output_dir`: Location of parent output directory for Balrog images and config files. Images are saved as `{output_dir}/balrog_images/{realization}/{tilename}/{band}/{chipname}_balrog_inj.fits`, and tile configs are saved to `{output_dir}/configs/bal_config_{realization}_{tilename}.yaml`.
 * `verbose`: Use -v for more verbose messages.
@@ -106,18 +107,24 @@ python balrog/balrog_injection.py config/bal_config.yaml inputs/tilelist.csv inp
 -t inputs/tiles -o outputs/
 ```
 
+Alternatively, these values could have been set in the `image` field of the `config_file` (except for `output_dir`; see example file) in which case you would simply type
+
+```
+python balrog/balrog_injection.py config/bal_config.yaml
+```
+
 ## Balrog Config
 
 The global balrog config file is very similar to yaml config files used for GalSim. Check out the [GalSim demo page](https://github.com/GalSim-developers/GalSim/wiki/Tutorials) for lots of examples of how to use the yaml files and how they are translated to python scripts. The important parts are summarized in the comments of the example config [bal_config.yaml](https://github.com/sweverett/Balrog-GalSim/blob/master/config/bal_config.yaml). (**Note**: You will need to change a few path names in the config file to work for your local machine!) 
 
 However, note that a Balrog config will **not** run successfully if called by the `galsim` executable; it only houses the global simulation variables while the individual chip injections parameters are set during the `balrog_injection.py` script. Each tile produces its own complete multi-output yaml config file that is sent to `galsim` at the end of processing.
 
 There are a few config inputs specific to the `image` field of Balrog configs that are worth highlighting here:
-* `n_galaxies`: The total number of galaxies to be injected per DES tile.
-* `gal_density`: The final injected Balrog galaxy density in the tile field.
+* `n_galaxies`: The total number of galaxies to be injected per DES tile **per realization**.
+* `gal_density`: The injected Balrog galaxy density in the tile field **per realization**.
 * `n_realizations`: The number of injection realizations used to reach the desired galaxy count or density.
 
-Two things to note: (1) **Only one** of `n_galaxies` or `gal_density` is allowed as an input; not both! (2) Either input should give the desired **final** count or density. The script will calculate the injection number per realization given the input and the total number of realizations to be computed.
+Two things to note: (1) **Only one** of `n_galaxies` or `gal_density` is allowed as an input; not both! (2) Either input should give the desired count or density **per realization**!. An older version of the code had this set to the desired final count/desnity, but this was counter-intuitive for users.
 
 ## Input Catalogs