Artificial Star Input Lists¶

The BEAST requires artificial star tests (ASTs) to produce a noise model. The AST input list software generates lists of magnitudes and (if desired) positions for ASTs that can be injected into the observed imaging and then re-photometered to assess the photometric bias, uncertainty, and completeness as a function of the model grid. The output from this software must be run through the same photometry routine (typically DOLPHOT) as used for the photometry measurements themselves.

Once the input lists have been run through the user’s photometry program and each input flux has an associated output flux, those results can be used as input ASTs for the building the BEAST noise model.

To generate a BEAST-friendly lists of artificial stars, follow the BEAST Workflow instructions. There are two methods by which the artificial SEDs can be chosen.

Flux bin method (recommended): The range of fluxes in the model grid is split into bins (default=40, set by ast_n_flux_bins), and models are randomly selected. The model is retained if there are fewer than the set number of models (default=50, set by ast_n_per_flux_bin) in each of the relevant flux bins.
Random SEDs method (not recommended): Generate fake stars by uniformly sampling log(age) space and randomly drawing from the metallicities in the model grid. This results in uneven constraints on the noise model, since there will be very few stars that probe the brightest or faintest parts of the model grid.

If the user needs to supplement their existing input ASTs in particular areas of the color-magnitude diagrams set by bright and faint magnitudes in each filter, the user can use ‘–suppl_seds’ option when generating additional input ASTs. By default, new input ASTs will be randomly selected within the given magnitude ranges.

Functions¶

Picking SEDs¶

These functions are found in beast.observationmodel.ast.make_ast_input_list.

pick_models: Samples the model grid and outputs models that fit within the mag limits.
pick_models_toothpick_style: Tries to pick models in a way that evenly samples the range of fluxes in each band. Models will be picked until each magnitude bin for each band is covered by a given number of fake stars.
mag_limits: Determines the magnitude limits for the models in each filter in the photometry file.
supplement_ast: Supplement the existing input ASTs that fulfill the user defined magnitude limits.

Picking positions¶

These functions are found in beast.observationmodel.ast.make_ast_xy_list.

pick_positions: Uses the observed stellar catalog to distribution the artificial stars in a similar spatial pattern to the observed catalog
pick_positions_from_map: Uses one of the maps generated by create_background_density_map to make sure that each of the different source density or background regimes in the image are properly sampled. The source density or background range is divided into bins, and the set of SEDs chosen by one of the pick_models functions above is then reused for each background intensity bin.

Parameters in beast_settings.txt¶

Parameters used by the flux bin method of selecting SEDs¶

ast_n_flux_bins : integer (Default = 40)

Number of flux bins into which the dynamic range of the model grid in each filter is divided (if pick_models_toothpick_style is used)
ast_n_per_flux_bin : integer (Default = 50)

Minimum number of model SEDs that need to fall into each bin (if pick_models_toothpick_style is used)

Parameters used by the random SED selection method¶

ast_bands_above_maglimit : integer (Default = 3)

Number of filters that must be above the magnitude limit for an AST to be included in the list
ast_maglimit : float (single value or array with one value per filter)
- option 1: [number] to change the number of mags fainter than the 90th percentile faintest star in the photometry catalog to be used for the mag cut. (Default = 1)
- option 2: [space-separated list of numbers] to set custom faint end limits (one value for each band).
ast_models_selected_per_age : integer (Default = 70)

Number of models to pick per age

Parameters used by the supplementing AST method¶

ast_supplement : bool

If True, supplement the existing input ASTs
ast_N_supplement : integer (Default = 1000)

Number of unique model SEDs to select. These selected unique SEDs will be repeated over N number of source density bins. In total, the user will supplement ast_N_supplement x ast_N_bins
ast_existing_file : string (optional)

If the name of the existing input AST parameter file is supplied, additional ASTs will be selected by excluding the SED models listed in that file.
ast_suppl_maglimit : dictionary (optional)

If supplied, these magnitude limits will be applied to the SED model grids when selecting additional ASTs. This is a dictionary that includes information for the magnitude cuts as a function of the filters included in observation.

For example, for a field observed with HST_WFC3_F475W and HST_WFC3_F814W, to set a magnitude range limit of 16<HST_WFC3_F475W<28 mag, and 15<HST_WFC3_F814W<27 mag you need to set the following within the beast_settings file:
```
# initialize and populate the dictionary of desired magnitude limits
ast_suppl_maglimits = {}

# the magntidue limits are defined by the filter and a list of the limits in magnitudes
ast_suppl_maglimits["HST_WFC3_F475W"] = [16,28]
ast_suppl_maglimits["HST_WFC3_F814W"] = [15,27]

# set the key word
ast_suppl_maglimit = ast_suppl_maglimits
```
or, equivalently:
```
ast_suppl_maglimit = {‘F475W’: (16,28), ‘F814W’: (15,27)}
```
ast_suppl_colorlimit : dictionary (optional)

If supplied, these color limits will be applied to the SED model grids when selecting additional ASTs. This is a dictionary that includes information for the color cuts as a function of the filters included in observation.

For example, for a field observed with HST_WFC3_F336W, HST_WFC3_F475W, and HST_WFC3_F814W, to set a color range limit of HST_WFC3_F475W-HST_WFC3_F814W<6, HST_WFC3_F336W-HST_WFC3_F475W<5 and HST_WFC3_F336W-HST_WFC3_F814W<4, you need to set the following within the beast_settings file:
```
# initialize the dictionary of desired magnitude limits
ast_suppl_colorlimits = {}

# the color limits are defined by the first filter in the color (e.g, X for X-Y),
# and the input is a list including the second filter (e.g., Y for X-Y) and the
# color limit in magnitudes:
ast_suppl_colorlimits["HST_WFC3_F475W"] = [["HST_WFC3_F814W",6]]
ast_suppl_colorlimits["HST_WFC3_F336W"] = [["HST_WFC3_F475W",5], ["HST_WFC3_F814W",4]]

# set the key word
ast_suppl_colorlimit =  ast_suppl_colorlimits
```

Parameters used for selecting SED positions¶

ast_with_positions : boolean

If True, the ast list is produced with X,Y positions.

If False, the ast list is produced with only fluxes.
ast_realization_per_model : integer (Default = 20)

Number of Realizations of each included AST model to be put into the list. The default (20) is necessary for truncheon noise model, but one realization is sufficient for the toothpick noise model.
ast_density_table : string or None

Name of the density table created by tools.create_background_density_map If supplied, pick_positions_from_map will be used to repeat the ASTs in the table for each source density or background density region. The source density and background maps are in the same format.
ast_N_bins : integer (Default = 4)

Number of source density or background bins that you want ASTs repeated over
ast_pixel_distribution : float (Default = 10)

(Used if ast_with_positions is True and ast_density_table is None)

Minimum pixel separation between AST position and catalog star used to determine the AST spatial distribution.
ast_reference_image : string or None

Name of the reference image used by DOLPHOT when running the measured photometry. Used by pick_positions_from_map to convert coordinates between x/y and RA/Dec. Note that if your catalog only has x/y positions (not RA/Dec), this must be specified for some of the boundary checkers to function.
ast_coord_boundary : list of two arrays, or None

If supplied, these RA/Dec coordinates will be used to limit the region over which ASTs are generated. Input should be list of two arrays, the first RA and the second Dec, ordered sequentially around the region (either CW or CCW).

Returns¶

Table of fake star fluxes for all bands in the beast_settings photometry file. The file will be in ascii format in the project directory, and it will have the name [project]/[project]_inputAST.txt.

The table will have either approximately ast_n_flux_bins * ast_n_per_flux_bin * ast_realization_per_model (flux bin method) or <number of ages> * ast_models_selected_per_age * ast_realization_per_model (random SEDs method) lines. If the source density or background levels are being utilized, this number will be multiplied by the number of bins chosen. If ast_with_positions is True then each line will start with 0 1 X Y, which are the first four columns required by DOLPHOT to define the input star position.

The code will also optionally output a fits file, [project]/[project]_ASTparams.fits, which has the physical parameters associated with each of the artificial stars as well as their indices in the spec and sed grids. It will have either approximately ast_n_flux_bins * ast_n_per_flux_bin lines or <number of ages> * ast_models_selected_per_age lines, and has the same columns as the main SED grid file.

Navigation