desisim API

desisim

Tools for DESI instrument simulations, including input templates. It does not cover cosmology simulations.

desisim.archetypes

Archetype routines for desisim.

class desisim.archetypes.ArcheTypes(chi2)

Object for generating archetypes and determining their responsibility.

Parameters:

chi2 (numpy.ndarray) – Chi^2 matrix computed by desisim.archetypes.compute_chi2().

get_archetypes(chi2_thresh=0.1, responsibility=False)

Solve the SCP problem to get the final set of archetypes and, optionally, their responsibility.

Note: We assume that each template has uniform “cost” but a more general model in principle could be used / implemented.

Parameters:

• chi2 (numpy.ndarray) – Chi^2 matrix computed by archetypes.compute_chi2().

• chi2_thresh (float) – Threshold chi2 value to differentiate “different” templates.

• responsibility (bool) – If True, then compute and return the responsibility of each archetype.

Returns:

• If responsibility==True then returns a tuple of (iarch, resp, respindx) where –

  iarchinteger numpy.array

  Indices of the archetypes [N].

  respinteger numpy.array

  Responsibility of each archetype [N].

  respindxlist of

  Indices the parent sample each archetype is responsible for [N].

• If responsibility==False then only iarch is returned.

responsibility(iarch, a_matrix)

Method to determine the responsibility of each archetype.

In essence, the responsibility is the number of templates described by each archetype.

Parameters:

• iarch (indices of the archetypes) –

• a_matrix (distance matrix) –

Returns:

• resp (responsibility of each archetype (number of objects represented by each archetype))

• respindx (list containing the indices of the parent objects represented by each archetype)

desisim.archetypes.compute_chi2(flux, ferr=None)

Compute the chi2 distance matrix.

Parameters:

• flux (numpy.ndarray) – Array [Nspec, Npix] of spectra or templates where Nspec is the number of spectra and Npix is the number of pixels.

• ferr (numpy.ndarray) – Uncertainty spectra ccorresponding to flux (default None).

Returns:

chi2numpy.ndarray

Chi^2 matrix [Nspec, Nspec] between all combinations of normalized spectra.

ampnumpy.ndarray

Amplitude matrix [Nspec, Nspec] between all combinations of spectra.

Return type:

Tuple of (chi2, amp) where

desisim.bal

Functions and methods for inserting BALs into QSO spectra.

class desisim.bal.BAL

Base class for inserting BALs into (input) QSO spectra.

empty_balmeta(qsoredshift=None)

Initialize an empty metadata table for BALs.

insert_bals(qsowave, qsoflux, qsoredshift, balprob=0.12, seed=None, verbose=False, qsoid=None)

Probabilistically inserts BALs into one or more QSO spectra.

Parameters:

• qsowave (numpy.ndarray) – observed-frame wavelength array [Angstrom]

• qsoflux (numpy.ndarray) – array of observed frame flux values.

• qsoredshift (numpy.array or float) – QSO redshift

• balprob (float, optional) – Probability that a QSO is a BAL (default 0.12). Only used if QSO(balqso=True) at instantiation.

• seed (int, optional) – input seed for the random numbers.

• verbose (bool, optional) – Be verbose!

Returns:

QSO spectrum with the BAL included. balmeta (astropy.Table): metadata table for each BAL.

Return type:

bal_qsoflux (numpy.ndarray)

template_balmeta(indx)

Initialize an empty metadata table for BALs.

desisim.batch

Batch scripts. Why exactly is this sub-package different from desisim.scripts?

desisim.batch.calc_nodes(ntasks, tasktime, maxtime)

Return a recommended number of nodes to use to process ntasks within maxtime if each one takes tasktime minutes.

desisim.batch.pixsim

Provides utility functions for batch processing of pixel-level simulations at NERSC. This is a temporary pragmatic package – after desispec.pipeline code is merged and vetted, this should use that infrastructure for more rigorous logging, environment setup, and scaling flexibility.

Example:

#- From python import desisim.batch.pixsim flavors = [‘arc’, ‘flat’, ‘dark’, ‘dark’, ‘gray’, ‘gray’, ‘bright’, ‘bright’] expids = range(len(flavors)) desisim.batch.pixsim.batch_newexp(‘newexp-blat.sh’, flavors, expids=expids) desisim.batch.pixsim.batch_pixsim(‘pixsim-blat.sh’, flavors, expids=expids)

#- then from the command line [edison] sbatch newexp-batch.sh Submitted batch job 233895 [edison] sbatch -d afterok:233895 pixsim-batch.sh Submitted batch job 233901

desisim.batch.pixsim.batch_newexp(batchfile, flavors, nspec=5000, night=None, expids=None, nodes=None, pixprod=None, desi_spectro_sim=None, tileids=None, seed=None)

Write a slurm batch script for run newexp-desi for the list of flavors

desisim.batch.pixsim.batch_pixsim(batchfile, flavors, nspec=5000, night=None, expids=None, nodes=None, pixprod=None, desi_spectro_sim=None, seed=None)

Write a slurm batch script for run newexp-desi for the list of flavors

desisim.cosmology

All cosmology related routines of desisim should be put here for consistency.

desisim.dla

Functions and methods for inserting DLAs into QSO spectra.

desisim.dla.calc_lz(z, boost=1.6)

Parameters:

• z (ndarray) – redshift values for evaluation

• boost (float) – boost for SLLS (should be 1 if only running DLAs)

Returns:

l(z) aka dN/dz values of DLAs

Return type:

ndarray

desisim.dla.calculate_lox(model, NHI_min, NHI_max=None, neval=10000, cumul=False)

Calculate l(X) over an N_HI interval

Parameters:

• z (float) – Redshift for evaluation

• NHI_min (float) – minimum log NHI value

• NHI_max (float, optional) – maximum log NHI value for evaluation (Infinity)

• neval (int, optional) – Discretization parameter (10000)

• cumul (bool, optional) – Return a cumulative array? (False)

• cosmo (astropy.cosmology, optional) – Cosmological model to adopt (as needed)

Returns:

lX – l(X) value

Return type:

float

desisim.dla.dla_spec(wave, dlas)

Generate spectrum absorbed by dlas :param wave: observed wavelengths :type wave: ndarray :param dlas: DLA dicts :type dlas: list

Returns:

ndarray of absorbed flux

Return type:

abs_flux

desisim.dla.evaluate_fN(model, NHI)

Evaluate an f(N,X) model at a set of NHI values

Parameters:

NHI (array) – log NHI values

Returns:

log_fN – f(NHI,X) values

Return type:

array

desisim.dla.init_fNHI(slls=False, mix=True)

Parameters:

• slls (bool) – SLLS only?

• mix (bool) – Mix of DLAs and SLLS?

Returns:

fNHI model

Return type:

model

desisim.dla.insert_dlas(wave, zem, rstate=None, seed=None, fNHI=None, debug=False, **kwargs)

Insert zero, one or more DLAs into a given spectrum towards a source with a given redshift :param wave: wavelength array in Ang :type wave: ndarray :param zem: quasar emission redshift :type zem: float :param rstate: for random numberes :type rstate: numpy.random.rstate, optional :param seed: :type seed: int, optional :param fNHI: f_NHI object :type fNHI: spline :param **kwargs: Passed to init_fNHI()

Returns:

List of DLA dict’s with keys z,N dla_model (ndarray): normalized specrtrum with DLAs inserted

Return type:

dlas (list)

desisim.dla.voigt_tau(wave, par)

Find the optical depth at input wavelengths Taken from linetools.analysis.voigt

This is a stripped down routine for calculating a tau array for an input line. Built for speed, not utility nor with much error checking. Use wisely. And take careful note of the expected units of the inputs (cgs)

Parameters:

• wave (ndarray) – Assumed to be in cm

• parm (list) –

  Line parameters. All are input unitless and should be in cgs

  par[0] = logN (cm^-2) par[1] = z par[2] = b in cm/s par[3] = wrest in cm par[4] = f value par[5] = gamma (s^-1)

Returns:

tau – Optical depth at input wavelengths

Return type:

ndarray

desisim.dla.voigt_wofz(vin, a)

Uses scipy function for calculation. Taken from linetools.analysis.voigt

Parameters:

• vin (ndarray) – u parameter

• a (float) – a parameter

Returns:

voigt

Return type:

ndarray

desisim.eboss

Functions and methods for mimicking eBOSS survey.

class desisim.eboss.FootprintEBOSS(nside=16)

Class to store eBOSS footprint and provide useful functions.

class desisim.eboss.RedshiftDistributionEBOSS(dz=0.04, nside=16)

Class to store eBOSS redshift distribution fraction to DESI redshift distribution and provide useful functions.

static read_sdss_redshift_distribution(dz, nside)

Read the SDSS redshift fraction ascii file

Parameters:

• dz (float) – Step in redshift

• nside (int) – NSIDE for the sky

Returns:

redshift fraction histogram dictionnary

Return type:

hist (dic)

redshift_fraction(ra, dec, z)

Get the associated fraction for randoms at a given redshift slice

Parameters:

• ra (float, array of float) – Right Ascension

• dec (float, array of float) – Declination

• z (float, array of float) – redshift

Returns:

fraction to use to select randoms

Return type:

fraction (float, array of float)

desisim.eboss.create_sdss2desi_redshift_distribution_ratio(sdss_cat, desi_cat, out, dz=0.04, mjd_min=55000, nside=16, nest=True, zminDensity=1.8, densityCut=30.0)

Create an ascii file giving the subsample fraction as a function of redshift

to get the same redshift distribution in DESI as in SDSS

Parameters:

• sdss_cat (path) – Input SDSS quasar catalog

• desi_cat (path) – Input DESI quasar catalog

• out (path) – Output ascii file

• dz (float) – Step in redshift (default=0.04)

• mjd_min (int) – Minimum MJD (default=55000)

• nside (int) – NSIDE for the sky (default==16)

• nest (bool) – NEST for the sky (default==True)

• zminDensity (float) – Redshift minimum cut to compute the density (default=1.8)

• densityCut (float) – Density criterium for low vs. high (default=30.)

Returns:

None

desisim.eboss.create_sdss_footprint(sdss_cat, out, mjd_min=55000, zmin=1.8, nside=16, nest=True)

Create an ascii file giving for each HEALPix index the

density of quasars in number per square degree

Parameters:

• sdss_cat (path) – Input SDSS quasar catalog

• out (path) – Output ascii file

• mjd_min (int) – Minimum MJD (default=55000)

• zmin (float) – Minimum redshift (default==1.8)

• nside (int) – NSIDE for the sky (default==16)

• nest (bool) – NEST for the sky (default==True)

Returns:

None

desisim.eboss.sdss_subsample(ra, dec, input_highz_density, eboss_footprint)

Downsample input list of angular positions based on SDSS footprint

and input density of all quasars .

Parameters:

• ra (ndarray) – Right ascension (degrees)

• dec (ndarray) – Declination (degrees)

• input_highz_density (float) – Input density of all quasars per sq.deg.

Returns:

mask to apply to downsample input list

Return type:

selection (ndarray)

desisim.eboss.sdss_subsample_redshift(ra, dec, z, eboss_redshift)

Get the array of selection to get the redshift distribution of SDSS

Parameters:

• ra (float, array of float) – Right Ascension

• dec (float, array of float) – Declination

• z (array of float) – redshift

Returns:

Array for selection

Return type:

selection (array of bool)

desisim.io

I/O routines for desisim

class desisim.io.SimSpec(flavor, wave, flux, skyflux, fibermap, truth, obsconditions, header, objtruth=None)

Lightweight wrapper object for simspec data

Object has properties flavor, nspec, wave, flux, skyflux, fibermap, truth, obsconditions, header, cameras.

cameras is dict, keyed by camera name, of SimSpecCameras objects with properies wave, phot, skyphot.

add_camera(camera, wave, phot, skyphot=None)

Add per-camera photons to this SimSpec object, using SimSpecCamera

Parameters:

• camera – camera name, e.g. b0, r1, z9

• wave – 1D[nwave] array of wavelengths

• phot – 2D[nspec, nwave] array of photons per bin (not per Angstrom)

Optional:

skyphot: 2D[nspec, nwave] array of sky photons per bin

class desisim.io.SimSpecCamera(camera, wave, phot, skyphot=None)

Wrapper of per-camera photon data from a simspec file

desisim.io._parse_filename(filename)

Parse filename and return (prefix, camera, expid)

camera=None if the filename isn’t camera specific

e.g. /blat/foo/simspec-00000003.fits -> (‘simspec’, None, 3) e.g. /blat/foo/preproc-r2-00000003.fits -> (‘preproc’, ‘r2’, 3)

desisim.io._qso_format_version(filename)

Return 1 or 2 depending upon QSO basis template file structure

desisim.io._resize(image, shape)

Resize input image to have new shape, preserving its 2D arrangement

Parameters:

• image – 2D ndarray

• shape – tuple (ny,nx) for desired output shape

Returns:

new image with image.shape == shape

desisim.io.empty_metatable(nmodel=1, objtype='ELG', subtype='', simqso=False, input_meta=False)

Initialize template metadata tables depending on the given object type.

Parameters:

• nmodel (int) – Number of rows in output table. Defaults to 1.

• objtype (str) – Object type. Defaults to ELG.

• subtype (str) – Subtype for the given object type (e.g., LYA is objtype=QSO). Defaults to .

• simqso (bool) – Initialize a templates.SIMQSO-style objmeta table rather than a templates.QSO one. Defaults to False.

• input_meta (bool) – Initialize an input_meta table for use with the various desisim.templates classes (see its use in, e.g., desitarget.mock.mockmaker) Defaults to False.

Returns:

• meta (astropy.table.Table) – Metadata table which is agnostic about the object type.

• objmeta (astropy.table.Table) – Objtype-specific supplemental metadata table (e.g., containing the [OII] flux for ELG targets and surface gravity for stars.

desisim.io.empty_snemetatable(nmodel=1)

Initialize a metadata table for SNE.

Parameters:

nmodel (int) – Number of rows in output table. Defaults to 1.

Returns:

snemeta – Metadata table.

Return type:

astropy.table.Table

desisim.io.fibers2cameras(fibers)

Return a list of cameras covered by an input array of fiber IDs

desisim.io.find_basis_template(objtype, indir=None)

Return the most recent template in $DESI_BASIS_TEMPLATE/{objtype}_template*.fits

desisim.io.find_cosmics(camera, exptime=1000, cosmics_dir=None)

Return full path to cosmics template file to use

Parameters:

• camera (str) – e.g. ‘b0’, ‘r1’, ‘z9’

• exptime (int, optional) – exposure time in seconds

• cosmics_dir (str, optional) – directory to look for cosmics templates; defaults to $DESI_COSMICS_TEMPLATES if set or otherwise $DESI_ROOT/spectro/templates/cosmics/v0.3 (note HARDCODED version)

Exposure times <120 sec will use the bias templates; otherwise they will use the dark cosmics templates

desisim.io.findfile(filetype, night, expid, camera=None, outdir=None, mkdir=True)

Return canonical location of where a file should be on disk

Parameters:

• filetype (str) – file type, e.g. ‘preproc’ or ‘simpix’

• night (str) – YEARMMDD string

• expid (int) – exposure id integer

• camera (str) – e.g. ‘b0’, ‘r1’, ‘z9’

• outdir (Optional[str]) – output directory; defaults to $DESI_SPECTRO_SIM/$PIXPROD

• mkdir (Optional[bool]) – create output directory if needed; default True

Returns:

full file path to output file

Return type:

str

Also see desispec.io.findfile() which has equivalent functionality for real data files; this function is only be for simulation files.

desisim.io.get_tile_radec(tileid)

Return (ra, dec) in degrees for the requested tileid.

If tileid is not in DESI, return (0.0, 0.0) TODO: should it raise an exception instead?

desisim.io.load_simspec_summary(indir, verbose=False)

Combine fibermap and simspec files under indir into single truth catalog

Parameters:

indir – path to input directory; search this and all subdirectories

Returns:

astropy.table.Table with true Z catalog

desisim.io.read_basis_templates(objtype, subtype='', outwave=None, nspec=None, infile=None, onlymeta=False, verbose=False)

Return the basis (continuum) templates for a given object type. Optionally returns a randomly selected subset of nspec spectra sampled at wavelengths outwave.

Parameters:

• objtype (str) – object type to read (e.g., ELG, LRG, QSO, STAR, STD, WD, MWS_STAR, BGS).

• subtype (str, optional) – template subtype, currently only for white dwarfs. The choices are DA and DB and the default is to read both types.

• outwave (numpy.array, optional) – array of wavelength at which to sample the spectra.

• nspec (int, optional) – number of templates to return

• infile (str, optional) – full path to input template file to read, over-riding the contents of the $DESI_BASIS_TEMPLATES environment variable.

• onlymeta (Bool, optional) – read just the metadata table and return

• verbose – bool Be verbose. (Default: False)

Returns:

Tuple of (outflux, outwave, meta) where outflux is an Array [ntemplate,npix] of flux values [erg/s/cm2/A]; outwave is an Array [npix] of wavelengths for FLUX [Angstrom]; meta is a Meta-data table for each object. The contents of this table varies depending on what OBJTYPE has been read.

Raises:

• EnvironmentError – If the required $DESI_BASIS_TEMPLATES environment variable is not set.

• IOError – If the basis template file is not found.

desisim.io.read_cosmics(filename, expid=1, shape=None, jitter=True)

Reads a dark image with cosmics from the input filename.

The input might have multiple dark images; use the expid%n image where n is the number of images in the input cosmics file.

Parameters:

• filename – FITS filename with EXTNAME=IMAGE-, IVAR-, MASK-* HDUs

• expid – integer, use expid % n image where n is number of images

• shape – (ny, nx, optional) tuple for output image shape

• jitter (bool, optional) – If True (default), apply random flips and rolls so you don’t get the exact same cosmics every time

Returns:

desisim.image.Image object with attributes pix, ivar, mask

desisim.io.read_simspec(filename, cameras=None, comm=None, readflux=True, readphot=True)

Read a simspec file and return a SimSpec object

Parameters:

filename – input simspec file name

Options:

cameras: camera name or list of names, e.g. b0, r1, z9 comm: MPI communicator readflux: if True (default), include flux readphot: if True (default), include per-camera photons

desisim.io.simdir(night=None, expid=None, mkdir=False)

Return $DESI_SPECTRO_SIM/$PIXPROD/{night} If mkdir is True, create directory if needed

desisim.io.write_simpix(outfile, image, camera, meta)

Write simpix data to outfile.

Parameters:

• outfile – output file name, e.g. from io.findfile(‘simpix’, …)

• image – 2D noiseless simulated image (numpy.ndarray)

• meta – dict-like object that should include FLAVOR and EXPTIME, e.g. from HDU0 FITS header of input simspec file

desisim.io.write_simspec(sim, truth, fibermap, obs, expid, night, objmeta=None, outdir=None, filename=None, header=None, overwrite=False)

Write a simspec file

Parameters:

• sim (Simulator) – specsim Simulator object

• truth (Table) – truth metadata Table

• fibermap (Table) – fibermap Table

• obs (dict-like) – dict-like observation conditions with keys SEEING (arcsec), EXPTIME (sec), AIRMASS, MOONFRAC (0-1), MOONALT (deg), MOONSEP (deg)

• expid (int) – integer exposure ID

• night (str) – YEARMMDD string

• objmeta (dict) – objtype-specific metadata

• outdir (str, optional) – output directory

• filename (str, optional) – if None, auto-derive from envvars, night, expid, and outdir

• header (dict-like) – header to include in HDU0

• overwrite (bool, optional) – overwrite pre-existing files

Notes

Calibration exposures can use truth=None and obs=None.

desisim.io.write_simspec_arc(filename, wave, phot, header, fibermap, overwrite=False)

Alternate writer for arc simspec files which just have photons

class desisim.lya_mock_p1d.MockMaker(N2=15, dv_kms=10.0, seed=666, white_noise=False)

Class to generate 1D mock Lyman alpha skewers.

get_density(var_delta, z, delta)

Transform Gaussian field delta to lognormal density, at each z.

get_gaussian_fields(Ns=1, new_seed=None)

Generate Ns Gaussian fields at redshift z_c.

If new_seed is set, it will reset random generator with it.

get_lya_skewers(Ns=10, new_seed=None)

Return Ns Lyman alpha skewers (wavelength, flux).

If new_seed is set, it will reset random generator with it.

get_redshifts()

Get redshifts for each cell in the array (centered at z_c).

desisim.lya_mock_p1d.get_tau(z, density)

transform lognormal density to optical depth, at each z

desisim.lya_mock_p1d.power_amplitude(z)

Add redshift evolution to the Gaussian power spectrum.

desisim.lya_mock_p1d.power_kms(z_c, k_kms, dv_kms, white_noise)

Return Gaussian P1D at different wavenumbers k_kms (in s/km), fixed z_c.

Other arguments:

dv_kms: if non-zero, will multiply power by top-hat kernel of this width white_noise: if set to True, will use constant power of 100 km/s

desisim.lya_spectra

Function to simulate a QSO spectrum including Lyman-alpha absorption.

desisim.lya_spectra.apply_lya_transmission(qso_wave, qso_flux, trans_wave, trans)

Apply transmission to input flux, interpolating if needed. Note that the transmission might include Lyman-beta and metal absorption, so we should probably change the name of this function.

Parameters:

• qso_wave – 1D[nwave] array of QSO wavelengths

• qso_flux – 2D[nqso, nwave] array of fluxes

• trans_wave – 1D[ntranswave ] array of transmission wavelength samples

• trans – 2D[nqso, ntranswave] transmissions [0-1]

Returns:

output_flux[nqso, nwave]

This routine simply apply the transmission the only thing besides multiplication is a wavelength interpolation of transmission to the QSO wavelength grid

desisim.lya_spectra.apply_metals_transmission(qso_wave, qso_flux, trans_wave, trans, metals, mocktype, strengths=None)

Apply metal transmission to input flux, interpolating if needed. The input transmission should be only due to lya, if not has no meaning. This function should not be used in London mocks with version > 2.0, since these have their own metal transmission already in the files, and even the “TRANSMISSION” HDU includes already Lyman beta.

Parameters:

• qso_wave – 1D[nwave] array of QSO wavelengths

• qso_flux – 2D[nqso, nwave] array of fluxes

• trans_wave – 1D[ntranswave ] array of lya transmission wavelength samples

• trans – 2D[nqso, ntranswave] transmissions [0-1]

• metals – list of metal names to use

Returns:

output_flux[nqso, nwave]

desisim.lya_spectra.get_spectra(lyafile, nqso=None, wave=None, templateid=None, normfilter='sdss2010-g', seed=None, rand=None, qso=None, add_dlas=False, debug=False, nocolorcuts=True)

Generate a QSO spectrum which includes Lyman-alpha absorption.

Parameters:

• lyafile (str) – name of the Lyman-alpha spectrum file to read.

• nqso (int, optional) – number of spectra to generate (starting from the first spectrum; if more flexibility is needed use TEMPLATEID).

• wave (numpy.ndarray, optional) – desired output wavelength vector.

• templateid (int numpy.ndarray, optional) – indices of the spectra (0-indexed) to read from LYAFILE (default is to read everything). If provided together with NQSO, TEMPLATEID wins.

• normfilter (str, optional) – normalization filter

• seed (int, optional) – Seed for random number generator.

• rand (numpy.RandomState, optional) – RandomState object used for the random number generation. If provided together with SEED, this optional input superseeds the numpy.RandomState object instantiated by SEED.

• qso (desisim.templates.QSO, optional) – object with which to generate individual spectra/templates.

• add_dlas (bool) – Inject damped Lya systems into the Lya forest These are done according to the current best estimates for the incidence dN/dz (Prochaska et al. 2008, ApJ, 675, 1002) Set in calc_lz These are not inserted according to overdensity along the sightline

• nocolorcuts (bool, optional) – Do not apply the fiducial rzW1W2 color-cuts cuts (default True).

Returns (flux, wave, meta, dla_meta) where:

• flux (numpy.ndarray): Array [nmodel, npix] of observed-frame spectra (erg/s/cm2/A).

• wave (numpy.ndarray): Observed-frame [npix] wavelength array (Angstrom).

• meta (astropy.Table): Table of meta-data [nmodel] for each output spectrum with columns defined in desisim.io.empty_metatable plus RA, DEC.

• objmeta (astropy.Table): Table of additional object-specific meta-data [nmodel] for each output spectrum with columns defined in desisim.io.empty_metatable.

• dla_meta (astropy.Table): Table of meta-data [ndla] for the DLAs injected into the spectra. Only returned if add_dlas=True

Note: dla_meta is only included if add_dlas=True.

desisim.lya_spectra.read_lya_skewers(lyafile, indices=None, read_dlas=False, add_metals=False, add_lyb=False)

Reads Lyman alpha transmission skewers (from CoLoRe, format v2.x.y)

Parameters:

lyafile – full path to input FITS filename

Options:

indices: indices of input file to sub-select read_dlas: try read DLA HDU from file add_metals: try to read metals HDU and multiply transmission

Returns:

wave[nwave] transmission[nlya, nwave] metadata[nlya] dlas[ndla] (if read_dlas=True, otherwise None)

Input file must have WAVELENGTH, TRANSMISSION, and METADATA HDUs

desisim.obs

Utility functions related to simulating observations for DESI

desisim.obs.get_next_expid(n=None)

Return the next exposure ID to use from {proddir}/etc/next_expid.txt and update the exposure ID in that file.

Use file locking to prevent multiple readers from getting the same ID or accidentally clobbering each other while writing.

Parameters:

n (int, optional) – number of contiguous expids to return as a list. If None, return a scalar. Note that n=1 returns a list of length 1.

BUGS:

• if etc/next_expid.txt doesn’t exist, initial file creation is probably not threadsafe.

• File locking mechanism doesn’t work on NERSC Edison, to turned off for now.

desisim.obs.get_next_tileid(program='DARK')

Return tileid of next tile to observe

Parameters:

program (optional) – dark, gray, or bright

Note

Simultaneous calls will return the same tileid; it does not reserve the tileid.

desisim.obs.get_night(t=None, utc=None)

Return YEARMMDD for tonight. The night roles over at local noon. i.e. 1am and 11am is the previous date; 1pm is the current date.

Parameters:

• t – local time.struct_time tuple of integers (year, month, day, hour, min, sec, weekday, dayofyear, DSTflag) default is time.localtime(), i.e. now

• utc – time.struct_time tuple for UTC instead of localtime

Note

this only has one second accuracy; good enough for sims but not to be used for actual DESI ops.

desisim.obs.new_exposure(program, nspec=5000, night=None, expid=None, tileid=None, nproc=None, seed=None, obsconditions=None, specify_targets={}, testslit=False, exptime=None, arc_lines_filename=None, flat_spectrum_filename=None, outdir=None, overwrite=False)

Create a new exposure and output input simulation files. Does not generate pixel-level simulations or noisy spectra.

Parameters:

• program (str) – ‘arc’, ‘flat’, ‘bright’, ‘dark’, ‘bgs’, ‘mws’, …

• nspec (int, optional) – number of spectra to simulate

• night (str, optional) – YEARMMDD string

• expid (int, optional) – positive integer exposure ID

• tileid (int, optional) – integer tile ID

• nproc (object, optional) – What does this do?

• seed (int, optional) – random seed

• obsconditions (str or dict-like, optional) – see options below

• specify_targets (dict of dicts, optional) – Define target properties like magnitude and redshift for each target class. Each objtype has its own key,value pair see simspec.templates.specify_galparams_dict() or simsepc.templates.specify_starparams_dict()

• testslit (bool, optional) – simulate test slit if True, default False; only for arc/flat

• exptime (float, optional) – exposure time [seconds], overrides obsconditions[‘EXPTIME’]

• arc_lines_filename (str, optional) – use alternate arc lines filename (used if program=”arc”)

• flat_spectrum_filename (str, optional) – use alternate flat spectrum filename (used if program=”flat”)

• outdir (str, optional) – output directory

• overwrite (bool, optional) – optionally clobber existing files

Returns:

sim, fibermap, meta, obsconditions, objmeta

Return type:

science

Writes to outdir or $DESI_SPECTRO_SIM/$PIXPROD/{night}/

• fibermap-{expid}.fits

• simspec-{expid}.fits

input obsconditions can be a string ‘dark’, ‘gray’, ‘bright’, or dict-like observation metadata with keys SEEING (arcsec), EXPTIME (sec), AIRMASS, MOONFRAC (0-1), MOONALT (deg), MOONSEP (deg). Output obsconditions is is expanded dict-like structure.

program is used to pick the sky brightness, and is propagated to desisim.targets.sample_objtype() to get the correct distribution of targets for a given program, e.g. ELGs, LRGs, QSOs for program=’dark’.

if program is ‘arc’ or ‘flat’, then sim is truth table with keys FLUX and WAVE; and meta=None and obsconditions=None.

Also see simexp.simarc(), .simflat(), and .simscience(), the last of which simulates a science exposure given surveysim obsconditions input, fiber assignments, and pre-generated mock target spectra.

desisim.obs.specter_objtype(desitype)

Convert a list of DESI object types into ones that specter knows about

desisim.obs.update_obslog(obstype='science', program='DARK', expid=None, dateobs=None, tileid=-1, ra=None, dec=None)

Update obslog with a new exposure

obstype : ‘arc’, ‘flat’, ‘bias’, ‘test’, ‘science’, … program : ‘DARK’, ‘GRAY’, ‘BRIGHT’, ‘CALIB’ expid : integer exposure ID, default from get_next_expid() dateobs : time.struct_time tuple; default time.localtime() tileid : integer TileID, default -1, i.e. not a DESI tile ra, dec : float (ra, dec) coordinates, default tile ra,dec or (0,0)

returns tuple (expid, dateobs)

TODO: normalize obstype vs. program; see desisim issue #97

desisim.pixelsplines

Pixel-integrated spline utilities.

Written by A. Bolton, U. of Utah, 2010-2013.

exception desisim.pixelsplines.PixSplineError(value)

class desisim.pixelsplines.PixelSpline(pixbound, flux)

Pixel Spline object class.

Initialize as follows: PS = PixelSpline(pixbound, flux) where pixbound = array of pixel boundaries in baseline units and flux = array of specific flux values in baseline units.

Assumptions: ‘pixbound’ should have one more element than ‘flux’, and units of ‘flux’ are -per-unit-baseline, for the baseline units in which pixbound is expressed, averaged over the extent of each pixel.

point_evaluate(xnew, missing=0.0)

Evaluate underlying pixel spline at array of points BUG: input currently needs to be at least 1D array.

resample(pb_new)

Method to resample a pixelspline analytically onto a new set of pixel boundaries.

class desisim.pixelsplines.WeightedRebinCoadder(fluxes, invvars, pixbounds)

Objet class for weighted rebinning and coaddition of spectra

Initialize as follows: WRC = WeighedRebinCoadder(fluxes, invvars, pixbounds) where fluxes = list of arrays of specific flux values invvars = list of arrays of associated inverse variances pixbounds = list of arrays of pixel boundaries in baseline units

desisim.pixelsplines.cen2bound(pixelcen)

Convenience function to do the obvious thing to transform pixel centers to pixel boundaries.

desisim.pixelsplines.compute_duck_slopes(pixbound, flux)

Compute the slope of the illuminating quadratic spline at the locations of the ‘ducks’, i.e., the pixel boundaries, given the integrated flux per unit baseline within the pixels.

ARGUMENTS: pixbound: (npix + 1) ndarray of pixel boundaries, in units of wavelength or log-wavelength or frequency or whatever you like. flux: (npix) ndarray of spectral flux (energy or counts) per abscissa unit, averaged over the extent of the pixel

RETURNS: an (npix+1) ndarray of the slope of the underlying/illuminating flux per unit abscissa spectrum at the position of the pixel boundaries, a.k.a. ‘ducks’. The end conditions are taken to be zero slope, so the exterior points of the output are zeros.

desisim.pixelsplines.gauss_blur_matrix(pixbound, sig_conv)

Function to generate a Gaussian blurring matrix for a pixelized spectrum, from specified pixel boundaries and ‘sigma’ vector. The matrix will be flux-conserving if the spectrum to which it is applied has units of ‘counts per unit x’, and pixbound and sig_conv both have units of x.

pixbound should have one more element than sig_conv.

Output is a scipy sparse matrix that can implement the blurring as: blurflux = gauss_blur_matrix * flux where ‘flux’ has the same dimensions as ‘sig_conv’.

desisim.pixsim

Tools for DESI pixel level simulations using specter

desisim.pixsim._project(args)

Helper function to project photons onto a subimage

Parameters:

• [psf (tuple/array of) –

• wave –

• phot –

• specmin] –

Returns (xyrange, subimage) such that

xmin, xmax, ymin, ymax = xyrange image[ymin:ymax, xmin:xmax] += subimage

desisim.pixsim.get_nodes_per_exp(nnodes, nexposures, ncameras, user_nodes_per_comm_exp=None)

Calculate how many nodes to use per exposure

Parameters:

• nnodes – number of nodes in MPI COMM_WORLD (not number of ranks)

• nexposures – number of exposures to process

• ncameras – number of cameras per exposure

• user_nodes_per_comm_exp (int, optional) – user override of number of nodes to use; used to check requirements

Returns number of nodes to include in sub-communicators used to process individual exposures

Notes

• Uses the largest number of nodes per exposure that will still result in efficient node usage

• requires that (nexposures*ncameras) / nnodes = int

• the derived nodes_per_comm_exp * nexposures / nodes = int

• See desisim.test.test_pixsim.test_get_nodes_per_exp() for examples

• if user_nodes_per_comm_exp is given, requires that GreatestCommonDivisor(nnodes, ncameras) / user_nodes_per_comm_exp = int

desisim.pixsim.mpi_count_nodes(comm)

Return the number of nodes in this communicator

desisim.pixsim.mpi_split_by_node(comm, nodes_per_communicator)

Split an MPI communicator into sub-communicators with integer numbers of nodes per communicator

Parameters:

• comm – MPI communicator

• nodes_per_communicator – number of nodes per sub-communicator

Returns:

MPI sub-communicator, node_index, total_num_nodes

Notes

• total number of nodes in original communicator must be an integer multiple of nodes_per_communicator

• if comm is split into N sub-communicators, node_index is the index of which of the N is returned for this rank

• total_num_nodes = number of nodes in original communicator

desisim.pixsim.parallel_project(psf, wave, phot, specmin=0, ncpu=None, comm=None)

Using psf, project phot[nspec, nw] vs. wave[nw] onto image

Return 2D image

desisim.pixsim.photpix2raw(phot, gain=1.0, readnoise=3.0, offset=None, nprescan=7, noverscan=50, readorder='lr', noisydata=True)

Add prescan, overscan, noise, and integerization to an image

Parameters:

• phot – 2D float array of mean input photons per pixel

• gain (float, optional) – electrons/ADU

• readnoise (float, optional) – CCD readnoise in electrons

• offset (float, optional) – bias offset to add

• nprescan (int, optional) – number of prescan pixels to add

• noverscan (int, optional) – number of overscan pixels to add

• readorder (str, optional) – ‘lr’ or ‘rl’ to indicate readout order ‘lr’ : add prescan on left and overscan on right of image ‘rl’ : add prescan on right and overscan on left of image

• noisydata (boolean, optional) – if True, don’t add noise, e.g. because input signal already had noise from a cosmics image

Returns 2D integer ndarray:

image = int((poisson(phot) + offset + gauss(readnoise))/gain)

Integerization happens twice: the mean photons are poisson sampled into integers, but then offets, readnoise, and gain are applied before resampling into ADU integers

This is intended to be used per-amplifier, not for an entire CCD image.

desisim.pixsim.simulate(camera, simspec, psf, nspec=None, ncpu=None, cosmics=None, wavemin=None, wavemax=None, preproc=True, comm=None)

Run pixel-level simulation of input spectra

Parameters:

• camera (string) – b0, r1, .. z9

• simspec – desispec.io.SimSpec object from desispec.io.read_simspec()

• psf – subclass of specter.psf.psf.PSF, e.g. from desimodel.io.load_psf()

Options:

nspec (int): number of spectra to simulate ncpu (int): number of CPU cores to use in parallel cosmics (desispec.image.Image): e.g. from desisim.io.read_cosmics() wavemin (float): minimum wavelength range to simulate wavemax (float): maximum wavelength range to simulate preproc (boolean, optional) : also preprocess raw data (default True)

Returns:

(image, rawpix, truepix) tuple, where image is the preproc Image object

(only header is meaningful if preproc=False), rawpix is a 2D ndarray of unprocessed raw pixel data, and truepix is a 2D ndarray of truth for image.pix

desisim.pixsim.simulate_exposure(simspecfile, rawfile, cameras=None, ccdshape=None, simpixfile=None, addcosmics=None, comm=None, keywords=None, outfibermap=None, **kwargs)

Simulate frames from an exposure, including I/O

Parameters:

• simspecfile – input simspec format file with spectra

• rawfile – output raw data file to write

Options:

cameras: str or list of str, e.g. b0, r1, .. z9 ccdshape: (npix_y, npix_x) primarily used to limit memory while testing simpixfile: output file for noiseless truth pixels addcosmics: if True (must be specified via command input), add cosmics from real data comm: MPI communicator object keywords: dictionnary with keywords to add to the headers outfibermap: output fibermap

Additional keyword args are passed to pixsim.simulate()

For a lower-level pixel simulation interface that doesn’t perform I/O, see pixsim.simulate()

Note: call desi_preproc or desispec.preproc.preproc to pre-process the output desi*.fits file for overscan subtraction, noise estimation, etc.

desisim.qso_template

Stuff dealing with QSO templates.

desisim.qso_template.desi_qso_templ

Module for Fitting PCA to the BOSS QSOs

01-Dec-2014 by JXP

desisim.qso_template.desi_qso_templ.chk_desi_qso_templates(infil=None, outfil=None, N_perz=100)

desisim.qso_template.desi_qso_templ.desi_qso_templates(z_wind=0.2, zmnx=(0.4, 4.0), outfil=None, N_perz=500, boss_pca_fil=None, wvmnx=(3500.0, 10000.0), rebin_wave=None, rstate=None, sdss_pca_fil=None, no_write=False, redshift=None, seed=None, old_read=False, ipad=40, cosmo=None)

Generate QSO templates for DESI

Rebins to input wavelength array (or log10 in wvmnx)

Parameters:

• z_wind (float, optional) – Window for sampling PCAs

• zmnx (tuple, optional) – Min/max for generation

• N_perz (int, optional) – Number of draws per redshift window

• old_read (bool, optional) – Read the files the old way

• seed (int, optional) – Seed for the random number state

• rebin_wave (ndarray, optional) – Input wavelengths for rebinning

• wvmnx (tuple, optional) – Wavelength limits for rebinning (not used with rebin_wave)

• redshift (ndarray, optional) – Redshifts desired for the templates

• ipad (int, optional) – Padding for enabling enough models

• cosmo (astropy.cosmology.core, optional) – Cosmology inistantiation from astropy.cosmology.code

Returns:

• wave (ndarray) – Wavelengths that the spectra were rebinned to

• flux (ndarray (2D; flux vs. model))

• z (ndarray) – Redshifts

desisim.qso_template.desi_qso_templ.fig_desi_templ_z_i(outfil=None, boss_fil=None, flg=0)

flg = 0: Redshift flg = 1: imag

desisim.qso_template.desi_qso_templ.mean_templ_zi(zimag, debug=False, i_wind=0.1, z_wind=0.05, boss_pca_fil=None)

Generate ‘mean’ templates at given z,i

Parameters:

• zimag (list of tuples) – Redshift, imag pairs for the templates

• i_wind (float (0.1 mag)) – Window for smoothing imag

• z_wind (float (0.05 mag)) – Window for smoothing redshift

desisim.qso_template.desi_qso_templ.repackage_coeff(boss_pca_fil=None, sdss_pca_fil=None, outfil='qso_templates_v2.0.fits')

Repackage the coefficients and redshifts into a single FITS file

Returns:

desisim.qso_template.desi_qso_templ.tst_random_set()

Generate a small set of random templates for testing :return:

desisim.qso_template.fit_boss_qsos

Module for Fitting PCA to the BOSS QSOs

01-Dec-2014 by JXP

desisim.qso_template.fit_boss_qsos.do_boss_lya_parallel(istart, iend, cut_Lya, output, debug=False)

Generate PCA coeff for the BOSS Lya DR10 dataset, v2.1

Parameters:

cut_Lya (boolean (True)) – Avoid using the Lya forest in the analysis

desisim.qso_template.fit_boss_qsos.do_sdss_lya_parallel(istart, iend, cut_Lya, output, debug=False)

Generate PCA coeff for the SDSS DR7 dataset, 0.5<z<2

Parameters:

cut_Lya (boolean (True)) – Avoid using the Lya forest in the analysis

desisim.qso_template.fit_boss_qsos.failed_parallel()

Collision with np.dot Might fix with OPENBLAS_NUM_THREADS=1

desisim.qso_template.fit_boss_qsos.fit_eigen(flux, ivar, eigen_flux)

Fit the spectrum with the eigenvectors. Pass back the coefficients

desisim.qso_template.fit_boss_qsos.read_qso_eigen(eigen_fil=None)

Input the QSO Eigenspectra

desisim.qso_template.fit_boss_qsos.splice_fits(flg=0)

Splices together the various PCA fits for SDSS or BOSS

flg: int (0)

0=BOSS, 1=SDSS

desisim.qso_template.qso_pca

Module for generate QSO PCA templates

24-Nov-2014 by JXP

desisim.qso_template.qso_pca.do_boss_lya_parallel(istart, iend, output, debug=False, cut_Lya=True)

Generate PCA coeff for the BOSS Lya DR10 dataset, v2.1

Parameters:

cut_Lya (boolean (True)) – Avoid using the Lya forest in the analysis

desisim.qso_template.qso_pca.fit_eigen(flux, ivar, eigen_flux)

Fit the spectrum with the eigenvectors. Pass back the coefficients

desisim.qso_template.qso_pca.read_qso_eigen(eigen_fil=None)

Input the QSO Eigenspectra

desisim.qso_template.tests

Module for generate QSO PCA templates

24-Nov-2014 by JXP

I don’t think the documentation of this module is correct.

desisim.quickcat

Code for quickly generating an output zcatalog given fiber assignment tiles, a truth catalog, and optionally a previous zcatalog.

desisim.quickcat.get_median_obsconditions(tileids)

Gets the observational conditions for a set of tiles.

Parameters:

tileids – list of tileids that were observed

Returns:

Table with the observational conditions for every tile.

It inclues at least the following columns:

'TILEID': array of tile IDs
'AIRMASS': array of airmass values on a tile
'EBMV': array of E(B-V) values on a tile
'LINTRANS': array of atmospheric transparency during spectro obs; floats [0-1]
'MOONFRAC': array of moonfraction values on a tile.
'SEEING': array of FWHM seeing during spectroscopic observation on a tile.

desisim.quickcat.get_observed_redshifts(targets, truth, targets_in_tile, obsconditions, parameter_filename=None, ignore_obscondition=False)

Returns observed z, zerr, zwarn arrays given true object types and redshifts

Parameters:

• targets – target catalog table; currently used only for target mask bits

• truth – truth table with OIIFLUX, TRUEZ

• targets_in_tile – dictionary. Keys correspond to tileids, its values are the arrays of targetids observed in that tile.

• obsconditions – table observing conditions with columns ‘TILEID’: array of tile IDs ‘AIRMASS’: array of airmass values on a tile ‘EBMV’: array of E(B-V) values on a tile ‘LINTRANS’: array of atmospheric transparency during spectro obs; floats [0-1] ‘MOONFRAC’: array of moonfraction values on a tile. ‘SEEING’: array of FWHM seeing during spectroscopic observation on a tile.

• parameter_filename – yaml file with quickcat parameters

• ignore_obscondition – if True, no variation of efficiency with obs. conditions (adjustment of exposure time should correct for mean change of S/N)

Returns:

tuple of (zout, zerr, zwarn)

desisim.quickcat.get_redshift_efficiency(simtype, targets, truth, targets_in_tile, obsconditions, params, ignore_obscondition=False)

Simple model to get the redshift effiency from the observational conditions or observed magnitudes+redshuft

Parameters:

• simtype – ELG, LRG, QSO, MWS, BGS

• targets – target catalog table; currently used only for TARGETID

• truth – truth table with OIIFLUX, TRUEZ

• targets_in_tile – dictionary. Keys correspond to tileids, its values are the arrays of targetids observed in that tile.

• obsconditions – table observing conditions with columns ‘TILEID’: array of tile IDs ‘AIRMASS’: array of airmass values on a tile ‘EBMV’: array of E(B-V) values on a tile ‘LINTRANS’: array of atmospheric transparency during spectro obs; floats [0-1] ‘MOONFRAC’: array of moonfraction values on a tile. ‘SEEING’: array of FWHM seeing during spectroscopic observation on a tile.

• parameter_filename – yaml file with quickcat parameters

• ignore_obscondition – if True, no variation of efficiency with obs. conditions (adjustment of exposure time should correct for mean change of S/N)

Returns:

tuple of arrays (observed, p) both with same length as targets

observed: boolean array of whether the target was observed in these tiles

p: probability to get this redshift right

desisim.quickcat.get_zeff_obs(simtype, obsconditions)

desisim.quickcat.quickcat(tilefiles, targets, truth, fassignhdu='FIBERASSIGN', zcat=None, obsconditions=None, perfect=False)

Generates quick output zcatalog

Parameters:

• tilefiles – list of fiberassign tile files that were observed

• targets – astropy Table of targets

• truth – astropy Table of input truth with columns TARGETID, TRUEZ, and TRUETYPE

• zcat (optional) – input zcatalog Table from previous observations

• obsconditions (optional) – Table or ndarray with observing conditions from surveysim

• perfect (optional) – if True, treat spectro pipeline as perfect with input=output, otherwise add noise and zwarn!=0 flags

Returns:

zcatalog astropy Table based upon input truth, plus ZERR, ZWARN, NUMOBS, and TYPE columns

desisim.quickcat.reverse_dictionary(a)

Inverts a dictionary mapping.

Parameters:

a – input dictionary.

Returns:

output reversed dictionary.

Return type:

b

desisim.quicksurvey

Code for quickly simulating the survey results given a mock catalog and a list of tile epochs to observe.

Directly depends on the following DESI products:

• desitarget.mtl

• desisim.quickcat

• fiberassign

class desisim.quicksurvey.SimSetup(output_path, targets_path, fiberassign, exposures, fiberassign_dates)

Setup to simulate the DESI survey

output_path

Path to write the outputs.x

Type:

str

targets_path

Path where the files targets.fits can be found

Type:

str

epochs_path

Path where the epoch files can be found.

Type:

str

fiberassign

Name of the fiberassign script

Type:

str

template_fiberassign

Filename of the template input for fiberassign

Type:

str

n_epochs

number of epochs to be simulated.

Type:

int

backup_epoch_data(epoch_id=0)

Deletes files in the temporary output directory

Parameters:

epoch_id (int) – Epoch’s ID to backup/copy from the output directory.

cleanup_directories()

Deletes files in the temporary output directory

create_directories()

Creates output directories to store simulation results.

create_surveyfile(epoch)

Creates text file of tiles survey_list.txt to be used by fiberassign

Parameters:

epoch (int) – epoch of tiles to write

Notes

The file is written to the temporary directory in self.tmp_output_path

epoch_data_exists(epoch_id=0)

Check epoch directory for zcat.fits and mtl.fits files.

simulate()

Simulate the DESI setup described by a SimSetup object.

simulate_epoch(epoch, truth, targets, perfect=False, zcat=None)

Core routine simulating a DESI epoch,

Parameters:

• epoch (int) – epoch to simulate

• perfect (boolean) – Default: False. Selects whether how redshifts are taken from the truth file. True: redshifts are taken without any error from the truth file. False: redshifts include uncertainties.

• truth (Table) – Truth data

• targets (Table) – Targets data

• zcat (Table) – Redshift Catalog Data

Notes

This routine simulates three steps: * Merged target list creation * Fiber allocation * Redshift catalogue construction

update_observed_tiles(epoch)

Creates the list of tilefiles to be gathered to build the redshift catalog.

desisim.scripts

Main functions and command-line parsing.

desisim.scripts.brightsims

Generate a canonical set of bright-time simulations.

desisim.scripts.brightsims

Generate a canonical set of bright-time simulations.

desisim.scripts.fastframe.main(args=None)

Converts simspec -> frame files; see fastframe –help for usage options

class desisim.scripts.lya_simqso_model.LogPhiStarPLEPivot(*args: Any, **kwargs: Any)

The PLE-Pivot model is PLE (fixed Phi*) below zpivot and LEDE (polynomial in log(Phi*) above zpivot.

class desisim.scripts.lya_simqso_model.MStarPLEPivot(*args: Any, **kwargs: Any)

The PLE-Pivot model for Mstar encapsulates two evolutionary models, one for z<zpivot and one for z>zp.

desisim.scripts.newarc.main(args=None)

TODO: document

Note: this bypasses specsim since we don’t have an arclamp model in surface brightness units; we only have electrons on the CCD

desisim.scripts.newflat.main(args=None)

Generates a new flat exposure; see newflat –help for usage options

desisim.scripts.pixsim_nights

This is a module.

desisim.scripts.pixsim

This is a module.

desisim.scripts.pixsim.expand_args(args)

expand camera string into list of cameras

Generate S/N plots as a function of object type for the current production

Read fibermaps and zbest files to generate QA related to redshifts

and compare against the ‘true’ values

desisim.scripts.quickgalaxies

class desisim.scripts.quickgalaxies.SetDefaultFromFile(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)

Abstract interface class to set command-line arguments from a file.

class desisim.scripts.quickgalaxies.SetDefaultFromYAMLFile(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)

Concrete class that sets command-line arguments from a YAML file.

_get_config_from_file(filename)

Implementation of configuration reader.

Parameters:

filename (string) – Name of configuration file to read.

Returns:

config – Configuration dictionary.

Return type:

dictionary

desisim.scripts.quickgalaxies._default_wave(wavemin=None, wavemax=None, dw=0.2)

Generate a default wavelength vector for the output spectra.

desisim.scripts.quickgalaxies._get_healpixels_in_footprint(nside=64)

Obtain a list of HEALPix pixels in the DESI footprint.

Parameters:

nside (int) – HEALPix nside parameter (in form nside=2**k, k=[1,2,3,…]).

Returns:

healpixels – List of HEALPix pixels within the DESI footprint.

Return type:

ndarray

desisim.scripts.quickgalaxies.bgs_write_simdata(sim, overwrite=False)

Create a metadata table with simulation inputs.

Parameters:

• sim (dict) – Simulation parameters from command line.

• overwrite (bool) – Overwrite simulation data file.

Returns:

simdata – Data table written to disk.

Return type:

Table

desisim.scripts.quickgalaxies.parse(options=None)

Parse command-line options.

desisim.scripts.quickgalaxies.simdata2obsconditions(sim)

Pack simdata observation conditions into a dictionary.

Parameters:

simdata (Table) – Simulation data table.

Returns:

obs – Observation conditions dictionary.

Return type:

dict

desisim.scripts.quickgalaxies.write_templates(filename, flux, wave, target, truth, objtruth)

Write galaxy templates to a FITS file.

Parameters:

• filename (str) – Path to output file.

• flux (ndarray) – Array of flux data for template spectra.

• wave (ndarray) – Array of wavelengths.

• target (Table) – Target information.

• truth (Table) – Template simulation truth.

• objtruth (Table) – Object-specific truth data.

desisim.scripts.quickgen

Quickgen quickly simulates pipeline outputs if given input files.

• must provide simspec and fibermap files via newexp script

• Number of spectra to be simulated can be given as an argument for quickgen, but the number of spectra in the simspec file is taken by default

• For this option, airmass and exposure time are keywords given to newexp

• The keywords provided in the examples are all required, additional keywords are provided below

• Collect a set of templates to simulate as a new exposure:

  newexp --nspec 500 --night 20150915 --expid 0 --flavor dark
  

• newexp keyword arguments:

  --flavor : arc/flat/dark/gray/bright/bgs/mws/elg/lrg/qso, type=str, default='dark'
  --tileid : tile id, type=int
  --expid : exposure id, type=int
  --exptime : exposure time in seconds, default for arc = 5s, flat = 10s, dark/elg/lrg/qso=1000s, bright/bgs/mws=300s, type=int
  --night : YEARMMDD, type=str
  --nspec : Number of spectra to simulate, type=int, default=5000
  --airmass : type=float, default=1.0
  --seed : random number seed, type=int
  --testslit : test slit simulation with fewer fibers, action="store_true"
  --arc-lines : alternate arc lines filename, type=str, default=None
  --flat-spectrum : alternate flat spectrum filename, type=str
  

• Actually do the simulation:

  simdir=$DESI_SPECTRO_SIM/$PIXPROD/20150915
  quickgen --simspec $simdir/simspec-00000000.fits --fibermap $simdir/fibermap-00000000.fits
  

• quickgen output (can also provide frame file only as keyword):

  1. frame-{camera}-{expid}.fits : raw extracted photons with no calibration at all
  2. sky-{camera}-{expid}.fits : the sky model in photons
  3. fluxcalib-{camera}-{expid}.fits] : the flux calibration vectors
  4. cframe-{camera}-{expid}.fits : flux calibrated spectra
  
  These files are written to $simdir/{expid}
  

• nspec, config, seed, moon-phase, moon-angle, moon-zenith

• simspec, fibermap, nstart, spectrograph, frameonly zrange-qso, zrange-elg, zrange-lrg, zrange-bgs, sne-rfluxratiorange, add-SNeIa

desisim.scripts.quickgen._add_truth(hdus, header, meta, trueflux, sflux, wave, channel)

Utility function for adding truth to an output FITS file.

desisim.scripts.quickquasars._func(arg)

Used for multiprocessing.Pool

desisim.scripts.quickquasars.get_healpix_info(ifilename)

Read the header of the tranmission file to find the healpix pixel, nside and if we are lucky the scheme. If it fails, try to guess it from the filename (for backward compatibility).

Parameters:

ifilename – full path to input transmission file

Returns:

HEALPix pixel corresponding to the file nside: HEALPix nside value hpxnest: Whether HEALPix scheme in the file was nested

Return type:

healpix

desisim.scripts.quickquasars.is_south(dec)

Identify which QSOs are in the south vs the north, since these are on different photometric systems. See https://github.com/desihub/desitarget/issues/353 for details.

desisim.scripts.quickspectra.sim_spectra(wave, flux, program, spectra_filename, obsconditions=None, sourcetype=None, targetid=None, redshift=None, expid=0, seed=0, skyerr=0.0, ra=None, dec=None, meta=None, fibermap_columns=None, fullsim=False, use_poisson=True, specsim_config_file='desi', dwave_out=None, save_resolution=True, source_contribution_smoothing=0)

Simulate spectra from an input set of wavelength and flux and writes a FITS file in the Spectra format that can be used as input to the redshift fitter.

Parameters:

• wave – 1D np.array of wavelength in Angstrom (in vacuum) in observer frame (i.e. redshifted)

• flux – 1D or 2D np.array. 1D array must have same size as wave, 2D array must have shape[1]=wave.size flux has to be in units of 10^-17 ergs/s/cm2/A

• spectra_filename – path to output FITS file in the Spectra format

• program – dark, lrg, qso, gray, grey, elg, bright, mws, bgs ignored if obsconditions is not None

Optional:

obsconditions : dictionnary of observation conditions with SEEING EXPTIME AIRMASS MOONFRAC MOONALT MOONSEP sourcetype : list of string, allowed values are (sky,elg,lrg,qso,bgs,star), type of sources, used for fiber aperture loss , default is star targetid : list of targetids for each target. default of None has them generated as str(range(nspec)) redshift : list/array with each index being the redshifts for that target expid : this expid number will be saved in the Spectra fibermap seed : random seed skyerr : fractional sky subtraction error ra : numpy array with targets RA (deg) dec : numpy array with targets Dec (deg) meta : dictionnary, saved in primary fits header of the spectra file fibermap_columns : add these columns to the fibermap fullsim : if True, write full simulation data in extra file per camera use_poisson : if False, do not use numpy.random.poisson to simulate the Poisson noise. This is useful to get reproducible random realizations. save_resolution : if True it will save the Resolution matrix for each spectra. If False returns a resolution matrix (useful for mocks to save disk space). source_contribution_smoothing : If > 0, contribution of source electrons to the noise and variance is Gaussian smoothed by this value. This reduces signal-noise coupling especially for Lya forest.

desisim.scripts.quicktransients

desisim.scripts.quicktransients._get_healpixels_in_footprint(nside=64)

Obtain a list of HEALPix pixels in the DESI footprint.

Parameters:

nside (int) – HEALPix nside parameter (in form nside=2**k, k=[1,2,3,…]).

Returns:

healpixels – List of HEALPix pixels within the DESI footprint.

Return type:

ndarray

desisim.scripts.quicktransients._set_wave(wavemin=None, wavemax=None, dw=0.8)

Set default wavelength grid for simulations.

Parameters:

• wavemin (float or None) – Minimum wavelength, in Angstroms.

• wavemax (float or None) – Maximum wavelength, in Angstroms.

• dw (float) – Bin size.

Returns:

wave – Grid of wavelength values.

Return type:

ndarray

desisim.scripts.quicktransients.parse(options=None)

Parse command line options.

desisim.scripts.quicktransients.write_templates(filename, flux, wave, target, truth, objtruth)

Write galaxy templates to a FITS file. :param filename: Path to output file. :type filename: str :param flux: Array of flux data for template spectra. :type flux: ndarray :param wave: Array of wavelengths. :type wave: ndarray :param target: Target information. :type target: Table :param truth: Template simulation truth. :type truth: Table :param objtruth: Object-specific truth data. :type objtruth: Table

desisim.simexp._calib_screen_uniformity(theta=None, radius=None)

Returns calibration screen relative non-uniformity as a function of theta (degrees) or focal plane radius (mm)

desisim.simexp._specsim_config_for_wave(wave, dwave_out=None, specsim_config_file='desi')

Generate specsim config object for a given wavelength grid

Parameters:

wave – array of linearly spaced wavelengths in Angstroms

Options:

specsim_config_file: (str) path to DESI instrument config file.

default is desi config in specsim package.

Returns:

specsim Configuration object with wavelength parameters set to match this input wavelength grid

desisim.simexp.fibermeta2fibermap(fiberassign, meta)

Convert a fiberassign + targeting metadata table into a fibermap Table

A future refactor will standardize the column names of fiber assignment, target catalogs, and fibermaps, but in the meantime this is needed.

desisim.simexp.get_mock_spectra(fiberassign, mockdir=None, nside=64, obscon=None)

Parameters:

fiberassign – table loaded from fiberassign tile file

Options:

mockdir (str): base directory under which files are found nside (int): healpix nside for file directory grouping obscon (str): (observing conditions) None/dark/bright extra dir level

Returns (flux, wave, meta) tuple

desisim.simexp.get_source_types(fibermap)

Return a list of specsim source types based upon fibermap[‘DESI_TARGET’]

Parameters:

fibermap – fibermap Table including DESI_TARGET column

Returns array of source_types ‘sky’, ‘elg’, ‘lrg’, ‘qso’, ‘star’

Unassigned fibers fibermap[‘TARGETID’] == -1 will be treated as ‘sky’

If fibermap.meta[‘FLAVOR’] = ‘arc’ or ‘flat’, returned source types will match that flavor, though specsim doesn’t use those as source_types

TODO: specsim/desimodel doesn’t have a fiber input loss model for BGS yet, so BGS targets get source_type = ‘lrg’ (!)

desisim.simexp.read_fiberassign(tilefile_or_id, indir=None)

Returns fiberassignment table for tileid

Parameters:

tilefile_or_id (int or str) – tileid (int) or full path to tile file (str)

Returns:

fiberassignment Table from HDU 1

desisim.simexp.read_mock_spectra(truthfile, targetids, mockdir=None)

Reads mock spectra from a truth file

Parameters:

• truthfile (str) – full path to a mocks truth-*.fits file

• targetids (array-like) – targetids to load from that file

• mockdir –

  ???

Returns (flux, wave, truth) tuples:

flux[nspec, nwave]: flux in 1e-17 erg/s/cm2/Angstrom wave[nwave]: wavelengths in Angstroms truth[nspec]: metadata truth table objtruth: dictionary keyed by objtype type with type-specific truth

desisim.simexp.simarc(arcdata, nspec=5000, nonuniform=False, testslit=False)

Simulates an arc lamp exposure

Parameters:

• arcdata (Table) – Table with columns VACUUM_WAVE and ELECTRONS

• nspec (int, optional) –

• nonuniform (bool, optional) – include calibration screen non-uniformity

• testslit (bool, optional) – this argument is undocumented.

Returns: (wave, phot, fibermap)

wave: 1D[nwave] wavelengths in Angstroms phot: 2D[nspec,nwave] photons observed by CCD (i.e. electrons) fibermap: fibermap Table

Note: this bypasses specsim since we don’t have an arclamp model in surface brightness units; we only have electrons on the CCD. But it does include the effect of varying fiber sizes.

desisim.simexp.simflat(flatfile, nspec=5000, nonuniform=False, exptime=10, testslit=False, psfconvolve=True, specsim_config_file='desi')

Simulates a flat lamp calibration exposure

Parameters:

• flatfile (str) – filename with flat lamp spectrum data

• nspec (int, optional) – number of spectra to simulate

• nonuniform (bool, optional) – include calibration screen non-uniformity

• exptime (float, optional) – exposure time in seconds

• psfconvolve (bool, optional) – passed to simspec.simulator.Simulator camera_output. if True, convolve with PSF and include per-camera outputs

• specsim_config_file (str, optional) – path to DESI instrument config file. default is desi config in specsim package.

Returns: (sim, fibermap)

sim: specsim Simulator object fibermap: fibermap Table

desisim.simexp.simscience(targets, fiberassign, obsconditions='DARK', expid=None, nspec=None, psfconvolve=True)

Simulates a new DESI exposure from surveysim+fiberassign+mock spectra

Parameters:

• targets (tuple) – tuple of (flux[nspec,nwave], wave[nwave], meta[nspec])

• fiberassign (Table) – fiber assignments table

• obsconditions (object, optional) –

  observation metadata as

  str: DARK (default) or GRAY or BRIGHT

  dict or row of Table with keys:

  SEEING (arcsec), EXPTIME (sec), AIRMASS,
  MOONFRAC (0-1), MOONALT (deg), MOONSEP (deg)
  

  Table including EXPID for subselection of which row to use filename with obsconditions Table; expid must also be set

• expid (int, optional) – exposure ID

• nspec (int, optional) – number of spectra to simulate

• psfconvolve (bool, optional) – passed to simspec.simulator.Simulator camera_output. if True, convolve with PSF and include per-camera outputs

Returns: (sim, fibermap, meta)

sim: specsim.simulate.Simulator object fibermap: Table meta: target metadata truth table

See obs.new_exposure() for function to generate new random exposure, independent from surveysim, fiberassignment, and pre-generated mocks.

desisim.simexp.simulate_spectra(wave, flux, fibermap=None, obsconditions=None, redshift=None, dwave_out=None, seed=None, psfconvolve=True, specsim_config_file='desi')

Simulates an exposure without reading/writing data files

Parameters:

• wave (array) – 1D wavelengths in Angstroms

• flux (array) – 2D[nspec,nwave] flux in 1e-17 erg/s/cm2/Angstrom or astropy Quantity with flux units

• fibermap (Table, optional) – table from fiberassign or fibermap; uses X/YFOCAL_DESIGN, TARGETID, DESI_TARGET

• obsconditions (dict-like, optional) – observation metadata including SEEING (arcsec), EXPTIME (sec), AIRMASS, MOONFRAC (0-1), MOONALT (deg), MOONSEP (deg)

• redshift (array-like, optional) – list/array with each index being the redshifts for that target

• seed (int, optional) – random seed

• psfconvolve (bool, optional) – passed to simspec.simulator.Simulator camera_output. if True, convolve with PSF and include per-camera outputs

• specsim_config_file (str, optional) – path to DESI instrument config file. default is desi config in specsim package.

Returns:

A specsim.simulator.Simulator object

TODO: galsim support

desisim.simexp.targets2truthfiles(targets, basedir, nside=64, obscon=None)

Return list of mock truth files that contain these targets

Parameters:

• targets – table with TARGETID column, e.g. from fiber assignment

• basedir – base directory under which files are found

Options:

nside (int): healpix nside for file directory grouping obscon (str): (observing conditions) None/dark/bright extra dir level

Returns (truthfiles, targetids):

truthfiles: list of truth filenames targetids: list of lists of targetids in each truthfile

i.e. targetids[i] is the list of targetids from targets[‘TARGETID’] that

are in truthfiles[i]

desisim.spec_qa

Tools for DESI QA with simulations It does not cover cosmology simulations.

desisim.spec_qa.high_level

Module to run high_level QA on a given DESI run

Written by JXP on 3 Sep 2015

desisim.spec_qa.high_level.get_meta()

Get META data on production

desisim.spec_qa.high_level.main()

Runs the process

desisim.spec_qa.redshifts

Module to run high_level QA on a given DESI run

Written by JXP on 3 Sep 2015

desisim.spec_qa.redshifts.calc_dz(simz_tab)

Calcualte deltaz/(1+z) for a given simz_tab

desisim.spec_qa.redshifts.calc_dzsig(simz_tab)

Calcualte deltaz/sig(z) for a given simz_tab

desisim.spec_qa.redshifts.calc_obj_stats(simz_tab, objtype)

Calculate redshift statistics for a given objtype

Parameters:

• simz_tab (Table) – TODO: document this

• objtype (str) – Object type, e.g. ‘ELG’, ‘LRG’

Returns:

stat_dict – Survey results for a given object type

Return type:

dict

desisim.spec_qa.redshifts.criteria(simz_tab, objtype=None, dvlimit=None)

Analyze the input table for various criteria

Parameters:

• simz_tab (Table) –

• objtype (str, optional -- Restrict analysis to a specific object type) –

Returns:

• objtype_mask (ndarray) – Match to input objtype (if any given)

• z_mask (ndarray) – Analyzed by the redshift analysis software

• survey_mask (ndarray) – Part of the DESI survey (not filler)

• dv_mask (ndarray) – Satisfies the dv criterion; Either specific to each objtype or using an input dvlimit

• zwarn_mask (ndarray) – ZWARN=0

desisim.spec_qa.redshifts.dz_summ(simz_tab, outfile=None, pdict=None, min_count=20)

Generate a summary figure comparing zfind to ztruth.

Parameters:

• simz_tab (Table) – Table of redshift information.

• pp (PdfPages object) – This parameter is not documented.

• pdict (dict) – Guides the plotting parameters

• min_count (int, optional) – This parameter is not documented.

desisim.spec_qa.redshifts.load_z(fibermap_files, zbest_files=None, outfil=None)

Load input and output redshift values for a set of exposures

Parameters:

• fibermap_files (list) – List of fibermap files; None of these should be calibration..

• zbest_files (list, optional) – List of zbest output files Slurped from fibermap info if not provided

• outfil (str, optional) – Output file for the table

Returns:

• simz_tab (astropy.Table) – Merged table of simpsec data

• zb_tab (astropy.Table) – Merged table of zbest output

desisim.spec_qa.redshifts.match_truth_z(simz_tab, zb_tab, mini_read=False, outfil=None)

Match truth and zbest tables :param simz_tab: astropy.Table; Either generated from load_z() or read from disk via ‘truth.fits’ :param zb_tab: astropy.Table; Either generated from load_z() or read from disk via ‘zcatalog-mini.fits’ :param mini_read: bool, optional; Tables were read from the summary tables written to disk :param outfil: str, optional :return: simz_tab: modified in place

desisim.spec_qa.redshifts.obj_fig(simz_tab, objtype, summ_stats, outfile=None)

Generate QA plot for a given object type

desisim.spec_qa.redshifts.obj_requirements(zstats, objtype)

Assess where a given objtype passes the requirements Requirements from Doc 318 (August 2014)

Parameters:

• zstats (Object) – This parameter is not documented.

• objtype (str) – Object type, e.g. ‘ELG’, ‘LRG’

Returns:

Pass/fail dict

Return type:

dict

desisim.spec_qa.redshifts.plot_slices(x, y, ok, bad, x_lo, x_hi, y_cut, num_slices=5, min_count=100, axis=None)

Scatter plot with 68, 95 percentiles superimposed in slices.

Requires that the matplotlib package is installed.

Parameters:

• x (array of float) – X-coordinates to scatter plot. Points outside [ x_lo, x_hi ] are not displayed.

• y (array of float) – Y-coordinates to scatter plot. Y values are assumed to be roughly symmetric about zero.

• ok (array of bool) – Array of booleans that identify which fits are considered good.

• bad (array of bool) – Array of booleans that identify which fits have failed catastrophically.

• x_lo (float) – Minimum value of x to plot.

• x_hi (float) – Maximum value of x to plot.

• y_cut (float) – The target maximum value of \(|y|\). A dashed line at this value is added to the plot, and the vertical axis is clipped at \(|y| = 1.25 imes y_{cut}\) (but values outside this range are included in the percentile statistics).

• num_slices (int) – Number of equally spaced slices to divide the interval [ x_lo, x_hi ] into.

• min_count (int) – Do not use slices with fewer points for superimposed percentile statistics.

• axis (matplotlib axis object or None) – Uses the current axis if this is None.

desisim.spec_qa.redshifts.slice_simz(simz_tab, objtype=None, z_analy=False, survey=False, catastrophic=False, goodz=False, all_zwarn0=False, **kwargs)

Slice input simz_tab in one of many ways

Parameters:

• z_analy (bool, optional) – redshift analysis required?

• all_zwarn0 (bool, optional) – Ignores catastrophic failures in the slicing to return all sources with ZWARN==0

• survey (bool, optional) – Only include objects that satisfy the Survey requirements e.g. ELGs with sufficient OII_flux

• catastrophic (bool, optional) – Restrict to catastropic failures

• goodz (bool, optional) – Restrict to good redshifts

• all_zwarn0 – Restrict to ZWARN=0 cases

• **kwargs (passed to criteria) –

Returns:

simz_table

Return type:

Table cut by input parameters

desisim.spec_qa.redshifts.spectype_confusion(simz_tab, zb_tab=None)

Generate a Confusion Matrix for spectral types See the Confusion_matrix_spectypes Notebook in docs/nb for an example

Parameters:

• simz_tab (Table) – Truth table; may be input from truth.fits

• zb_tab (Table (optional)) – zcatalog/zbest table; may be input from zcatalog-mini.fits If provided, used to match the simz_tab to the zbest quantities

Returns:

• simz_tab (astropy.Table) – Merged table of simpsec data

• results (dict) – Nested dict. First key is the TRUESPECTYPE Second key is the SPECTYPE e.g. results[‘QSO’][‘QSO’] reports the number of True QSO classified as QSO results[‘QSO’][‘Galaxy’] reports the number of True QSO classified as Galaxy

desisim.spec_qa.redshifts.summ_fig(simz_tab, summ_tab, meta, outfile=None)

Generate summary summ_fig :param simz_tab: :param summ_tab: :param meta: :param outfile: :return:

desisim.spec_qa.redshifts.summ_stats(simz_tab)

Generate summary stats

Parameters:

simz_tab (Table) – Table summarizing redshifts

Returns:

List of summary stat dicts

Return type:

lis

desisim.spec_qa.redshifts.zstats(simz_tab, objtype=None, dvlimit=None, count=False, survey=False)

Perform statistics on the input truth+z table good = Satisfies dv criteria and ZWARN==0 fail = Fails dv criteria with ZWARN==0 (catastrophic failures) miss = Satisfies dv criteria but ZWARN!=0 (missed opportunities) lost = Fails dv criteria and ZWARN!=0 (lost, but at least we knew it)

Parameters:

• simz_tab –

• objtype –

• dvlimit – float, optional – Over-rides object specific dv limits

• count – bool, optional

• survey – bool, optional – Restrict to targets meeting the Survey criteria (e.g. ELG flux)

Returns:

just the raw counts of each category :: ngood, nfail, nmiss, nlost else: percentile of each relative to ntot, and ntot

Return type:

if count=True

desisim.spec_qa.s2n

Module to examine S/N in object spectra

desisim.spec_qa.s2n.load_all_s2n_values(nights, channel, sub_exposures=None)

Calculate S/N values for a set of spectra from an input list of nights

Parameters:

• nights – list

• channel – str (‘b’,’r’,’z’)

• sub_exposures –

Returns:

dict

Contains all the S/N info for all nights in the given channel

Return type:

fdict

desisim.spec_qa.s2n.load_s2n_values(objtype, nights, channel, sub_exposures=None)

DEPRECATED

Calculate S/N values for a set of spectra

Parameters:

• objtype – str

• nights – list

• channel – str

• sub_exposures –

Returns:

dict

Contains S/N info

Return type:

fdict

desisim.spec_qa.s2n.obj_s2n_wave(s2n_dict, wv_bins, flux_bins, otype, outfile=None, ax=None)

Generate QA of S/N for a given object type

desisim.spec_qa.s2n.obj_s2n_z(s2n_dict, z_bins, flux_bins, otype, outfile=None, ax=None)

Generate QA of S/N for a given object type vs. z (mainly for ELG)

desisim.spec_qa.s2n.parse_s2n_values(objtype, fdict)

Parse the input set of S/N measurements on objtype

Parameters:

• objtype – str

• fdict – dict Contains all the S/N info for all nights in a given channel

Returns:

dict

Contains all the S/N info for the given objtype

Return type:

pdict

desisim.spec_qa.redshifts

Module to run high_level QA on a given DESI run

Written by JXP on 3 Sep 2015

desisim.spec_qa.utils.catastrophic_dv(objtype)

Pass back catastrophic velocity limit for given objtype From DESI document 318 (August 2014) in docdb

Parameters:

objtype (str) – Object type, e.g. ‘ELG’, ‘LRG’

desisim.spec_qa.utils.elg_flux_lim(z, oii_flux)

Assess which objects pass the ELG flux limit Uses DESI document 318 from August 2014

Parameters:

• z (ndarray) – ELG redshifts

• oii_flux (ndarray) – [OII] fluxes

desisim.spec_qa.utils.get_sty_otype()

Styles for plots

desisim.spec_qa.utils.match_otype(tbl, objtype)

Generate a mask for the input objtype :param tbl: :param objtype: str :return: targets: bool mask

desisim.specsim

DESI wrapper functions for external specsim classes.

desisim.specsim.get_simulator(config='desi', num_fibers=1, camera_output=True)

returns new or cached specsim.simulator.Simulator object

Also adds placeholder for BGS fiberloss if that isn’t already in the config

desisim.targets

Utility functions for working with simulated targets.

desisim.targets._default_wave(wavemin=None, wavemax=None, dw=0.2)

Construct and return the default wavelength vector.

desisim.targets.get_simtype(spectype, desi_target, bgs_target, mws_target)

Derive the simulation type from the redshift spectype and target bits

Parameters:

• spectype – array of ‘GALAXY’, ‘QSO’, ‘STAR’

• *_target – target mask bits

Returns array of simulation types: ELG, LRG, QSO, BGS, …

TODO: add subtypes of STAR

desisim.targets.get_targets(nspec, program, tileid=None, seed=None, specify_targets={}, specmin=0)

Generates a set of targets for the requested program

Parameters:

• nspec – (int) number of targets to generate

• program – (str) program name DARK, BRIGHT, GRAY, MWS, BGS, LRG, ELG, …

Options:

• tileid: (int) tileid, used for setting RA,dec

• seed: (int) random number seed

• specify_targets: (dict of dicts) Define target properties like magnitude and redshift

  for each target class. Each objtype has its own key,value pair see simspec.templates.specify_galparams_dict() or simsepc.templates.specify_starparams_dict()

• specmin: (int) first spectrum number (0-indexed)

Returns:

• fibermap

• targets as tuple of (flux, wave, meta)

desisim.targets.get_targets_parallel(nspec, program, tileid=None, nproc=None, seed=None, specify_targets={})

Parallel wrapper for get_targets()

nproc (int) is number of multiprocessing processes to use.

desisim.targets.sample_nz(objtype, n)

Given objtype = ‘LRG’, ‘ELG’, ‘QSO’, ‘STAR’, ‘STD’ return array of n redshifts that properly sample n(z) from $DESIMODEL/data/targets/nz*.dat

desisim.targets.sample_objtype(nobj, program)

Return a random sampling of object types (dark, bright, MWS, BGS, ELG, LRG, QSO, STD, BAD_QSO)

Parameters:

nobj – number of objects to generate

Returns:

(true_objtype, target_objtype) where true_objtype is the array of

what type the objects actually are and target_objtype is the array of type they were targeted as

Notes

• Actual fiber assignment will result in higher relative fractions of LRGs and QSOs in early passes and more ELGs in later passes.

• Also ensures at least 2 sky and 1 stdstar, even if nobj is small

desisim.templates

Functions to simulate spectral templates for DESI.

class desisim.templates.BGS(minwave=3600.0, maxwave=10000.0, cdelt=0.2, wave=None, transient=None, tr_fluxratio=(0.01, 1.0), tr_epoch=(-10, 10), include_mgii=False, colorcuts_function=None, normfilter_north='BASS-r', normfilter_south='decam2014-r', baseflux=None, basewave=None, basemeta=None)

Generate Monte Carlo spectra of bright galaxy survey galaxies (BGSs).

make_templates(nmodel=100, zrange=(0.01, 0.45), magrange=(17.0, 20.2), oiiihbrange=(-1.3, 0.6), vdisprange=(120.0, 300.0), minhbetaflux=0.0, trans_filter='decam2014-r', redshift=None, mag=None, vdisp=None, seed=None, input_meta=None, input_objmeta=None, nocolorcuts=False, nocontinuum=False, agnlike=False, novdisp=False, south=True, restframe=False, verbose=False)

Build Monte Carlo BGS spectra/templates.

See the GALAXY.make_galaxy_templates function for documentation on the arguments and inherited attributes. Here we only document the arguments that are specific to the BGS class.

Parameters:

• oiiihbrange (float, optional) – Minimum and maximum logarithmic [OIII] 5007/H-beta line-ratio. Defaults to a uniform distribution between (-1.3, 0.6).

• vdisprange (float, optional) – Minimum and maximum velocity dispersion range. Defaults to (120, 300) km/s.

• minhbetaflux (float, optional) – Minimum H-beta flux (default 0.0 erg/s/cm2).

Returns (outflux, wave, meta, objmeta) tuple where:

• outflux (numpy.ndarray): Array [nmodel, npix] of observed-frame spectra (1e-17 erg/s/cm2/A).

• wave (numpy.ndarray): Observed-frame [npix] wavelength array (Angstrom).

• meta (astropy.Table): Table of meta-data [nmodel] for each output spectrum.

• objmeta (astropy.Table): Additional objtype-specific table data [nmodel] for each spectrum.

Raises:

class desisim.templates.ELG(minwave=3600.0, maxwave=10000.0, cdelt=0.2, wave=None, transient=None, tr_fluxratio=(0.01, 1.0), tr_epoch=(-10, 10), include_mgii=False, colorcuts_function=None, normfilter_north='BASS-g', normfilter_south='decam2014-g', baseflux=None, basewave=None, basemeta=None)

Generate Monte Carlo spectra of emission-line galaxies (ELGs).

make_templates(nmodel=100, zrange=(0.6, 1.6), magrange=(20.0, 23.4), oiiihbrange=(-0.5, 0.2), vdisprange=(50.0, 150.0), minoiiflux=0.0, trans_filter='decam2014-r', redshift=None, mag=None, vdisp=None, seed=None, input_meta=None, input_objmeta=None, nocolorcuts=False, nocontinuum=False, agnlike=False, novdisp=False, south=True, restframe=False, verbose=False)

Build Monte Carlo ELG spectra/templates.

See the GALAXY.make_galaxy_templates function for documentation on the arguments and inherited attributes. Here we only document the arguments that are specific to the ELG class.

Parameters:

• oiiihbrange (float, optional) – Minimum and maximum logarithmic [OIII] 5007/H-beta line-ratio. Defaults to a uniform distribution between (-0.5, 0.2).

• vdisprange (float, optional) – Minimum and maximum velocity dispersion range. Defaults to (50, 150) km/s.

• minoiiflux (float, optional) – Minimum [OII] 3727 flux (default 0.0 erg/s/cm2).

Returns (outflux, wave, meta, objmeta) tuple where:

• outflux (numpy.ndarray): Array [nmodel, npix] of observed-frame spectra (1e-17 erg/s/cm2/A).

• wave (numpy.ndarray): Observed-frame [npix] wavelength array (Angstrom).

• meta (astropy.Table): Table of meta-data [nmodel] for each output spectrum.

• objmeta (astropy.Table): Additional objtype-specific table data [nmodel] for each spectrum.

Raises:

class desisim.templates.EMSpectrum(minwave=3650.0, maxwave=7075.0, cdelt_kms=20.0, log10wave=None, include_mgii=False)

Construct a complete nebular emission-line spectrum.

Read the requisite external data files and initialize the output wavelength array.

The desired output wavelength array can either by passed directly using LOG10WAVE (note: must be a log-base10, i.e., constant-velocity pixel array!) or via the MINWAVE, MAXWAVE, and CDELT_KMS arguments.

In addition, three data files are required: ${DESISIM}/data/recombination_lines.escv, ${DESISIM}/data/forbidden_lines.esv, and ${DESISIM}/data/forbidden_mog.fits.

TODO (@moustakas): Incorporate AGN-like emission-line ratios. TODO (@moustakas): Think about how to best include dust attenuation in the lines.

Parameters:

• minwave (float, optional) – Minimum value of the output wavelength array [Angstrom, default 3600].

• maxwave (float, optional) – Minimum value of the output wavelength array [Angstrom, default 10000].

• cdelt_kms (float, optional) – Spacing of the output wavelength array [km/s, default 20].

• log10wave (numpy.ndarray, optional) – Input/output wavelength array (log10-Angstrom, default None).

• include_mgii (bool, optional) – Include Mg II in emission (default False).

log10wave

Wavelength array constructed from the input arguments.

Type:

numpy.ndarray

line

Table containing the laboratoy (vacuum) wavelengths and nominal line-ratios for several dozen forbidden and recombination nebular emission lines.

Type:

astropy.Table

forbidmog

Table containing the mixture of Gaussian parameters encoding the forbidden emission-line priors.

Type:

GaussianMixtureModel

oiiidoublet

Intrinsic [OIII] 5007/4959 doublet ratio (set by atomic physics).

Type:

float32

niidoublet

Intrinsic [NII] 6584/6548 doublet ratio (set by atomic physics).

Type:

float32

Raises:

IOError – If the required data files are not found.

spectrum(oiiihbeta=None, oiihbeta=None, niihbeta=None, siihbeta=None, oiidoublet=0.73, siidoublet=1.3, linesigma=75.0, zshift=0.0, oiiflux=None, hbetaflux=None, seed=None)

Build the actual emission-line spectrum.

Building the emission-line spectrum involves three main steps. First, the oiiihbeta, oiihbeta, and niihbeta emission-line ratios are either drawn from the empirical mixture of Gaussians (recommended!) or input values are used to construct the line-ratios of the strongest optical forbidden lines relative to H-beta.

Note that all three of oiiihbeta, oiihbeta, and niihbeta must be specified simultaneously in order for them to be used.

Second, the requested [OII] 3726,29 and [SII] 6716,31 doublet ratios are imposed.

And finally the full emission-line spectrum is self-consistently normalized to either an integrated [OII] 3726,29 line-flux or an integrated H-beta line-flux. Generally an ELG and LRG spectrum will be normalized using [OII] while the a BGS spectrum will be normalized using H-beta. Note that the H-beta normalization trumps the [OII] normalization (in the case that both are given).

TODO (@moustakas): Add a suitably scaled nebular continuum spectrum. TODO (@moustakas): Add more emission lines (e.g., [NeIII] 3869).

Parameters:

• oiiihbeta (float, optional) – Desired logarithmic [OIII] 5007/H-beta line-ratio (default -0.2). A sensible range is [-0.5,0.2].

• oiihbeta (float, optional) – Desired logarithmic [OII] 3726,29/H-beta line-ratio (default 0.1). A sensible range is [0.0,0.4].

• niihbeta (float, optional) – Desired logarithmic [NII] 6584/H-beta line-ratio (default -0.2). A sensible range is [-0.6,0.0].

• siihbeta (float, optional) – Desired logarithmic [SII] 6716/H-beta line-ratio (default -0.3). A sensible range is [-0.5,0.2].

• oiidoublet (float, optional) – Desired [OII] 3726/3729 doublet ratio (default 0.73).

• siidoublet (float, optional) – Desired [SII] 6716/6731 doublet ratio (default 1.3).

• linesigma (float, optional) – Intrinsic emission-line velocity width/sigma (default 75 km/s). A sensible range is [30-150].

• zshift (float, optional) – Perturb the emission lines from their laboratory (rest) wavelengths by a factor 1+ZSHIFT (default 0.0). Use with caution!

• oiiflux (float, optional) – Normalize the emission-line spectrum to this integrated [OII] emission-line flux (default None).

• hbetaflux (float, optional) – Normalize the emission-line spectrum to this integrated H-beta emission-line flux (default None).

• seed (int, optional) – input seed for the random numbers.

Returns:

Tuple of (emspec, wave, line), where emspec is an Array [npix] of flux values [erg/s/cm2/A]; wave is an Array [npix] of vacuum wavelengths corresponding to FLUX [Angstrom, linear spacing]; line is a Table of emission-line parameters used to generate the emission-line spectrum.

class desisim.templates.GALAXY(objtype='ELG', minwave=3600.0, maxwave=10000.0, cdelt=0.2, wave=None, transient=None, tr_fluxratio=(0.01, 1.0), tr_epoch=(-10, 10), include_mgii=False, colorcuts_function=None, normfilter_north='BASS-r', normfilter_south='decam2014-r', normline='OII', baseflux=None, basewave=None, basemeta=None)

Base class for generating Monte Carlo spectra of the various flavors of galaxies (ELG, BGS, and LRG).

_blurmatrix(vdisp, log=None)

Pre-compute the blur_matrix as a dictionary keyed by each unique value of vdisp.

lineratios(nobj, oiiihbrange=(-0.5, 0.2), oiidoublet_meansig=(0.73, 0.05), agnlike=False, rand=None)

Get the correct number and distribution of the forbidden and [OII] 3726/3729 doublet emission-line ratios. Note that the agnlike option is not yet supported.

Supporting oiiihbrange needs a different (fast) approach. Suppressing the code below for now until it’s needed.

make_galaxy_templates(nmodel=100, zrange=(0.6, 1.6), magrange=(20.0, 22.0), oiiihbrange=(-0.5, 0.2), vdisprange=(100.0, 300.0), minlineflux=0.0, trans_filter='decam2014-r', maxiter=10, seed=None, redshift=None, mag=None, vdisp=None, input_meta=None, input_objmeta=None, nocolorcuts=False, nocontinuum=False, agnlike=False, novdisp=False, south=True, restframe=False, verbose=False)

Build Monte Carlo galaxy spectra/templates.

This function chooses random subsets of the basis continuum spectra (for the given galaxy spectral type), constructs an emission-line spectrum (if desired), redshifts, convolves by the intrinsic velocity dispersion, and then finally normalizes each spectrum to a (generated or input) apparent magnitude.

In detail, each (output) model gets randomly assigned a continuum (basis) template; however, if that template doesn’t pass the (spectral) class-specific color cuts (at the specified redshift), then we iterate through the rest of the templates until we find one that does pass the color-cuts.

The user also (optionally) has a lot of flexibility over the inputs/outputs and can specify any combination of the redshift, velocity dispersion, and apparent magnitude (in the normalization filter specified in the GALAXY.__init__ method) inputs. Alternatively, the user can pass a complete metadata table, in order to easily regenerate spectra on-the-fly (see the documentation for the input_meta argument, below).

Note

The default inputs are generally set to values which are appropriate for ELGs, so be sure to alter them when generating templates for other spectral classes.

Parameters:

• nmodel (int, optional) – Number of models to generate (default 100).

• zrange (float, optional) – Minimum and maximum redshift range. Defaults to a uniform distribution between (0.6, 1.6).

• magrange (float, optional) – Minimum and maximum magnitude in the bandpass specified by self.normfilter_south (if south=True) or self.normfilter_north (if south=False). Defaults to a uniform distribution between (20.0, 22.0).

• oiiihbrange (float, optional) – Minimum and maximum logarithmic [OIII] 5007/H-beta line-ratio. Defaults to a uniform distribution between (-0.5, 0.2).

• vdisprange (float, optional) – Minimum and maximum velocity dispersion range. Defaults to (100, 300) km/s.

• minlineflux (float, optional) – Minimum emission-line flux in the line specified by self.normline (default 0 erg/s/cm2).

• trans_filter (str) – filter corresponding to TRANS_FLUXRATIORANGE (default ‘decam2014-r’).

• maxiter (int) – maximum number of iterations for generating the requested number of templates template which also satisfy the color-cuts (default 10).

• seed (int, optional) – Input seed for the random numbers.

• redshift (float, optional) – Input/output template redshifts. Array size must equal nmodel. Ignores zrange input.

• mag (float, optional) – Input/output template magnitudes in the bandpass specified by self.normfilter_south (if south=True) or self.normfilter_north (if south=False). Array size must equal nmodel. Ignores magrange input.

• vdisp (float, optional) – Input/output velocity dispersions in km/s. Array size must equal nmodel.

• input_meta (astropy.Table) – Input metadata table with the following required columns: TEMPLATEID, SEED, REDSHIFT, MAG, and MAGFILTER (see desisim.io.empty_metatable for the expected data types). In addition, in order to faithfully reproduce a previous set of spectra, then VDISP must also be passed (normally returned in the OBJMETA table). If present, then all other optional inputs (nmodel, redshift, mag, zrange, logvdisp_meansig, etc.) are ignored.

• input_objmeta (astropy.Table) – Input object-specific metadata table.

• nocolorcuts (bool, optional) – Do not apply the color-cuts specified by the self.colorcuts_function function (default False).

• nocontinuum (bool, optional) – Do not include the stellar continuum in the output spectrum (useful for testing; default False). Note that this option automatically sets nocolorcuts to True and transient to False.

• novdisp (bool, optional) – Do not velocity-blur the spectrum (default False).

• agnlike (bool, optional) – Adopt AGN-like emission-line ratios (e.g., for the LRGs and some BGS galaxies) (default False, meaning we adopt star-formation-like line-ratios). Option not yet supported.

• south (bool, optional) – Apply “south” color-cuts using the DECaLS filter system, otherwise apply the “north” (MzLS+BASS) color-cuts. Defaults to True.

• restframe (bool, optional) – If True, return full resolution restframe templates instead of resampled observer frame.

• verbose (bool, optional) – Be verbose!

Returns (outflux, wave, meta, objmeta) tuple where:

• outflux (numpy.ndarray): Array [nmodel, npix] of observed-frame spectra (1e-17 erg/s/cm2/A).

• wave (numpy.ndarray): Observed-frame [npix] wavelength array (Angstrom).

• meta (astropy.Table): Table of meta-data [nmodel] for each output spectrum.

• objmeta (astropy.Table): Additional objtype-specific table data [nmodel] for each spectrum.

Raises:

ValueError –

class desisim.templates.LRG(minwave=3600.0, maxwave=10000.0, cdelt=0.2, wave=None, transient=None, tr_fluxratio=(0.01, 1.0), tr_epoch=(-10, 10), colorcuts_function=None, normfilter_north='MzLS-z', normfilter_south='decam2014-z', baseflux=None, basewave=None, basemeta=None)

Generate Monte Carlo spectra of luminous red galaxies (LRGs).

make_templates(nmodel=100, zrange=(0.35, 1.0), magrange=(18.2, 21.1), vdisprange=(150.0, 300.0), trans_filter='decam2014-r', redshift=None, mag=None, vdisp=None, seed=None, input_meta=None, input_objmeta=None, nocolorcuts=False, novdisp=False, agnlike=False, south=True, restframe=False, verbose=False)

Build Monte Carlo BGS spectra/templates.

See the GALAXY.make_galaxy_templates function for documentation on the arguments and inherited attributes. Here we only document the arguments that are specific to the LRG class.

Parameters:

• vdisprange (float, optional) – Minimum and maximum velocity dispersion range. Defaults to (150, 300) km/s.

• agnlike (bool, optional) – adopt AGN-like emission-line ratios (not yet supported; defaults False).

Returns (outflux, wave, meta, objmeta) tuple where:

• outflux (numpy.ndarray): Array [nmodel, npix] of observed-frame spectra (1e-17 erg/s/cm2/A).

• wave (numpy.ndarray): Observed-frame [npix] wavelength array (Angstrom).

• meta (astropy.Table): Table of meta-data [nmodel] for each output spectrum.

• objmeta (astropy.Table): Additional objtype-specific table data [nmodel] for each spectrum.

Raises:

class desisim.templates.MWS_STAR(minwave=3600.0, maxwave=10000.0, cdelt=0.2, wave=None, colorcuts_function=None, normfilter_north='BASS-r', normfilter_south='decam2014-r', baseflux=None, basewave=None, basemeta=None)

Generate Monte Carlo spectra of Milky Way Survey (magnitude-limited) stars.

make_templates(nmodel=100, vrad_meansig=(0.0, 200.0), magrange=(16.0, 20.0), seed=None, redshift=None, mag=None, input_meta=None, input_objmeta=None, star_properties=None, nocolorcuts=False, south=True, restframe=False, verbose=False)

Build Monte Carlo spectra/templates for MWS_STAR stars.

See the SUPERSTAR.make_star_templates function for documentation on the arguments and inherited attributes. Here we only document the arguments which are specific to the MWS_STAR class.

Args:

Returns (outflux, wave, meta, objmeta) tuple where:

• outflux (numpy.ndarray): Array [nmodel, npix] of observed-frame spectra (1e-17 erg/s/cm2/A).

• wave (numpy.ndarray): Observed-frame [npix] wavelength array (Angstrom).

• meta (astropy.Table): Table of meta-data [nmodel] for each output spectrum.

• objmeta (astropy.Table): Additional objtype-specific table data [nmodel] for each spectrum.

Raises:

class desisim.templates.QSO(minwave=3600.0, maxwave=10000.0, cdelt=0.2, wave=None, basewave_min=1200, basewave_max=25000.0, basewave_R=8000, normfilter_north='BASS-r', normfilter_south='decam2014-r', colorcuts_function=None, balqso=False, z_wind=0.2)

Generate Monte Carlo spectra of quasars (QSOs).

_sample_pcacoeff(nsample, coeff, samplerand)

Draw from the distribution of PCA coefficients.

make_templates(nmodel=100, zrange=(0.5, 4.0), magrange=(17.5, 22.7), seed=None, redshift=None, mag=None, input_meta=None, input_objmeta=None, N_perz=40, maxiter=20, uniform=False, balprob=0.12, lyaforest=True, noresample=False, nocolorcuts=False, south=True, verbose=False)

Build Monte Carlo QSO spectra/templates.

This function generates QSO spectra on-the-fly using PCA decomposition coefficients of SDSS and BOSS QSO spectra. The default is to generate flat, uncorrelated priors on redshift and apparent magnitude (in the bandpass specified by self.normfilter).

However, the user also (optionally) has flexibility over the inputs/outputs and can specify any combination of the redshift and output apparent magnitude. Alternatively, the user can pass a complete metadata table, in order to easily regenerate spectra on-the-fly (see the documentation for the input_meta argument, below).

Note

The templates are only defined in the range 3500-10000 A (observed).

Parameters:

• nmodel (int, optional) – Number of models to generate (default 100).

• zrange (float, optional) – Minimum and maximum redshift range. Defaults to a uniform distribution between (0.5, 4.0).

• magrange (float, optional) – Minimum and maximum magnitude in the bandpass specified by self.normfilter_south (if south=True) or self.normfilter_north (if south=False). Defaults to a uniform distribution between (17, 22.7).

• seed (int, optional) – input seed for the random numbers.

• redshift (float, optional) – Input/output template redshifts. Array size must equal nmodel. Ignores zrange input.

• mag (float, optional) – Input/output template magnitudes in the bandpass specified by self.normfilter_south (if south=True) or self.normfilter_north (if south=False). Array size must equal nmodel. Ignores magrange input.

• input_meta (astropy.Table) – Input metadata table with the following required columns: SEED, REDSHIFT, MAG, and MAGFILTER (see desisim.io.empty_metatable for the expected data types). If present, then all other optional inputs (nmodel, redshift, mag, zrange, etc.) are ignored. Note that this argument cannot be used (at this time) to precisely reproduce templates that have had BALs inserted.

• input_objmeta (astropy.Table) – Input object-specific metadata table.

• N_perz (int, optional) – Number of templates per redshift redshift value to generate (default 20).

• maxiter (int) – maximum number of iterations for findng a non-negative template that also satisfies the color-cuts (default 20).

• uniform (bool, optional) – Draw uniformly from the PCA coefficients (default False).

• balprob (float, optional) – Probability that a QSO is a BAL (default 0.12). Only used if QSO(balqso=True) at instantiation.

• lyaforest (bool, optional) – Include Lyman-alpha forest absorption (default True).

• noresample (bool, optional) – Do not resample the QSO spectra in wavelength (default False).

• nocolorcuts (bool, optional) – Do not apply the fiducial rzW1W2 color-cuts cuts (default False).

• south (bool, optional) – Apply “south” color-cuts using the DECaLS filter system, otherwise apply the “north” (MzLS+BASS) color-cuts. Defaults to True.

• verbose (bool, optional) – Be verbose!

Returns (outflux, wave, meta, objmeta) tuple where:

• outflux (numpy.ndarray): Array [nmodel, npix] of observed-frame spectra (1e-17 erg/s/cm2/A).

• wave (numpy.ndarray): Observed-frame wavelength array (Angstrom).

  If noresample=True then this is an [nmodel, npix] array (a different observed-frame array for each object), otherwise it’s a one-dimensional [npix]-length array.

• meta (astropy.Table): Table of meta-data [nmodel] for each output spectrum.

• objmeta (astropy.Table): Additional objtype-specific table data [nmodel] for each spectrum.

Raises:

ValueError –

class desisim.templates.SIMQSO(minwave=3600.0, maxwave=10000.0, cdelt=0.2, wave=None, nproc=1, basewave_min=450.0, basewave_max=60000.0, basewave_R=8000, normfilter_north='BASS-r', normfilter_south='decam2014-r', colorcuts_function=None, restframe=False, sqmodel='default')

Generate Monte Carlo spectra of quasars (QSOs) using simqso.

_make_simqso_templates(redshift=None, magrange=None, mag=None, seed=None, lyaforest=True, nocolorcuts=False, noresample=False, input_qsometa=None, south=True)

Wrapper function for actually generating the templates.

empty_qsometa(qsometa, nmodel)

Initialize an empty QsoSimPoints object, which contains all the metadata needed to regenerate simqso spectra.

make_templates(nmodel=100, zrange=(0.5, 4.0), magrange=(17.0, 22.7), seed=None, redshift=None, mag=None, maxiter=20, input_qsometa=None, qsometa_extname='QSOMETA', return_qsometa=False, lyaforest=True, nocolorcuts=False, noresample=False, south=True, verbose=False)

Build Monte Carlo QSO spectra/templates.

• This function generates QSO spectra on-the-fly using @imcgreer’s simqso. The default is to generate flat, uncorrelated priors on redshift, absolute magnitudes based on the SDSS/DR9 QSOLF, and to compute the corresponding apparent magnitudes using the appropriate per-object K-correction.

  Alternatively, the redshift can be input and the absolute and apparent magnitudes will again be computed self-consistently from the QSOLF.

  Providing apparent magnitudes on input is not supported although it could be if there is need. However, one can control the apparent brightness of the resulting QSO spectra by specifying magrange.

• The way the code is currently structured could lead to memory problems if one attempts to generate very large numbers of spectra simultaneously (>10^4, perhaps, depending on the machine). However, it can easily be refactored to generate the appropriate number of templates in chunks at the expense of some computational speed.

Parameters:

• nmodel (int, optional) – Number of models to generate (default 100).

• zrange (float, optional) – Minimum and maximum redshift range. Defaults to a uniform distribution between (0.5, 4.0).

• magrange (float, optional) – Minimum and maximum magnitude in the bandpass specified by self.normfilter_south (if south=True) or self.normfilter_north (if south=False). Defaults to a uniform distribution between (17, 22.7).

• seed (int, optional) – input seed for the random numbers.

• redshift (float, optional) – Input/output template redshifts. Array size must equal nmodel. Ignores zrange input.

• mag (float, optional) – Not currently supported or used, but see magrange. Defaults to None.

• maxiter (int) – maximum number of iterations for findng a template that satisfies the color-cuts (default 20).

• input_qsometa (simqso.sqgrids.QsoSimPoints object or FITS filename) – Input QsoSimPoints object or FITS filename (with a qsometa_extname HDU) from which to (re)generate the QSO spectra. All other inputs are ignored when this optional input is present. Please be cautious when using this argument, as it has not been fully tested.

• qsometa_extname (str) – FITS extension name to read when input_qsometa is a filename. Defaults to ‘QSOMETA’.

• return_qsometa (bool, optional) – Return the simqso.sqgrids.QsoSimPoints object, which contains all the data necessary to regenerate the QSO spectra. In particular, the data attribute is an astropy.Table object which contains lots of useful info. This object can be written to disk with the simqso.sqgrids.QsoSimObjects.write method (default False).

• lyaforest (bool, optional) – Include Lyman-alpha forest absorption (default True).

• nocolorcuts (bool, optional) – Do not apply the fiducial rzW1W2 color-cuts cuts (default False).

• noresample (bool, optional) – Do not resample the QSO spectra in wavelength (default False).

• south (bool, optional) – Apply “south” color-cuts using the DECaLS filter system, otherwise apply the “north” (MzLS+BASS) color-cuts. Defaults to True.

• verbose (bool, optional) – Be verbose!

Returns (outflux, wave, meta, qsometa) tuple where:

• outflux (numpy.ndarray): Array [nmodel, npix] of observed-frame spectra (1e-17 erg/s/cm2/A).

• wave (numpy.ndarray): Observed-frame [npix] wavelength array (Angstrom).

• meta (astropy.Table): Table of meta-data [nmodel] for each output spectrum.

• objmeta (astropy.Table): Additional objtype-specific table data [nmodel] for each spectrum.

In addition, if return_qsometa=True then a fourth argument, qsometa, is returned (see the return_qsometa documentation, above).

Raises:

ValueError –

class desisim.templates.STAR(minwave=3600.0, maxwave=10000.0, cdelt=0.2, wave=None, baseflux=None, basewave=None, basemeta=None)

Generate Monte Carlo spectra of generic stars.

make_templates(nmodel=100, vrad_meansig=(0.0, 200.0), magrange=(18.0, 23.5), seed=None, redshift=None, mag=None, input_meta=None, input_objmeta=None, star_properties=None, south=True, restframe=False, verbose=False)

Build Monte Carlo spectra/templates for generic stars.

See the SUPERSTAR.make_star_templates function for documentation on the arguments and inherited attributes. Here we only document the arguments which are specific to the STAR class.

Args:

Returns (outflux, wave, meta, objmeta) tuple where:

• outflux (numpy.ndarray): Array [nmodel, npix] of observed-frame spectra (1e-17 erg/s/cm2/A).

• wave (numpy.ndarray): Observed-frame [npix] wavelength array (Angstrom).

• meta (astropy.Table): Table of meta-data [nmodel] for each output spectrum.

• objmeta (astropy.Table): Additional objtype-specific table data [nmodel] for each spectrum.

Raises:

class desisim.templates.STD(minwave=3600.0, maxwave=10000.0, cdelt=0.2, wave=None, colorcuts_function=None, normfilter_north='BASS-r', normfilter_south='decam2014-r', baseflux=None, basewave=None, basemeta=None)

Generate Monte Carlo spectra of (metal-poor, main sequence turnoff) standard stars (STD).

make_templates(nmodel=100, vrad_meansig=(0.0, 200.0), magrange=(16.0, 19.0), seed=None, redshift=None, mag=None, input_meta=None, input_objmeta=None, star_properties=None, nocolorcuts=False, south=True, restframe=False, verbose=False)

Build Monte Carlo spectra/templates for STD stars.

See the SUPERSTAR.make_star_templates function for documentation on the arguments and inherited attributes. Here we only document the arguments which are specific to the STD class.

Args:

Returns (outflux, wave, meta, objmeta) tuple where:

• outflux (numpy.ndarray): Array [nmodel, npix] of observed-frame spectra (1e-17 erg/s/cm2/A).

• wave (numpy.ndarray): Observed-frame [npix] wavelength array (Angstrom).

• meta (astropy.Table): Table of meta-data [nmodel] for each output spectrum.

• objmeta (astropy.Table): Additional objtype-specific table data [nmodel] for each spectrum.

Raises:

class desisim.templates.SUPERSTAR(objtype='STAR', subtype='', minwave=3600.0, maxwave=10000.0, cdelt=0.2, wave=None, normfilter_north='BASS-r', normfilter_south='decam2014-r', colorcuts_function=None, baseflux=None, basewave=None, basemeta=None)

Base class for generating Monte Carlo spectra of the various flavors of stars.

make_star_templates(nmodel=100, vrad_meansig=(0.0, 200.0), magrange=(18.0, 22.0), seed=None, redshift=None, mag=None, input_meta=None, input_objmeta=None, star_properties=None, nocolorcuts=False, south=True, restframe=False, verbose=False)

Build Monte Carlo spectra/templates for various flavors of stars.

This function chooses random subsets of the continuum spectra for the type of star specified by OBJTYPE, adds radial velocity jitter, applies the targeting color-cuts, and then normalizes the spectrum to the magnitude in the given filter.

The user also (optionally) has a lot of flexibility over the inputs/outputs and can specify any combination of the radial velocity and apparent magnitude (in the normalization filter specified in the GALAXY.__init__ method) inputs. Alternatively, the user can pass a complete metadata table, in order to easily regenerate spectra on-the-fly (see the documentation for the input_meta argument, below). Finally, the user can pass a star_properties table in order to interpolate the base templates to non-gridded values of [Fe/H], logg, and Teff.

Note

• The default inputs are generally set to values which are appropriate for generic stars, so be sure to alter them when generating templates for other spectral classes.

• If both input_meta and star_properties are passed, then star_properties is ignored.

Parameters:

• nmodel (int, optional) – Number of models to generate (default 100).

• vrad_meansig (float, optional) – Mean and sigma (standard deviation) of the radial velocity “jitter” (in km/s) that should be included in each spectrum. Defaults to a normal distribution with a mean of zero and sigma of 200 km/s.

• magrange (float, optional) – Minimum and maximum magnitude in the bandpass specified by self.normfilter_south (if south=True) or self.normfilter_north (if south=False). Defaults to a uniform distribution between (18, 22).

• seed (int, optional) – input seed for the random numbers.

• redshift (float, optional) – Input/output (dimensionless) radial velocity. Array size must equal nmodel. Ignores vrad_meansig input.

• mag (float, optional) – Input/output template magnitudes in the bandpass specified by self.normfilter_south (if south=True) or self.normfilter_north (if south=False). Array size must equal nmodel. Ignores magrange input.

• input_meta (astropy.Table) – Input metadata table with the following required columns: TEMPLATEID, SEED, REDSHIFT, MAG, and MAGFILTER (see desisim.io.empty_metatable for the expected data types). If present, then all other optional inputs (nmodel, redshift, mag, zrange, vrad_meansig, etc.) are ignored.

• input_objmeta (astropy.Table) – Input object-specific metadata table.

• star_properties (astropy.Table) – Input table with the following required columns: REDSHIFT, MAG, MAGFILTER, TEFF, LOGG, and FEH (except for WDs, which don’t need to have an FEH column). Optionally, SEED can also be included in the table. When this table is passed, the basis templates are interpolated to the desired physical values provided, enabling large numbers of mock stellar spectra to be generated with physically consistent properties. However, be warned that the interpolation scheme is very rudimentary.

• nocolorcuts (bool, optional) – Do not apply the color-cuts specified by the self.colorcuts_function function (default False).

• south (bool, optional) – Apply “south” color-cuts using the DECaLS filter system, otherwise apply the “north” (MzLS+BASS) color-cuts. Defaults to True.

• restframe (bool, optional) – If True, return full resolution restframe templates instead of resampled observer frame.

• verbose (bool, optional) – Be verbose!

Returns (outflux, wave, meta) tuple where:

• outflux (numpy.ndarray): Array [nmodel, npix] of observed-frame spectra (1e-17 erg/s/cm2/A).

• wave (numpy.ndarray): Observed-frame [npix] wavelength array (Angstrom).

• meta (astropy.Table): Table of meta-data [nmodel] for each output spectrum.

Raises:

ValueError –

class desisim.templates.WD(minwave=3600.0, maxwave=10000.0, cdelt=0.2, wave=None, subtype='DA', colorcuts_function=None, normfilter_north='BASS-g', normfilter_south='decam2014-g', baseflux=None, basewave=None, basemeta=None)

Generate Monte Carlo spectra of white dwarfs.

make_templates(nmodel=100, vrad_meansig=(0.0, 200.0), magrange=(16.0, 19.0), seed=None, redshift=None, mag=None, input_meta=None, input_objmeta=None, star_properties=None, nocolorcuts=False, south=True, restframe=False, verbose=False)

Build Monte Carlo spectra/templates for WD stars.

See the SUPERSTAR.make_star_templates function for documentation on the arguments and inherited attributes. Here we only document the arguments which are specific to the WD class.

Args:

Returns (outflux, wave, meta, objmeta) tuple where:

• outflux (numpy.ndarray): Array [nmodel, npix] of observed-frame spectra (1e-17 erg/s/cm2/A).

• wave (numpy.ndarray): Observed-frame [npix] wavelength array (Angstrom).

• meta (astropy.Table): Table of meta-data [nmodel] for each output spectrum.

• objmeta (astropy.Table): Additional objtype-specific table data [nmodel] for each spectrum.

Raises:

ValueError – If the INPUT_META or STAR_PROPERTIES table contains different values of SUBTYPE.

desisim.templates.specify_galparams_dict(templatetype, zrange=None, magrange=None, oiiihbrange=None, logvdisp_meansig=None, minlineflux=None, trans_rfluxratiorange=None, redshift=None, mag=None, vdisp=None, nocolorcuts=None, nocontinuum=None, agnlike=None, novdisp=None, restframe=None)

Creates a dictionary of keyword variables to be passed to GALAXY.make_templates (or one of GALAXY’s child classes). Allows the user to fully define the templated spectra, via defining individual targets or ranges in values. Values already specified in get_targets are not included here. Anything not define or set to None will not be assigned and CLASS.make_templates will assume the following as defaults:

• nmodel=100, zrange=(0.6, 1.6), magrange=(21.0, 23.5),

• oiiihbrange=(-0.5, 0.2), logvdisp_meansig=(1.9, 0.15),

• minlineflux=0.0, trans_rfluxratiorange=(0.01, 0.1),

• seed=None, redshift=None, mag=None, vdisp=None,

• input_meta=None, nocolorcuts=False, nocontinuum=False,

• agnlike=False, novdisp=False, restframe=False, verbose=False

Parameters:

• nmodel (*) – Number of models to generate (default 100).

• zrange (*) – Minimum and maximum redshift range. Defaults to a uniform distribution between (0.6, 1.6).

• magrange (*) – Minimum and maximum magnitude in the bandpass specified by self.normfilter. Defaults to a uniform distribution between (21, 23.4) in the r-band.

• oiiihbrange (*) – Minimum and maximum logarithmic [OIII] 5007/H-beta line-ratio. Defaults to a uniform distribution between (-0.5, 0.2).

• logvdisp_meansig (*) – Logarithmic mean and sigma values for the (Gaussian) stellar velocity dispersion distribution. Defaults to log10-sigma=1.9+/-0.15 km/s.

• minlineflux (*) – Minimum emission-line flux in the line specified by self.normline (default 0 erg/s/cm2).

• trans_rfluxratiorange (*) – r-band flux ratio of the SNeIa spectrum with respect to the underlying galaxy. Defaults to a uniform distribution between (0.01, 0.1).

• seed (*) – Input seed for the random numbers.

• redshift (*) – Input/output template redshifts. Array size must equal nmodel. Ignores zrange input.

• mag (*) – Input/output template magnitudes in the band specified by self.normfilter. Array size must equal nmodel. Ignores magrange input.

• vdisp (*) – Input/output velocity dispersions. Array size must equal nmodel. Ignores magrange input.

• input_meta (*) – Input metadata table with the following required columns: TEMPLATEID, SEED, REDSHIFT, VDISP, MAG (where mag is specified by self.normfilter). In addition, if transient is True then the table must also contain SNE_TEMPLATEID, SNE_EPOCH, and SNE_RFLUXRATIO columns. See desisim.io.empty_metatable for the required data type for each column. If this table is passed then all other optional inputs (nmodel, redshift, vdisp, mag, zrange, logvdisp_meansig, etc.) are ignored.

• nocolorcuts (*) – Do not apply the color-cuts specified by the self.colorcuts_function function (default False).

• nocontinuum (*) – Do not include the stellar continuum in the output spectrum (useful for testing; default False). Note that this option automatically sets nocolorcuts to True and transient to False.

• novdisp (*) – Do not velocity-blur the spectrum (default False).

• agnlike (*) – Adopt AGN-like emission-line ratios (e.g., for the LRGs and some BGS galaxies) (default False, meaning we adopt star-formation-like line-ratios). Option not yet supported.

• restframe (*) – If True, return full resolution restframe templates instead of resampled observer frame.

• verbose (*) – Be verbose!

Returns:

dictionary containing all of the values passed defined

with variable names as the corresonding key. These are intentionally identical to those passed to the make_templates classes above

Return type:

• fulldef_dict (dict)

desisim.templates.specify_starparams_dict(templatetype, vrad_meansig=None, magrange=None, redshift=None, mag=None, input_meta=None, star_properties=None, nocolorcuts=None, restframe=None)

Creates a dictionary of keyword variables to be passed to SUPERSTAR.make_templates (or one of SUPERSTAR’s child classes). Allows the user to fully define the templated spectra, via defining individual targets or ranges in values. Values already specified in get_targets are not included here. Anything not define or set to None will not be assigned and CLASS.make_templates will assume the following as defaults:

• nmodel=100, vrad_meansig=(0.0, 200.0),

• magrange=(18.0, 23.5), seed=None, redshift=None,

• mag=None, input_meta=None, star_properties=None,

• nocolorcuts=False, restframe=False, verbose=False

Parameters:

• nmodel (*) – Number of models to generate (default 100).

• vrad_meansig (*) – Mean and sigma (standard deviation) of the radial velocity “jitter” (in km/s) that should be included in each spectrum. Defaults to a normal distribution with a mean of zero and sigma of 200 km/s.

• magrange (*) – Minimum and maximum magnitude in the bandpass specified by self.normfilter. Defaults to a uniform distribution between (18, 23.5) in the r-band.

• seed (*) – input seed for the random numbers.

• redshift (*) – Input/output (dimensionless) radial velocity. Array size must equal nmodel. Ignores vrad_meansig input.

• mag (*) – Input/output template magnitudes in the band specified by self.normfilter. Array size must equal nmodel. Ignores magrange input.

• input_meta (*) – Input metadata table with the following required columns: TEMPLATEID, SEED, REDSHIFT, and MAG (where mag is specified by self.normfilter). See desisim.io.empty_metatable for the required data type for each column. If this table is passed then all other optional inputs (nmodel, redshift, mag, vrad_meansig etc.) are ignored.

• star_properties (*) – Input table with the following required columns: REDSHIFT, MAG, TEFF, LOGG, and FEH (except for WDs, which don’t need to have an FEH column). Optionally, SEED can also be included in the table. When this table is passed, the basis templates are interpolated to the desired physical values provided, enabling large numbers of mock stellar spectra to be generated with physically consistent properties.

• nocolorcuts (*) – Do not apply the color-cuts specified by the self.colorcuts_function function (default False).

• restframe (*) – If True, return full resolution restframe templates instead of resampled observer frame.

• verbose (*) – Be verbose!

Returns:

dictionary containing all of the values passed defined

with variable names as the corresonding key. These are intentionally identical to those passed to the make_templates classes above

Return type:

• fulldef_dict (dict)

Module for defining interface to transient models.

class desisim.transients.ModelBuilder(modelclass)

A class which can build a transient model. It allows the TransientModels object registry to register the model without instantiating it until it’s needed. This is handy because some models take time and memory to instantiate.

class desisim.transients.TabularModel(modelname, modeltype, filename, filefmt)

flux(t, wl)

Return flux vs wavelength at a given time t.

Parameters:

• t (float or astropy.units.quantity.Quantity) – Time of observation, with t=0 representing max light.

• wl (list or ndarray) – Wavelength array to compute the flux.

Returns:

flux – Normalized flux array as a function of wavelength.

Return type:

list or ndarray

maxtime()

Return maximum time used in model (peak light at t=0).

maxwave()

Return maximum wavelength stored in model.

mintime()

Return minimum time used in model (peak light at t=0).

minwave()

Return minimum wavelength stored in model.

set_model_pars(modelpars)

Set model parameters.

Parameters:

modelpars (dict) – Parameters used to initialize the internal model.

class desisim.transients.Transient(modelname, modeltype)

Abstract base class to enforce interface for transient flux models.

desisim.util

Utility functions for desisim. These may belong elsewhere?

desisim.util.dateobs2night(dateobs)

Convert UTC dateobs to KPNO YEARMMDD night string

Parameters:

dateobs – float -> interpret as MJD str -> interpret as ISO 8601 YEAR-MM-DDThh:mm:ss.s string astropy.time.Time -> UTC python datetime.datetime -> UTC

TODO: consider adding format option to pass to astropy.time.Time without

otherwise questioning the dateobs format

desisim.util.medxbin(x, y, binsize, minpts=20, xmin=None, xmax=None)

Compute the median (and other statistics) in fixed bins along the x-axis.

desisim.util.spline_medfilt2d(image, kernel_size=201)

Returns a 2D spline interpolation of a median filtered input image