search

sweverett / Balrog-GalSim

Modules for GalSim that will be useful for DES images in conjunction with Balrog.
MIT License
5 stars 5 forks source link

readme

Balrog-GalSim

Balrog is an image simulation tool for making randoms and characterizing systematics by embedding fake objects into real imaging to accurately characterize measurement biases. This is an extension of the work done by Suchyta et al. for science verification data of the Dark Energy Survey (DES). Check out the original repo here.

While Balrog is not specific to DES, the current version of this code only supports DES chip images and ngmix galaxy catalogs for injection inputs. Hopefully this generalization will be added soon; in the meantime, you can start a branch and one of the developers will help guide you on what small changes need to be made. Most changes can be made in the input GalSim config file.

The archived repository for the DES Year 3 (Y3) cosmology analysis calibration described in Everett et al. 2020 can be found here: DOI

Installation

The only non-standard Balrog dependency is GalSim. While it's a non-trivial install, the installation wiki found here outlines the steps in great detail. (edit - Galsim 2.0+ can now be installed with pip/conda!)

Once GalSim is installed, simply clone this repo:

git clone git@github.com:sweverett/Balrog-GalSim.git

Running Balrog

(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] [-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:

Required Directory Structures

Note that the current version of Balrog only supports DES injections. Part of this requirement is due to an assumption of how tiles and single exposure chips are are named and structured with respect to one another. Inside the tile_dir there should be a collection of directories with DES tilenames with each housing the nullweight chip images in their respective {tilename}/{nullwt-{band}} directories. Visually:

Balrog-Galsim
│   README.md    
│
└───balrog
|      ...
|
└───config
|      ...
└───inputs
│   │
│   └───tiles
|       |   
│       └───DES2329-5622
|       |    |
|       |    └───nullwt-g
|       |    |      gchip1.fits
|       |    |      gchip2.fits
|       |    |      ...
|       |    └───nullwt-r
|       |    |      rchip1.fits
|       |    |      rchip2.fits
|       |    |      ...
|       |    └───nullwt-i
|       |    |      ...
|       |    └───nullwt-z
|       |    |      ... 
|       |    └───psfs
|       |           psf1.fits 
|       |           psf2.fits 
|       |           ...
|       └───DES2349+1334
|       |       ...
|       └───DES0744+1126
|       |       ...
|       └───...
|   
└───output_dir
    |
    └───conifgs
    |       ...
    └───balrog_images
        |
        └───DES2329-5622
        └───DES2349+1334
        ...

Example Usage

Let's say you are running the standard DES Y3 setup for Balrog. Then running from the repo home you would use the following values for the above inputs:

and so the terminal command would be

python balrog/balrog_injection.py config/bal_config.yaml inputs/tilelist.csv inputs/Y3A2_COADDTILE_GEOM.fits \
-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 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. (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:

Two things to note: (1) Only one of n_objects or object_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

(more later - for now, ngmix_catalog, meds_catalog, des_star_catalog. See balinput.py and balobject.py)

(Fits file containing input objects to be injected into chip images. For now only ngmix catalogs are supported (gauss, cm, or mof photometry), but the code is designed to allow other input types in future including galaxy postage stamps. Some of the standard GalSim inputs may also work, but arent' currently supported.)

More to come...

Contributors