User Guide

StarbugII has a simple command line interface that follows standard GNU Linux argument input and parsing standards. There are two main programs associated with the tool: starbug2 the core photometry suite of routines and starbug2-match a basic collection of matching routines.

Detailed Guides

Basic Usage

The two basic input and output products are photometric source lists and images. The various starbug2 routines will take and/or export one or both of these products. The program uses standard fits formatted files and for most of the routines, the inputs can either have been created by starbug2 at a previous stage or user defined. The underlying ethos of starbug2 is that the tool is simple and powerful and allows the user to do whatever they want, it is however up to their discretion, whether what they are doing is a good idea. For example, one may conduct forced photometry from HST source lists on JWST images, or run faint source detection on residual images.

To see the basic usage information for starbug2, run:

$~ starbug2 -vh

    usage: starbug2 [-ABDfGhMPSv] [-b bgdfile] [-d apfile] [-n ncores] [-o ouput] [-p file.param] [-s opt=val] image.fits ...
       -A  --apphot          : run aperture photometry on a source list
       -B  --background      : run background estimation
       -b  --bgdfile         : load background (-bgd.fits) file
       -d  --apfile  ap.fits : load a source detection (-ap.fits) file to skip the source detection step
       -D  --detect          : run source detection
       -f  --find            : attempt to find associated -ap -bgd files
       -G  --geom            : calculate geometric stats on source list
       -h  --help            : display uasage information
       -M  --match           : match outputs from all input image files
       -n  --ncores      num : number of CPU cores to split process between
       -o  --output      dir : output directory
       -p  --param   a.param : load parameter file
       -P  --psf             : run psf photometry
       -s  --set      option : set value in parameter file at runtime (-s SIGSKY=3)
       -S  --subbgd          : subtract background from image
       -v  --verbose         : display verbose outputs

       --> Single run commands
           --init                     : Initialise Starbug (post install)
           --local-param              : Make a local copy of the default parameter file
           --update-param             : Update an out-of-date local parameter file
           --generate-psf             : Generate a single PSF. Set FILTER, DET_NAME, PSF_SIZE with -s
           --generate-region   a.fits : Make a ds9 region file with a detection file
           --generate-run      *.fits : Generate a simple run script
           --version                  : Print starbug2 version

           --apply-zeropint    a.fits : Apply a zeropoint (-s ZP_MAG=1.0) to a.fits
           --calc-instr-zp     a.fits : Calculate and apply an instrumental zero point onto a.fits

       --> typical runs
          $~ starbug2 -vD -p file.param image.fits      //Source detect on image with a parameter file
          $~ starbug2 -vDM -n4 images*.fits             //Source detect and match outputs of a list of images
          $~ starbug2 -vd image-ap.fits -BP image.fits  //PSF photometry on an image with a source file (image-ap.fits)

For basic usage information for starbug2-match, run:

$~ starbug2-match -vh

    usage: starbug2-match [-BGfhv] [-o output] [-p file.param] [-s KEY=VAL] table.fits ...
        -B  --band               : match in "BAND" mode (does not preserve a column for every frame)
        -C  --cascade            : match in "CASCADE" mode (left justify columns)
        -D  --dither             : match in "DITHER" mode (preserves a column for every frame)
        -f  --full               : export full catalogue
        -G  --generic            : match in "GENERIC" mode
        -h  --help               : show help message
        -o  --output  file.fits  : output matched catalogue
        -p  --param   file.param : load starbug parameter file
        -s  --set     option     : set value in parameter file at runtime (-s MATCH_THRESH=1)

        --> typical runs
           $~ starbug2-match -Gfo outfile.fits tab1.fits tab2.fits
           $~ starbug2-match -sMATCH_THRESH=0.2 -sBRIDGE_COL=F444W -Bo out.fits F*W.fits