desitarget API

desitarget

Tools for DESI target selection.

desitarget.QA

Module dealing with Quality Assurance tests for Target Selection

desitarget.QA._in_desi_footprint(targs, radec=False)

Convenience function for using is_point_in_desi to find which targets are in the footprint.

Parameters:

• targs (array or str) – Targets in the DESI data model format, or any array that contains RA and DEC columns.

• radec (bool, optional, defaults to False) – If True then the passed objs is an [RA, Dec] list instead of a rec array.

Returns:

The INDICES of the input targs that are in the DESI footprint.

Return type:

integer

desitarget.QA._javastring()

Return a string that embeds a date in a webpage

desitarget.QA._load_dndz(tcnames=None)

Load the predicted redshift distributions for each target class.

Parameters:

tcnames (list) – A list of strings, e.g. “[‘QSO’,’LRG’,’ALL’] If passed, return only a dictionary for those specific bits.

Returns:

A dictionary where the keys are the bit names and the values are the dndz as a function of redshift (as another dictionary with keys ‘z’, and ‘dndz’, respectively.

Return type:

dictionary

desitarget.QA._load_systematics()

Loads information for making systematics plots.

Returns:

A dictionary where the keys are the names of the systematics and the values are arrays of where to clip these systematics in plots

Return type:

dictionary

desitarget.QA._load_targdens(tcnames=None, bit_mask=None)

Loads the target info dictionary as in desimodel.io.load_target_info() and extracts the target density information in a format useful for targeting QA plots.

Parameters:

• tcnames (list) – A list of strings, e.g. “[‘QSO’,’LRG’,’ALL’] If passed, return only a dictionary for those specific bits.

• bit_mask (list or ~numpy.array, optional, defaults to None) – If passed, load the bit names from this mask (with no associated expected densities) rather than loading the main survey bits and densities. Must be a desi mask object, e.g., loaded as from desitarget.targetmask import desi_mask. Any bit names that contain “NORTH” or “SOUTH” or calibration bits will be removed. A list of several masks can be passed rather than a single mask.

Returns:

A dictionary where the keys are the bit names and the values are the densities.

Return type:

dictionary

Notes

If bit_mask happens to correpond to the main survey masks, then the default behavior is triggered (as if bit_mask=None).

desitarget.QA._parse_tcnames(tcstring=None, add_all=True)

Turn a comma-separated string of target class names into a list.

Parameters:

• tcstring (str, optional, defaults to “ELG,QSO,LRG,MWS,BGS,STD,LGE(ALL)”) – Comma-separated names of target classes e.g. QSO,LRG. Options are ELG, QSO, LRG, MWS, BGS, STD, “LGE”.

• add_all (boolean, optional, defaults to True) – If True, then include ALL in the default names.

Returns:

The string of names is converted to a list.

Return type:

list

Notes

• One use of this function is to check for valid target class strings. An IOError is raised if a string is invalid.

desitarget.QA._prepare_systematics(data, colname)

Functionally convert systematics to more user-friendly numbers.

:param data array: An array of the systematic. :param colname: The column name of the passed systematic, e.g. STARDENS. :type colname: str

Returns:

The systematics converted by the appropriate function

Return type:

array

desitarget.QA.make_qa_page(targs, mocks=False, makeplots=True, max_bin_area=1.0, qadir='.', clip2foot=False, weight=True, imaging_map_file=None, tcnames=None, systematics=True, numproc=8, downsample=None)

Make a directory containing a webpage in which to embed QA plots.

Parameters:

• targs (array or str) – An array of targets in the DESI data model format. If a string is passed then the targets are read from the file with the passed name (supply the full directory path). The string can also be a directory of HEALPixel-split target files which will be read in using desitarget.io.read_targets_in_box().

• mocks (boolean, optional, default=False) – If True, add plots only relevant to mocks to the webpage.

• makeplots (boolean, optional, default=True) – If True, then create the plots as well as the webpage.

• max_bin_area (float, optional, defaults to 1 degree) – Bin size in RA/Dec is set as close as possible to this value.

• qadir (str, optional, defaults to the current directory) – The output directory to which to write produced plots.

• clip2foot (boolean, optional, defaults to False) – Use desimodel.footprint.is_point_in_desi to restrict targs to the DESI spectroscopic footprint.

• weight (boolean, optional, defaults to True) – If set, weight pixels to offset under-dense pixels at footprint edges. Uses the imaging_map_file HEALPix file for real targets and the DESIMODEL HEALPix footprint file for mock targets.

• imaging_map_file (str, optional, defaults to no weights) – If weight is set, then this is the location of the imaging HEALPix map (e.g. made by desitarget.randoms.pixmap()). Defaults to 1 everywhere (i.e. no weights) for the real targets. If this is not set, then systematics plots cannot be made.

• tcnames (list) – String-list, e.g. [‘QSO’,’LRG’,’ALL’] If passed, return only QA pages for those specific bits. A useful speed-up when testing.

• systematics (boolean, optional, defaults to True) – If sent, then add plots of systematics to the front page.

• numproc (int, optional, defaults to 8) – The number of parallel processes to use to generate plots.

• downsample (int, optional, defaults to None) – If not None, downsample targets by (roughly) this value, e.g. for downsample=10 a set of 900 targets would have ~90 random targets returned. A speed-up for experimenting with large files.

Returns:

But the page index.html and associated pages and plots are written to qadir.

Return type:

Nothing

Notes

If making plots, then the DESIMODEL environment variable must be set to find the file of HEALPixels that overlap the DESI footprint.

desitarget.QA.make_qa_plots(targs, qadir='.', targdens=None, max_bin_area=1.0, weight=True, imaging_map_file=None, truths=None, objtruths=None, tcnames=None, cmx=False, bit_mask=None, mocks=False, numproc=8)

Make DESI targeting QA plots given a passed set of targets.

Parameters:

• targs (array or str) – Array of targets in the DESI data model format. If a string is passed then the targets are read from the file with the passed name (supply the full directory path).

• qadir (str, optional, defaults to the current directory) – The output directory to which to write produced plots.

• targdens (dictionary, optional) – A dictionary of DESI target classes and the goal density for that class. Used to label the goal density on histogram plots.

• max_bin_area (float, optional, defaults to 1 degree) – The bin size for sky maps in RA/Dec correspond to this value.

• weight (boolean, optional, defaults to True) – If set, weight pixels using the DESIMODEL HEALPix footprint file to offset under-dense pixels at the footprint edges.

• imaging_map_file (str, optional, defaults to no weights) – If weight is set, this file is the location of the imaging HEALPixel map (e.g. made by :func:` desitarget.randoms.pixmap()`. If not sent, then weights default to 1 (i.e. no weighting).

• truths (array or str) – The truth objects from which the targs were derived in the DESI data model format. If a string is passed then read from that file (supply the full directory path).

• objtruths (dict) – Object type-specific truth metadata.

• tcnames (list, defaults to None) – Strings, e.g. [‘QSO’,’LRG’,’ALL’] If passed, return only the QA pages for those specific bits. A useful speed-up when testing.

• cmx (boolean, defaults to False) – Pass as True to use commissioning bits instead of SV or main survey bits. Commissioning files have no MWS or BGS columns.

• bit_mask (list or ~numpy.array, optional) – Load bit names from this passed mask or list of masks instead of from the (default) main survey mask.

• mocks (boolean, optional, default=False) – If True, also make plots that are only relevant to mocks.

• numproc (int, optional, defaults to 8) – The number of parallel processes to use to generate plots.

Returns:

• float – The total area of the survey used to make the QA plots.

• dict – A nested dictionary of each of the bit-names. Each bit-key has a dictionary of the 10 densest pixels in the DESI tiling. Includes RA, DEC, DENSITY (per sq. deg.) and NSIDE for each HEALpixel.

Notes

• The DESIMODEL environment variable must be set to find the default expected target densities.

• When run, a set of targeting .png plots are written to qadir.

desitarget.QA.mock_qafractype(cat, objtype, qadir='.', fileprefix='mock-fractype')

Targeting QA Bar plot of the fraction of each classification type assigned to (mock) targets.

Parameters:

• cat (array) – An array of targets that contains at least TRUESPECTYPE.

• objtype (str) – The name of a DESI target class (e.g., "ELG") that corresponds to the passed cat.

• qadir (str, optional, defaults to the current directory) – The output directory to which to write produced plots.

• fileprefix (str, optional, defaults to "mock-fractype" for) – String to be added to the front of the output file name.

Returns:

But .png plots of target colors are written to qadir. The file is called: {qadir}/{fileprefix}-{objtype}.png.

Return type:

Nothing

desitarget.QA.mock_qanz(cat, objtype, qadir='.', area=1.0, dndz=None, nobjscut=1000, fileprefixz='mock-nz', fileprefixzmag='mock-zvmag')

Make N(z) and z vs. mag DESI QA plots given a passed set of MOCK TRUTH.

Parameters:

• cat (array) – An array of targets that contains at least TRUEZ for redshift information and MAG for magnitude information.

• objtype (str) – The name of a DESI target class (e.g., "ELG") that corresponds to the passed cat.

• qadir (str, optional, defaults to the current directory) – The output directory to which to write produced plots.

• area (float) – Total area in deg2.

• dndz (dict) – Dictionary output of _load_dndz

• nobjscut (int, optional, defaults to 1000) – Make a hexbin plot when the number of objects is greater than nobjscut, otherwise make a scatterplot.

• fileprefixz (str, optional, defaults to "color" for) – String to be added to the front of the output N(z) plot file name.

• fileprefixzmag (str, optional, defaults to "color" for) – String to be added to the front of the output z vs. mag plot file name.

Returns:

But .png plots of target colors are written to qadir. Two plots are made:

The file containing N(z) is called:

{qadir}/{fileprefixz}-{objtype}.png.

The file containing z vs. zerr is called:

{qadir}/{fileprefixzmag}-{objtype}.png.

Return type:

Nothing

desitarget.QA.qacolor(cat, objtype, extinction, qadir='.', fileprefix='color', nodustcorr=False, mocks=False, nobjscut=1000, seed=None)

Make color-based DESI targeting QA plots given a passed set of targets.

Parameters:

• cat (array) – An array of targets that contains at least FLUX_G, FLUX_R, FLUX_Z and FLUX_W1, FLUX_W2 columns for color information.

• objtype (str) – The name of a DESI target class (e.g., "ELG") that corresponds to the passed cat.

• extinction (array) – An array containing the extinction in each band of interest, must contain at least the columns MW_TRANSMISSION_G, _R, _Z, _W1, _W2.

• qadir (str, optional, defaults to the current directory) – The output directory to which to write produced plots.

• fileprefix (str, optional, defaults to "color") – String to be added to the front of the output file name.

• nodustcorr (boolean, optional, defaults to False) – Do not correct for dust extinction.

• mocks (boolean, optional, default=False) – If True, input catalog is a “truths” catalog.

• nobjscut (int, optional, defaults to 1000) – Make a hexbin plot when the number of objects is greater than nobjscut, otherwise make a scatterplot.

• seed (int, optional) – Seed to reproduce random points plotted on hexbin plots.

Returns:

But .png plots of target colors are written to qadir. The file is called: {qadir}/{fileprefix}-{bands}-{objtype}.png where bands might be, e.g., grz.

Return type:

Nothing

desitarget.QA.qagaia(cat, objtype, qadir='.', fileprefix='gaia', nobjscut=1000, seed=None)

Make Gaia-based DESI targeting QA plots given a passed set of targets.

Parameters:

• cat (array) – An array of targets that contains at least “RA”, “PARALLAX”, “PMRA” and “PMDEC”.

• objtype (str) – The name of a DESI target class (e.g., "ELG") that corresponds to the passed cat.

• qadir (str, optional, defaults to the current directory) – The output directory to which to write produced plots.

• fileprefix (str, optional, defaults to "gaia") – String to be added to the front of the output file name.

• nobjscut (int, optional, defaults to 1000) – Make a hexbin plot when the number of objects is greater than nobjscut, otherwise make a scatterplot.

• seed (int, optional) – Seed to reproduce random points plotted on hexbin plots.

Returns:

But .png plots of Gaia information are written to qadir. Two plots are made:

The file containing distances from parallax is called:

{qadir}/{fileprefix}-{parallax}-{objtype}.png.

The file containing proper motion information is called:

{qadir}/{fileprefix}-{pm}-{objtype}.png.

Return type:

Nothing

desitarget.QA.qahisto(cat, objtype, qadir='.', targdens=None, upclip=None, weights=None, max_bin_area=1.0, fileprefix='histo', catispix=False)

Visualize the target density with a histogram of densities. First version taken shamelessly from desitarget.mock.QA (which was originally written by J. Moustakas).

Parameters:

• cat (array) – An array of targets that contains at least RA and DEC columns for coordinate information.

• objtype (str) – The name of a DESI target class (e.g., "ELG") that corresponds to the passed cat.

• qadir (str, optional, defaults to the current directory) – The output directory to which to write produced plots.

• targdens (dictionary, optional, defaults to None) – A dictionary of DESI target classes and the goal density for that class. Used, if passed, to label the goal density on the histogram plot.

• upclip (float, optional, defaults to None) – A cutoff at which to clip the targets at the “high density” end to make plots conform to similar density scales.

• weights (array, optional, defaults to None) – A weight for each of the passed targets (e.g., to upweight each target in a partial pixel at the edge of the DESI footprint).

• max_bin_area (float, optional, defaults to 1 degree) – The bin size in RA/Dec in targs is chosen to be as close as possible to this value.

• fileprefix (str, optional, defaults to "histo") – String to be added to the front of the output file name.

• catispix (boolean, optional, defaults to False) – If this is True, then cat corresponds to the HEALpixel numbers already precomputed using pixels = footprint.radec2pix(nside, cat["RA"], cat["DEC"]) from the RAs and Decs ordered as for weights, rather than the catalog itself. If this is True, then max_bin_area must correspond to the nside used to precompute the pixel numbers.

Returns:

But a .png histogram of target densities is written to qadir. The file is called: {qadir}/{fileprefix}-{objtype}.png.

Return type:

Nothing

desitarget.QA.qamag(cat, objtype, qadir='.', fileprefix='nmag', area=1.0)

Make magnitude-based DESI targeting QA plots given a passed set of targets.

Parameters:

• cat (array) – An array of targets that contains at least FLUX_G, FLUX_R, FLUX_Z and FLUX_W1, columns for magnitude information.

• objtype (str) – The name of a DESI target class (e.g., "ELG") that corresponds to the passed cat.

• qadir (str, optional, defaults to the current directory) – The output directory to which to write produced plots.

• fileprefix (str, optional, defaults to "nmag" for) – String to be added to the front of the output file name.

• area (float) – Total area in deg2.

Returns:

But .png plots of target colors are written to qadir. The file is called: {qadir}/{fileprefix}-{filter}-{objtype}.png where filter might be, e.g., g. ASCII versions of those files are also written with columns of magnitude bin and target number density. The file is called {qadir}/{fileprefix}-{filter}-{objtype}.dat.

Return type:

Nothing

desitarget.QA.qaskymap(cat, objtype, qadir='.', upclip=None, weights=None, max_bin_area=1.0, fileprefix='skymap')

Visualize the target density with a skymap. First version lifted shamelessly from desitarget.mock.QA (which was originally written by J. Moustakas).

Parameters:

• cat (array) – An array of targets that contains at least RA and DEC columns for coordinate information.

• objtype (str) – The name of a DESI target class (e.g., "ELG") that corresponds to the passed cat.

• qadir (str, optional, defaults to the current directory) – The output directory to which to write produced plots.

• upclip (float, optional, defaults to None) – A cutoff at which to clip the targets at the “high density” end to make plots conform to similar density scales.

• weights (array, optional, defaults to None) – A weight for each of the passed targets (e.g., to upweight each target in a partial pixel at the edge of the DESI footprint).

• max_bin_area (float, optional, defaults to 1 degree) – The bin size in RA/Dec in targs is chosen to be as close as possible to this value.

• fileprefix (str, optional, defaults to "radec" for (RA/Dec)) – String to be added to the front of the output file name.

Returns:

Dictionary of the 10 densest pixels in the DESI tiling. Includes RA, DEC, DENSITY (per sq. deg.) and NSIDE for each HEALpixel.

Return type:

dict

Notes

In addition to the returned dictionary, a .png sky map is written to qadir. The file is called: {qadir}/{fileprefix}-{objtype}.png.

desitarget.QA.qasystematics_scatterplot(pixmap, syscolname, targcolname, qadir='.', downclip=None, upclip=None, nbins=10, fileprefix='sysdens', xlabel=None)

Make a target density vs. systematic scatter plot.

Parameters:

• pixmap (array) – An array of systematics binned in HEALPixels, made by, e.g. make_imaging_weight_map.

• syscolname (str) – The name of the passed systematic, e.g. STARDENS.

• targcolname (str) – The name of the passed column of target densities, e.g. QSO.

• qadir (str, optional, defaults to the current directory) – The output directory to which to write produced plots.

• downclip (float, optional, defaults to None) – A cutoff at which to clip the systematics at the low end.

• upclip (float, optional, defaults to None) – A cutoff at which to clip the systematics at the high end.

• nbins (int, optional, defaults to 10) – The number of bins to produce in the scatter plot.

• fileprefix (str, optional, defaults to "histo") – String to be added to the front of the output file name.

• xlabel (str, optional, if None defaults to syscolname) – An informative title for the x-axis of the plot.

Returns:

But a .png histogram of target densities is written to qadir. The file is called: {qadir}/{fileprefix}-{syscolname}-{targcolname}.png.

Return type:

Nothing

Notes

The passed pixmap must contain a column FRACAREA which is used to filter out any pixel with less than 90% areal coverage.

desitarget.QA.qasystematics_skyplot(pixmap, colname, qadir='.', downclip=None, upclip=None, fileprefix='systematics', plottitle='')

Visualize systematics with a sky map.

Parameters:

• pixmap (array) – An array of systematics binned in HEALPixels, made by, e.g. make_imaging_weight_map. Assumed to be in the NESTED scheme and ORDERED BY INCREASING HEALPixel.

• colname (str) – The name of the passed systematic, e.g. STARDENS.

• qadir (str, optional, defaults to the current directory) – The output directory to which to write produced plots.

• downclip (float, optional, defaults to None) – A cutoff at which to clip the systematics at the low end.

• upclip (float, optional, defaults to None) – A cutoff at which to clip the systematics at the high end.

• fileprefix (str, optional, defaults to "histo") – String to be added to the front of the output file name.

• plottitle (str, optional, defaults to empty string) – An informative title for the plot.

Returns:

But a .png histogram of target densities is written to qadir. The file is called: {qadir}/{fileprefix}-{colname}.png.

Return type:

Nothing

desitarget.QA.read_data(targfile, mocks=False, downsample=None, header=False)

Read in the data, including any mock data (if present).

Parameters:

• targfile (str) – The full path to a mock target file in the DESI X per cent survey directory structure, e.g., /global/projecta/projectdirs/desi/datachallenge/dc17b/targets/, or to a data file, or to a directory of HEALPixel-split target files which will be read in with desitarget.io.read_targets_in_box().

• mocks (boolean, optional, defaults to False) – If True, read in mock data.

• downsample (int, optional, defaults to None) – If not None, downsample targets by (roughly) this value, e.g. for downsample=10 a set of 900 targets would have ~90 random targets returned. A speed-up for experimenting with large files.

• header (bool, optional, defaults to False) – If True then return the header of the file as an additional output (targs, truths, objtruths, header) instead of (targs, truths, objtruths).

Returns:

• targs (array) – A rec array containing the targets catalog.

• truths (array) – A rec array containing the truths catalog (if present and mocks=True).

• objtruths (dict) – Object type-specific truth metadata (if present and mocks=True).

desitarget.too

Targets of Opportunity.

desitarget.ToO._check_ledger(inledger, survey='main')

Perform checks that the ledger conforms to requirements.

Parameters:

• inledger (Table) – A Table of input Targets of Opportunity from the ToO ledger.

• survey (str, optional, defaults to 'main') – Certain extra checks are only conducted if survey is 'main'.

• None – But a series of checks of the ledger are conducted.

desitarget.ToO._get_too_header()

Convenience function that returns a standard header for ToO files.

desitarget.ToO._write_too_files(filename, data, ecsv=True, survey='main')

Write ToO ledgers and files.

Parameters:

• filename (str) – Full path to filename to which to write Targets of Opportunity.

• data (ndarray or ~astropy.table.Table) – Table or array of Targets of Opportunity to write.

• ecsv (bool, optional, defaults to True) – If True then write as a .ecsv file, if False then write as a .fits file.

• survey (str, optional, defaults to 'main') – If survey is “main”, create a separate file that holds the fiber observations, which resembles the output file but with ToO. replaced by ToO-fiber. in the filename. Also, again if survey is main append new entries to files rather than writing a full, new file. Performs a look up on TARGETID to find existing entries in the ToO. and Too-fiber. files to only append new entries.

Returns:

But data is written to filename with standard ToO formalism.

Return type:

None

desitarget.ToO.all_integers_between_many_limits(ibegin, iend)

Return array of all integers between arrays of start/end limits.

Parameters:

• ibegin (array_like) – Array of beginning integers.

• iend (array_like) – Array of ending integers.

Returns:

1-D, sorted array of all integers in all [ibegin, iend] ranges. Ranges are inclusive, so iend is included for every pair.

Return type:

array_like

desitarget.ToO.finalize_too(inledger, survey='main')

Add necessary targeting columns to a ToO ledger.

Parameters:

• inledger (Table) – A Table of input Targets of Opportunity from the ToO ledger.

• survey (str, optional, defaults to 'main') – Specifies which target masks yaml file to use for bits, and which column names to add in the output file. Options are 'main' and 'svX’ (where X is 1, 2, 3 etc.) for the main survey and different iterations of SV, respectively.

Returns:

A Table of targets generated from the ToO ledger, with the necessary columns added for fiberassign to run.

Return type:

Table

desitarget.ToO.get_filename(toodir=None, ender='ecsv', outname=False)

Construct the input/output ToO filenames (with full directory path).

Parameters:

• toodir (str, optional, defaults to None) – The directory to treat as the Targets of Opportunity I/O directory. If None then look up from the $TOO_DIR environment variable.

• ender (str, optional, defaults to “ecsv”) – File format (in file name), likely either “ecsv” or “fits”.

• outname (bool, optional, defaults to False) – If True return the output ToO filename. Otherwise return the input ToO filename.

Returns:

The directory to treat as the Targets of Opportunity I/O directory.

Return type:

str

desitarget.ToO.get_too_dir(toodir=None)

Convenience function to grab the TOO_DIR environment variable.

Parameters:

toodir (str, optional, defaults to None) – The directory to treat as the Targets of Opportunity I/O directory. If None then look up from the $TOO_DIR environment variable.

Returns:

The directory to treat as the Targets of Opportunity I/O directory.

Return type:

str

desitarget.ToO.ledger_to_targets(toodir=None, survey='main', ecsv=True, outdir=None)

Convert a ToO ledger to a file of ToO targets.

Parameters:

• toodir (str, optional, defaults to None) – The directory to treat as the Targets of Opportunity I/O directory. If None then look up from the $TOO_DIR environment variable.

• survey (str, optional, defaults to 'main') – Specifies which target masks yaml file to use for bits, and which column names to add in the output file. Options are 'main' and 'svX’ (where X is 1, 2, 3 etc.) for the main survey and different iterations of SV, respectively.

• ecsv (bool, optional, defaults to True) – If True then write as a .ecsv file, if False then write as a .fits file.

• outdir (str, optional, defaults to None) – If passed and not None, then read the input ledger from toodir but write the file of targets to outdir.

Returns:

A Table of targets generated from the ToO ledger. The output targets are also written to toodir (or $TOO_DIR) or outdir.

Return type:

Table

Notes

• One purpose of this code is to add all of the necessary columns for fiberassign to run.

• Another purpose is to run some simple checks that the ToO targets do not exceed allowed specifications.

desitarget.ToO.make_initial_ledger(toodir=None)

Set up the initial ToO ledger with one ersatz observation.

Parameters:

toodir (str, optional, defaults to None) – The directory to treat as the Targets of Opportunity I/O directory. If None then look up from the $TOO_DIR environment variable.

Returns:

A Table of the initial, example values for the ToO ledger. The initial (.ecsv) ledger is also written to toodir or $TOO_DIR.

Return type:

Table

desitarget.ToO.max_integers_in_interval(ibegin, iend, narray)

Maximum across [ibegin, iend] ranges totalled over intervals.

Parameters:

• ibegin (array_like) – Array of beginning integers.

• iend (array_like) – Array of ending integers.

• narray (array_like or int or list) – Intervals over which to sum and return the maximum.

Returns:

The maximum number of integers across all of the ranges [ibegin, iend] in each of the intervals in narray.

Return type:

array_like

Notes

• Ranges are inclusive, so iend is included for every pair.

• An example use would be: for a series of ranges of days [0, 365], [180, 456], [90, 565] what is the maximum number of days that occurs in any rolling 365-day period? The answer would clearly be 3, in this case, as, say, day 181, occurs in all three ranges.

desitarget.ToO.rolling_sum(array, n)

Sum each value in an array across itself and the next n-1 values.

Parameters:

• array (array_like) – A 1-D array of integers.

• n (int) – A window over which to sum.

Returns:

Each value in the input summed with the next n-1 values in the array. By definition, the output array will have n-1 fewer indexes than the input array.

Return type:

array_like

Notes

• h/t moving average and rolling sum on stack overflow.

desitarget.brightmask

Module for studying and masking bright sources in the sweeps

desitarget.brightmask._rexlike(rextype)

If the object is REX (a round exponential galaxy)

desitarget.brightmask.generate_safe_locations(sourcemask, Nperradius=1)

Given a mask, generate SAFE (BADSKY) locations at its periphery.

Parameters:

• sourcemask (recarray) – A recarray containing a bright mask as made by, e.g., desitarget.brightmask.make_bright_star_mask()

• Nperradius (int, optional, defaults to 1.) – Number of safe locations to make per arcsec radius of each mask.

Returns:

• ra (array_like.) – The Right Ascensions of the SAFE (BADSKY) locations.

• dec (array_like.) – The Declinations of the SAFE (BADSKY) locations.

Notes

• See Tech Note 2346 for details.

desitarget.brightmask.get_mask_dir()

Convenience function to grab the MASK_DIR environment variable.

Returns:

The directory stored in the $MASK_DIR environment variable.

Return type:

str

desitarget.brightmask.get_recent_mask_dir(input_dir=None)

Grab the most recent sub-directory of masks in MASK_DIR.

Parameters:

input_dir (str, optional, defaults to None) – If passed and not None, then this is returned as the output.

Returns:

If input_dir is not None, then the most recently created sub-directory (with the appropriate format for a mask directory) in $MASK_DIR is returned.

Return type:

str

desitarget.brightmask.get_safe_targets(targs, sourcemask, bricks_are_hpx=False)

Get SAFE (BADSKY) locations for targs, set TARGETID/DESI_TARGET.

Parameters:

• targs (ndarray) – Targets made by, e.g. desitarget.cuts.select_targets().

• sourcemask (ndarray) – A bright source mask as made by, e.g. desitarget.brightmask.make_bright_star_mask().

• bricks_are_hpx (bool, optional, defaults to False) – Instead of using bricks to calculate BRICKIDs, use HEALPixels at the “standard” size from gaiamatch.get_gaia_nside_brick().

Returns:

SAFE (BADSKY) locations for targs with the same data model as for targs.

Return type:

ndarray

Notes

• Tech Note 2346 details SAFE (BADSKY) locations.

• Tech Note 2348 details setting the SKY bit in TARGETID.

• Hard-coded to create 1 safe location per arcsec of mask radius. The correct number (Nperradius) for DESI is an open question.

desitarget.brightmask.is_bright_source(targs, sourcemask)

Determine whether targets are, themselves, a bright source mask.

Parameters:

• targs (recarray) – Targets as made by, e.g., desitarget.cuts.select_targets().

• sourcemask (recarray) – A recarray containing a bright source mask as made by, e.g., desitarget.brightmask.make_bright_star_mask()

Returns:

is_mask – True for targs that are, themselves, a mask.

Return type:

array_like

desitarget.brightmask.is_in_bright_mask(targs, sourcemask, inonly=False)

Determine whether a set of targets is in a bright star mask.

Parameters:

• targs (recarray) – A recarray of targets, skies etc., as made by, e.g., desitarget.cuts.select_targets().

• sourcemask (recarray) – A recarray containing a mask as made by, e.g., desitarget.brightmask.make_bright_star_mask()

• inonly (boolean, optional, defaults to False) – If True, then only calculate the in_mask return but not the near_mask return, which is about a factor of 2 faster.

Returns:

• list – [in_mask, near_mask] where in_mask (near_mask) is a boolean array that is True for targs that are IN (NEAR) a mask. If inonly is True then this is just [in_mask].

• class: list – [used_in_mask, used_near_mask] where used_in_mask (used_near_mask) is a boolean array that is True for masks in sourcemask that contain a target at the IN (NEAR) radius. If inonly is True then this is just [used_in_mask].

desitarget.brightmask.make_bright_star_mask(maglim=12.0, matchrad=1.0, numproc=32, maskepoch=2023.0, gaiaepoch=2015.5, nside=None, pixels=None)

Make an all-sky bright star mask using Tycho, Gaia and URAT.

Parameters:

• maglim (float, optional, defaults to 12.) – Faintest magnitude at which to make the mask. This magnitude is interpreted as G-band for Gaia and, in order of preference, VT then HP then BT for Tycho (not every Tycho source has each band).

• matchrad (int, optional, defaults to 1.) – Tycho sources that match a Gaia source at this separation in ARCSECONDS are NOT included in the output mask. The matching is performed rigorously, accounting for Gaia proper motions.

• numproc (int, optional, defaults to 16.) – Number of processes over which to parallelize

• maskepoch (float) – The mask is built at this epoch. Not all sources have proper motions from every survey, so proper motions are used, in order of preference, from Gaia, URAT, then Tycho.

• gaiaepoch (float, optional, defaults to Gaia DR2 (2015.5)) – The epoch of the Gaia observations. Should be 2015.5 unless we move beyond Gaia DR2.

• nside (int, optional, defaults to None) – If passed, create a mask only in nested HEALPixels in pixels at this nside. Otherwise, run for the whole sky. If nside is passed then pixels must be passed too.

• pixels (list, optional, defaults to None) – If passed, create a mask only in nested HEALPixels at nside for pixel integers in pixels. Otherwise, run for the whole sky. If pixels is passed then nside must be passed too.

Returns:

• The bright star mask in the form of maskdatamodel.dtype:

• REF_CAT is “T2” for Tycho and “G2” for Gaia.

• REF_ID is Tyc1`*1,000,000+`Tyc2`*10+`Tyc3 for Tycho2; “sourceid” for Gaia-DR2 and Gaia-DR2 with URAT.

• REF_MAG is, in order of preference, G-band for Gaia, VT then HP then BT for Tycho.

• URAT_ID contains the URAT reference number for Gaia objects that use the URAT proper motion, or -1 otherwise.

• The radii are in ARCSECONDS.

• E1 and E2 are placeholders for ellipticity components, and are set to 0 for Gaia and Tycho sources.

• TYPE is always PSF for star-like objects.

• Note that the mask is based on objects in the pixel AT THEIR NATIVE EPOCH NOT AT THE INPUT maskepoch. It is therefore possible for locations in the output mask to be just beyond the boundaries of the input pixel.

Return type:

recarray

Notes

• Runs (all-sky) in ~20 minutes for numproc=32 and maglim=12.

• IN_RADIUS (NEAR_RADIUS) corresponds to IN_BRIGHT_OBJECT (NEAR_BRIGHT_OBJECT) in data/targetmask.yaml. These radii are set in the function desitarget.brightmask.radius().

• The correct mask size for DESI is an open question.

• The GAIA_DIR, URAT_DIR and TYCHO_DIR environment variables must be set.

desitarget.brightmask.make_bright_star_mask_in_hp(nside, pixnum, verbose=True, gaiaepoch=2015.5, maglim=12.0, matchrad=1.0, maskepoch=2023.0)

Make a bright star mask in a HEALPixel using Tycho, Gaia and URAT.

Parameters:

• nside (int) – (NESTED) HEALPixel nside.

• pixnum (int) – A single HEALPixel number.

• verbose (bool) – If True then log informational messages.

Returns:

The bright star mask in the form of maskdatamodel.dtype.

Return type:

recarray

Notes

• Runs in a a minute or so for a typical nside=4 pixel.

• See make_bright_star_mask() for descriptions of the output mask and the other input parameters.

desitarget.brightmask.mask_targets(targs, inmaskdir, nside=2, pixlist=None, bricks_are_hpx=False)

Add bits for if objects occupy masks, and SAFE (BADSKY) locations.

Parameters:

• targs (str or ~numpy.ndarray) – An array of targets/skies etc. created by, e.g., desitarget.cuts.select_targets() OR the filename of a file that contains such a set of targets/skies, etc.

• inmaskdir (str, optional) – An input bright star mask file or HEALPixel-split directory as made by desitarget.brightmask.make_bright_star_mask()

• nside (int, optional, defaults to 2) – The nside at which the targets were generated. If the mask is a HEALPixel-split directory, then this helps to perform more efficient masking as only the subset of masks that are in pixels containing targs at this nside will be considered (together with neighboring pixels to account for edge effects).

• pixlist (list or int, optional) – A set of HEALPixels corresponding to the targs. Only the subset of masks in HEALPixels in pixlist at nside will be considered (together with neighboring pixels to account for edge effects). If None, then the pixels touched by targs is derived from from targs itself.

• bricks_are_hpx (bool, optional, defaults to False) – Instead of using bricks to calculate BRICKIDs, use HEALPixels at the “standard” size from gaiamatch.get_gaia_nside_brick().

Returns:

Input targets with the DESI_TARGET column updated to reflect the BRIGHT_OBJECT bits and SAFE (BADSKY) sky locations added around the perimeter of the mask.

Return type:

ndarray

Notes

• Tech Note 2346 details SAFE (BADSKY) locations.

desitarget.brightmask.max_objid_bricks(targs)

For a set of targets, return the maximum value of BRICK_OBJID in each BRICK_ID

Parameters:

targs (recarray) – A recarray of targets as made by desitarget.cuts.select_targets

Returns:

maxobjid – A dictionary with keys for each unique BRICKID and values of the maximum OBJID in that brick

Return type:

dictionary

desitarget.brightmask.plot_mask(mask, limits=None, radius='IN_RADIUS', show=True)

Plot a mask or masks.

Parameters:

• mask (recarray) – A mask, as constructed by, e.g. make_bright_star_mask().

• limits (list, optional) – RA/Dec plot limits in the form [ramin, ramax, decmin, decmax].

• radius – Which mask radius to plot (IN_RADIUS or NEAR_RADIUS).

• show (boolean) – If True, then display the plot, Otherwise, just execute the plot commands so it can be added to or saved to file later.

Return type:

Nothing

desitarget.brightmask.radii(mag)

The relation used to set the radius of bright star masks.

Parameters:

mag (flt or recarray) – Magnitude. Typically, in order of preference, G-band for Gaia or VT then HP then BT for Tycho.

Returns:

• recarray – The IN_RADIUS, corresponding to the IN_BRIGHT_OBJECT bit in data/targetmask.yaml.

• recarray – The NEAR_RADIUS, corresponding to the NEAR_BRIGHT_OBJECT bit in data/targetmask.yaml`.

desitarget.brightmask.set_target_bits(targs, sourcemask, return_masks=False)

Apply bright source mask to targets, return desi_target array.

Parameters:

• targs (recarray) – Targets as made by, e.g., desitarget.cuts.select_targets().

• sourcemask (recarray) – A recarray containing a bright source mask as made by, e.g. desitarget.brightmask.make_bright_star_mask or desitarget.brightmask.make_bright_source_mask.

• return_masks (bool) – If True also return boolean arrays of which of the masks in sourcemask contain a target.

Returns:

• recarray – DESI_TARGET column updates with bright source information bits.

• list, only returned if return_masks is True – [used_in_mask, used_near_mask] where used_in_mask (used_near_mask) is a boolean array that is True for masks in sourcemask that contain a target at the IN (NEAR) radius.

Notes

• Sets IN_BRIGHT_OBJECT and NEAR_BRIGHT_OBJECT via matches to circular and/or elliptical masks.

• Sets BRIGHT_OBJECT via an index match on TARGETID (defined as in desitarget.targets.encode_targetid()).

See desitarget.targetmask for the definition of each bit.

desitarget.cmx

A subpackage with modules to select commissioning (cmx) targets.

desitarget.cmx.cmx_cuts

Target Selection for DESI commissioning (cmx) derived from the cmx wiki.

A collection of helpful (static) methods to check whether an object’s flux passes a given selection criterion (e.g. STD_TEST).

desitarget.cmx.cmx_cuts._get_cmxdir(cmxdir=None)

Retrieve the base cmx directory with appropriate error checking.

cmxdirstr, optional, defaults to CMX_DIR

Directory in which to find commmissioning files to which to match, such as the CALSPEC stars. If not specified, the cmx directory is taken to be the value of the CMX_DIR environment variable.

desitarget.cmx.cmx_cuts.apply_cuts(objects, cmxdir=None, noqso=False)

Commissioning (cmx) target selection, return target mask arrays.

Parameters:

• objects (ndarray) – numpy structured array with UPPERCASE columns needed for target selection, OR a string tractor/sweep filename

• cmxdir (str, optional, defaults to CMX_DIR) – Directory to find commmissioning files to which to match, such as the CALSPEC stars. If not specified, the cmx directory is taken to be the value of 2:envvar:CMX_DIR.

• noqso (boolean, optional, defaults to False) – If passed, do not run the quasar selection. All QSO bits will be set to zero. Intended use is to speed unit tests.

Returns:

• ndarray – commissioning target selection bitmask flags for each object.

• array_like – a priority shift of 10*(25-rmag) based on r-band magnitude. (for STD_DITHER, STD_GAIA sources).

• See desitarget.cmx.cmx_targetmask.cmx_mask for bit definitions.

desitarget.cmx.cmx_cuts.apply_cuts_gaia(numproc=4, cmxdir=None, nside=None, pixlist=None, test=False)

Gaia-only-based CMX target selection, return target mask arrays.

Parameters:

• numproc (int, optional, defaults to 4) – The number of parallel processes to use.

• cmxdir (str, optional, defaults to CMX_DIR) – Directory to find commmissioning files to match, such as for the CALSPEC stars. If not specified, taken to be the value of the CMX_DIR environment variable.

• nside (int, optional, defaults to None) – (NESTED) HEALPix nside used with pixlist and bundlefiles.

• pixlist (list or int, optional, defaults to None) – Only return targets in a set of (NESTED) HEALpixels at nside. Useful for parallelizing, as input files will only be processed if they touch a pixel in the passed list.

• test (bool, optional, defaults to False) – If True, then we’re running unit tests and don’t have to find and read every possible Gaia file.

Returns:

• ndarray – Commissioning target selection bitmask flags for each object.

• ndarray – numpy structured array of Gaia sources that were read in from file for the passed pixel constraints (or no pixel constraints).

• array_like – a priority shift of 10*(25-rmag) based on GAIA_PHOT_RP_MEAN_MAG. (for STD_DITHER_GAIA sources).

Notes

• May take a long time if no pixel constraints are passed.

• Only run on Gaia-only target selections.

• The environment variable $GAIA_DIR must be set.

See desitarget.cmx.cmx_targetmask.cmx_mask for bit definitions.

desitarget.cmx.cmx_cuts.isBACKUP(ra=None, dec=None, gaiagmag=None, primary=None)

BACKUP targets based on Gaia magnitudes.

Parameters:

• ra (array_like or None) – Right Ascension and Declination in degrees.

• dec (array_like or None) – Right Ascension and Declination in degrees.

• gaiagmag (array_like or None) – Gaia-based g MAGNITUDE (not Galactic-extinction-corrected). (same units as the Gaia data model).

• primary (array_like or None) – True for objects that should be passed through the selection.

Returns:

• array_like – True if and only if the object is a bright “BACKUP” target.

• array_like – True if and only if the object is a faint “BACKUP” target.

desitarget.cmx.cmx_cuts.isBGS(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, rfiberflux=None, gnobs=None, rnobs=None, znobs=None, gfracmasked=None, rfracmasked=None, zfracmasked=None, gfracflux=None, rfracflux=None, zfracflux=None, gfracin=None, rfracin=None, zfracin=None, gfluxivar=None, rfluxivar=None, zfluxivar=None, maskbits=None, Grr=None, w1snr=None, gaiagmag=None, objtype=None, primary=None, south=True, targtype=None)

Definition of BGS target classes for SV. Returns a boolean array.

Parameters:

• south (boolean, defaults to True) – Use cuts appropriate to the Northern imaging surveys (BASS/MzLS) if south=False, otherwise use cuts appropriate to the Southern imaging survey (DECaLS).

• targtype (str, optional, defaults to faint) – Pass bright for the BGS_BRIGHT selection or faint for the BGS_FAINT selection or faint_ext for the BGS_FAINT_EXTENDED selection or lowq for the BGS_LOW_QUALITY selection or fibmag for the BGS_FIBER_MAGNITUDE selection.

Returns:

True if and only if the object is a BGS target of type targtype.

Return type:

array_like

Notes

• Current version (10/14/19) is version 105 on the SV wiki.

• See set_target_bits() for other parameters.

desitarget.cmx.cmx_cuts.isBGS_colors(rflux=None, rfiberflux=None, south=True, targtype=None, primary=None)

Standard set of masking cuts used by all BGS target selection classes (see, e.g., isBGS() for parameters).

desitarget.cmx.cmx_cuts.isELG_colors(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, gfiberflux=None, primary=None, south=True)

Color cuts for ELG target selection classes (see, e.g., desitarget.cuts.set_target_bits() for parameters).

desitarget.cmx.cmx_cuts.isFIRSTLIGHT(gaiadtype, cmxdir=None, nside=None, pixlist=None)

First light/Mini-SV targets via reading files from Arjun Dey.

Parameters:

• gaiadtype (dtype) – Data type (dtype) for Gaia-only CMX targets.

• cmxdir (str, optional, defaults to CMX_DIR) – Directory to find commmissioning files. If not specified, taken from the CMX_DIR environment variable.

• nside (int, optional, defaults to None) – (NESTED) HEALPix nside used with pixlist and bundlefiles.

• pixlist (list or int, optional, defaults to None) – Only return targets in a set of (NESTED) HEALpixels at nside. Useful for parallelizing, as input files will only be processed if they touch a pixel in the passed list.

Returns:

• array_like – bit values for each of the first light targets.

• array_like – Array of the first light targets munged into Gaia-only format.

desitarget.cmx.cmx_cuts.isLRG_colors(gflux=None, rflux=None, zflux=None, w1flux=None, zfiberflux=None, south=True, primary=None)

See isLRG() for details.

desitarget.cmx.cmx_cuts.isQSO_color_high_z(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, south=True)

Color cut to select Highz QSO (z>~2.)

desitarget.cmx.cmx_cuts.isQSO_colors(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, primary=None, south=True)

Test if sources have quasar-like colors in a color box. (see, e.g., isQSO_cuts()).

desitarget.cmx.cmx_cuts.isQSO_cuts(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, w1snr=None, w2snr=None, dchisq=None, maskbits=None, objtype=None, gnobs=None, rnobs=None, znobs=None, primary=None, south=True)

Definition of QSO target classes from color cuts. Returns a boolean array.

Parameters:

south (boolean, defaults to True) – Use cuts appropriate to the Northern imaging surveys (BASS/MzLS) if south=False, otherwise use cuts appropriate to the Southern imaging survey (DECaLS).

Returns:

True for objects that pass the quasar color/morphology/logic cuts.

Return type:

array_like

Notes

• See set_target_bits() for other parameters.

desitarget.cmx.cmx_cuts.isQSO_highz_faint(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, objtype=None, release=None, dchisq=None, gnobs=None, rnobs=None, znobs=None, maskbits=None, primary=None, south=True)

Definition of QSO target for highz (z>2.0) faint QSOs. Returns a boolean array.

Parameters:

south (boolean, defaults to True) – Use cuts appropriate to the Northern imaging surveys (BASS/MzLS) if south=False, otherwise use cuts appropriate to the Southern imaging survey (DECaLS).

Returns:

True for objects that pass the quasar color/morphology/logic cuts.

Return type:

array_like

Notes

• See set_target_bits() for other parameters.

desitarget.cmx.cmx_cuts.isQSO_randomforest(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, objtype=None, release=None, dchisq=None, maskbits=None, gnobs=None, rnobs=None, znobs=None, primary=None, south=True)

Definition of QSO target class using random forest. Returns a boolean array.

Parameters:

south (boolean, defaults to True) – Use cuts appropriate to the Northern imaging surveys (BASS/MzLS) if south=False, otherwise use cuts appropriate to the Southern imaging survey (DECaLS).

Returns:

True for objects that pass the quasar color/morphology/logic cuts.

Return type:

array_like

Notes

• See set_target_bits() for other parameters.

desitarget.cmx.cmx_cuts.isQSOz5_colors(gflux=None, rflux=None, zflux=None, gsnr=None, rsnr=None, zsnr=None, w1flux=None, w2flux=None, primary=None, south=True)

Color cut to select z~5 quasar targets. (See isQSOz5_cuts()).

desitarget.cmx.cmx_cuts.isQSOz5_cuts(gflux=None, rflux=None, zflux=None, gsnr=None, rsnr=None, zsnr=None, gnobs=None, rnobs=None, znobs=None, w1flux=None, w2flux=None, w1snr=None, w2snr=None, dchisq=None, maskbits=None, objtype=None, primary=None, south=True)

Definition of z~5 QSO target classes from color cuts. Returns a boolean array.

Parameters:

south (boolean, defaults to True) – Use cuts appropriate to the Northern imaging surveys (BASS/MzLS) if south=False, otherwise use cuts appropriate to the Southern imaging survey (DECaLS).

Returns:

True for objects that pass the quasar color/morphology/logic cuts.

Return type:

array_like

Notes

• See set_target_bits() for other parameters.

desitarget.cmx.cmx_cuts.isSTD_calspec(ra=None, dec=None, cmxdir=None, matchrad=1.0, primary=None)

Match to CALSPEC stars for commissioning tests.

Parameters:

• ra (array_like or None) – Right Ascension and Declination in degrees.

• dec (array_like or None) – Right Ascension and Declination in degrees.

• cmxdir (str, optional, defaults to CMX_DIR) – Directory to find commmissioning files to match, such as for the CALSPEC stars. If not specified, taken to be the value of the CMX_DIR environment variable.

• matchrad (float, optional, defaults to 1 arcsec) – The matching radius in arcseconds.

• primary (array_like or None) – True for objects that should be passed through the selection.

Returns:

True if and only if the object is a “CALSPEC” target.

Return type:

array_like

desitarget.cmx.cmx_cuts.isSTD_colors(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, primary=None)

Select STD stars based on Legacy Surveys color cuts. Returns a boolean array. see isSTD() for other details.

desitarget.cmx.cmx_cuts.isSTD_dither(obs_gflux=None, obs_rflux=None, obs_zflux=None, isgood=None, primary=None)

Gaia stars for dithering-and-other tests during commissioning.

Parameters:

• obs_gflux (array_like or None) – The flux in nano-maggies of g, r, z bands WITHOUT any Galactic extinction correction.

• obs_rflux (array_like or None) – The flux in nano-maggies of g, r, z bands WITHOUT any Galactic extinction correction.

• obs_zflux (array_like or None) – The flux in nano-maggies of g, r, z bands WITHOUT any Galactic extinction correction.

• isgood (array_like or None) – True for objects that pass the logic cuts in passesSTD_logic().

• primary (array_like or None) – True for objects that should be passed through the selection.

Returns:

• array_like – True if and only if the object is a Gaia “STD_GAIA” target.

• array_like – A priority shift of 10*(25-rmag) based on r-band magnitude.

Notes

• This version (08/30/18) is version 4 on the cmx wiki.

desitarget.cmx.cmx_cuts.isSTD_dither_gaia(ra=None, dec=None, gmag=None, rmag=None, aen=None, paramssolved=None, dupsource=None, pmra=None, pmdec=None, nside=2, primary=None, test=False)

Gaia stars for dithering tests outside of the Legacy Surveys area.

Parameters:

• ra (array_like or None) – Right Ascension and Declination in degrees.

• dec (array_like or None) – Right Ascension and Declination in degrees.

• gmag (array_like or None) – GAIA_PHOT_G_MEAN_MAG, GAIA_PHOT_R_MEAN_MAG.

• rmag (array_like or None) – GAIA_PHOT_G_MEAN_MAG, GAIA_PHOT_R_MEAN_MAG.

• aen (array_like or None) – Gaia Astrometric Excess Noise.

• paramssolved (array_like or None) – How many parameters were solved for in Gaia.

• dupsource (array_like or None) – Whether the source is a duplicate in Gaia.

• pmra (array_like or None) – Gaia-based proper motion in RA and Dec.

• pmdec (array_like or None) – Gaia-based proper motion in RA and Dec.

• nside (int, optional, defaults to 2) – (NESTED) HEALPix nside, if targets are being parallelized. The default of 2 should be benign for serial processing.

• primary (array_like or None) – True for objects that should be passed through the selection.

• test (bool, optional, defaults to False) – If True, then we’re running unit tests and don’t have to find and read every possible Gaia file.

Returns:

• array_like – True if the object is a Gaia “STD_DITHER_GAIA” target.

• array_like – A priority shift of 10*(25-rmag) based on rmag.

Notes

• This version (11/17/20) is version 70 on the cmx wiki.

desitarget.cmx.cmx_cuts.isSTD_dither_spec(gaiagmag=None, gaiarmag=None, obs_rflux=None, isgood=None, primary=None)

Gaia stars for dithering-only tests during commissioning.

Parameters:

• gaiagmag (array_like or None) – The Gaia G-band and R-band mean magnitudes.

• gaiarmag (array_like or None) – The Gaia G-band and R-band mean magnitudes.

• obs_rflux (array_like or None) – The flux in nano-maggies in Legacy Surveys r-band WITHOUT any Galactic extinction correction. Used for prioritizing.

• isgood (array_like or None) – True for objects that pass the logic cuts in passesSTD_logic().

• primary (array_like or None) – True for objects that should be passed through the selection.

Returns:

• array_like – True if and only if the object is a Gaia “STD_DITHER” target.

• array_like – A priority shift of 10*(25-rmag) based on r-band magnitude.

Notes

• This version (11/02/19) is version 48 on the cmx wiki.

desitarget.cmx.cmx_cuts.isSTD_gaia(primary=None, gaia=None, astrometricexcessnoise=None, pmra=None, pmdec=None, parallax=None, dupsource=None, paramssolved=None, gaiagmag=None, gaiabmag=None, gaiarmag=None)

Gaia quality cuts used to define STD star targets see isSTD() for other details.

desitarget.cmx.cmx_cuts.isSTD_test(obs_gflux=None, obs_rflux=None, obs_zflux=None, isgood=None, primary=None)

Very bright Gaia stars for early commissioning tests.

Parameters:

• obs_gflux (array_like or None) – The flux in nano-maggies of g, r, z bands WITHOUT any Galactic extinction correction.

• obs_rflux (array_like or None) – The flux in nano-maggies of g, r, z bands WITHOUT any Galactic extinction correction.

• obs_zflux (array_like or None) – The flux in nano-maggies of g, r, z bands WITHOUT any Galactic extinction correction.

• isgood (array_like or None) – True for objects that pass the logic cuts in passesSTD_logic().

• primary (array_like or None) – True for objects that should be passed through the selection.

Returns:

True if and only if the object is a Gaia “test” target.

Return type:

array_like

Notes

• This version (08/30/18) is version 4 on the cmx wiki.

• See also the Gaia data model.

desitarget.cmx.cmx_cuts.isSV0_BGS(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, rfiberflux=None, gnobs=None, rnobs=None, znobs=None, gfracmasked=None, rfracmasked=None, zfracmasked=None, gfracflux=None, rfracflux=None, zfracflux=None, gfracin=None, rfracin=None, zfracin=None, gfluxivar=None, rfluxivar=None, zfluxivar=None, maskbits=None, Grr=None, w1snr=None, gaiagmag=None, objtype=None, primary=None)

Definition of an SV0-like BGS target. Returns a boolean array.

:param See set_target_bits().:

Returns:

True if and only if the object is an SV-like BGS target.

Return type:

array_like

Notes

• Current version (02/19/20) is version 55 on the cmx wiki.

• Hardcoded for south=False.

• Combines bright/faint/faint_ext/fibmag BGS-like SV classes into one bit.

• desitarget.cmx.cmx_cuts.apply_cuts() also additionally removes objects from this class that either have Gaia provenance and Gaia G < 16 OR that have Legacy Surveys g < 16.

desitarget.cmx.cmx_cuts.isSV0_ELG(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, gsnr=None, rsnr=None, zsnr=None, gfiberflux=None, gnobs=None, rnobs=None, znobs=None, maskbits=None, primary=None)

Definition of an SV0-like ELG target. Returns a boolean array.

:param See set_target_bits().:

Returns:

True if and only if the object is an SV-like ELG target.

Return type:

array_like

Notes

• Current version (10/14/19) is version 107 on the SV wiki.

• Hardcoded for south=False.

• Combines all ELG-like SV classes into one bit.

desitarget.cmx.cmx_cuts.isSV0_LRG(gflux=None, rflux=None, zflux=None, w1flux=None, rfiberflux=None, zfiberflux=None, gflux_snr=None, rflux_snr=None, zflux_snr=None, w1flux_snr=None, gnobs=None, rnobs=None, znobs=None, maskbits=None, primary=None)

Target Definition of an SV0-like LRG. Returns a boolean array.

:param See set_target_bits().:

Returns:

True if and only if the object is an LRG color-selected target. If floats are passed, a float is returned.

Return type:

array_like or float

Notes

• Current version (02/19/20) is version 50 on the cmx wiki.

• Hardcoded for south=False.

• Combines all LRG-like SV classes into one bit.

desitarget.cmx.cmx_cuts.isSV0_MWS(rflux=None, obs_rflux=None, objtype=None, paramssolved=None, gaiagmag=None, gaiabmag=None, gaiarmag=None, parallaxerr=None, pmra=None, pmdec=None, parallax=None, parallaxovererror=None, photbprpexcessfactor=None, astrometricsigma5dmax=None, gaiaaen=None, galb=None, gaia=None, primary=None)

Initial SV-like Milky Way Survey selections (MzLS/BASS imaging).

:param - See set_target_bits() for parameters.:

Returns:

• array_like – True if and only if the object is a MWS_MAIN or MWS_NEARBY target from early SV/main survey classes.

• array_like – True if and only if the object is an early-SV/main survey MWS_WD target.

• array_like – True if and only if the object is an early-SV/main survey SV0_MWS_FAINT target.

Notes

• All Gaia quantities are as in the Gaia data model.

• Returns the equivalent of PRIMARY target classes from version 55 (02/19/20) of the cmx wiki. Ignores target classes that “smell” like secondary targets (as they are outside of the footprint or are based on catalog-matching). Simplifies flag cuts, and simplifies the MWS_MAIN class to not include sub-classes.

• desitarget.cmx.cmx_cuts.apply_cuts() also additionally removes objects from this class that either have Gaia provenance and Gaia G < 16 OR that have Legacy Surveys g < 16.

desitarget.cmx.cmx_cuts.isSV0_QSO(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, gsnr=None, rsnr=None, zsnr=None, w1snr=None, w2snr=None, gnobs=None, rnobs=None, znobs=None, maskbits=None, dchisq=None, objtype=None, primary=None)

Target Definition of an SV0-like QSO. Returns a boolean array.

:param See set_target_bits().:

Returns:

• array_like or float –

  True if and only if the object is an SV-like QSO target.

  If floats are passed, a float is returned.

• array_like or float – True if and only if the object is an SV-like QSO target that passes something like the QSO_Z5 (high-z) selection from SV.

Notes

• Current version (02/19/20) is version 51 on the cmx wiki.

• Current version (03/10/20) for the high-z (QSO_Z5 selection) is version 59 on the cmx wiki.

• Hardcoded for south=False.

• Combines all QSO-like SV classes into one bit.

desitarget.cmx.cmx_cuts.isSV0_STD(gflux=None, rflux=None, zflux=None, primary=None, gfracflux=None, rfracflux=None, zfracflux=None, gfracmasked=None, rfracmasked=None, zfracmasked=None, gnobs=None, rnobs=None, znobs=None, gfluxivar=None, rfluxivar=None, zfluxivar=None, objtype=None, gaia=None, astrometricexcessnoise=None, paramssolved=None, pmra=None, pmdec=None, parallax=None, dupsource=None, gaiagmag=None, gaiabmag=None, gaiarmag=None, bright=False)

Select STD targets using color cuts and photometric quality cuts.

Parameters:

bright (boolean, defaults to False) – if True apply magnitude cuts for “bright” conditions; otherwise, choose “normal” brightness standards. Cut is performed on gaiagmag.

Returns:

True if and only if the object is a STD star.

Return type:

array_like

Notes

• This version (11/05/18) is version 24 on the SV wiki.

• See set_target_bits() for other parameters.

desitarget.cmx.cmx_cuts.notinBGS_mask(gflux=None, rflux=None, zflux=None, gnobs=None, rnobs=None, znobs=None, primary=None, gfracmasked=None, rfracmasked=None, zfracmasked=None, gfracflux=None, rfracflux=None, zfracflux=None, gfracin=None, rfracin=None, zfracin=None, w1snr=None, gfluxivar=None, rfluxivar=None, zfluxivar=None, Grr=None, gaiagmag=None, maskbits=None, objtype=None, targtype=None)

Standard set of masking cuts used by all BGS target selection classes (see, e.g., isBGS_faint() for parameters).

desitarget.cmx.cmx_cuts.notinELG_mask(maskbits=None, gsnr=None, rsnr=None, zsnr=None, gnobs=None, rnobs=None, znobs=None, primary=None)

Standard set of masking cuts used by all ELG target selection classes. (see set_target_bits() for parameters).

desitarget.cmx.cmx_cuts.notinLRG_mask(primary=None, rflux=None, zflux=None, w1flux=None, zfiberflux=None, gnobs=None, rnobs=None, znobs=None, rflux_snr=None, zflux_snr=None, w1flux_snr=None, maskbits=None)

See isLRG() for details.

Returns:

True if and only if the object is NOT masked for poor quality.

Return type:

array_like

desitarget.cmx.cmx_cuts.passesSTD_logic(gfracflux=None, rfracflux=None, zfracflux=None, objtype=None, gaia=None, pmra=None, pmdec=None, aen=None, dupsource=None, paramssolved=None, primary=None)

The default logic/mask cuts for commissioning stars.

Parameters:

• gfracflux (array_like or None) – Profile-weighted fraction of the flux from other sources divided by the total flux in g, r and z bands.

• rfracflux (array_like or None) – Profile-weighted fraction of the flux from other sources divided by the total flux in g, r and z bands.

• zfracflux (array_like or None) – Profile-weighted fraction of the flux from other sources divided by the total flux in g, r and z bands.

• objtype (array_like or None) – The Legacy Surveys TYPE to restrict to point sources.

• gaia (boolean array_like or None) – True if there is a match between this object in the Legacy Surveys and in Gaia.

• pmra (array_like or None) – Gaia-based proper motion in RA and Dec.

• pmdec (array_like or None) – Gaia-based proper motion in RA and Dec.

• aen (array_like or None) – Gaia Astrometric Excess Noise.

• dupsource (array_like or None) – Whether the source is a duplicate in Gaia.

• paramssolved (array_like or None) – How many parameters were solved for in Gaia.

• primary (array_like or None) – True for objects that should be passed through the selection.

Returns:

• array_like –

  True if and only if the object passes the logic cuts for

  cmx stars with fracflux_X < 0.01.

• array_like –

  True if and only if the object passes the logic cuts for

  cmx stars with fracflux_X < 0.002.

Notes

• This version (08/30/18) is version 4 on the cmx wiki.

• All Gaia quantities are as in the Gaia data model.

desitarget.cmx.cmx_cuts.select_targets(infiles, numproc=4, cmxdir=None, noqso=False, nside=None, pixlist=None, bundlefiles=None, extra=None, resolvetargs=True, backup=True, test=False)

Process input files in parallel to select commissioning (cmx) targets

Parameters:

• infiles (list or str) – List of input filenames (tractor/sweep files) OR one filename.

• numproc (int, optional, defaults to 4) – The number of parallel processes to use.

• cmxdir (str, optional, defaults to CMX_DIR) – Directory to find commmissioning files to which to match, such as the CALSPEC stars. If not specified, the cmx directory is taken to be the value of CMX_DIR.

• noqso (boolean, optional, defaults to False) – If passed, do not run the quasar selection. All QSO bits will be set to zero. Intended use is to speed unit tests.

• nside (int, optional, defaults to None) – (NESTED) HEALPix nside used with pixlist and bundlefiles.

• pixlist (list or int, optional, defaults to None) – Only return targets in a set of (NESTED) HEALpixels at nside. Useful for parallelizing, as input files will only be processed if they touch a pixel in the passed list.

• bundlefiles (int, defaults to None) – If not None, then, instead of selecting gfas, print the slurm script to run in pixels at nside. Is an integer rather than a boolean for historical reasons.

• extra (str, optional) – Extra command line flags to be passed to the executable lines in the output slurm script. Used in conjunction with bundlefiles.

• resolvetargs (boolean, optional, defaults to True) – If True, resolve overlapping north/south Legacy Surveys targets into a set of unique sources based on location.

• backup (boolean, optional, defaults to True) – If True, also run the Gaia-only BACKUP_BRIGHT/FAINT targets.

• test (bool, optional, defaults to False) – If True, then we’re running unit tests and don’t have to find and read every possible Gaia file.

Returns:

The subset of input targets which pass the cmx cuts, including an extra column for CMX_TARGET.

Return type:

ndarray

Notes

• if numproc==1, use serial code instead of parallel.

desitarget.cmx.cmx_targetmask

This looks more like a script than an actual module.

desitarget.cuts

An old copy of the Main Survey cuts (../cuts.py) that were used for commissioning (cmx).

desitarget.cmx.ms_cuts._check_BGS_targtype(targtype)

Fail if targtype is not one of the strings ‘bright’, ‘faint’ or ‘wise’.

desitarget.cmx.ms_cuts._psflike(psftype)

If the object is PSF

desitarget.cmx.ms_cuts.isBGS(rfiberflux=None, gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, gnobs=None, rnobs=None, znobs=None, gfracmasked=None, rfracmasked=None, zfracmasked=None, gfracflux=None, rfracflux=None, zfracflux=None, gfracin=None, rfracin=None, zfracin=None, gfluxivar=None, rfluxivar=None, zfluxivar=None, maskbits=None, Grr=None, refcat=None, w1snr=None, gaiagmag=None, objtype=None, primary=None, south=True, targtype=None)

Definition of BGS target classes. Returns a boolean array.

Parameters:

targtype (str, optional, defaults to faint) – Pass bright to use colors appropriate to the BGS_BRIGHT selection or faint to use colors appropriate to the BGS_FAINT selection or wise to use colors appropriate to the BGS_WISE selection.

Returns:

True if and only if the object is a BGS target of type targtype.

Return type:

array_like

Notes

• Current version (10/24/18) is version 143 on the wiki.

• See set_target_bits() for other parameters.

desitarget.cmx.ms_cuts.isBGS_colors(rfiberflux=None, gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, south=True, targtype=None, primary=None)

Standard set of color-based cuts used by all BGS target selection classes (see, e.g., isBGS() for parameters).

desitarget.cmx.ms_cuts.isBGS_lslga(gflux=None, rflux=None, zflux=None, w1flux=None, refcat=None, maskbits=None, south=True, targtype=None)

Module to recover the LSLGA objects in all BGS target selection classes (see, e.g., isBGS() for parameters).

desitarget.cmx.ms_cuts.isELG(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, gsnr=None, rsnr=None, zsnr=None, gnobs=None, rnobs=None, znobs=None, maskbits=None, south=True, primary=None)

Definition of ELG target classes. Returns a boolean array. (see set_target_bits() for parameters).

Notes: - Current version (12/09/20) is version 233 on the wiki.

desitarget.cmx.ms_cuts.isELG_colors(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, south=True, primary=None)

Color cuts for ELG target selection classes (see, e.g., set_target_bits() for parameters).

desitarget.cmx.ms_cuts.isLRG(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, zfiberflux=None, rfluxivar=None, zfluxivar=None, w1fluxivar=None, gnobs=None, rnobs=None, znobs=None, maskbits=None, primary=None, south=True)

Parameters:

south (boolean, defaults to True) – Use cuts appropriate to the Northern imaging surveys (BASS/MzLS) if south=False, otherwise use cuts appropriate to the Southern imaging survey (DECaLS).

Returns:

True if and only if the object is an LRG target.

Return type:

array_like

Notes

• Current version (12/07/2020) is version 232 on the wiki.

• See set_target_bits() for other parameters.

desitarget.cmx.ms_cuts.isLRG_colors(gflux=None, rflux=None, zflux=None, w1flux=None, zfiberflux=None, ggood=None, w2flux=None, primary=None, south=True)

(see, e.g., isLRG()).

Notes

• the ggood and w2flux inputs are an attempt to maintain backwards-compatibility with the mocks.

desitarget.cmx.ms_cuts.isQSO_randomforest(gflux=None, rflux=None, zflux=None, maskbits=None, w1flux=None, w2flux=None, objtype=None, release=None, gnobs=None, rnobs=None, znobs=None, deltaChi2=None, primary=None, ra=None, dec=None, south=True, return_probs=False)

Define QSO targets from a Random Forest. Returns a boolean array.

Parameters:

• south (boolean, defaults to True) – If False, shift photometry to the Northern (BASS/MzLS) imaging system.

• return_probs (boolean, defaults to False) – If True, return the QSO/high-z QSO probabilities in addition to the QSO target booleans. Only coded up for DR8 or later of the Legacy Surveys. Will return arrays of zeros for earlier DRs.

Returns:

• array_like – True for objects that are Random Forest quasar targets.

• array_like – True for objects that are high-z RF quasar targets.

• array_like – The (float) probability that a target is a quasar. Only returned if return_probs is True.

• array_like – The (float) probability that a target is a high-z quasar. Only returned if return_probs is True.

Notes

• Current version (20/11/20) is version 173 on the wiki.

• See set_target_bits() for other parameters.

desitarget.cmx.ms_cuts.notinBGS_mask(gnobs=None, rnobs=None, znobs=None, primary=None, gfracmasked=None, rfracmasked=None, zfracmasked=None, gfracflux=None, rfracflux=None, zfracflux=None, gfracin=None, rfracin=None, zfracin=None, w1snr=None, gfluxivar=None, rfluxivar=None, zfluxivar=None, Grr=None, gaiagmag=None, maskbits=None, targtype=None)

Standard set of masking cuts used by all BGS target selection classes (see, e.g., isBGS() for parameters).

desitarget.cmx.ms_cuts.notinELG_mask(maskbits=None, gsnr=None, rsnr=None, zsnr=None, gnobs=None, rnobs=None, znobs=None, primary=None)

Standard set of masking cuts used by all ELG target selection classes. (see set_target_bits() for parameters).

desitarget.cmx.ms_cuts.notinLRG_mask(primary=None, rflux=None, zflux=None, w1flux=None, zfiberflux=None, gnobs=None, rnobs=None, znobs=None, rfluxivar=None, zfluxivar=None, w1fluxivar=None, maskbits=None)

See isLRG() for details.

Returns:

True if and only if the object is NOT masked for poor quality.

Return type:

array_like

desitarget.cmx.ms_cuts.shift_photo_north(gflux=None, rflux=None, zflux=None)

Convert fluxes in the northern (BASS/MzLS) to the southern (DECaLS) system.

Parameters:

• gflux (array_like or float) – The flux in nano-maggies of g, r, z bands.

• rflux (array_like or float) – The flux in nano-maggies of g, r, z bands.

• zflux (array_like or float) – The flux in nano-maggies of g, r, z bands.

Return type:

The equivalent fluxes shifted to the southern system.

Notes

• see also https://desi.lbl.gov/DocDB/cgi-bin/private/RetrieveFile?docid=3390;filename=Raichoor_DESI_05Dec2017.pdf;version=1

• Update for DR9 https://desi.lbl.gov/trac/attachment/wiki/TargetSelectionWG/TargetSelection/North_vs_South_dr9.png

desitarget.cuts

Target Selection for Legacy Surveys catalogue data derived from the wiki.

A collection of helpful (static) methods to check whether an object’s flux passes a given selection criterion (e.g. LRG, ELG or QSO).

desitarget.cuts.MWS_too_bright(gaiagmag=None, zfibertotflux=None)

Whether a target is too bright to include for MWS observations.

Parameters:

• gaiagmag (ndarray) – Gaia-based g-band MAGNITUDE.

• zfibertotflux (ndarray) – Predicted fiber flux from ALL sources at object’s location in 1 arcsecond seeing in z. NOT corrected for Galactic extinction.

Returns:

True if and only if the object is FAINTER than the MWS bright-cut limits.

Return type:

array_like

Notes

• Current version (04/02/21) is version 17 on the SV3 wiki.

desitarget.cuts._check_BGS_targtype(targtype)

Fail if targtype is not one ‘bright’, ‘faint’ or ‘wise’.

desitarget.cuts._check_BGS_targtype_sv(targtype)

check targtype (‘bright’, ‘faint’, ‘faint_ext’, ‘lowq’, ‘fibmag’).

desitarget.cuts._gal_coords(ra, dec)

Shift RA, Dec to Galactic coordinates.

Parameters:

• ra (array_like or float) – RA, Dec coordinates (degrees)

• dec (array_like or float) – RA, Dec coordinates (degrees)

Return type:

The Galactic longitude and latitude (l, b)

desitarget.cuts._get_colnames(objects)

Simple wrapper to get the column names.

desitarget.cuts._is_row(table)

Return True/False if this is a table row instead of a full table.

supports numpy.ndarray, astropy.io.fits.FITS_rec, astropy.table.Table

desitarget.cuts._isonnorthphotsys(photsys)

If the object is from the northen photometric system

desitarget.cuts._prepare_gaia(objects, colnames=None)

Process the various Gaia inputs for target selection.

desitarget.cuts._prepare_optical_wise(objects, mask=True)

Process the Legacy Surveys inputs for target selection.

Parameters:

mask (boolean, optional, defaults to True) – Send False to turn off any masking cuts based on the MASKBITS column. The default behavior is to always mask using MASKBITS.

desitarget.cuts._psflike(psftype)

If the object is PSF

desitarget.cuts.apply_cuts(objects, qso_selection='randomforest', tcnames=['ELG', 'QSO', 'LRG', 'MWS', 'BGS', 'STD', 'LGE'], qso_optical_cuts=False, survey='main', resolvetargs=True, mask=True)

Perform target selection on objects, returning target mask arrays.

Parameters:

• objects (ndarray or str) – numpy structured array with UPPERCASE columns needed for target selection, OR a string tractor/sweep filename.

• qso_selection (str, optional, default is 'randomforest') – The algorithm to use for QSO selection; valid options are 'colorcuts' and 'randomforest'

• tcnames (list, defaults to running all target classes) – A list of strings, e.g. [‘QSO’,’LRG’]. If passed, process targets only for those specific classes. A useful speed-up when testing. Options are [“ELG”, “QSO”, “LRG”, “MWS”, “BGS”, “STD”, “LGE”].

• qso_optical_cuts (boolean defaults to False) – Apply just optical color-cuts when selecting QSOs with qso_selection="colorcuts".

• survey (str, defaults to 'main') – Which target masks yaml file and target selection cuts to use. Options are 'main' and 'svX’ (where X is 1, 2, 3 etc.) for the main survey and different iterations of SV, respectively.

• resolvetargs (boolean, optional, defaults to True) – If True, if objects consists of all northern (southern) sources then only apply the northern (southern) cuts.

• mask (boolean, optional, defaults to True) – Send False to turn off any masking cuts based on the MASKBITS column. Default is to always mask using MASKBITS.

Returns:

(desi_target, bgs_target, mws_target) where each element is an ndarray of target selection bitmask flags for each object.

Return type:

ndarray

Notes

• If objects is an astropy Table with lowercase column names, they will be converted to UPPERCASE in-place, thus modifying the input table. To avoid this, pass in objects.copy() instead.

• See desitarget.targetmask for the definition of each bit.

desitarget.cuts.apply_cuts_gaia(numproc=4, survey='main', nside=None, pixlist=None, test=False)

Gaia-only-based target selection, return target mask arrays.

Parameters:

• numproc (int, optional, defaults to 4) – The number of parallel processes to use.

• survey (str, defaults to 'main') – Which target masks yaml file and target selection cuts to use. Options are 'main' and 'svX’ (where X is 1, 2, 3 etc.) for the main survey and different iterations of SV, respectively.

• nside (int, optional, defaults to None) – (NESTED) HEALPix nside used with pixlist and bundlefiles.

• pixlist (list or int, optional, defaults to None) – Only return targets in a set of (NESTED) HEALpixels at nside. Useful for parallelizing, as input files will only be processed if they touch a pixel in the passed list.

• test (bool, optional, defaults to False) – If True, then we’re running unit tests and don’t have to find and read every possible Gaia file when calling apply_cuts_gaia().

Returns:

• ndarray – desi_target selection bitmask flags for each object.

• ndarray – bgs_target selection bitmask flags for each object.

• ndarray – mws_target selection bitmask flags for each object.

• ndarray – numpy structured array of Gaia sources that were read in from file for the passed pixel constraints (or no pixel constraints).

Notes

• May take a long time if no pixel constraints are passed.

• Only run on Gaia-only target selections.

• The environment variable $GAIA_DIR must be set.

See desitarget.svX.svX_targetmask.desi_mask or desitarget.targetmask.desi_mask for bit definitions.

desitarget.cuts.backupGiantDownsample(l, b)

Return the downsampling factor as a function of l,b

Parameters:

• l (array) – Galactic longitude

• b (array) – Galactic latitude

Returns:

frac – The fraction of objects to select

Return type:

array

desitarget.cuts.isBACKUP(ra=None, dec=None, gaiagmag=None, gaiabmag=None, gaiarmag=None, parallax=None, parallaxerr=None, primary=None)

BACKUP targets based on Gaia magnitudes.

Parameters:

• ra (array_like or None) – Right Ascension and Declination in degrees.

• dec (array_like or None) – Right Ascension and Declination in degrees.

• gaiagmag (array_like or None) – Gaia-based g, b and r MAGNITUDES (not corrected for Galactic extinction (same units as the Gaia data model).

• gaiabmag (array_like or None) – Gaia-based g, b and r MAGNITUDES (not corrected for Galactic extinction (same units as the Gaia data model).

• gaiarmag (array_like or None) – Gaia-based g, b and r MAGNITUDES (not corrected for Galactic extinction (same units as the Gaia data model).

• parallax (array_like or None) – Gaia parallax and error (same units as the Gaia data model)

• parallaxerr (array_like or None) – Gaia parallax and error (same units as the Gaia data model)

• primary (array_like or None) – True for objects that should be passed through the selection.

Returns:

• array_like – True if and only if the object is a bright “BACKUP” target.

• array_like – True if and only if the object is a faint “BACKUP” target.

• array_like – True if and only if the object is a very faint “BACKUP” target.

• array_like – True if and only if the object is a gaia-selected giant “BACKUP” target.

Notes

• Current version (10/22/21) is version 273 on the wiki.

desitarget.cuts.isBGS(rfiberflux=None, gflux=None, rflux=None, zflux=None, rfibertotflux=None, w1flux=None, w2flux=None, gnobs=None, rnobs=None, znobs=None, gfluxivar=None, rfluxivar=None, zfluxivar=None, maskbits=None, Grr=None, refcat=None, w1snr=None, w2snr=None, gaiagmag=None, objtype=None, primary=None, south=True, targtype=None)

Definition of BGS target classes. Returns a boolean array.

Parameters:

targtype (str, optional, defaults to faint) – Pass bright for the BGS_BRIGHT selection. or faint for the BGS_FAINT selection or wise for the BGS_WISE (AGN-like) selection.

Returns:

True if the object is a BGS target of type targtype.

Return type:

array_like

Notes

• Current version (05/11/21) is version 264 on the wiki.

• See set_target_bits() for other parameters.

desitarget.cuts.isBGS_colors(rfiberflux=None, gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, rfibertotflux=None, maskbits=None, south=True, targtype=None, primary=None)

Standard color-based cuts used by all BGS target selection classes (see, e.g., isBGS() for parameters).

desitarget.cuts.isBGS_sga(gflux=None, rflux=None, zflux=None, w1flux=None, refcat=None, rfibertotflux=None, rfiberflux=None, maskbits=None, south=True, targtype=None)

Module to recover the SGA objects in all BGS target classes (see, e.g., isBGS() for parameters).

desitarget.cuts.isBGS_wise(rfiberflux=None, gflux=None, rflux=None, zflux=None, w1flux=None, rfibertotflux=None, w2flux=None, refcat=None, maskbits=None, w1snr=None, w2snr=None, Grr=None, gaiagmag=None, gfluxivar=None, rfluxivar=None, zfluxivar=None, gnobs=None, rnobs=None, znobs=None, south=True, targtype=None, objtype=None, primary=None)

Standard color-based cuts used by all BGS target selection classes (see, e.g., isBGS() for parameters).

desitarget.cuts.isELG(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, gfiberflux=None, gsnr=None, rsnr=None, zsnr=None, gnobs=None, rnobs=None, znobs=None, maskbits=None, south=True, primary=None)

Definition of ELG target classes. Returns a boolean array. (see set_target_bits() for parameters).

Notes: - Current version (03/27/21) is version 8 on the SV3 wiki.

desitarget.cuts.isELG_colors(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, gfiberflux=None, rfiberflux=None, zfiberflux=None, south=True, primary=None)

Color cuts for ELG target selection classes (see, e.g., set_target_bits() for parameters).

desitarget.cuts.isGAIA_STD(ra=None, dec=None, galb=None, gaiaaen=None, pmra=None, pmdec=None, parallax=None, parallaxovererror=None, ebv=None, gaiabprpfactor=None, gaiasigma5dmax=None, gaiagmag=None, gaiabmag=None, gaiarmag=None, gaiadupsource=None, gaiaparamssolved=None, primary=None, test=False, nside=2)

Standards based solely on Gaia data.

Parameters:

• ebv (array_like) – E(B-V) values from the SFD dust maps.

• test (bool, optional, defaults to False) – If True, then we’re running unit tests and don’t have to find and read every possible Gaia file.

• nside (int, optional, defaults to 2) – (NESTED) HEALPix nside, if targets are being parallelized. The default of 2 should be benign for serial processing.

Returns:

• array_like – True if the object is a bright “GAIA_STD_FAINT” target.

• array_like – True if the object is a faint “GAIA_STD_BRIGHT” target.

• array_like – True if the object is a white dwarf “GAIA_STD_WD” target.

Notes

• Current version (01/28/21) is version 244 on the wiki.

• See set_target_bits() for other parameters.

desitarget.cuts.isLRG(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, zfiberflux=None, rfluxivar=None, zfluxivar=None, w1fluxivar=None, gaiagmag=None, gnobs=None, rnobs=None, znobs=None, maskbits=None, zfibertotflux=None, primary=None, south=True, ext=False)

Parameters:

• south (boolean, defaults to True) – Use cuts appropriate to the Northern imaging surveys (BASS/MzLS) if south=False, otherwise use cuts appropriate to the Southern imaging survey (DECaLS).

• ext (int, defaults to False) – If True, then apply the DESI extension selection instead of the standard Main Survey selection.

Returns:

True if and only if the object is an LRG target.

Return type:

array_like

Notes

• Current version (05/07/21) is version 260 on the wiki.

• See set_target_bits() for other parameters.

desitarget.cuts.isLRG_colors(gflux=None, rflux=None, zflux=None, w1flux=None, gfiberflux=None, rfiberflux=None, zfiberflux=None, ggood=None, w2flux=None, primary=None, south=True, ext=False)

(see, e.g., isLRG()).

Notes

• the ggood and w2flux inputs are an attempt to maintain backwards-compatibility with the mocks.

desitarget.cuts.isMWSSTAR_colors(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, primary=None, south=True)

A reasonable range of g-r for MWS targets. Returns a boolean array.

Parameters:

• gflux – array_like The flux in nano-maggies of g, r, z, w1, and w2 bands.

• rflux – array_like The flux in nano-maggies of g, r, z, w1, and w2 bands.

• zflux – array_like The flux in nano-maggies of g, r, z, w1, and w2 bands.

• w1flux – array_like The flux in nano-maggies of g, r, z, w1, and w2 bands.

• w2flux – array_like The flux in nano-maggies of g, r, z, w1, and w2 bands.

• primary – array_like or None Set to True for objects to initially consider as possible targets. Defaults to everything being True.

• south – boolean, defaults to True Use color-cuts based on photometry from the “south” (DECaLS) as opposed to the “north” (MzLS+BASS).

Returns:

boolean array, True if the object has colors like an old stellar population, which is what we expect for the main MWS sample

Return type:

mask

Notes

The full MWS target selection also includes PSF-like and fracflux cuts and will include Gaia information; this function is only to enforce a reasonable range of color/TEFF when simulating data.

desitarget.cuts.isMWS_WD(primary=None, gaia=None, galb=None, astrometricexcessnoise=None, pmra=None, pmdec=None, parallax=None, parallaxovererror=None, photbprpexcessfactor=None, astrometricsigma5dmax=None, gaiagmag=None, gaiabmag=None, gaiarmag=None, paramssolved=None)

Set bits for WHITE DWARF Milky Way Survey targets.

:param see set_target_bits() for parameters.:

Returns:

array_like.

True if and only if the object is a MWS-WD target.

Return type:

mask

Notes: - Current version (08/01/18) is version 121 on the wiki.

desitarget.cuts.isMWS_bhb(primary=None, objtype=None, gaia=None, gaiaaen=None, gaiadupsource=None, gaiagmag=None, gflux=None, rflux=None, zflux=None, w1flux=None, w1snr=None, maskbits=None, gnobs=None, rnobs=None, znobs=None, gfracmasked=None, rfracmasked=None, zfracmasked=None, parallax=None, parallaxerr=None)

Set bits for BHB Milky Way Survey targets.

:param see set_target_bits() for other parameters.:

Returns:

mask – True if and only if the object is a MWS-BHB target.

Return type:

array_like.

Notes

• Criteria supplied by Sergey Koposov.

• gflux, rflux, zflux, w1flux have been corrected for extinction (unlike other MWS selections, which use obs_flux).

• Current version (02/18/21) is version 246 on the wiki.

desitarget.cuts.isMWS_faint_colors(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, pmra=None, pmdec=None, parallax=None, parallaxerr=None, obs_rflux=None, objtype=None, paramssolved=None, gaiagmag=None, gaiabmag=None, gaiarmag=None, gaiaaen=None, primary=None, south=True)

Set of cuts to define a fainter extension to the MWS main sample. (see, e.g., isMWS_main() for parameters).

desitarget.cuts.isMWS_main(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, gnobs=None, rnobs=None, gfracmasked=None, rfracmasked=None, pmra=None, pmdec=None, parallax=None, parallaxerr=None, obs_rflux=None, objtype=None, gaia=None, gaiagmag=None, gaiabmag=None, gaiarmag=None, gaiaaen=None, gaiadupsource=None, paramssolved=None, primary=None, south=True, maskbits=None)

Set bits for main MWS targets.

:param see set_target_bits() for parameters.:

Returns:

array_like.

True if the object is a MWS_BROAD target.

mask2array_like.

True if the object is a MWS_MAIN_RED target.

mask3array_like.

True if the object is a MWS_MAIN_BLUE target.

mask4array_like.

True if the object is a MWS_FAINT_RED target.

mask5array_like.

True if the object is a MWS_FAINT_BLUE target.

Return type:

mask1

Notes: - Current version (05/04/21) is version 256 on the wiki.

desitarget.cuts.isMWS_main_colors(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, pmra=None, pmdec=None, parallax=None, parallaxerr=None, obs_rflux=None, objtype=None, paramssolved=None, gaiagmag=None, gaiabmag=None, gaiarmag=None, gaiaaen=None, primary=None, south=True)

Set of color-based cuts used by MWS target selection classes (see, e.g., isMWS_main() for parameters).

desitarget.cuts.isMWS_nearby(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, objtype=None, gaia=None, primary=None, paramssolved=None, pmra=None, pmdec=None, parallax=None, parallaxerr=None, obs_rflux=None, gaiagmag=None, gaiabmag=None, gaiarmag=None)

Set bits for NEARBY Milky Way Survey targets.

:param see set_target_bits() for parameters.:

Returns:

array_like.

True if and only if the object is a MWS-NEARBY target.

Return type:

mask

Notes: - Current version (09/20/18) is version 129 on the wiki.

desitarget.cuts.isQSO_colors(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, optical=False, south=True)

Tests if sources have quasar-like colors in a color box. (see, e.g., isQSO_cuts()).

desitarget.cuts.isQSO_cuts(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, w1snr=None, w2snr=None, maskbits=None, gnobs=None, rnobs=None, znobs=None, objtype=None, primary=None, optical=False, south=True)

QSO targets from color cuts. Returns a boolean array.

Parameters:

• optical (boolean, defaults to False) – Apply just optical color-cuts.

• south (boolean, defaults to True) – Use cuts for Northern imaging (BASS/MzLS) if south=False, otherwise use cuts for Southern imaging (DECaLS).

Returns:

True for objects passing quasar color/morphology/logic cuts.

Return type:

array_like

Notes

• Current version (06/05/19) is version 176 on the wiki.

• See set_target_bits() for other parameters.

desitarget.cuts.isQSO_randomforest(gflux=None, rflux=None, zflux=None, maskbits=None, w1flux=None, w2flux=None, objtype=None, gnobs=None, rnobs=None, znobs=None, primary=None, ra=None, dec=None, south=True, return_probs=False)

Define QSO targets from a Random Forest. Returns a boolean array.

Parameters:

• south (boolean, defaults to True) – If False, shift photometry to the Northern (BASS/MzLS) imaging system.

• return_probs (boolean, defaults to False) – If True, return QSO probabilities in addition to the target boolean. Only coded up for DR8 or later of the Legacy Surveys imaging. Will return arrays of zeros for earlier Data Releases.

Returns:

• array_like – True for objects that are Random Forest quasar targets.

• array_like – The (float) probability that a target is a quasar. Only returned if return_probs is True.

Notes

• Current version (05/06/21) is version 259 on the wiki.

• See set_target_bits() for other parameters.

desitarget.cuts.isSTD(gflux=None, rflux=None, zflux=None, primary=None, gfracflux=None, rfracflux=None, zfracflux=None, gfracmasked=None, rfracmasked=None, zfracmasked=None, gnobs=None, rnobs=None, znobs=None, gfluxivar=None, rfluxivar=None, zfluxivar=None, objtype=None, gaia=None, astrometricexcessnoise=None, paramssolved=None, pmra=None, pmdec=None, parallax=None, dupsource=None, gaiagmag=None, gaiabmag=None, gaiarmag=None, bright=False, usegaia=True, maskbits=None, south=True)

Select STD targets using color, photometric quality cuts (PSF-like and fracflux). See isSTD_colors() for additional info.

Parameters:

• gflux – array_like The flux in nano-maggies of g, r, z bands.

• rflux – array_like The flux in nano-maggies of g, r, z bands.

• zflux – array_like The flux in nano-maggies of g, r, z bands.

• primary – array_like or None True for possible targets. Defaults to True for all.

• gfracflux – array_like Profile-weighted fraction of the flux from other sources divided by the total flux in g, r and z bands.

• rfracflux – array_like Profile-weighted fraction of the flux from other sources divided by the total flux in g, r and z bands.

• zfracflux – array_like Profile-weighted fraction of the flux from other sources divided by the total flux in g, r and z bands.

• gfracmasked – array_like Fraction of masked pixels in the g, r and z bands.

• rfracmasked – array_like Fraction of masked pixels in the g, r and z bands.

• zfracmasked – array_like Fraction of masked pixels in the g, r and z bands.

• gnobs – array_like Number of observations (in the central pixel) in g, r and z.

• rnobs – array_like Number of observations (in the central pixel) in g, r and z.

• znobs – array_like Number of observations (in the central pixel) in g, r and z.

• gfluxivar – array_like The flux inverse variances in g, r, and z bands.

• rfluxivar – array_like The flux inverse variances in g, r, and z bands.

• zfluxivar – array_like The flux inverse variances in g, r, and z bands.

• objtype – array_like or None TYPE column of the catalogue to restrict to point sources.

• gaia – boolean array_like or None True if there is a match between this object in the Legacy Surveys and in Gaia.

• astrometricexcessnoise – array_like or None Excess noise of the source in Gaia.

• paramssolved – array_like or None How many parameters were solved for in Gaia.

• pmra – array_like or None Gaia-based proper motion in RA and Dec and parallax

• pmdec – array_like or None Gaia-based proper motion in RA and Dec and parallax

• parallax – array_like or None Gaia-based proper motion in RA and Dec and parallax

• dupsource – array_like or None Whether the source is a duplicate in Gaia.

• gaiagmag – array_like or None Gaia-based g-, b- and r-band MAGNITUDES.

• gaiabmag – array_like or None Gaia-based g-, b- and r-band MAGNITUDES.

• gaiarmag – array_like or None Gaia-based g-, b- and r-band MAGNITUDES.

• bright – boolean, defaults to False if True apply mag cuts for “bright” conditions; otherwise, for “dark” conditions. Cut is performed on gaiagmag.

• usegaia – boolean, defaults to True if True then call isSTD_gaia() to set the logic cuts. If Gaia is not available (perhaps if you’re using mocks) then send False, in which case we use the LS r-band as a proxy for Gaia G. False ignores that we have already corrected for Galactic extinction (incorrectly).

• south – boolean, defaults to True Use color-cuts based on photometry from the “south” (DECaLS) as opposed to the “north” (MzLS+BASS).

Returns:

boolean array, True if the object has colors like a STD.

Return type:

mask

Notes: - Gaia-based quantities are as in the Gaia data model. - Current version (02/18/21) is version 246 on the wiki.

desitarget.cuts.isSTD_colors(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, primary=None, south=True)

Select STD stars based on Legacy Surveys. Returns a boolean array.

Parameters:

• gflux – array_like The flux in nano-maggies of g, r, z, w1, and w2 bands.

• rflux – array_like The flux in nano-maggies of g, r, z, w1, and w2 bands.

• zflux – array_like The flux in nano-maggies of g, r, z, w1, and w2 bands.

• w1flux – array_like The flux in nano-maggies of g, r, z, w1, and w2 bands.

• w2flux – array_like The flux in nano-maggies of g, r, z, w1, and w2 bands.

• primary – array_like or None Set to True for objects to consider as possible STDs. Defaults to everything being True.

• south – boolean, defaults to True Use color-cuts based on photometry from the “south” (DECaLS) as opposed to the “north” (MzLS+BASS).

Returns:

boolean array, True if the object has colors like a STD star target.

Return type:

mask

Notes

• Current version (08/01/18) is version 121 on the wiki.

desitarget.cuts.isSTD_gaia(primary=None, gaia=None, astrometricexcessnoise=None, pmra=None, pmdec=None, parallax=None, dupsource=None, paramssolved=None, gaiagmag=None, gaiabmag=None, gaiarmag=None)

Gaia quality cuts used to define STD star targets.

Parameters:

• primary – array_like or None Set to True for objects to consider as possible STDs. Defaults to everything being True.

• gaia – boolean array_like or None True if there is a match between this object in the Legacy Surveys and in Gaia.

• astrometricexcessnoise – array_like or None Excess noise of the source in Gaia

• pmra – array_like or None Gaia-based proper motion in RA and Dec and parallax (same units as the Gaia data model).

• pmdec – array_like or None Gaia-based proper motion in RA and Dec and parallax (same units as the Gaia data model).

• parallax – array_like or None Gaia-based proper motion in RA and Dec and parallax (same units as the Gaia data model).

• dupsource – array_like or None Whether the source is a duplicate in Gaia.

• paramssolved – array_like or None How many parameters were solved for in Gaia.

• gaiagmag – array_like or None Gaia-based g, b and r MAGNITUDES (not corrected for Galactic extinction (same units as the Gaia data model).

• gaiabmag – array_like or None Gaia-based g, b and r MAGNITUDES (not corrected for Galactic extinction (same units as the Gaia data model).

• gaiarmag – array_like or None Gaia-based g, b and r MAGNITUDES (not corrected for Galactic extinction (same units as the Gaia data model).

Returns:

boolean array, True if the object passes Gaia quality cuts.

Return type:

mask

Notes: - Current version (08/01/18) is version 121 on the wiki.

desitarget.cuts.notinBGS_mask(gnobs=None, rnobs=None, znobs=None, primary=None, gfluxivar=None, rfluxivar=None, zfluxivar=None, Grr=None, gaiagmag=None, maskbits=None, targtype=None)

Standard masking cuts used by all BGS target selection classes (see, e.g., isBGS() for parameters).

desitarget.cuts.notinELG_mask(maskbits=None, gsnr=None, rsnr=None, zsnr=None, gnobs=None, rnobs=None, znobs=None, primary=None)

Standard set of masking cuts used by all ELG target selection classes. (see set_target_bits() for parameters).

desitarget.cuts.notinLRG_mask(primary=None, rflux=None, zflux=None, w1flux=None, zfiberflux=None, gnobs=None, rnobs=None, znobs=None, rfluxivar=None, zfluxivar=None, w1fluxivar=None, gaiagmag=None, maskbits=None, zfibertotflux=None)

See isLRG() for details.

Returns:

True if and only if the object is NOT masked for poor quality.

Return type:

array_like

desitarget.cuts.notinMWS_main_mask(gaia=None, gfracmasked=None, gnobs=None, gflux=None, rfracmasked=None, rnobs=None, rflux=None, maskbits=None, gaiadupsource=None, primary=None)

Standard set of masking-based cuts used by MWS target classes (see, e.g., isMWS_main() for parameters).

desitarget.cuts.random_fraction_of_trues(fraction, bool_array)

Return True for a random subset of array entries that are True.

Parameters:

• fraction (float) – The fraction of the True entries to retain as True. Should be between 0 and 1.

• bool_array (array_like or bool) – A boolean array, or scalar.

Returns:

The original bool_array, with a random fraction of True entries retained as True and the others set to False. If a scalar is passed, then a scalar is returned.

Return type:

array_like

desitarget.cuts.select_targets(infiles, numproc=4, qso_selection='randomforest', gaiasub=False, nside=None, pixlist=None, bundlefiles=None, extra=None, radecbox=None, radecrad=None, mask=True, tcnames=['ELG', 'QSO', 'LRG', 'MWS', 'BGS', 'STD', 'LGE'], survey='main', resolvetargs=True, backup=True, return_infiles=False, test=False)

Process input files in parallel to select targets.

Parameters:

• infiles (list or str) – List of input filenames (tractor or sweep) OR a single filename.

• numproc (int, optional, defaults to 4) – The number of parallel processes to use.

• qso_selection (str, optional, default is 'randomforest') – The algorithm to use for QSO selection; valid options are 'colorcuts' and 'randomforest'.

• gaiasub (boolean, optional, defaults to False) – If True, substitute Gaia EDR3 proper motion and parallax columns over the sweeps values. If True, then the GAIA_DIR environment variable must be set to find the Gaia sweeps files.

• nside (int, optional, defaults to None) – (NESTED) HEALPixel nside used with pixlist and bundlefiles.

• pixlist (list or int, optional, defaults to None) – Only return targets in (NESTED) HEALpixels at nside. Also useful for parallelizing as input files will only be processed if they touch a pixel in the passed list.

• bundlefiles (int, defaults to None) – If not None, then instead of selecting targets, print a slurm script that balances the input file distribution at bundlefiles files per node. So, e.g., if bundlefiles is 100 commands would be printed with pixlist values to pass to the code to pack at about 100 files per node across all of the passed infiles.

• extra (str, optional) – Extra command line flags to be passed to the executable lines in the output slurm script. Used in conjunction with bundlefiles.

• radecbox (list, defaults to None) – 4-entry coordinate list [ramin, ramax, decmin, decmax]. Only targets inside this “box” region will be processed.

• radecrad (list, defaults to None) – 3-entry coordinate list [ra, dec, radius] for RA/Dec/radius in degrees. Only targets in this “circle” region will be processed.

• mask (boolean, optional, defaults to True) – Send False to turn off any masking cuts based on MASKBITS. The default behavior is to always mask using MASKBITS.

• tcnames (list, defaults to running all target classes) – List of strings, e.g. [‘QSO’,’LRG’]. If passed, process targets only for those specific classes. A useful speed-up when testing. Options are [“ELG”, “QSO”, “LRG”, “MWS”, “BGS”, “STD”, “LGE”].

• survey (str, defaults to 'main') – Which target masks yaml file and target selection cuts to use. Options are 'main' and 'svX’ (where X is 1, 2, 3 etc.) for the main survey and different iterations of SV, respectively.

• resolvetargs (boolean, optional, defaults to True) – If True, resolve targets into northern targets in northern regions and southern targets in southern regions.

• backup (boolean, optional, defaults to True) – If True, also run the Gaia-only BACKUP_BRIGHT/FAINT targets.

• return_infiles (boolean, optional, defaults to False) – If True, return the filenamess from infiles that were processed. Useful when running with pixlist, radecbox or radecrad to see which files were actually required.

• test (bool, optional, defaults to False) – If True, then we’re running unit tests and don’t have to find and read every possible Gaia file when calling apply_cuts_gaia().

Returns:

• ndarray – The subset of input targets which pass the cuts, including extra columns for DESI_TARGET, BGS_TARGET, and MWS_TARGET target selection bitmasks.

• list, only returned if return_infiles is True – A list of the input files that actually needed to be processed.

Notes

• if numproc==1, use serial code instead of parallel.

• only one of pixlist, radecbox, radecrad should be passed. They all denote regions on the sky, using different formalisms.

desitarget.cuts.set_target_bits(photsys_north, photsys_south, obs_rflux, gflux, rflux, zflux, w1flux, w2flux, gfiberflux, rfiberflux, zfiberflux, gfibertotflux, rfibertotflux, zfibertotflux, objtype, release, ra, dec, gfluxivar, rfluxivar, zfluxivar, w1fluxivar, gnobs, rnobs, znobs, gfracflux, rfracflux, zfracflux, gfracmasked, rfracmasked, zfracmasked, gfracin, rfracin, zfracin, gallmask, rallmask, zallmask, gsnr, rsnr, zsnr, w1snr, w2snr, deltaChi2, dchisq, gaia, pmra, pmdec, parallax, parallaxovererror, parallaxerr, gaiagmag, gaiabmag, gaiarmag, gaiaaen, gaiadupsource, gaiaparamssolved, gaiabprpfactor, gaiasigma5dmax, galb, tcnames, qso_optical_cuts, qso_selection, maskbits, Grr, refcat, primary, resolvetargs=True)

Perform target selection on parameters, return target mask arrays.

Parameters:

• photsys_north (ndarray) – True for objects that were drawn from northern (MzLS/BASS) or southern (DECaLS) imaging, respectively.

• photsys_south (ndarray) – True for objects that were drawn from northern (MzLS/BASS) or southern (DECaLS) imaging, respectively.

• obs_rflux (ndarray) – rflux but WITHOUT any Galactic extinction correction.

• gflux (ndarray) – The flux in nano-maggies of g, r, z, W1 and W2 bands. Corrected for Galactic extinction.

• rflux (ndarray) – The flux in nano-maggies of g, r, z, W1 and W2 bands. Corrected for Galactic extinction.

• zflux (ndarray) – The flux in nano-maggies of g, r, z, W1 and W2 bands. Corrected for Galactic extinction.

• w1flux (ndarray) – The flux in nano-maggies of g, r, z, W1 and W2 bands. Corrected for Galactic extinction.

• w2flux (ndarray) – The flux in nano-maggies of g, r, z, W1 and W2 bands. Corrected for Galactic extinction.

• gfiberflux (ndarray) – Predicted fiber flux from object in 1 arcsecond seeing in g/r/z. Corrected for Galactic extinction.

• rfiberflux (ndarray) – Predicted fiber flux from object in 1 arcsecond seeing in g/r/z. Corrected for Galactic extinction.

• zfiberflux (ndarray) – Predicted fiber flux from object in 1 arcsecond seeing in g/r/z. Corrected for Galactic extinction.

• gfibertotflux (ndarray) – Predicted fiber flux from ALL sources at object’s location in 1 arcsecond seeing in g/r/z. NOT corrected for Galactic extinction.

• rfibertotflux (ndarray) – Predicted fiber flux from ALL sources at object’s location in 1 arcsecond seeing in g/r/z. NOT corrected for Galactic extinction.

• zfibertotflux (ndarray) – Predicted fiber flux from ALL sources at object’s location in 1 arcsecond seeing in g/r/z. NOT corrected for Galactic extinction.

• objtype (ndarray) – The Legacy Surveys imaging TYPE and RELEASE columns.

• release (ndarray) – The Legacy Surveys imaging TYPE and RELEASE columns.

• gfluxivar (ndarray) – The flux inverse variances in g, r, z and W1 bands.

• rfluxivar (ndarray) – The flux inverse variances in g, r, z and W1 bands.

• zfluxivar (ndarray) – The flux inverse variances in g, r, z and W1 bands.

• w1fluxivar (ndarray) – The flux inverse variances in g, r, z and W1 bands.

• gnobs (ndarray) – The number of observations (in the central pixel) in g, r and z.

• rnobs (ndarray) – The number of observations (in the central pixel) in g, r and z.

• znobs (ndarray) – The number of observations (in the central pixel) in g, r and z.

• gfracflux (ndarray) – Profile-weighted fraction of the flux from other sources divided by the total flux in g, r and z bands.

• rfracflux (ndarray) – Profile-weighted fraction of the flux from other sources divided by the total flux in g, r and z bands.

• zfracflux (ndarray) – Profile-weighted fraction of the flux from other sources divided by the total flux in g, r and z bands.

• gfracmasked (ndarray) – Fraction of masked pixels in the g, r and z bands.

• rfracmasked (ndarray) – Fraction of masked pixels in the g, r and z bands.

• zfracmasked (ndarray) – Fraction of masked pixels in the g, r and z bands.

• gallmask (ndarray) – Bitwise mask set if the central pixel from all images satisfy each condition in g, r, z.

• rallmask (ndarray) – Bitwise mask set if the central pixel from all images satisfy each condition in g, r, z.

• zallmask (ndarray) – Bitwise mask set if the central pixel from all images satisfy each condition in g, r, z.

• gsnr (ndarray) – Signal-to-noise in g, r, z, W1 and W2 defined as the flux per band divided by sigma (flux x sqrt of the inverse variance).

• rsnr (ndarray) – Signal-to-noise in g, r, z, W1 and W2 defined as the flux per band divided by sigma (flux x sqrt of the inverse variance).

• zsnr (ndarray) – Signal-to-noise in g, r, z, W1 and W2 defined as the flux per band divided by sigma (flux x sqrt of the inverse variance).

• w1snr (ndarray) – Signal-to-noise in g, r, z, W1 and W2 defined as the flux per band divided by sigma (flux x sqrt of the inverse variance).

• w2snr (ndarray) – Signal-to-noise in g, r, z, W1 and W2 defined as the flux per band divided by sigma (flux x sqrt of the inverse variance).

• deltaChi2 (ndarray) – chi2 difference between PSF and SIMP, dchisq_PSF - dchisq_SIMP.

• dchisq (ndarray) – Difference in chi2 between successively more-complex model fits. Columns are model fits, in order, of PSF, REX, EXP, DEV, COMP.

• gaia (ndarray) – True if there is a match between this object in the Legacy Surveys and in Gaia.

• pmra (ndarray) – Gaia-based proper motion in RA and Dec, and parallax and error.

• pmdec (ndarray) – Gaia-based proper motion in RA and Dec, and parallax and error.

• parallax (ndarray) – Gaia-based proper motion in RA and Dec, and parallax and error.

• parallaxovererror (ndarray) – Gaia-based proper motion in RA and Dec, and parallax and error.

• gaiagmag (ndarray) – Gaia-based g-, b- and r-band MAGNITUDES.

• gaiabmag (ndarray) – Gaia-based g-, b- and r-band MAGNITUDES.

• gaiarmag (ndarray) – Gaia-based g-, b- and r-band MAGNITUDES.

• gaiaaen (ndarray) – Gaia-based measures of Astrometric Excess Noise, whether the source is a duplicate, and how many parameters were solved for.

• gaiadupsource (ndarray) – Gaia-based measures of Astrometric Excess Noise, whether the source is a duplicate, and how many parameters were solved for.

• gaiaparamssolved (ndarray) – Gaia-based measures of Astrometric Excess Noise, whether the source is a duplicate, and how many parameters were solved for.

• gaiabprpfactor (ndarray) – Gaia_based BP/RP excess factor and longest semi-major axis of 5-d error ellipsoid.

• gaiasigma5dmax (ndarray) – Gaia_based BP/RP excess factor and longest semi-major axis of 5-d error ellipsoid.

• galb (ndarray) – Galactic latitude (degrees).

• tcnames (list, defaults to running all target classes) – A list of strings, e.g. [‘QSO’,’LRG’]. If passed, process only only those specific target classes. A useful speed-up for tests. Options are [“ELG”, “QSO”, “LRG”, “MWS”, “BGS”, “STD”, “LGE”].

• qso_optical_cuts (boolean defaults to False) – Apply just optical color-cuts when selecting QSOs with qso_selection="colorcuts".

• qso_selection (str, optional, defaults to ‘randomforest’) – The algorithm to use for QSO selection; valid options are ‘colorcuts’ and ‘randomforest’

• maskbits (boolean array_like or None) – General Legacy Surveys mask bits.

• Grr (array_like or None) – Gaia G band magnitude minus observational r magnitude.

• primary (ndarray) – True for objects that should be considered when setting bits.

• survey (str, defaults to 'main') – Specifies which target masks yaml file and target selection cuts to use. Options are 'main' and 'svX’ (X is 1, 2, etc.) for the main survey and different iterations of SV, respectively.

• resolvetargs (boolean, optional, defaults to True) – If True, if only northern (southern) sources are passed then only apply the northern (southern) cuts to those sources.

• ra (ndarray) – The Ra, Dec position of objects

• dec (ndarray) – The Ra, Dec position of objects

Returns:

(desi_target, bgs_target, mws_target) where each element is an ndarray of target selection bitmask flags for each object.

Return type:

ndarray

Notes

• Gaia quantities have units as for the Gaia data model.

desitarget.cuts.shift_photo_north(gflux=None, rflux=None, zflux=None)

Convert fluxes in the northern (BASS/MzLS) to the southern (DECaLS) system.

Parameters:

• gflux (array_like or float) – The flux in nano-maggies of g, r, z bands.

• rflux (array_like or float) – The flux in nano-maggies of g, r, z bands.

• zflux (array_like or float) – The flux in nano-maggies of g, r, z bands.

Return type:

The equivalent fluxes shifted to the southern system.

Notes

• see also https://desi.lbl.gov/DocDB/cgi-bin/private/RetrieveFile?docid=3390;filename=Raichoor_DESI_05Dec2017.pdf;version=1

• Update for DR9 https://desi.lbl.gov/trac/attachment/wiki/TargetSelectionWG/TargetSelection/North_vs_South_dr9.png

desitarget.cuts.shift_photo_north_pure(gflux=None, rflux=None, zflux=None)

Same as shift_photo_north_pure() accounting for zero fluxes.

Parameters:

• gflux (array_like or float) – The flux in nano-maggies of g, r, z bands.

• rflux (array_like or float) – The flux in nano-maggies of g, r, z bands.

• zflux (array_like or float) – The flux in nano-maggies of g, r, z bands.

Return type:

The equivalent fluxes shifted to the southern system.

Notes

• see also https://desi.lbl.gov/DocDB/cgi-bin/private/RetrieveFile?docid=3390;filename=Raichoor_DESI_05Dec2017.pdf;version=1

• Update for DR9 https://desi.lbl.gov/trac/attachment/wiki/TargetSelectionWG/TargetSelection/North_vs_South_dr9.png

desitarget.cuts.unextinct_fluxes(objects)

Calculate unextincted DECam and WISE fluxes.

Parameters:

objects – array or Table with columns FLUX_G, FLUX_R, FLUX_Z, MW_TRANSMISSION_G, MW_TRANSMISSION_R, MW_TRANSMISSION_Z, FLUX_W1, FLUX_W2, MW_TRANSMISSION_W1, MW_TRANSMISSION_W2.

Returns:

array or Table with columns GFLUX, RFLUX, ZFLUX, W1FLUX, W2FLUX.

Output type is the same as the input type.

desitarget.gaiamatch

Useful Gaia matching and manipulation routines.

desitarget.gaiamatch._get_gaia_nside()

Grab the HEALPixel nside to be used throughout this module.

Returns:

The HEALPixel nside number for Gaia file creation and retrieval.

Return type:

int

desitarget.gaiamatch.check_gaia_survey(dr)

Convenience function to check allowed Gaia Data Releases

Parameters:

dr (str) – Name of a Gaia data release. Options are “dr2”, “edr3”, “dr3”. If one of those options isn’t passed, a ValueError is raised.

desitarget.gaiamatch.find_gaia_files(objs, neighbors=True, radec=False, dr='dr2', lightweight=False)

Find full paths to Gaia healpix files for objects by RA/Dec.

Parameters:

• objs (ndarray) – Array of objects. Must contain at least the columns “RA” and “DEC”.

• neighbors (bool, optional, defaults to True) – Also return all neighboring pixels that touch the files of interest in order to prevent edge effects (e.g. if a Gaia source is 1 arcsec away from a primary source and so in an adjacent pixel).

• radec (bool, optional, defaults to False) – If True then the passed objs is an [RA, Dec] list instead of a rec array.

• dr (str, optional, defaults to “dr2”) – Name of a Gaia data release. Options are “dr2”, “edr3”, “dr3”.

• lightweight (bool, optional, defaults to False) – If True search for and use the “lightweight” version of the Gaia files made by, e.g., make_gaia_light_dr3(). These only contain Gaia objects brighter than 16th mag so are speedier for discarding objects near bright sources.

Returns:

A list of all Gaia files that need to be read in to account for objects at the passed locations.

Return type:

list

Notes

• The environment variable $GAIA_DIR must be set.

desitarget.gaiamatch.find_gaia_files_beyond_gal_b(mingalb, neighbors=True, dr='dr2')

Find full paths to Gaia healpix files beyond a Galactic b.

Parameters:

• mingalb (float) – Closest latitude to Galactic plane to return HEALPixels (e.g. send 10 to limit to pixels beyond -10o <= b < 10o).

• neighbors (bool, optional, defaults to True) – Also return files corresponding to neighboring pixels that touch in order to prevent edge effects (e.g. if a Gaia source might be 1 arcsec beyond mingalb and so in an adjacent pixel).

• dr (str, optional, defaults to “dr2”) – Name of a Gaia data release. Options are “dr2”, “edr3”, “dr3”.

Returns:

All Gaia files that need to be read in to account for objects further from the Galactic plane than mingalb.

Return type:

list

Notes

• The environment variable $GAIA_DIR must be set.

• desitarget.geomask.hp_beyond_gal_b() is already quite inclusive, so you may retrieve some extra files along the mingalb boundary.

desitarget.gaiamatch.find_gaia_files_box(gaiabounds, neighbors=True, dr='dr2')

Find full paths to Gaia healpix files in an RA/Dec box.

Parameters:

• gaiabounds (list) – A region of the sky bounded by RA/Dec. Pass as a 4-entry list to represent an area bounded by [RAmin, RAmax, DECmin, DECmax]

• neighbors (bool, optional, defaults to True) – Also return files corresponding to all neighboring pixels that touch the files that touch the box in order to prevent edge effects (e.g. if a Gaia source might be 1 arcsec outside of the box and so in an adjacent pixel)

• dr (str, optional, defaults to “dr2”) – Name of a Gaia data release. Options are “dr2”, “edr3”, “dr3”.

Returns:

A list of all Gaia files that need to be read in to account for objects in the passed box.

Return type:

list

Notes

• Uses the healpy routines that rely on fact, so the usual warnings about returning different pixel sets at different values of fact apply. See: https://healpy.readthedocs.io/en/latest/generated/healpy.query_polygon.html

• The environment variable $GAIA_DIR must be set.

desitarget.gaiamatch.find_gaia_files_hp(nside, pixlist, neighbors=True, dr='dr2')

Find full paths to Gaia healpix files in a set of HEALPixels.

Parameters:

• nside (int) – (NESTED) HEALPixel nside.

• pixlist (list or int) – A set of HEALPixels at nside.

• neighbors (bool, optional, defaults to True) – Also return files corresponding to all neighbors that touch the pixels in pixlist to prevent edge effects (e.g. a Gaia source is 1 arcsec outside of pixlist and so in an adjacent pixel).

• dr (str, optional, defaults to “dr2”) – Name of a Gaia data release. Options are “dr2”, “edr3”, “dr3”.

Returns:

A list of all Gaia files that need to be read in to account for objects in the passed list of pixels.

Return type:

list

Notes

• The environment variable $GAIA_DIR must be set.

desitarget.gaiamatch.find_gaia_files_tiles(tiles=None, neighbors=True, dr='dr2')

Parameters:

• tiles (ndarray) – Array of tiles, or None to use all DESI tiles from desimodel.io.load_tiles().

• neighbors (bool, optional, defaults to True) – Also return all neighboring pixels that touch the files of interest in order to prevent edge effects (e.g. if a Gaia source is 1 arcsec away from a primary source and so in an adjacent pixel).

• dr (str, optional, defaults to “dr2”) – Name of a Gaia data release. Options are “dr2”, “edr3”, “dr3”.

Returns:

A list of all Gaia files that touch the passed tiles.

Return type:

list

Notes

• The environment variables $GAIA_DIR and $DESIMODEL must be set.

desitarget.gaiamatch.gaia_csv_to_fits(dr='dr2', numproc=32, mopup=False, full=False, boolfix=False, outdir=None)

Convert files in $GAIA_DIR/csv to files in $GAIA_DIR/fits.

Parameters:

• dr (str, optional, defaults to “dr2”) – Name of a Gaia data release. Options are “dr2”, “edr3”, “dr3”. For “edr3” the directory used is actually $GAIA_DIR/../gaia_edr3 For “dr3” the directory used is actually $GAIA_DIR/../gaia_dr3

• numproc (int, optional, defaults to 32) – The number of parallel processes to use.

• mopup (bool, optional, defaults to False) – If True then just convert any remaining files, rather than all of the the csv files. The $GAIA_DIR/fits/hpx-to-files.pickle file is not produced in this case, and will need to be run separately with the hpx_pickle_from_fits function.

• full (bool, optional, defaults to False) – If True then write out all of the columns in the Gaia csv files rather than just those in the Gaia data model. Also, if True, write to a directory named “fits-full” instead of to a directory named “fits”. This is ONLY IMPLEMENTED for dr=”dr3”. The code will flag an error for other values of dr.

• boolfix (bool, optional, defaults to False) – Files generated with this code before version 2.7.0 of desitarget included a parsing bug where ALL Boolean columns for edr3 or dr3 would be set to False. For backward compatibility, the old behavior is retained for dr2 and edr3 UNLESS boolfix is passed as True. The old behavior is retained for edr3 because DESI target files were generated with the buggy code version.

• outdir (str, optional, defaults to writing to $GAIA_DIR) – Write to the passed directory instead of to $GAIA_DIR.

Returns:

But the archived Gaia CSV files in $GAIA_DIR/csv are converted to FITS files in the directory $GAIA_DIR/fits. Also, a look-up table is written to $GAIA_DIR/fits/hpx-to-files.pickle for which each index is an nside=_get_gaia_nside(), nested scheme HEALPixel and each entry is a list of the FITS files that touch that pixel.

Return type:

Nothing

Notes

• The environment variable $GAIA_DIR must be set.

• if numproc==1, use the serial code instead of the parallel code.

• Runs in 1-2 hours with numproc=32 for 61,234 Gaia DR2 files.

• Runs in 1-2 hours with numproc=32 for 3,386 Gaia EDR3 files.

• Runs in ~4.5 hours with numproc=16 for 3,386 Gaia DR3 files.

• Runs in 1-2 hours with numproc=64 for DR3 on Perlmutter CPUs.

desitarget.gaiamatch.gaia_dr_from_ref_cat(refcat)

Determine the Gaia DR from an array of values, check it’s unique.

Parameters:

ref_cat (ndarray or str) – A REF_CAT string or an array of REF_CAT strings (e.g. b”G2”).

Returns:

The corresponding Data Release number (e.g. 2)

Return type:

ndarray

Notes

• In reality, base code strips the final integer off strings like “X3”. So, can generically be used for that purpose.

desitarget.gaiamatch.gaia_fits_to_healpix(dr='dr2', numproc=32)

Convert files in $GAIA_DIR/fits to files in $GAIA_DIR/healpix.

Parameters:

• dr (str, optional, defaults to “dr2”) – Name of a Gaia data release. Options are “dr2”, “edr3”, “dr3”. For “edr3” the directory used is actually $GAIA_DIR/../gaia_edr3 For “dr3” the directory used is actually $GAIA_DIR/../gaia_dr3

• numproc (int, optional, defaults to 32) – The number of parallel processes to use.

Returns:

But the archived Gaia FITS files in $GAIA_DIR/fits are rearranged by HEALPixel in the directory $GAIA_DIR/healpix. The HEALPixel sense is nested with nside=_get_gaia_nside(), and each file in $GAIA_DIR/healpix is called healpix-xxxxx.fits, where xxxxx corresponds to the HEALPixel number.

Return type:

Nothing

Notes

• The environment variable $GAIA_DIR must be set.

• if numproc==1, use the serial code instead of the parallel code.

• Runs in 1-2 hours with numproc=32 for 61,234 Gaia DR2 files.

• Runs in ~15 minutes with numproc=32 for 3,386 Gaia EDR3 files.

• Runs in ~20 minutes with numproc=32 for 3,386 Gaia DR3 files.

desitarget.gaiamatch.gaia_psflike(aen, g, dr='dr2')

Whether an objects is PSF-like based on Gaia quantities.

Parameters:

• aen (array_like or :class`float`) – Gaia Astrometric Excess Noise.

• g (array_like or :class`float`) – Gaia-based g MAGNITUDE (not Galactic-extinction-corrected).

• dr (str, optional, defaults to “dr2”) – Name of a Gaia data release. Options are “dr2”, “edr3”

Returns:

:class:`array_like` or – A boolean that is True for objects that are psf-like based on Gaia quantities.

Return type:

class`float`

Notes

• Input quantities are the same as in the Gaia data model.

desitarget.gaiamatch.get_gaia_dir(dr='dr2')

Convenience function to grab the Gaia environment variable.

Parameters:

dr (str, optional, defaults to “dr2”) – Name of a Gaia data release. Options are “dr2”, “edr3”, “dr3”

Returns:

The directory stored in the $GAIA_DIR environment variable.

Return type:

str

desitarget.gaiamatch.get_gaia_nside_brick(bricksize=0.25)

Grab the HEALPixel nside that corresponds to a brick.

Parameters:

bricksize (float, optional, defaults to 0.25) – Size of the brick, default is the Legacy Surveys standard.

Returns:

The HEALPixel nside number that corresponds to a brick.

Return type:

int

desitarget.gaiamatch.hpx_pickle_from_fits(dr='dr2')

Make $GAIA_DIR/fits/hpx-to-files.pickle independently of gaia_csv_to_fits

Parameters:

dr (str, optional, defaults to “dr2”) – Name of a Gaia data release. Options are “dr2”, “edr3”, “dr3”. For “edr3” the directory used is actually $GAIA_DIR/../gaia_edr3 For “dr3” the directory used is actually $GAIA_DIR/../gaia_dr3

Returns:

But a look-up table for which each index is a get_gaia_nside(), nested scheme HEALPixel and each entry is a list of the FITS files that touch that HEALPixel is written to $GAIA_DIR/fits/hpx-to-files.pickle.

Return type:

Nothing

Notes

• The environment variable $GAIA_DIR must be set.

• Runs in ~25 minutes for 3,386 Gaia DR3 files.

desitarget.gaiamatch.is_in_Galaxy(objs, radec=False)

An (l, b) cut developed by Boris Gaensicke to avoid the Galaxy.

Parameters:

• objs (ndarray) – Array of objects. Must contain at least the columns “RA” and “DEC”.

• radec (bool, optional, defaults to False) – If True then the passed objs is an [RA, Dec] list instead of a rec array.

Returns:

A boolean array that is True for objects that are close to the Galaxy and False for objects that aren’t.

Return type:

ndarray

desitarget.gaiamatch.make_gaia_files(dr='dr2', numproc=32, download=False)

Make the HEALPix-split Gaia DR2 files used by desitarget.

Parameters:

• dr (str, optional, defaults to “dr2”) – Name of a Gaia data release. Options are “dr2”, “edr3”. For “edr3” the directory used is actually $GAIA_DIR/../gaia_edr3.

• numproc (int, optional, defaults to 32) – The number of parallel processes to use.

• download (bool, optional, defaults to False) – If True then wget the Gaia DR2 csv files from ESA.

Returns:

But produces: - Full Gaia DR2 CSV files in $GAIA_DIR/csv. - FITS files with columns from ingaiadatamodel or inedr3datamodel in $GAIA_DIR/fits. - FITS files reorganized by HEALPixel in $GAIA_DIR/healpix.

The HEALPixel sense is nested with nside=_get_gaia_nside(), and each file in $GAIA_DIR/healpix is called healpix-xxxxx.fits, where xxxxx corresponds to the HEALPixel number.

Return type:

Nothing

Notes

• The environment variable $GAIA_DIR must be set.

• if numproc==1, use the serial code instead of the parallel code.

• Runs in ~26/20 hours for “dr2”/”edr3” if download is True.

• Runs in 1-2 hours with numproc=32 if download is False.

desitarget.gaiamatch.make_gaia_light_dr3(numproc=128)

Make lightweight versions of the Gaia DR3 HEALPixel files.

Parameters:

numproc (int, optional, defaults to 128) – The number of parallel processes to use.

Returns:

But the lightweight version of the healpix files are written to $GAIA_DIR/../gaia_dr3/lightweight.

Return type:

Nothing

Notes

• The environment variable $GAIA_DIR must be set.

• The lightweight files only contain objects brighter than 16th mag in G, BP, or RP and are most useful to mask bright objects.

• The lightweight files only contain the columns:

  SOURCE_ID, REF_EPOCH, RA, DEC, PMRA, PMDEC, PHOT_G_MEAN_MAG, PHOT_RP_MEAN_MAG, PHOT_G_MEAN_MAG

• Runs in about 5 minutes with numproc=128.

desitarget.gaiamatch.match_gaia_to_primary(objs, matchrad=0.2, retaingaia=False, gaiabounds=[0.0, 360.0, -90.0, 90.0], dr='edr3')

Match objects to Gaia healpix files and return Gaia information.

Parameters:

• objs (ndarray) – Must contain at least “RA”, “DEC”. ASSUMED TO BE AT A REFERENCE EPOCH OF 2015.5 and EQUINOX J2000/ICRS.

• matchrad (float, optional, defaults to 0.2 arcsec) – The matching radius in arcseconds.

• retaingaia (float, optional, defaults to False) – If set, return all of the Gaia information in the “area” occupied by objs (whether a Gaia object matches a passed RA/Dec or not.) THIS ASSUMES THAT THE PASSED OBJECTS ARE FROM A SWEEPS file and that integer values nearest the maximum and minimum passed RAs and Decs fairly represent the areal “edges” of that file.

• gaiabounds (list, optional, defaults to the whole sky) – Used with retaingaia to determine the area over which to retrieve Gaia objects that don’t match a sweeps object. Pass a 4-entry (corresponding to [RAmin, RAmax, DECmin, DECmax]).

• dr (str, optional, defaults to “edr3”) – Name of a Gaia data release. Options are “dr2”, “edr3”, “dr3”. Specifies which REF_EPOCH to use for matching and the output data model.

Returns:

Gaia information for each matching object, in a format like gaiadatamodel (for dr=dr2), edr3datamodel (dr=edr3) or dr3datamodelfull (for dr=dr3).

Return type:

ndarray

Notes

• The first len(objs) objects correspond row-by-row to objs.

• For objects that do NOT have a match in Gaia, the “REF_ID” column is set to -1, and all other columns are zero.

• If retaingaia is True then objects after the first len(objs) objects are Gaia objects that do not have a sweeps match but are in the area bounded by gaiabounds.

• After running targets for the DESI Main Survey (i.e. starting with Gaia DR3) a minor bug was identified where a match within matchrad was returned that wasn’t necessarily the CLOSEST match for instances of very close Gaia pairs. Therefore, for releases subsequent to Gaia DR3, this function is modified to always find the CLOSEST Gaia match rather than just ANY match that satisfies the matchrad constraint.

desitarget.gaiamatch.match_gaia_to_primary_post_dr3(objs, matchrad=0.2, dr='dr3', maglim=None, lightweight=False)

Match objects to Gaia healpix files starting with Gaia DR3.

Parameters:

• objs (ndarray) – Must contain at least “RA”, “DEC”. ASSUMED TO BE AT A REFERENCE EPOCH OF 2015.5 and EQUINOX J2000/ICRS.

• matchrad (float, optional, defaults to 0.2 arcsec) – The matching radius in arcseconds.

• dr (str, optional, defaults to “dr3”) – Name of a Gaia data release. Specifies which REF_EPOCH to use.

• maglim (float, optional) – Only return Gaia objects brighter than maglim in any Gaia band. Speed-up that also saves memory when matching to bright objects.

• lightweight (bool, optional, defaults to False) – If True search for and use the “lightweight” version of the Gaia files made by, e.g., make_gaia_light_dr3(). These only contain Gaia objects brighter than 16th mag so are speedier for discarding objects near bright sources.

Returns:

Gaia information for each matching object, in a format like dr3datamodelfull.

Return type:

ndarray

Notes

• Returned objects correspond row-by-row to objs.

• For objects that do NOT have a match in Gaia, the “REF_ID” column is set to -1, and all other columns are zero.

• This code fixes a number of minor issues related to close pairs in Gaia that were discovered after running Main Survey targets (i.e. starting with Gaia DR3). To reproduce DESI Main Survey targets, match_gaia_to_primary() should be used.

• Passing maglim might return different objects as well as speeding up the code. This is because matches will only be performed to brighter objects and their could be a bright object in the match radius farther away than a fainter object.

desitarget.gaiamatch.match_gaia_to_primary_post_dr3_quick(objs, matchrad=0.2, dr='dr3', maglim=None, nside=None, lightweight=False, verbose=False)

Version of match_gaia_to_primary_post_dr3() that might be quicker.

Parameters:

• objs (ndarray) – Must contain at least “RA”, “DEC”. ASSUMED TO BE AT A REFERENCE EPOCH OF 2015.5 and EQUINOX J2000/ICRS.

• matchrad (float, optional, defaults to 0.2 arcsec) – The matching radius in arcseconds.

• dr (str, optional, defaults to “dr3”) – Name of a Gaia data release. Specifies which REF_EPOCH to use.

• maglim (float, optional) – Only return Gaia objects brighter than maglim in any Gaia band. Speed-up that also saves memory when matching to bright objects. Objects for which there aren’t matches will be returned with all zero/null quantities.

• nside (int, optional) – The HEALPixel nside number used to organize the match. Defaults to a sixteenth of the resolution of the _get_gaia_nside() used to read Gaia files, which seems quick for lightweight=True.

• lightweight (bool, optional, defaults to False) – If True search for and use the “lightweight” version of the Gaia files made by, e.g., make_gaia_light_dr3(). These only contain Gaia objects brighter than 16th mag so are speedier for discarding objects near bright sources.

• verbose (bool, optional, defaults to False) – If True, log progress messages to screen.

Returns:

Gaia information for each matching object, in a format like dr3datamodelfull.

Return type:

ndarray

Notes

• Returned objects correspond row-by-row to objs.

• For objects that do NOT have a match in Gaia, the “REF_ID” column is set to -1, and all other columns are zero.

• Passing maglim might return different objects as well as speeding up the code. This is because matches will only be performed to brighter objects and their could be a bright object in the match radius farther away than a fainter object.

desitarget.gaiamatch.match_gaia_to_primary_single(objs, matchrad=0.2, dr='edr3')

Match ONE object to Gaia “chunks” files and return the Gaia information.

Parameters:

• objs (ndarray) – Must contain at least “RA” and “DEC”. MUST BE A SINGLE ROW.

• matchrad (float, optional, defaults to 0.2 arcsec) – The matching radius in arcseconds.

• dr (str, optional, defaults to “edr3”) – Name of a Gaia data release. Options are “dr2”, “edr3”, “dr3”. Specifies which REF_EPOCH to use for matching and the output data model.

Returns:

The matching Gaia information for the object, where the returned format and columns correspond to desitarget.secondary.gaiadatamodel

Return type:

ndarray

Notes

• If the object does NOT have a match in the Gaia files, the “REF_ID” column is set to -1, and all other columns are zero

• After running targets for the DESI Main Survey (i.e. starting with Gaia DR3) a minor bug was identified where a match within matchrad was returned that wasn’t necessarily the CLOSEST match for instances of very close Gaia pairs. Therefore, for releases subsequent to Gaia DR3, this function is modified to always find the CLOSEST Gaia match rather than just ANY match that satisfies the matchrad constraint.

desitarget.gaiamatch.pop_gaia_columns(inarr, popcols)

Convenience function to pop columns off an input array.

Parameters:

• inarr (ndarray) – Structured array with various column names.

• popcols (list) – List of columns to remove from the input array.

Returns:

Input array with columns in cols removed.

Return type:

ndarray

desitarget.gaiamatch.pop_gaia_coords(inarr)

Pop (DR2 and/or EDR3) GAIA_RA and GAIA_DEC columns off an array.

Parameters:

inarr (ndarray) – Structured array with various column names.

Returns:

Input array with Gaia RA/Dec columns removed.

Return type:

ndarray

desitarget.gaiamatch.read_gaia_file(filename, header=False, addobjid=False, dr='dr2', lightweight=False)

Read in a Gaia healpix file in the appropriate format for desitarget.

Parameters:

• filename (str) – File name of a single Gaia “healpix-” file.

• header (bool, optional, defaults to False) – If True then return (data, header) instead of just data.

• addobjid (bool, optional, defaults to False) – Include, in the output, two additional columns. A column “GAIA_OBJID” that is the integer number of each row read from file and a column “GAIA_BRICKID” that is the integer number of the file itself.

• dr (str, optional, defaults to “dr2”) – Name of a Gaia data release. Options are “dr2”, “edr3”, “dr3”. Used to format the output data model.

• lightweight (bool, optional, defaults to False) – If True search for and use the “lightweight” version of the Gaia files made by, e.g., make_gaia_light_dr3(). These only contain Gaia objects brighter than 16th mag so are speedier for discarding objects near bright sources.

Returns:

Gaia data in targeting format (upper-case etc.) with the columns corresponding to, e.g., desitarget.gaiamatch.gaiadatamodel.

Return type:

ndarray

Notes

• A better location for this might be in desitarget.io?

desitarget.gaiamatch.scrape_gaia(dr='dr2', nfiletest=None)

Retrieve the bulk CSV files released by the Gaia collaboration.

Parameters:

• dr (str, optional, defaults to “dr2”) – Name of a Gaia data release. Options are “dr2”, “edr3”, “dr3”. For “edr3” the directory used is actually $GAIA_DIR/../gaia_edr3 For “dr3” the directory used is actually $GAIA_DIR/../gaia_dr3

• nfiletest (int, optional, defaults to None) – If an integer is sent, only retrieve this number of files, for testing.

Returns:

But the archived Gaia CSV files are written to $GAIA_DIR/csv. For “edr3” the directory actually written to is $GAIA_DIR/../gaia_edr3. For “dr3” the written directory is $GAIA_DIR/../gaia_dr3.

Return type:

Nothing

Notes

• The environment variable $GAIA_DIR must be set.

• Runs in about 26 hours for 61,234 Gaia DR2 files.

• Runs in about 19 hours for 3,386 Gaia EDR3 files.

desitarget.gaiamatch.sub_gaia_edr3(filename, objs=None, suball=False)

Substitute Gaia EDR3 “astrometric” columns into DR9 sweeps.

Parameters:

• filename (str) – Full path to a sweeps file e.g. legacysurvey/dr9/south/sweep/9.0/sweep-210p015-220p020.fits.

• objs (array_like, optional, defaults to None) – The contents of filename. If None, read from filename.

• suball (bool, optional, defaults to False) – If True substitute all of the Gaia EDR3 columns, not just the “astrometric” set used for targeting.

Returns:

objs (or the contents of filename) is returned but with the PARALLAX, PARALLAX_IVAR, PMRA, PMRA_IVAR, PMDEC, PMDEC_IVAR columns substituted with their Gaia EDR3 values.

Return type:

array_like

Notes

• The GAIA_DIR environment variable must be set.

• The input objs will be altered (it it is not None).

desitarget.gaiamatch.unextinct_gaia_mags(G, Bp, Rp, ebv, scaling=0.86)

Correct gaia magnitudes based for dust.

Parameters:

• G (array_like or :class`float`) – Gaia-based G MAGNITUDE (not Galactic-extinction-corrected).

• Bp (array_like or :class`float`) – Gaia-based Bp MAGNITUDE (not Galactic-extinction-corrected).

• Rp (array_like or :class`float`) – Gaia-based Rp MAGNITUDE (not Galactic-extinction-corrected).

• ebv (array_like or :class`float`) – E(B-V) values from the SFD dust maps.

• scaling (int) – Multiply ebv by this scaling factor. Set to 0.86 to apply Schlafly & Finkbeiner (2011) correction.

Returns:

• :class:`array_like` or (class`float`) – Gaia-based G MAGNITUDE (with Galactic-extinction correction).

• :class:`array_like` or (class`float`) – Gaia-based Bp MAGNITUDE (not Galactic-extinction correction).

• :class:`array_like` or (class`float`) – Gaia-based Rp MAGNITUDE (not Galactic-extinction correction).

Notes

• See eqn1/tab1 of Gaia Collaboration/Babusiaux et al. (2018).

• First version borrowed shamelessly from Sergey Koposov.

desitarget.gaiamatch.write_gaia_matches(infiles, numproc=4, outdir='.', matchrad=0.2, dr='edr3', merge=False)

Match sweeps files to Gaia and rewrite with the Gaia columns added

Parameters:

• infiles (list or str) – A list of input filenames (sweep files) OR a single filename. The files must contain at least the columns “RA” and “DEC”.

• numproc (int, optional, defaults to 4) – The number of parallel processes to use.

• outdir (str, optional, default to the current directory) – The directory to write the files.

• matchrad (float, optional, defaults to 0.2 arcsec) – The matching radius in arcseconds.

• dr (str, optional, defaults to “edr3”) – Name of a Gaia data release. Options are “dr2”, “edr3”

• merge (bool, optional, defaults to False) – If True, merge the Gaia columns into the original sweeps file. Otherwise, just write the Gaia columns.

Returns:

But columns in gaiadatamodel or edr3datamodel that match the input sweeps files are written to file (if merge=False) or written after merging with the input sweeps columns (if merge=True). The output filename is the input filename with “.fits” replaced by “-gaia$DRmatch.fits”, where $DR is dr.

Return type:

Nothing

Notes

• if numproc==1, use the serial code instead of the parallel code.

• The environment variable $GAIA_DIR must be set.

desitarget.geomask

Utility functions for geometry on the sky, masking, matching, etc.

desitarget.geomask.add_hp_neighbors(nside, pixnum)

Add all neighbors in the NESTED scheme to a set of HEALPixels.

Parameters:

• nside (int) – (NESTED) HEALPixel nside.

• pixnum (list or int or ~numpy.ndarray) – HEALPixel numbers (or a single HEALPixel number).

Returns:

The passed list of pixels with all neighbors added to the list. Only unique pixels are returned, so any duplicate integers in the passed pixnum are removed.

Return type:

list

Notes

• Syntactic sugar around healpy.pixelfunc.get_all_neighbours().

desitarget.geomask.box_area(radecbox)

Determines the area of an RA, Dec box in square degrees.

Parameters:

radecbox (list) – 4-entry list of coordinates [ramin, ramax, decmin, decmax] forming the edges of a box in RA/Dec (degrees).

Returns:

The area of the passed box in square degrees.

Return type:

list

desitarget.geomask.brick_names_touch_hp(nside, numproc=1, fact=1048576)

Determine which of a set of brick names touch a set of HEALPixels.

Parameters:

• nside (int) – (NESTED) HEALPixel nside.

• numproc (int, optional, defaults to 1) – The number of parallel processes to use.

• fact (int, optional defaults to 2**20) – see documentation for healpy.query_polygon().

Returns:

A list of lists of input brick names that touch each HEALPixel at nside. So, e.g. for nside=2 the returned list will have 48 entries, and, for example, output[0] will be a list of names of bricks that touch HEALPixel 0.

Return type:

list

Notes

• Runs in ~65 (10) secs for numproc=1 (32) at nside=2 (fact=4).

• Runs in ~325 (20) secs for numproc=1 (32) at nside=64 (fact=4).

• Takes ~2x as long at the default fact=2**20 compared to fact=4, but fact=2**20 returns far fewer bricks for small nside.

desitarget.geomask.bundle_bricks(pixnum, maxpernode, nside, brickspersec=1.0, prefix='targets', gather=False, surveydirs=None, extra=None, seed=None, nchunks=10)

Determine the optimal packing for bricks collected by HEALpixel integer.

Parameters:

• pixnum (np.array) – List of integers, e.g., HEALPixel numbers occupied by a set of bricks (e.g. array([16, 16, 16…12 , 13, 19]) ).

• maxpernode (int) – The maximum number of pixels to bundle (e.g., if you were trying to pass maxpernode bricks, delineated by the HEALPixels they occupy, parallelized across a set of nodes).

• nside (int) – The HEALPixel nside number that was used to generate pixnum (NESTED scheme).

• brickspersec (float, optional, defaults to 1.) – The rough number of bricks processed per second by the code (parallelized across a chosen number of nodes)

• prefix (str, optional, defaults to ‘targets’) – Corresponds to the executable “X” that is run as select_X for a target type. This could be ‘randoms’, ‘skies’, ‘targets’, ‘gfas’. Also, ‘supp-skies’ can be passed to cover supplemental skies.

• gather (bool, optional, defaults to False) – If True add a command to combine all the HEALPix-split files into one large file. If False, do not provide that command. ONLY creates correct file names to gather RANDOMS files!

• surveydirs (list) – Root directories for a Legacy Surveys Data Release. Item 1 is used as the main directory. IF the list is length-2 then the second directory is added as “-s2” in the output script (e.g. [“/global/project/projectdirs/cosmo/data/legacysurvey/dr6”]).

• extra (str, optional) – Extra command line flags to be passed to the executable lines in the output slurm script.

• seed (int, optional, defaults to 1) – Random seed for file name. Only relevant for prefix=’randoms’.

• nchunks (int, optional, defaults to 10) – Number of smaller catalogs to split the random catalog into. Only relevant for prefix=’randoms’.

Returns:

• Nothing, but prints commands that would facilitate running a set of

• bricks by HEALPixel integer with the total number of bricks not to

• exceed maxpernode. Also prints total bricks on each node.

Notes

• For the packing algorithm see this post on Stack Overflow.

desitarget.geomask.cap_area(theta)

True area of a circle of a given radius drawn on the surface of a sphere

Parameters:

theta (array_like) – (angular) radius of a circle drawn on the surface of the unit sphere (in DEGREES)

Returns:

area – surface area on the sphere included within the passed angular radius

Return type:

array_like

Notes

• The approximate formula pi*theta**2 is only accurate to ~0.0025% at 1o, ~0.25% at 10o, sufficient for bright source mask purposes. But the equation in this function is more general.

• We recast the input array as float64 to circumvent precision issues with np.cos() when radii of only a few arcminutes are passed

• Even for passed radii of 1 (0.1) arcsec, float64 is sufficiently precise to give the correct area to ~0.00043 (~0.043%) using np.cos()

desitarget.geomask.check_nside(nside)

Flag an error if nside is not OK for NESTED HEALPixels.

Parameters:

nside (int or ~numpy.ndarray) – The HEALPixel nside number (NESTED scheme) or an array of such numbers.

Return type:

Nothing, but raises a ValueRrror for a bad nside.

desitarget.geomask.circle_boundaries(RAcens, DECcens, r, nloc)

Return RAs/Decs of a set of circular boundaries on the sky

Parameters:

• RAcens (ndarray) – Right Ascension of the centers of the circles (DEGREES)

• DECcens (ndarray) – Declination of the centers of the circles (DEGREES)

• r (ndarray) – radius of the circles (ARCSECONDS)

• nloc (ndarray) – the number of locations to generate, equally spaced around the periphery of each circle

Returns:

• ras (ndarray) –

  The Right Ascensions of nloc equally spaced locations on the

  periphery of the mask

• dec (array_like.) –

  The Declinations of nloc equally space locations on the periphery

  of the mask

desitarget.geomask.circles(x, y, s, c='b', vmin=None, vmax=None, **kwargs)

Make a scatter plot of circles. Similar to plt.scatter, but the size of circles are in data scale

Parameters:

• x (scalar or array_like, shape (n, )) – Input data

• y (scalar or array_like, shape (n, )) – Input data

• s (scalar or array_like, shape (n, )) – Radius of circles.

• c (color or sequence of color, optional, default : 'b') – c can be a single color format string, or a sequence of color specifications of length N, or a sequence of N numbers to be mapped to colors using the cmap and norm specified via kwargs. Note that c should not be a single numeric RGB or RGBA sequence because that is indistinguishable from an array of values to be colormapped. (If you insist, use color instead.) c can be a 2-D array in which the rows are RGB or RGBA, however.

• vmin (scalar, optional, default: None) – vmin and vmax are used in conjunction with norm to normalize luminance data. If either are None, the min and max of the color array is used.

• vmax (scalar, optional, default: None) – vmin and vmax are used in conjunction with norm to normalize luminance data. If either are None, the min and max of the color array is used.

• kwargs (~matplotlib.collections.Collection properties) – Eg. alpha, edgecolor(ec), facecolor(fc), linewidth(lw), linestyle(ls), norm, cmap, transform, etc.

Returns:

paths

Return type:

~matplotlib.collections.PathCollection

Examples

>>> a = np.arange(11)
>>> circles(a, a, s=a*0.2, c=a, alpha=0.5, ec='none')
>>> plt.colorbar()

References

With thanks to https://gist.github.com/syrte/592a062c562cd2a98a83

desitarget.geomask.dr9_or_dr11_brick_file(surveybrickfn, dr9nfn, dr9sfn, dr11fn, threshfrac=0.25, outfn=None)

From DR9/DR11 brick files, determine which bricks are in DR9/DR11.

Parameters:

• surveybrickfn (str) – Root path to a Legacy Surveys general brick file, e.g., at NERSC, /global/cfs/cdirs/cosmo/data/legacysurvey/dr11/survey-bricks.fits.gz

• dr9nfn (str) – Root path to a DR9 north NEXP all bricks file, as made by dr_nexp_all_bricks()

• dr9sfn (str) – Root path to a DR9 south NEXP all bricks file, as made by dr_nexp_all_bricks()

• dr11fn (str) – Root path to a DR11 NEXP all bricks file, as made by dr_nexp_all_bricks()

• threshfrac (float, optional, defaults to 0.25) – Threshold by which a DR11 brick has to exceed a DR9 brick in terms of the fraction of area covered by at least one observation in all the g, r, z filters (FALLPRIMGE1 in the NEXP all bricks files).

• outfn (str, optional, defaults to None) – If passed, write the output array to this file path.

Returns:

Brick file that resembles surveybrickfn but with FALLPRIMGE1 added for DR9 north (DR9N), DR9 south (DR9S) and DR11 (see dr_nexp_per_brick() for an explanation of this parameter) and DRVERSION added, which is (9) 11 for a DR9 (DR11) brick.

Return type:

ndarray

desitarget.geomask.dr_nexp_all_bricks(drdir, numproc=1, outfn=None)

Find number of exposures in all bricks of an imaging data release.

Parameters:

• drdir (str) – Root path to an LS imaging data release directory, e.g. /global/cfs/cdirs/cosmo/data/legacysurvey/dr9/south/ at NERSC.

• numproc (int, optional, defaults to 1) – The number of parallel processes to use. numproc=128 results in approximately 100 bricks being processed per second.

• outfn (str, optional, defaults to None) – If passed, write the output array to this file path.

Returns:

Array of information for all bricks in the passed data release. See dr_nexp_per_brick() for the returned columns.

Return type:

ndarray

desitarget.geomask.dr_nexp_per_brick(brickpath)

Find number of exposures in one brick of an imaging data release.

Parameters:

brickpath (str) – Path to a brick directory from an LS imaging data release, e.g. /global/cfs/cdirs/cosmo/data/legacysurvey/dr9/south/coadd/000/0001m322 at NERSC.

Returns:

An array of information for the passed brick, including: BRICKNAME: Name of the brick. NPIXPRIM: Number of pixels in the primary LS area of the brick. NGPIXPRIMGE1: Number of pixels in g filter with >= 1 exposure. NGPIXPRIMGE2: Number of pixels in g filter with >= 2 exposures. NGPIXPRIMGE3: Number of pixels in g filter with >= 3 exposures. NRPIXPRIMGE1: Number of pixels in r filter with >= 1 exposure. NRPIXPRIMGE2: Number of pixels in r filter with >= 2 exposures. NRPIXPRIMGE3: Number of pixels in r filter with >= 3 exposures. NZPIXPRIMGE1: Number of pixels in z filter with >= 1 exposure. NZPIXPRIMGE2: Number of pixels in z filter with >= 2 exposures. NZPIXPRIMGE3: Number of pixels in z filter with >= 3 exposures. NALLPRIMGE1: Number of pixels in all filters with >= 1 exposure. NALLPRIMGE2: Number of pixels in all filters with >= 2 exposures. NALLPRIMGE3: Number of pixels in all filters with >= 3 exposures. FALLPRIMGE1: Pixel fraction in all filters with >= 1 exposure. (i.e. NALLPRIMGE1/NPIXPRIM). FALLPRIMGE2: Pixel fraction in all filters with >= 2 exposures. FALLPRIMGE3: Pixel fraction in all filters with >= 3 exposures.

Return type:

ndarray

desitarget.geomask.ellipse_boundary(RAcen, DECcen, r, e1, e2, nloc=50)

Return RA/Dec of an elliptical boundary on the sky

Parameters:

• RAcen (float) – Right Ascension of the center of the ellipse (DEGREES)

• DECcen (float) – Declination of the center of the ellipse (DEGREES)

• r (float) – Half-light radius of the ellipse (ARCSECONDS)

• e1 (float) – First ellipticity component of the ellipse

• e2 (float) – Second ellipticity component of the ellipse

• nloc (int, optional, defaults to 50) – the number of locations to generate, equally spaced around the periphery of the ellipse

Returns:

• ndarray – Right Ascensions along the boundary of (each) ellipse

• ndarray – Declinations along the boundary of (each) ellipse

Notes

• The parametrization is explained at

  http://legacysurvey.org/dr4/catalogs/

• Much of the math is taken from:

  https://github.com/dstndstn/tractor/blob/master/tractor/ellipses.py

desitarget.geomask.ellipse_matrix(r, e1, e2)

Calculate transformation matrix from half-light-radius to ellipse

Parameters:

• r (float or ~numpy.ndarray) – Half-light radius of the ellipse (ARCSECONDS)

• e1 (float or ~numpy.ndarray) – First ellipticity component of the ellipse

• e2 (float or ~numpy.ndarray) – Second ellipticity component of the ellipse

Returns:

A 2x2 matrix to transform points measured in coordinates of the effective-half-light-radius to RA/Dec offset coordinates

Return type:

ndarray

Notes

• If a float is passed then the output shape is (2,2,1)

  otherwise it’s (2,2,len(r))

• The parametrization is explained at

  http://legacysurvey.org/dr4/catalogs/

• Much of the math is taken from:

  https://github.com/dstndstn/tractor/blob/master/tractor/ellipses.py

desitarget.geomask.ellipses(x, y, w, h=None, rot=0.0, c='b', vmin=None, vmax=None, **kwargs)

Make a scatter plot of ellipses

Parameters:

• x (scalar or array_like, shape (n, )) – Center of ellipses.

• y (scalar or array_like, shape (n, )) – Center of ellipses.

• w (scalar or array_like, shape (n, )) – Total length (diameter) of horizontal/vertical axis. h is set to be equal to w by default, ie. circle.

• h (scalar or array_like, shape (n, )) – Total length (diameter) of horizontal/vertical axis. h is set to be equal to w by default, ie. circle.

• rot (scalar or array_like, shape (n, )) – Rotation in degrees (anti-clockwise).

• c (color or sequence of color, optional, default : 'b') – c can be a single color format string, or a sequence of color specifications of length N, or a sequence of N numbers to be mapped to colors using the cmap and norm specified via kwargs. Note that c should not be a single numeric RGB or RGBA sequence because that is indistinguishable from an array of values to be colormapped. (If you insist, use color instead.) c can be a 2-D array in which the rows are RGB or RGBA, however.

• vmin (scalar, optional, default: None) – vmin and vmax are used in conjunction with norm to normalize luminance data. If either are None, the min and max of the color array is used.

• vmax (scalar, optional, default: None) – vmin and vmax are used in conjunction with norm to normalize luminance data. If either are None, the min and max of the color array is used.

• kwargs (~matplotlib.collections.Collection properties) – Eg. alpha, edgecolor(ec), facecolor(fc), linewidth(lw), linestyle(ls), norm, cmap, transform, etc.

Returns:

paths

Return type:

~matplotlib.collections.PathCollection

Examples

>>> a = np.arange(11)
>>> ellipses(a, a, w=4, h=a, rot=a*30, c=a, alpha=0.5, ec='none')
>>> plt.colorbar()

References

With thanks to https://gist.github.com/syrte/592a062c562cd2a98a83

desitarget.geomask.get_default_maskbits(bgs=False, mws=False, dr11=False)

Return the names of the default MASKBITS for targets.

Parameters:

• bgs (bool, defaults to False.) – If True load the “default” scheme for Bright Galaxy Survey targets. Otherwise, load the default for other target classes.

• mws (bool, defaults to False.) – If True load the “default” scheme for Milky Way Survey targets. Otherwise, load the default for other target classes.

• dr11 (bool, defaults to False.) – If True use default MASKBITS for DR11 instead of pre-DR11.

Returns:

A list of the default MASKBITS names for targets.

Return type:

list

Notes

• Only one of bgs or mws can be True.

desitarget.geomask.get_imaging_maskbits(bitnamelist=None)

Return MASKBITS names and bits from the Legacy Surveys.

Parameters:

bitnamelist (list, optional, defaults to None) – If not None, return the bit values corresponding to the passed names. Otherwise, return the full MASKBITS dictionary.

Returns:

A list of the MASKBITS values if bitnamelist is passed, otherwise the full MASKBITS dictionary of names-to-values.

Return type:

list or dict

Notes

• For the definitions of the mask bits, see, e.g., https://www.legacysurvey.org/dr8/bitmasks/#maskbits

desitarget.geomask.hp_beyond_gal_b(nside, mingalb, neighbors=True)

Find HEALPixels with centers and neighbors beyond a Galactic b.

Parameters:

• nside (int) – (NESTED) HEALPixel nside.

• mingalb (float) – Closest latitude to Galactic plane to return HEALPixels (e.g. send 10 to limit to pixels beyond -10o <= b < 10o).

• neighbors (bool, optional, defaults to True) – If False, return all HEALPixels with centers beyond the passed mingalb. If True also return the neighbors of these pixels (to avoid edge effects).

Returns:

HEALPixels at the passed nside that lie north and south of the passed mingalb.

Return type:

list

Notes

• Pixels are in the NESTED scheme.

desitarget.geomask.hp_in_box(nside, radecbox, inclusive=True, fact=4)

Determine which HEALPixels touch an RA, Dec box.

Parameters:

• nside (int) – (NESTED) HEALPixel nside.

• radecbox (list) – 4-entry list of coordinates [ramin, ramax, decmin, decmax] forming the edges of a box in RA/Dec (degrees).

• inclusive (bool, optional, defaults to True) – see documentation for healpy.query_polygon().

• fact (int, optional defaults to 4) – see documentation for healpy.query_polygon().

Returns:

HEALPixels at the passed nside that touch the RA/Dec box.

Return type:

list

Notes

• Uses healpy.query_polygon() to retrieve the RA geodesics and then hp_in_dec_range() to limit by Dec.

• When the RA range exceeds 180o, healpy.query_polygon() defines the range as that with the smallest area (i.e the box can wrap-around in RA). To avoid any ambiguity, this function will only limit by the passed Decs in such cases.

• Only strictly correct for Decs from -90+1e-3(o) to 90-1e3(o).

desitarget.geomask.hp_in_cap(nside, radecrad, inclusive=True, fact=4)

Determine which HEALPixels touch an RA, Dec, radius cap.

Parameters:

• nside (int) – (NESTED) HEALPixel nside.

• radecrad (list, defaults to None) – 3-entry list of coordinates [ra, dec, radius] forming a cap or “circle” on the sky. ra, dec and radius are all in degrees.

• inclusive (bool, optional, defaults to True) – see documentation for healpy.query_disc().

• fact (int, optional defaults to 4) – see documentation for healpy.query_disc().

Returns:

A list of HEALPixels at the passed nside that touch the cap.

Return type:

list

Notes

• Just syntactic sugar around healpy.query_disc().

desitarget.geomask.hp_in_dec_range(nside, decmin, decmax, inclusive=True)

HEALPixels in a specified range of Declination.

Parameters:

• nside (int) – (NESTED) HEALPixel nside.

• decmin (float) – Declination range (degrees).

• decmax (float) – Declination range (degrees).

• inclusive (bool, optional, defaults to True) – see documentation for healpy.query_strip().

Returns:

(Nested) HEALPixels at nside in the specified Dec range.

Return type:

list

Notes

• Just syntactic sugar around healpy.query_strip().

• healpy.query_strip() isn’t implemented for the NESTED scheme in early healpy versions, so this queries in the RING scheme and then converts to the NESTED scheme.

desitarget.geomask.imaging_mask(maskbits, bitnamelist=['BRIGHT', 'GALAXY', 'CLUSTER'], bgsmask=False, mwsmask=False)

Apply the ‘geometric’ masks from the Legacy Surveys imaging.

Parameters:

• maskbits (ndarray or None) – General array of Legacy Surveys mask bits.

• bitnamelist (list, defaults to func:get_default_maskbits()) – List of Legacy Surveys mask bits to set to False.

• bgsmask (bool, defaults to False.) – Load the “default” scheme for Bright Galaxy Survey targets. Overrides bitnamelist.

• bgsmask – Load the “default” scheme for Milky Way Survey targets. Overrides bitnamelist.

Returns:

A boolean array that is the same length as maskbits that contains False where any bits in bitnamelist are set.

Return type:

ndarray

Notes

• Only one of bgsmask or mwsmask can be True.

desitarget.geomask.is_in_box(objs, radecbox)

Determine which of an array of objects are inside an RA, Dec box.

Parameters:

• objs (ndarray) – An array of objects. Must include at least the columns “RA” and “DEC”.

• radecbox (list) – 4-entry list of coordinates [ramin, ramax, decmin, decmax] forming the edges of a box in RA/Dec (degrees).

Returns:

True for objects in the box, False for objects outside of the box.

Return type:

ndarray

Notes

• Tests the minimum RA/Dec with >= and the maximum with <

desitarget.geomask.is_in_cap(objs, radecrad)

Determine which of an array of objects lie inside an RA, Dec, radius cap.

Parameters:

• objs (ndarray) – An array of objects. Must include at least the columns “RA” and “DEC”.

• radecrad (list, defaults to None) – 3-entry list of coordinates [ra, dec, radius] forming a cap or “circle” on the sky. ra, dec and radius are all in degrees.

Returns:

True for objects in the cap, False for objects outside of the cap.

Return type:

ndarray

Notes

• Tests the separation with <=, so include objects on the cap boundary.

• See also is_in_circle() which handles multiple caps.

desitarget.geomask.is_in_circle(ras, decs, RAcens, DECcens, r)

Whether a set of points is in a set of circular masks on the sky.

Parameters:

• ras (ndarray) – Array of Right Ascensions to test.

• decs (ndarray) – Array of Declinations to test.

• RAcen (ndarray) – Right Ascension of the centers of the circles (DEGREES).

• DECcen (ndarray) – Declination of the centers of the circles (DEGREES).

• r (ndarray) – Radius of the circles (ARCSECONDS).

Returns:

An array that is the same length as RA/Dec that is True for points that are in any of the masks and False for points that are not in any of the masks.

Return type:

boolean

desitarget.geomask.is_in_ellipse(ras, decs, RAcen, DECcen, r, e1, e2)

Determine whether points lie within an elliptical mask on the sky

Parameters:

• ras (ndarray) – Array of Right Ascensions to test

• decs (ndarray) – Array of Declinations to test

• RAcen (float) – Right Ascension of the center of the ellipse (DEGREES)

• DECcen (float) – Declination of the center of the ellipse (DEGREES)

• r (float) – Half-light radius of the ellipse (ARCSECONDS)

• e1 (float) – First ellipticity component of the ellipse

• e2 (float) – Second ellipticity component of the ellipse

Returns:

An array that is the same length as RA/Dec that is True for points that are in the mask and False for points that are not in the mask

Return type:

boolean

Notes

• The parametrization is explained at

  http://legacysurvey.org/dr4/catalogs/

• Much of the math is taken from:

  https://github.com/dstndstn/tractor/blob/master/tractor/ellipses.py

desitarget.geomask.is_in_ellipse_matrix(ras, decs, RAcen, DECcen, G)

Determine whether points lie within an elliptical mask on the sky

Parameters:

• ras (ndarray) – Array of Right Ascensions to test

• decs (ndarray) – Array of Declinations to test

• RAcen (float) – Right Ascension of the center of the ellipse (DEGREES)

• DECcen (float) – Declination of the center of the ellipse (DEGREES)

• G (ndarray) – A 2x2 matrix to transform points measured in coordinates of the effective-half-light-radius to RA/Dec offset coordinates as generated by, e.g., desitarget.geomask.ellipse_matrix

Returns:

An array that is the same length as ras/decs that is True for points that are in the mask and False for points that are not in the mask

Return type:

boolean

Notes

• The parametrization is explained at

  http://legacysurvey.org/dr4/catalogs/

• Much of the math is taken from:

  https://github.com/dstndstn/tractor/blob/master/tractor/ellipses.py

• G should have a shape of (2,2) (i.e. np.shape(G) gives (2,2)

desitarget.geomask.is_in_gal_box(objs, lbbox, radec=False)

Determine which of an array of objects are in a Galactic l, b box.

Parameters:

• objs (ndarray or list) – An array of objects. Must include at least the columns “RA” and “DEC”.

• radecbox (list) – 4-entry list of coordinates [lmin, lmax, bmin, bmax] forming the edges of a box in Galactic l, b (degrees).

• radec (bool, optional, defaults to False) – If True then the passed objs is an [RA, Dec] list instead of a rec array.

Returns:

True for objects in the box, False for objects outside of the box.

Return type:

ndarray

Notes

• Tests the minimum l/b with >= and the maximum with <

desitarget.geomask.is_in_hp(objs, nside, pixlist, radec=False)

Determine which of an array of objects lie inside a set of HEALPixels.

Parameters:

• objs (ndarray) – Array of objects. Must include at columns “RA” and “DEC”.

• nside (int) – The HEALPixel nside number (NESTED scheme).

• pixlist (list or int or ~numpy.ndarray) – The list of HEALPixels in which to find objects.

• radec (bool, optional, defaults to False) – If True objs is an [RA, Dec] list instead of a rec array.

Returns:

True for objects in pixlist, False for other objects.

Return type:

ndarray

desitarget.geomask.match(A, B, check_for_dups=True)

Return matching indexes for two arrays on a unique key.

Parameters:

• A (ndarray or list) – An array of integers.

• B (ndarray or list) – An array of integers.

• check_for_dups (bool, optional, defaults to True) – If True trigger an exception if there are duplicates in either of the A or B arrays. Passing False for check_for_dups isn’t recommended, but is retained to facilitate comparisons against earlier versions of the function.

Returns:

• ndarray – The integer indexes in A that match to B.

• ndarray – The integer indexes in B that match to A.

Notes

• Result should be such that for Aii, Bii = match(A, B) np.all(A[Aii] == B[Bii]) is True.

• Only works if there is a unique mapping from A->B, i.e if A and B do NOT contain duplicates. This is explicitly checked if check_for_dups is True

• h/t Anand Raichoor by way of Stack Overflow.

desitarget.geomask.match_to(A, B, check_for_dups=True)

Return indexes where B matches A, holding A in place.

Parameters:

• A (ndarray or list) – Array of integers to match TO.

• B (ndarray or list) – Array of integers matched to A

• check_for_dups (bool, optional, defaults to True) – If True trigger an exception if there are duplicates in either of the A or B arrays. Passing False for check_for_dups isn’t recommended, but is retained to facilitate comparisons against earlier versions of the function.

Returns:

The integer indexes in A that B matches to.

Return type:

ndarray

Notes

• Result should be such that for ii = match_to(A, B) np.all(A[ii] == B) is True.

• We’re looking up locations of B in A so B can be a shorter array than A (provided the B->A matches are unique) but A cannot be a shorter array than B.

desitarget.geomask.nside2nside(nside, nsidenew, pixlist)

Change a list of HEALPixel numbers to a different NSIDE.

Parameters:

• nside (int) – The current HEALPixel nside number (NESTED scheme).

• nsidenew (int) – The new HEALPixel nside number (NESTED scheme).

• pixlist (list or ~numpy.ndarray) – The list of HEALPixels to be changed.

Returns:

The altered list of HEALPixels.

Return type:

ndarray

Notes

• The size of the input list will be altered. For instance, nside=2, pixlist=[0,1] is covered by only pixel [0] at nside=1 but by pixels [0, 1, 2, 3, 4, 5, 6, 7] at nside=4.

• Doesn’t check that the passed pixels are valid at nside.

desitarget.geomask.pixarea2nside(area)

Closest HEALPix nside for a given area.

Parameters:

area (float) – area in square degrees.

Returns:

HEALPix nside that corresponds to passed area.

Return type:

int

Notes

• Only considers 2**x nside values (1, 2, 4, 8 etc.)

desitarget.geomask.radec_match_to(matchto, objs, sep=1.0, radec=False, return_sep=False)

Match objects to a catalog list on RA/Dec.

Parameters:

• matchto (ndarray or list) – Coordinates to match TO. Must include columns “RA” and “DEC”.

• objs (ndarray or list) – Objects matched to matchto. Must include “RA” and “DEC”.

• sep (float, defaults to 1 arcsecond) – Separation at which to match objs to matchto in ARCSECONDS.

• radec (bool, optional, defaults to False) – If True then objs and matchto are [RA, Dec] lists instead of rec arrays.

• return_sep (bool, optional, defaults to False) – If True then return the separation between each object, not just the indexes of the match.

Returns:

• ndarray (of integers) – Indexes in matchto where objs matches matchto at < sep.

• ndarray (of integers) – Indexes in objs where objs matches matchto at < sep.

• ndarray (of floats) – The distances in ARCSECONDS of the matches. Only returned if return_sep is True.

Notes

• Sense is important. Every coordinate pair in objs is matched to matchto, but NOT every coordinate pair in matchto is matched to objs. matchto is the “parent” catalog being matched to, i.e. we’re looking for the instances where objs has a match in matchto. The array of returned indexes thus can’t be longer than objs. Consider this example:

  >>> mainra, maindec = [100], [30]
  >>> ras, decs = [100, 100, 100], [30, 30, 30]
  >>>
  >>> radec_match_to([mainra, maindec], [ras, decs], radec=True)
  >>> Out: (array([0, 0, 0]), array([0, 1, 2]))
  >>>
  >>> radec_match_to([ras, decs], [mainra, maindec], radec=True)
  >>> Out: (array([0]), array([0]))
  

• Only returns the CLOSEST match within sep arcseconds.

desitarget.geomask.rewind_coords(ranow, decnow, pmra, pmdec, epochnow=2015.5, epochnowdec=None, epochpast=1991.5, epochpastdec=None)

Shift coordinates into the past based on proper motions.

Parameters:

• ranow (flt or ~numpy.ndarray) – Right Ascension (degrees) at “current” epoch.

• decnow (flt or ~numpy.ndarray) – Declination (degrees) at “current” epoch.

• pmra (flt or ~numpy.ndarray) – Proper motion in RA (mas/yr).

• pmdec (flt or ~numpy.ndarray) – Proper motion in Dec (mas/yr).

• epochnow (flt or ~numpy.ndarray, optional) – The “current” epoch (years). Defaults to Gaia DR2 (2015.5).

• epochnowdec (flt or ~numpy.ndarray, optional) – If passed and not None then epochnow is interpreted as the epoch of the RA and this is interpreted as the epoch of the Dec.

• epochpast (flt or ~numpy.ndarray, optional) – Epoch in the past (years). Defaults to Tycho DR2 mean (1991.5).

• epochpastdec (flt or ~numpy.ndarray, optional) – If passed and not None then epochpast is interpreted as the epoch of the RA and this is interpreted as the epoch of the Dec.

Returns:

• ndarray – Right Ascension in the past (degrees).

• ndarray – Declination in the past (degrees).

Notes

• All output RAs will be in the range 0 < RA < 360o.

• Only called “rewind_coords” to correspond to the default epochnow > epochpast. “fast forwarding” works fine, too, i.e., you can pass epochpast > epochnow to move coordinates to a future epoch.

• Inaccurate to ~0.1” for motions as high as ~10”/yr (Barnard’s Star) after ~200 years because of the simplified cosdec term.

desitarget.geomask.shares_hp(nside, objs1, objs2, radec=False)

Check if arrays of objects occupy the same HEALPixels.

Parameters:

• nside (int) – HEALPixel nside integer (NESTED scheme).

• objs1 (ndarray or list) – First set of objects. Must include columns “RA” and “DEC”.

• objs (ndarray or list) – Second set of objects. Must include “RA” and “DEC”.

• radec (bool, optional, defaults to False) – If True then objs1 and objs2 are [RA, Dec] lists instead of rec arrays.

Returns:

• ndarray (of booleans) –

  True for objects in objs1 that share a HEALPixel with

  objects in objs2 at nside. Same length as objs1

• ndarray (of booleans) –

  True for objects in objs2 that share a HEALPixel with

  objects in objs1 at nside. Same length as objs2

desitarget.geomask.sphere_circle_ra_off(theta, centdec, declocs)

Offsets in RA needed for given declinations in order to draw a (small) circle on the sphere

Parameters:

• theta (float) – (angular) radius of a circle drawn on the surface of the unit sphere (in DEGREES)

• centdec (float) – declination of the center of the circle to be drawn on the sphere (in DEGREES)

• declocs (array_like) – declinations of positions on the boundary of the circle at which to calculate RA offsets (in DEGREES)

Returns:

raoff – offsets in RA that correspond to the passed dec locations for the given dec circle center (IN DEGREES)

Return type:

array_like

Notes

• This function is ambivalent to the SIGN of the offset. In other words, it can only draw the semi-circle in theta from -90o->90o, which corresponds to offsets in the POSITIVE RA direction. The user must determine which offsets are to the negative side of the circle, or call this function twice.

desitarget.geomask.sweep_files_touch_hp(nside, pixlist, infiles)

Determine which of a set of sweep files touch a set of HEALPixels.

Parameters:

• nside (int) – (NESTED) HEALPixel nside.

• pixlist (list or int) – A set of HEALPixels at nside.

• infiles (list or str) – A list of input (sweep filenames) OR a single filename.

Returns:

• list – A list of lists of input sweep files that touch each HEALPixel at nside. So, e.g. for nside=2 the returned list will have 48 entries, and, for example, output[0] will be a list of files that touch HEALPixel 0.

• list – The input pixlist reduced to just those pixels that touch the area covered by the input infiles.

• ndarray – A flattened array of all HEALPixels touched by the input infiles. Each HEALPixel will appear multiple times if it’s touched by multiple input sweep files.

desitarget.gfa

Guide/Focus/Alignment targets

desitarget.gfa.add_urat_pms(objs, numproc=4)

Add proper motions from URAT to a set of objects.

Parameters:

• objs (ndarray) – Array of objects to update. Must include the columns “PMRA”, “PMDEC”, “REF_ID” (unique per object) “URAT_ID” and “URAT_SEP”.

• numproc (int, optional, defaults to 4) – The number of parallel processes to use.

Returns:

The input array with the “PMRA”, PMDEC”, “URAT_ID” and “URAT_SEP” columns updated to include URAT information.

Return type:

ndarray

Notes

• Order is retained using “REF_ID”: The input and output arrays should have the same order.

desitarget.gfa.all_gaia_in_tiles(maglim=18, numproc=4, allsky=False, tiles=None, mindec=-30, mingalb=10, nside=None, pixlist=None, addobjid=False, addparams=False, test=False, dr='dr2')

An array of all Gaia objects in the DESI tiling footprint

Parameters:

• maglim (float, optional, defaults to 18) – Magnitude limit for GFAs in Gaia G-band.

• numproc (int, optional, defaults to 4) – The number of parallel processes to use.

• allsky (bool, defaults to False) – If True, assume that the DESI tiling footprint is the entire sky regardless of the value of tiles.

• tiles (ndarray, optional, defaults to None) – Array of DESI tiles. If None, then load the entire footprint.

• mindec (float, optional, defaults to -30) – Minimum declination (o) to include for output Gaia objects.

• mingalb (float, optional, defaults to 10) – Closest latitude to Galactic plane for output Gaia objects (e.g. send 10 to limit to areas beyond -10o <= b < 10o).

• nside (int, optional, defaults to None) – (NESTED) HEALPix nside to use with pixlist.

• pixlist (list or int, optional, defaults to None) – Only return sources in a set of (NESTED) HEALpixels at the supplied nside.

• addobjid (bool, optional, defaults to False) – If True, include, in the output, a column “GAIA_OBJID” that is the integer number of each row read from each Gaia file.

• addparams (bool, optional, defaults to False) – If True, include some additional Gaia columns: “GAIA_DUPLICATED_SOURCE” and “GAIA_ASTROMETRIC_PARAMS_SOLVED’.

• test (bool, optional, defaults to False) – If True, then we’re running unit tests and don’t have to find the dust maps.

• dr (str, optional, defaults to “dr2”) – Name of a Gaia data release. Options are “dr2”, “edr3”

Returns:

Gaia objects within the passed geometric constraints brighter than maglim, formatted like desitarget.gfa.gfadatamodel.

Return type:

ndarray

Notes

• The environment variables $GAIA_DIR and $DESIMODEL must be set.

desitarget.gfa.gaia_gfas_from_sweep(filename, maglim=18.0, dr='dr2')

Create a set of GFAs for one sweep file.

Parameters:

• filename (str) – A string corresponding to the full path to a sweep file name.

• maglim (float, optional, defaults to 18) – Magnitude limit for GFAs in Gaia G-band.

• dr (str, optional, defaults to “dr2”) – Name of a Gaia data release. Options are “dr2”, “edr3”

Returns:

GFA objects from Gaia, formatted according to desitarget.gfa.gfadatamodel.

Return type:

ndarray

desitarget.gfa.gaia_in_file(infile, maglim=18, mindec=-30.0, mingalb=10.0, nside=None, pixlist=None, addobjid=False, addparams=False, test=False, dr='dr2')

Retrieve the Gaia objects from a HEALPixel-split Gaia file.

Parameters:

• infile (str) – File name of a single Gaia “healpix” file.

• maglim (float, optional, defaults to 18) – Magnitude limit for GFAs in Gaia G-band.

• mindec (float, optional, defaults to -30) – Minimum declination (o) to include for output Gaia objects.

• mingalb (float, optional, defaults to 10) – Closest latitude to Galactic plane for output Gaia objects (e.g. send 10 to limit to areas beyond -10o <= b < 10o)”

• nside (int, optional, defaults to None) – (NESTED) HEALPix nside to use with pixlist.

• pixlist (list or int, optional, defaults to None) – Only return sources in a set of (NESTED) HEALpixels at the supplied nside.

• addobjid (bool, optional, defaults to False) – If True, include, in the output, a column “GAIA_OBJID” that is the integer number of each row read from file.

• addparams (bool, optional, defaults to False) – If True, include some additional Gaia columns: “GAIA_ASTROMETRIC_EXCESS_NOISE”, “GAIA_DUPLICATED_SOURCE”, “GAIA_ASTROMETRIC_PARAMS_SOLVED’, “EBV”.

• test (bool, optional, defaults to False) – If True, then we’re running unit tests and don’t have to find the dust maps.

• dr (str, optional, defaults to “dr2”) – Name of a Gaia data release. Options are “dr2”, “edr3”

Returns:

Gaia objects in the passed Gaia file brighter than maglim, formatted according to desitarget.gfa.gfadatamodel.

Return type:

ndarray

Notes

• A “Gaia healpix file” here is as made by, e.g. gaia_fits_to_healpix()

desitarget.gfa.gaia_morph(gaia, dr='dr2')

Retrieve morphological type for Gaia sources.

Parameters:

• gaia (ndarray) – Numpy structured array containing at least the columns, GAIA_PHOT_G_MEAN_MAG and GAIA_ASTROMETRIC_EXCESS_NOISE.

• dr (str, optional, defaults to “dr2”) – Name of a Gaia data release. Options are “dr2”, “edr3”

Returns:

An array of strings that is the same length as the input array and is set to either “GPSF” or “GGAL” based on a morphological cut with Gaia.

Return type:

array

desitarget.gfa.select_gfas(infiles, maglim=18, numproc=4, nside=None, pixlist=None, bundlefiles=None, extra=None, mindec=-30, mingalb=10, addurat=True, dr='dr2')

Create a set of GFA locations using Gaia and matching to sweeps.

Parameters:

• infiles (list or str) – A list of input filenames (sweep files) OR a single filename.

• maglim (float, optional, defaults to 18) – Magnitude limit for GFAs in Gaia G-band.

• numproc (int, optional, defaults to 4) – The number of parallel processes to use.

• nside (int, optional, defaults to None) – (NESTED) HEALPix nside to use with pixlist and bundlefiles.

• pixlist (list or int, optional, defaults to None) – Only return targets in a set of (NESTED) HEALpixels at the supplied nside. Useful for parallelizing.

• bundlefiles (int, defaults to None) – If not None, then, instead of selecting gfas, print the slurm script to run in pixels at nside. Is an integer rather than a boolean for historical reasons.

• extra (str, optional) – Extra command line flags to be passed to the executable lines in the output slurm script. Used in conjunction with bundlefiles.

• mindec (float, optional, defaults to -30) – Minimum declination (o) for output sources that do NOT match an object in the passed infiles.

• mingalb (float, optional, defaults to 10) – Closest latitude to Galactic plane for output sources that do NOT match an object in the passed infiles (e.g. send 10 to limit to regions beyond -10o <= b < 10o)”.

• addurat (bool, optional, defaults to True) – If True then substitute proper motions from the URAT catalog where Gaia is missing proper motions. Requires that the URAT_DIR is set and points to data downloaded and formatted by, e.g., make_urat_files().

• dr (str, optional, defaults to “dr2”) – Name of a Gaia data release. Options are “dr2”, “edr3”

Returns:

GFA objects from Gaia with the passed geometric constraints limited to the passed maglim and matched to the passed input files, formatted according to desitarget.gfa.gfadatamodel.

Return type:

ndarray

Notes

• If numproc==1, use the serial code instead of parallel code.

• If numproc > 4, then numproc=4 is enforced for (just those) parts of the code that are I/O limited.

desitarget.internal

This subpackage contains modules that are for strictly internal use by the desitarget package. End-users should not directly call any functions in this subpackage.

desitarget.internal.sharedmem

Easier parallel programming on shared memory computers.

The source code is at http://github.com/rainwoodman/sharedmem .

Programming Model

MapReduce provides the equivalent to multiprocessing.Pool, with the following differences:

• MapReduce does not require the work function to be picklable.

• MapReduce adds a reduction step that is guaranteed to run on the coordinator process’s scope.

• MapReduce allows the use of critical sections and ordered execution in the work function.

Modifications to shared Memory arrays, allocated via

• sharedmem.empty(),

• sharedmem.empty_like(),

• sharedmem.copy(),

are visible by all processes, including the coordinator process.

Usage

The package can be installed via easy_install sharedmem. Alternatively, the file sharedmem.py can be directly embedded into other projects.

The only external dependency is numpy, since this was designed to work with large shared memory chunks through numpy.ndarray.

Environment variable OMP_NUM_THREADS is used to determine the default number of workers.

Notes

This module depends on the fork system call, thus is available only on posix systems (not Windows).

Examples

Sum up a large array

>>> input = numpy.arange(1024 * 1024 * 128, dtype='f8')
>>> output = sharedmem.empty(1024 * 1024 * 128, dtype='f8')
>>> with MapReduce() as pool:
>>>    chunksize = 1024 * 1024
>>>    def work(i):
>>>        s = slice (i, i + chunksize)
>>>        output[s] = input[s]
>>>        return i, sum(input[s])
>>>    def reduce(i, r):
>>>        print('chunk', i, 'done')
>>>        return r
>>>    r = pool.map(work, range(0, len(input), chunksize), reduce=reduce)
>>> print numpy.sum(r)
>>>

Textual analysis

>>> input = file('mytextfile.txt').readlines()
>>> word_count = {'bacon': 0, 'eggs': 0 }
>>> with MapReduce() as pool:
>>>    def work(line):
>>>        words = line.split()
>>>        for word in words:
>>>            word_count[word] += 1
>>>        return word_count
>>>    def reduce(wc):
>>>        for key in word_count:
>>>            word_count[key] += wc[key]
>>> print word_count
>>>

pool.ordered can be used to require a block of code to be executed in order

>>> with MapReduce() as pool:
>>>    def work(i):
>>>         with pool.ordered:
>>>            print(i)
>>>    pool.map(work, range(10))

pool.critical can be used to require a block of code to be executed in a critical section.

>>> counter = sharedmem.empty(1)
>>> counter[:] = 0
>>> with MapReduce() as pool:
>>>    def work(i):
>>>         with pool.critical:
>>>             counter[:] += i
>>>    pool.map(work, range(10))
>>> print(counter)

API References

class desitarget.internal.sharedmem.MapReduce(backend=<class 'desitarget.internal.sharedmem.ProcessBackend'>, np=None)

A pool of worker processes for a Map-Reduce operation

Parameters:

• backend (ProcessBackend or ThreadBackend) – ProcessBackend is preferred. ThreadBackend can be used in cases where processes creation is not allowed.

• np (int or None) – Number of processes to use. Default (None) is from OMP_NUM_THREADS or the number of available cores on the computer. If np is 0, all operations are performed on the coordinator process – no child processes are created.

Notes

Always wrap the call to map() in a context manager (‘with’) block.

map(func, sequence, reduce=None, star=False)

Map-reduce with multile processes.

Apply func to each item on the sequence, in parallel. As the results are collected, reduce is called on the result. The reduced result is returned as a list.

Parameters:

• func (callable) –

  The function to call. It must accept the same number of arguments as the length of an item in the sequence.

  Warning

  func is not supposed to use exceptions for flow control. In non-debug mode all exceptions will be wrapped into a WorkerException.

• sequence (list or array_like) – The sequence of arguments to be applied to func.

• reduce (callable, optional) – Apply an reduction operation on the return values of func. If func returns a tuple, they are treated as positional arguments of reduce.

• star (boolean) – if True, the items in sequence are treated as positional arguments of reduce.

Returns:

results – The list of reduced results from the map operation, in the order of the arguments of sequence.

Return type:

list

Raises:

WorkerException – If any of the worker process encounters an exception. Inspect WorkerException.reason for the underlying exception.

desitarget.internal.sharedmem.MapReduceByThread(np=None)

Creates a MapReduce object but with the Thread backend.

The process backend is usually preferred.

exception desitarget.internal.sharedmem.StopProcessGroup

StopProcessGroup will terminate the worker process/thread

exception desitarget.internal.sharedmem.WorkerException(reason, traceback)

Represents an exception that has occured during a worker process

reason

The underlining reason of the exception. If the original exception can be pickled, the type of the exception is preserved. Otherwise, a LostExceptionType warning is issued, and reason is of type Exception.

Type:

Exception, or subclass of Exception.

traceback

The string version of the traceback that can be used to inspect the error.

Type:

str

class desitarget.internal.sharedmem.background(function, *args, **kwargs)

Asyncrhonized function call via a background process.

Parameters:

• function (callable) – the function to call

• *args (positional arguments)

• **kwargs (keyward arguments)

Examples

>>> def function(*args, **kwargs):
>>>    pass
>>> bg = background(function, *args, **kwargs)
>>> rt = bg.wait()

wait()

Wait and join the child process. The return value of the function call is returned. If any exception occurred it is wrapped and raised.

desitarget.internal.sharedmem.copy(a)

Copy an array to the shared memory.

Notes

copy is not always necessary because the private memory is always copy-on-write.

Use a = copy(a) to immediately dereference the old ‘a’ on private memory

desitarget.internal.sharedmem.cpu_count()

Returns the number of worker processes to be spawned.

The default value is the number of physical cpu cores seen by python. OMP_NUM_THREADS environment variable overrides it.

On PBS/torque systems if OMP_NUM_THREADS is empty, we try to use the value of PBS_NUM_PPN variable.

Notes

On some machines the physical number of cores does not equal the number of cpus shall be used. PSC Blacklight for example.

desitarget.internal.sharedmem.empty(shape, dtype='f8')

Create an empty shared memory array.

desitarget.internal.sharedmem.empty_like(array, dtype=None)

Create a shared memory array from the shape of array.

desitarget.internal.sharedmem.full(shape, value, dtype='f8')

Create a shared memory array of given shape and type, filled with value.

desitarget.internal.sharedmem.full_like(array, value, dtype=None)

Create a shared memory array with the same shape and type as a given array, filled with value.

desitarget.internal.sharedmem.get_debug()

Get the debug mode

desitarget.internal.sharedmem.set_debug(flag)

Set the debug mode.

In debug mode (flag==True), no workers are spawn. All work are done in serial on the coordinator thread/process. This eases debuggin when the worker throws out an exception.

desitarget.internal.sharedmem.total_memory()

Returns the the amount of memory available for use.

This function is not very useful. The memory is obtained from MemTotal entry in /proc/meminfo.

desitarget.io

Functions for reading, writing and manipulating files related to targeting.

desitarget.io._bright_or_dark(filename, hdr, data, obscon, mockdata=None)

modify data/file name for BRIGHT or DARK survey OBSCONDITIONS

Parameters:

• filename (str) – output target selection file.

• hdr (class:str) – header of the output target selection file.

• data (ndarray) – numpy structured array of targets.

• obscon (str) – Can be “DARK” or “BRIGHT” to only write targets appropriate for “DARK” or “BRIGHT” observing conditions. The relevant PRIORITY_INIT and NUMOBS_INIT columns will be derived from PRIORITY_INIT_DARK, etc. and filename will have “bright” or “dark” appended to the lowest DIRECTORY in the input filename.

• mockdata (dict, optional, defaults to None) – Dictionary of mock data to write out (only used in desitarget.mock.build.targets_truth via select_mock_targets).

Returns:

• str – The modified file name.

• data – The modified data.

desitarget.io._check_hpx_length(hpxlist, length=68, warning=False)

Check a list expressed as a csv string won’t exceed a length.

desitarget.io._get_targ_dir()

Convenience function to grab the TARGDIR environment variable.

Returns:

The directory stored in the $GAIA_DIR environment variable.

Return type:

str

desitarget.io.add_photsys(indata)

Add the PHOTSYS column to a sweeps-style array.

Parameters:

indata (ndarray) – Numpy structured array to which to add PHOTSYS column.

Returns:

Input array with PHOTSYS added (and set using RELEASE).

Return type:

ndarray

Notes

• The PHOTSYS column is only added if the RELEASE column is available in the passed indata.

desitarget.io.brickname_from_filename(filename)

Parse filename to check if this is a tractor brick file.

Parameters:

filename (str) – Name of a tractor brick file.

Returns:

Name of the brick in the file name.

Return type:

str

Raises:

ValueError – If the filename does not appear to be a valid tractor brick file.

desitarget.io.brickname_from_filename_with_prefix(filename, prefix='')

Parse filename to check if this is a brick file with a given prefix.

Parameters:

• filename (str) – Full name of a brick file.

• prefix (str) – Optional part of filename immediately preceding the brickname.

Returns:

Name of the brick in the file name.

Return type:

str

Raises:

ValueError – If the filename does not appear to be a valid brick file.

desitarget.io.check_both_set(hpxlist, nside)

Check that if one of two variables is set, the other is too

desitarget.io.check_fitsio_version(version='0.9.8')

fitsio prior to 0.9.8rc1 has a bug parsing boolean columns.

Parameters:

version (str, optional) – Default ‘0.9.8’. Having this parameter allows future-proofing and easier testing.

Raises:

ImportError – If the fitsio version is insufficiently recent.

desitarget.io.check_hp_target_dir(hpdirname)

Check fidelity of a directory of HEALPixel-partitioned targets.

Parameters:

hpdirname (str) – Full path to a directory containing targets that have been split by HEALPixel.

Returns:

• int – The HEALPixel NSIDE for the files in the passed directory.

• dict – A dictionary where the keys are each HEALPixel covered in the passed directory and the values are the file that includes that HEALPixel.

Notes

• Checks that all files are at the same NSIDE.

• Checks that no two files contain the same HEALPixels.

• Checks that HEALPixel numbers are consistent with NSIDE.

desitarget.io.decode_sweep_name(sweepname, nside=None, inclusive=True, fact=4)

Retrieve RA/Dec edges from a full directory path to a sweep file

Parameters:

• sweepname (str) – Full path to a sweep file, e.g., /a/b/c/sweep-350m005-360p005.fits

• nside (int, optional, defaults to None) – (NESTED) HEALPixel nside

• inclusive (book, optional, defaults to True) – see documentation for healpy.query_polygon()

• fact (int, optional defaults to 4) – see documentation for healpy.query_polygon()

Returns:

• list (if nside is None) – A 4-entry list of the edges of the region covered by the sweeps file in the form [RAmin, RAmax, DECmin, DECmax] For the above example this would be [350., 360., -5., 5.]

• list (if nside is not None) – A list of HEALPixels that touch the files at the passed nside For the above example this would be [16, 17, 18, 19]

desitarget.io.desitarget_nside()

Default HEALPix Nside for all target selection algorithms.

desitarget.io.desitarget_resolve_dec()

Default Dec cut to separate targets in BASS/MzLS from DECaLS.

desitarget.io.find_mtl_file_format_from_header(hpdirname, returnoc=False, override=False, forceoverride=False)

Construct MTL filename from a directory containing an MTL ledger.

Parameters:

• hpdirname (str) – Full path to a directory containing MTL ledgers that have been partitioned by HEALPixel.

• returnoc (bool, optional, defaults to False) – If True then also return the OBSCON header keyword for files in this directory.

• override (bool, optional, defaults to False) – If True, return the file form for an override ledger instead of a standard MTL ledger BUT if an OVERRIDE value is detected in the header of the first file found in hpdirname let it take precedence over override. See desitarget issue 784.

• forceoverride (bool, optional, defaults to False) – If True, return the file form for an override ledger instead of a standard MTL ledger REGARDLESS of any OVERRIDE value found in the header of the first file found in hpdirname.

Returns:

• str – The file form such that output.format(pixel) returns the full HEALPixel-dependent filename for a give pixel.

• str – The OBSCON header keyword. Only returned if returnoc is True.

Notes

• Should work for both .ecsv and .fits files.

• If both override and forceoverride are True, forceoverride takes precedence.

desitarget.io.find_star_files(objs, hpxdir, nside, neighbors=True, radec=False, strict=False)

Full paths to HEALPixel-split star files for objects by RA/Dec.

Parameters:

• objs (ndarray) – Array of objects. Must contain at least columns “RA” and “DEC”.

• hpxdir (str) – Name of the directory that hosts the HEALPixel-split files. Most likely this directory ends in “/healpix”.

• nside (int) – The (NESTED) HEALPixel nside integer.

• neighbors (bool, optional, defaults to True) – Also return all neighboring pixels that touch the files of interest to prevent edge effects (e.g. if a, say, Gaia source is 1 arcsec away from a primary source and so in an adjacent pixel).

• radec (bool, optional, defaults to False) – If True then the passed objs is an [RA, Dec] list instead of a rec array.

• strict (bool, optional, defaults to False) – Only return files that actually exist. This is useful for, e.g., URAT files, which don’t cover the whole sky and so don’t have files for every HEALPixel.

Returns:

A list of all files that need to be read in to account for objects at the passed locations.

Return type:

list

Notes

• “star” files, here might be Gaia, Tycho or URAT files.

desitarget.io.find_target_files(targdir, dr='X', flavor='targets', survey='main', obscon=None, hp=None, nside=None, resolve=True, supp=False, mock=False, nohp=False, seed=None, region=None, epoch=None, maglim=None, override=False, ender='fits')

Build the name of an output target file (or directory).

Parameters:

• targdir (str) – Name of a based directory for output target catalogs.

• dr (str or int, optional, defaults to “X”) – Name of a Legacy Surveys Data Release (e.g. 8). If this is an integer or a 1-character string it is prepended by “dr”.

• flavor (str, optional, defaults to targets) – Options: “skies”, “gfas”, “targets”, “randoms”, “masks”, “mtl”, “ToO”.

• survey (str, optional, defaults to main) – Options include “mainX”, “cmx”, “svX” (where X is 1, 2 etc.). Only relevant if flavor is “targets”.

• obscon (str, optional) – Name of the OBSCONDITIONS used to make the file (e.g. DARK).

• hp (list or int or str, optional) – HEALPixel numbers used to make the file (e.g. 42 or [12, 37] or “42” or “12,37”). Required if mock=`True`.

• nside (int, optional unless mock=`True`) – Nside corresponding to healpixel hp.

• resolve (bool, optional, defaults to True) – If True then find the resolve file. Otherwise find the noresolve file. Relevant if flavor is targets or randoms. Pass None to substitute resolve with “secondary”, which also works if flavor is mtl.

• supp (bool, optional, defaults to False) – If True then find the supplemental/backup file. Overrides the obscon option.

• mock (bool, optional, defaults to False) – If True then construct the file path for mock target catalogs and return (most other inputs are ignored).

• nohp (bool, optional, defaults to False) – If True, override the normal behavior for hp`=``None` and instead construct a filename that omits the -hpX- part.

• seed (int or str, optional) – If seed is not None, then it is added to the file name just before the “.fits” extension (i.e. “-8.fits” for seed of 8). Only relevant if flavor is “randoms”. If seed is not None and hp is not None then seed is added to the file name AFTER hp (i.e. “-8-hp-44.fits” for seed of 8 and hp of 44).

• region (int, optional) – If region is not None, then it is added to the directory name after resolve. Only relevant if flavor is “randoms”.

• epoch (float) – Epoch at which the mask was made. Only relevant if flavor is “masks”. Must be passed if flavor is “masks”.

• maglim (float, optional) – Magnitude limit to which the mask was made. Only relevant if flavor is “masks”. Must be passed if flavor is “masks”.

• override (bool, optional, defaults to False) – If True, this is an MTL override file. Any instance of “mtl” in the filename is replaced by “mtl-override” and the final part of the directory structure includes “override”.

• ender (str, optional, defaults to “fits”) – File format (in file name).

Returns:

The name of the output target file (or directory).

Return type:

str

Notes

• If hp is passed, the full file name is returned. If hp is None, the directory name where all of the hp files are stored is returned. The directory name is the expected input for the desitarget.io.read* convenience functions (desitarget.io.read_targets_in_hp(), etc.).

• On the other hand, if hp is None and nohp is True then a filename is returned that just omits the -hp-X- part.

desitarget.io.fix_tractor_dr1_dtype(objects)

DR1 tractor files have inconsistent dtype for the TYPE field. Fix this.

Parameters:

objects – numpy structured array from target file.

Returns:

structured array with TYPE.dtype = ‘S4’ if needed.

If the type was already correct, returns the original array.

desitarget.io.get_checksums(infiles, verbose=False, check_existing=True)

Get the sha256 checksums for a list of files.

Parameters:

• infiles (list or str) – The full paths to a file or files.

• verbose (bool, optional, defaults to False) – If True then log progress and times.

• check_existing (bool, optional, defaults to True) – If True check if any of the infiles is in a directory in which a .sha256sum file exists, and, if so, check generated checksums for each file against the corresponding entry in the relevant .sha256sum file (or files for infiles that span multiple directories). An exception is raised for a mismatch.

Returns:

A recarray with two columns “FILENAME” and “SHA256”.

Return type:

ndarray

desitarget.io.get_sha256sum(infile)

Get the sha256 checksum for a single file

Parameters:

infile (str) – The full path name to a file.

Returns:

The sha256 checksum for the passed infile.

Return type:

str

Notes

• h/t https://stackoverflow.com/questions/61229719

desitarget.io.gitversion()

Returns git describe –tags –dirty –always, or ‘unknown’ if not a git repo

desitarget.io.hpx_filename(hpx)

Return the standard name for HEALPixel-split input files

Parameters:

hpx (str or int) – A HEALPixel integer.

Returns:

Filename in the format used throughout desitarget for HEALPixel-split input databases.

Return type:

class: str

desitarget.io.is_sky_dir_official(skydirname)

Check a sky file or directory has the correct HEALPixel structure.

Parameters:

skydirname (str) – Full path to either a directory containing skies that have been partitioned by HEALPixel (i.e. as made by select_skies with the bundle_files option). Or the name of a single file of skies.

Returns:

True if the passed sky file or (the first sky file in the passed directory) is structured so that the list of healpixels in the file header (“FILEHPX”) at the file nside (“FILENSID”) in the file nested (or ring) scheme (“FILENEST”) is a true reflection of the HEALPixels in the file.

Return type:

bool

Notes

• A necessary check because although the targets and GFAs are parallelized to run in the exact boundaries of HEALPixels, the skies are parallelized across bricks that have CENTERS in a given HEALPixel.

• If this function returns False the remedy is typically to run bin/repartition_skies

• If a directory is passed, this isn’t an exhaustive check as only the first file is tested. That’s enough for just checking the output of select_skies, though.

desitarget.io.iter_files(root, prefix, ext='fits', ignore=None)

Iterator over files under in root directory with given prefix and extension. ignore is a list of strings that will be skipped in the directory or file names (for both a speed-up and trimming of files).

desitarget.io.iter_sweepfiles(root)

Iterator over all sweep files found under root directory.

desitarget.io.iter_tractorfiles(root)

Iterator over all tractor files found under root directory.

Parameters:

root (str) – Path to start looking. Can be a directory or a single file.

Returns:

An iterator of (brickname, filename).

Return type:

iterable

Examples

>>> for brickname, filename in iter_tractor('./'):
>>>     print(brickname, filename)

desitarget.io.list_sweepfiles(root)

Return a list of sweep files found under root directory.

desitarget.io.list_targetfiles(root)

Return a list of target files found under root directory.

desitarget.io.list_tractorfiles(root)

Return a list of tractor files found under root directory.

desitarget.io.load_pixweight(inmapfile, nside, pixmap=None)

Loads a pixel map from file and resamples to a different HEALPixel resolution (nside)

Parameters:

• inmapfile (str) – Name of the file containing the pixel weight map.

• nside (int) – After loading, the array will be resampled to this HEALPix nside.

• pixmap (~numpy.array, optional, defaults to None) – Pass a pixel map instead of loading it from file.

Returns:

HEALPixel weight map resampled to the requested nside.

Return type:

array

desitarget.io.load_pixweight_recarray(inmapfile, nside, pixmap=None)

Like load_pixweight but for a structured array map with multiple columns

Parameters:

• inmapfile (str) – Name of the file containing the pixel weight map.

• nside (int) – After loading, the array will be resampled to this HEALPix nside.

• pixmap (~numpy.array, optional, defaults to None) – Pass a pixel map instead of loading it from file.

Returns:

HEALPixel weight map with all columns resampled to the requested nside.

Return type:

array

Notes

• Assumes that tha passed map is in the NESTED scheme, and outputs to the NESTED scheme.

• All columns are resampled as the mean of the relevant pixels, except if a column HPXPIXEL is passed. That column is reassigned the appropriate pixel number at the new nside.

desitarget.io.read_ecsv_header(filename, cleanup=True)

Read header info from an ecsv file without reading the whole file.

Parameters:

• filename (str) – The full path to the .ecsv file of interest.

• cleanup (bool, optional, defaults to True) – If passed, perform some syntax cleanup to convert strings to more likely types. Integer strings will be changed to integer type, Quotation marks inside of strings will be removed, and instances of ‘false’ or ‘true’ will be changed to Boolean types.

Returns:

A dictionary of the “meta” keywords from the header.

Return type:

dict

desitarget.io.read_external_file(filename, header=False, columns=['RA', 'DEC'])

Read FITS file with loose requirements on upper-case columns and EXTNAME.

Parameters:

• filename (str) – File name with full directory path included.

• header (bool, optional, defaults to False) – If True then return (data, header) instead of just data.

• columns (list, optional, defaults to [“RA”, “DEC”]) – Specify the desired columns to read.

Returns:

• ndarray – The output data array.

• ndarray, optional – The output file header, if input header was True.

Notes

• Intended to be used with externally supplied files such as locations to be matched for commissioning or secondary targets.

desitarget.io.read_keyword_from_mtl_header(hpdirname, keyword)

Read in a header value from a Merget Target List ledger file.

Parameters:

• hpdirname (str) – Full path to either a directory containing MTLs that have been partitioned by HEALPixel (i.e. as made by desitarget.mtl.make_ledger_in_hp()). Or the name of a single MTL ledger.

• keyword (str) – A single header keyword.

Returns:

The value of keyword from the header of hpdirname if it is a file, or the value from the first file encountered in hpdirname

Return type:

str

desitarget.io.read_mtl_in_hp(hpdirname, nside, pixlist, unique=True, isodate=None, returnfn=False, initial=False, leq=False, columns=None, tabform='ascii.basic', maketwostyle=False, use_concatenate=False)

Read Merged Target List ledgers in a set of HEALPixels.

Parameters:

• hpdirname (str or list) –

  if a string:

  Full path to either a directory containing MTLs that have been partitioned by HEALPixel (i.e. as made by select_targets with the bundle_files option). Or the name of a single MTL of targets.

  If a list:

  Then this must be a list of two strings, with the strings having the same meaning as if one string is passed. The code switches to “multi-MTL” mode, where two MTLs are merged by matching on TARGETID and taking the highest-priority target. Extra columns are added to the output, indicating which of the MTLs was interested in each target. The strings must be the same input type, i.e. either two directories or files. The directories or files must share the same nside.

• nside (int) – The (NESTED) HEALPixel nside.

• pixlist (list or int or ~numpy.ndarray) – Return targets in these HEALPixels at the passed nside.

• unique (bool, optional, defaults to True) – If True then only read targets with unique TARGETID, where the last occurrence of the target in the ledger is the one that is retained. If False then read the entire ledger.

• isodate (str, defaults to None) – An ISO date, such as the date that is returned by the function desitarget.mtl.get_utc_date() `. The ledger is restricted to entries strictly BEFORE `isodate() before being extracted. If None is passed then no date restrictions are applied.

• returnfn (bool, optional, defaults to False) – If True then also return a dictionary of the filename that had to be read in each pixel to retrieve the MTL(s).

• initial (bool, optional, defaults to False) – If True then only read targets with unique TARGETID, where the FIRST occurrence of the target in the ledger is retained. i.e. read the initial state of the ledger. Overrides unique.

• leq (bool, optional, defaults to False) – If True, restrict the ledger to entries BEFORE or EQUAL TO isodate instead of the default behavior of strictly before isodate. Only relevant if isodate is passed.

• columns (list, optional) – Only return these target columns. RA and DEC will always be included in the output, whether or not they’re passed, as they are critical for determining if a location is in a HEALPixel.

• tabform (str, optional, defaults to ‘ascii.basic’) – Format to pass to the astropy Table.read() function. The default (‘ascii.basic’) is standard for reading and writing MTL files. But ‘ascii.ecsv’ is useful for some of the mock/alt-MTL work.

• maketwostyle (bool, optional, defaults to False) – If passed, add the extra columns that are added when running read_two_mtl_ledgers(), even if only reading one ledger.

• use_concatenate (bool, optional, defaults to False) – If passed, use np.concatenate() rather than stack_arrays to stack the list of mtls. This reproduces buggy behaviour described in https://github.com/desihub/desitarget/issues/883, where different column orders of read_two_mtl_ledgers() and read_one_mtl_ledger() was ignored in the concatenation process.

Returns:

• ndarray – A numpy structured array of the MTL(s).

• dict – A dictionary where the keys are pixels and values are filenames that were read (only returned if returnfn is True).

Notes

• In general, this will be quicker if pixlist contains closely grouped HEALPixels, as fewer files will need to be read.

desitarget.io.read_mtl_ledger(filename, unique=True, isodate=None, initial=False, leq=False, columns=None, tabform='ascii.basic', maketwostyle=False)

Read one or two MTL ledger files.

Parameters:

• filename (str or list) –

  If a string:

  Then this is the name of a ledger file containing a Merged Target List. If filename contains “.ecsv” then it will be read as an ECSV file. If it contains “.fits” then it will be read as a FITS file.

  If a list:

  Then this must be a list of two strings, with the strings having the same meaning as if one string is passed. The code switches to “multi-MTL” mode, where two MTLs are merged by matching on TARGETID and taking the highest-priority target. Extra columns are added to the output, indicating which of the MTLs was interested in each target.

• unique (bool, optional, defaults to True) – If True then only read targets with unique TARGETID, where the last occurrence of the target in the ledger is the one that is retained. If False then read the entire ledger.

• isodate (str, defaults to None) – A date in ISO format, such as returned by desitarget.mtl.get_utc_date() `. The ledger is restricted to entries strictly BEFORE `isodate() before being extracted. If None is passed then no date restrictions are applied.

• initial (bool, optional, defaults to False) – If True then only read targets with unique TARGETID, where the FIRST occurrence of the target in the ledger is retained. i.e. read the initial state of the ledger. Overrides unique.

• leq (bool, optional, defaults to False) – If True, restrict the ledger to entries BEFORE or EQUAL TO isodate instead of the default behavior of strictly before isodate. Only relevant if isodate is passed.

• columns (list, optional) – Only return these target columns.

• tabform (str, optional, defaults to ‘ascii.basic’) – Format to pass to the astropy Table.read() function. The default (‘ascii.basic’) is standard for reading and writing MTL files. But ‘ascii.ecsv’ is useful for some of the mock/alt-MTL work.

• maketwostyle (bool, optional, defaults to False) – If passed, add the extra columns that are added when running read_two_mtl_ledgers(), even if only reading one ledger.

Returns:

A structured numpy array of the MTL.

Return type:

ndarray

desitarget.io.read_mtl_tile_file(filename, unique=True)

Read which tiles have been processed by MTL from the tile file.

Parameters:

• filename (str) – The full path to the MTL tile file.

• unique (bool, optional, defaults to True) – If True then only read entires with unique TILEID, where the last occurrence of the TILEID in the file is the one that is retained. If False then read the entire file.

Returns:

A structured numpy array of the MTL tile file.

Return type:

ndarray

desitarget.io.read_mtl_veto_file(filename, survey='main')

Read an MTL veto file and perform basic checks on its format.

Parameters:

• filename (str) – The full path to the MTL veto file.

• survey (str, optional, defaults to “main”) – To look up the right MTL data model. Examples might be``’main’`` or 'svX’ (where X is 1, 2, 3 etc.) for the main survey and different iterations of SV, respectively.

Returns:

A structured array that only contains the relevant columns for vetoing. These are: [“TARGETID”, “RA”, “DEC”, “TIMESTAMP”].

Return type:

ndarray

Notes

• The checks that are performed include:

  • The file should include these columns (with correct type):

    RA, DEC, TARGETID, TIMESTAMP

  • No TARGETID should be duplicated.

  • No TIMESTAMP lower down in the file should be earlier in time that a TIMESTAMP higher up in the file.

desitarget.io.read_one_mtl_ledger(filename, unique=True, isodate=None, initial=False, leq=False, columns=None, tabform='ascii.basic', maketwostyle=False)

Wrapper to read individual MTL ledger files.

Parameters:

• filename (str) – Name of a ledger file containing a Merged Target List. If the filename contains “.ecsv” then it will be read as an ECSV file. If it contains “.fits” then it will be read as a FITS file. Input files can be gzipped.

• unique (bool, optional, defaults to True) – If True then only read targets with unique TARGETID, where the last occurrence of the target in the ledger is the one that is retained. If False then read the entire ledger.

• isodate (str, defaults to None) – A date in ISO format, such as returned by desitarget.mtl.get_utc_date() `. The ledger is restricted to entries strictly BEFORE `isodate() before being extracted. If None is passed then no date restrictions are applied.

• initial (bool, optional, defaults to False) – If True then only read targets with unique TARGETID, where the FIRST occurrence of the target in the ledger is retained. i.e. read the initial state of the ledger. Overrides unique.

• leq (bool, optional, defaults to False) – If True, restrict the ledger to entries BEFORE or EQUAL TO isodate instead of the default behavior of strictly before isodate. Only relevant if isodate is passed.

• columns (list, optional) – Only return these target columns.

• tabform (str, optional, defaults to ‘ascii.basic’) – Format to pass to the astropy Table.read() function. The default (‘ascii.basic’) is standard for reading and writing MTL files. But ‘ascii.ecsv’ is useful for some of the mock/alt-MTL work.

• maketwostyle (bool, optional, defaults to False) – If passed, add the extra columns that are added when running read_two_mtl_ledgers().

Returns:

A structured numpy array of the MTL.

Return type:

ndarray

desitarget.io.read_target_files(filename, columns=None, rows=None, header=False, downsample=None, verbose=False)

Wrapper to cycle through allowed extensions to read target files.

Parameters:

• filename (str) – Name of a target file of any type. Target file types include “TARGETS”, “GFA_TARGETS” and “SKY_TARGETS”.

• columns (list, optional) – Only read in these target columns.

• rows (list, optional) – Only read in these rows from the target file.

• header (bool, optional, defaults to False) – If True then return the header of the file.

• downsample (int, optional, defaults to None) – If not None, downsample the file by this integer value, e.g. for downsample=10 a file with 900 rows would have 90 random rows read in. Overrode by the rows kwarg if it is not None.

• verbose (bool, optional, defaults to False) – If True then log the file and extension that was read.

desitarget.io.read_targets_header(hpdirname, dtype=False, verbose=True)

Read in header of a targets file.

Parameters:

• hpdirname (str) – Full path to either a directory containing targets that have been partitioned by HEALPixel (i.e. as made by select_targets with the bundle_files option). Or the name of a single file of targets.

• dtype (bool, optional, defaults to False) – if True, also return the data model (dtype) of the targets.

• verbose (bool, optional, defaults to False) – If True then log messages and warnings.

Returns:

• FITSHDR – The header of hpdirname if it is a file, or the header of the first file encountered in hpdirname

• FITSHDR – The dtype of the file that corresponds to the header. Only returned if dtype is True.

desitarget.io.read_targets_in_box(hpdirname, radecbox=[0.0, 360.0, -90.0, 90.0], columns=None, header=False, quick=False, downsample=None, mtl=False, unique=True, isodate=None, initial=False, leq=False, tabform='ascii.basic')

Read in targets in an RA/Dec box.

Parameters:

• hpdirname (str) – Full path to either a directory containing targets that have been partitioned by HEALPixel (i.e. as made by select_targets with the bundle_files option). Or the name of a single file of targets.

• radecbox (list, defaults to the entire sky) – 4-entry list of coordinates [ramin, ramax, decmin, decmax] forming the edges of a box in RA/Dec (degrees).

• columns (list, optional) – Only read in these target columns.

• header (bool, optional, defaults to False) – If True then return the header of either the hpdirname file, or the last file read from the hpdirname directory.

• quick (bool, optional, defaults to False) – If True, call desitarget.io.read_targets_in_quick(). That version of the code assumes that hpdirname is a directory, which contains files that follow a strict data model. True overrides the mtl, unique, isodate and initial inputs.

• downsample (int, optional, defaults to None) – If not None, downsample targets by (roughly) this value, e.g. for downsample=10 a set of 900 targets would have ~90 random targets returned.

• mtl (bool, optional, defaults to False) – If True then read an MTL ledger file/directory instead of a target file/directory. If True then the columns and header kwargs are ignored and the full ledger is returned.

• unique (bool, optional, defaults to True) – If True then only read targets with unique TARGETID from MTL ledgers. Only used if mtl is True.

• isodate (str, defaults to None) – Only used if mtl is True An ISO date, such as returned by desitarget.mtl.get_utc_date() `. The ledger is restricted to entries strictly BEFORE `isodate() before being extracted. If None is passed then no date restrictions are applied.

• initial (bool, optional, defaults to False) – If True then only read targets with unique TARGETID, where the FIRST occurrence of the target in the ledger is retained. i.e. read the initial state of the ledger. Overrides unique. Only used if mtl is True.

• leq (bool, optional, defaults to False) – If True, restrict the ledger to entries BEFORE or EQUAL TO isodate instead of the default behavior of strictly before isodate. Only relevant if isodate is passed. Only used if mtl is True.

• tabform (str, optional, defaults to ‘ascii.basic’) – Format to pass to the astropy Table.read() function. The default (‘ascii.basic’) is standard for reading and writing MTL files. But ‘ascii.ecsv’ is useful for some of the mock/alt-MTL work. Only relevant when mtl is True.

Returns:

An array of targets in the passed RA/Dec box.

Return type:

ndarray

Notes

• If header is True, then a second output (the file header is returned).

desitarget.io.read_targets_in_cap(hpdirname, radecrad, columns=None, header=False, quick=False, mtl=False, unique=True, isodate=None, initial=False, leq=False, tabform='ascii.basic')

Read in targets in an RA, Dec, radius cap.

Parameters:

• hpdirname (str) – Full path to either a directory containing targets that have been partitioned by HEALPixel (i.e. as made by select_targets with the bundle_files option). Or the name of a single file of targets.

• radecrad (list) – 3-entry list of coordinates [ra, dec, radius] forming a cap or “circle” on the sky. ra, dec and radius are all in degrees.

• columns (list, optional) – Only read in these target columns.

• header (bool, optional, defaults to False) – If True then return the header of either the hpdirname file, or the last file read from the hpdirname directory.

• quick (bool, optional, defaults to False) – If True, call desitarget.io.read_targets_in_quick(). That version of the code assumes that hpdirname is a directory, which contains files that follow a strict data model. True overrides the mtl, unique, isodate and initial inputs.

• mtl (bool, optional, defaults to False) – If True then read an MTL ledger file/directory instead of a target file/directory. If True then the columns kwarg is ignored and the full ledger is returned.

• unique (bool, optional, defaults to True) – If True then only read targets with unique TARGETID from MTL ledgers. Only used if mtl is True.

• isodate (str, defaults to None) – Only used if mtl is True An ISO date, such as returned by desitarget.mtl.get_utc_date() `. The ledger is restricted to entries strictly BEFORE `isodate() before being extracted. If None is passed then no date restrictions are applied.

• initial (bool, optional, defaults to False) – If True then only read targets with unique TARGETID, where the FIRST occurrence of the target in the ledger is retained. i.e. read the initial state of the ledger. Overrides unique. Only used if mtl is True.

• leq (bool, optional, defaults to False) – If True, restrict the ledger to entries BEFORE or EQUAL TO isodate instead of the default behavior of strictly before isodate. Only relevant if isodate is passed. Only used if mtl is True.

• tabform (str, optional, defaults to ‘ascii.basic’) – Format to pass to the astropy Table.read() function. The default (‘ascii.basic’) is standard for reading and writing MTL files. But ‘ascii.ecsv’ is useful for some of the mock/alt-MTL work. Only relevant when mtl is True.

Returns:

An array of targets in the passed cap.

Return type:

ndarray

desitarget.io.read_targets_in_hp(hpdirname, nside, pixlist, columns=None, header=False, quick=False, downsample=None, verbose=False, mtl=False, unique=True, isodate=None, initial=False, leq=False, tabform='ascii.basic', maketwostyle=False)

Read in targets in a set of HEALPixels.

Parameters:

• hpdirname (str or list) –

  if a string:

  Full path to either a directory containing MTLs or targets partitioned by HEALPixel (i.e. as made by select_targets with the bundle_files option). Or the name of a single MTL or file of targets.

  If a list:

  Then this must be a list of two strings, with the strings having the same meaning as if one string is passed. The code switches to “multi-MTL” mode, where two MTLs are merged by matching on TARGETID and taking the highest-priority target. Extra columns are added to the output, indicating which of the MTLs was interested in each target. The strings must be the same input type, i.e. either two directories or files. The directories or files must share the same nside. For this mode, the input mtl must be True.

• nside (int) – The (NESTED) HEALPixel nside.

• pixlist (list or int or ~numpy.ndarray) – Return targets in these HEALPixels at the passed nside.

• columns (list, optional) – Only return these target columns.

• header (bool, optional, defaults to False) – If True then return the header of either the hpdirname file, or the last file read from the hpdirname directory.

• quick (bool, optional, defaults to False) – If True, call desitarget.io.read_targets_in_quick(). That version of the code assumes that hpdirname is a directory, with files that follow a strict data model. True overrides mtl/unique/isodate/downsample/verbose/initial.

• downsample (int, optional, defaults to None) – If not None, downsample targets by (roughly) this value, e.g. for downsample=10 a set of 900 targets would have ~90 random targets returned.

• verbose (bool, optional, defaults to False) – Passed to read_target_files().

• mtl (bool, optional, defaults to False) – If True then read an MTL ledger file/directory instead of targets. If True then the columns, header and downsample kwargs are ignored and the full ledger is returned.

• unique (bool, optional, defaults to True) – If True then only read targets with unique TARGETID from MTL ledgers. Only used if mtl is True.

• isodate (str, defaults to None) – Only used if mtl is True An ISO date, such as returned by desitarget.mtl.get_utc_date() `. The ledger is restricted to entries strictly BEFORE `isodate() before being extracted. If None is passed then no date restrictions are applied.

• initial (bool, optional, defaults to False) – If True then only read targets with unique TARGETID, where the FIRST occurrence of the target in the ledger is retained. i.e. read the initial state of the ledger. Overrides unique. Only used if mtl is True.

• leq (bool, optional, defaults to False) – If True, restrict the ledger to entries BEFORE or EQUAL TO isodate instead of the default behavior of strictly before isodate. Only relevant if isodate is passed. Only used if mtl is True.

• tabform (str, optional, defaults to ‘ascii.basic’) – Format to pass to the astropy Table.read() function. The default (‘ascii.basic’) is standard for reading and writing MTL files. But ‘ascii.ecsv’ is useful for some of the mock/alt-MTL work. Only relevant when mtl is True.

• maketwostyle (bool, optional, defaults to False) – If passed, add the extra columns that are added when running read_two_mtl_ledgers(), even if only reading one ledger. Only works when reading in MTLs rather than target files.

Returns:

An array of targets in the passed pixels.

Return type:

ndarray

Notes

• If header is True, then a second output (the file header is returned).

• In general, this will be quicker if pixlist contains closely grouped HEALPixels, as fewer files will need to be read.

• If mtl is True then this is just a wrapper on read_mtl_in_hp().

desitarget.io.read_targets_in_quick(hpdirname, shape=None, tiles=None, nside=None, pixlist=None, radecbox=[0.0, 360.0, -90.0, 90.0], radecrad=None, columns=None, header=False)

Read targets in various shapes, assuming a “standard” data model.

Parameters:

• hpdirname (str) – Full path to a directory containing targets that have been partitioned by HEALPixel (e.g. as made by select_targets with the bundle_files option).

• shape (str) – Type of geometric constraint being passed, options are “tiles”, “box”, “cap”, “hp”.

• tiles (ndarray, optional) – Array of tiles in the desimodel format, or None for all tiles from desimodel.io.load_tiles(). Only used if shape=tiles.

• nside (int) – The (NESTED) HEALPixel nside. Only used if shape=hp.

• pixlist (list or int or ~numpy.ndarray) – HEALPixels at the passed nside. Only used if shape=hp.

• radecbox (list, defaults to the entire sky) – 4-entry list of coordinates [ramin, ramax, decmin, decmax] forming box edges in RA/Dec (degrees). Only used if shape=box.

• radecrad (list) – 3-entry list of coordinates [ra, dec, radius] forming a cap or on the sky. ra, dec, radius in degrees. Only used if shape=cap.

• columns (list, optional) – Only read in these target columns.

• header (bool, optional, defaults to False) – If True then return the header of either the hpdirname file, or the last file read from the hpdirname directory.

Returns:

An array of targets in the passed geometric constraint.

Return type:

ndarray

Notes

• If header is True, then a second output (the file header is returned).

• $DESIMODEL must be set if shape=”tiles” and tiles=None.

• Assumes that the data model has these characteristics:

  • one HEALPixel per file.

  • no extraneous FITS files in the directory.

  • every file is formatted to finish “hp-{}.fits”.

  • every file has the same, correct FILENSID in its header.

  • the data, and related header, are in FITS extension 1.

• If you aren’t sure if the data model you have will work, or if running this code triggers an exception, instead try running the relevant “slow” function with quick=``False`` as a check, e.g. desitarget.io.read_targets_in_tiles(). The output TARGETIDs from this function and that approach should be identical, although the output may be ordered differently.

• Based on a suggestion from Anand Raichoor.

desitarget.io.read_targets_in_tiles(hpdirname, tiles=None, columns=None, header=False, quick=False, mtl=False, oldstyle=False, verbose=False, unique=True, isodate=None, initial=False, leq=False, tabform='ascii.basic', maketwostyle=False)

Read targets in DESI tiles, assuming the “standard” data model.

Parameters:

• hpdirname (str or list) –

  if a string:

  Full path to either a directory containing MTLs or targets partitioned by HEALPixel (i.e. as made by select_targets with the bundle_files option). Or the name of a single MTL or file of targets.

  If a list:

  Then this must be a list of two strings, with the strings having the same meaning as if one string is passed. The code switches to “multi-MTL” mode, where two MTLs are merged by matching on TARGETID and taking the highest-priority target. Extra columns are added to the output, indicating which of the MTLs was interested in each target. The strings must be the same input type, i.e. either two directories or files. The directories or files must share the same nside. For this mode the input mtl must be True.

• tiles (ndarray, optional) – Array of tiles in the desimodel format, or None to use all DESI tiles from desimodel.io.load_tiles().

• columns (list, optional) – Only read in these target columns.

• header (bool, optional, defaults to False) – If True then return the header of either the hpdirname file, or the last file read from the hpdirname directory.

• quick (bool, optional, defaults to False) – If True, call desitarget.io.read_targets_in_quick(). That version of the code assumes that hpdirname is a directory, of files that follow a strict data model. Passing quick=``True`` overrides the mtl/unique/isodate/initial inputs.

• mtl (bool, optional, defaults to False) – If True then read an MTL ledger file/directory instead of a target file/directory. If True then the columns and header kwargs are ignored and the full ledger is returned.

• oldstyle (bool, optional, defaults to False) – If True then use older (likely slower) code. This option is retained for tests, but we’ll likely deprecate it after testing. It only applies if quick`=``True`

• verbose (bool, optional, defaults to False) – If True then log informational messages.

• unique (bool, optional, defaults to True) – If True then only read targets with unique TARGETID from MTL ledgers. Only used if mtl is True.

• isodate (str, defaults to None) – Only used if mtl is True An ISO date, such as returned by desitarget.mtl.get_utc_date() `. The ledger is restricted to entries strictly BEFORE `isodate() before being extracted. If None is passed then no date restrictions are applied.

• initial (bool, optional, defaults to False) – If True then only read targets with unique TARGETID, where the FIRST occurrence of the target in the ledger is retained. i.e. read the initial state of the ledger. Overrides unique. Only used if mtl is True.

• leq (bool, optional, defaults to False) – If True, restrict the ledger to entries BEFORE or EQUAL TO isodate instead of the default behavior of strictly before isodate. Only relevant if isodate is passed. Only used if mtl is True.

• tabform (str, optional, defaults to ‘ascii.basic’) – Format to pass to the astropy Table.read() function. The default (‘ascii.basic’) is standard for reading and writing MTL files. But ‘ascii.ecsv’ is useful for some of the mock/alt-MTL work. Only relevant when mtl is True.

• maketwostyle (bool, optional, defaults to False) – If passed, add the extra columns that are added when running read_two_mtl_ledgers(), even if only reading one ledger. Only works when reading in MTLs rather than target files.

Returns:

An array of targets in the passed tiles.

Return type:

ndarray

Notes

• If header is True, then a second output (the file header is returned).

• The environment variable $DESIMODEL must be set.

desitarget.io.read_targets_in_tiles_quick(hpdirname, tiles=None, columns=None, header=False, verbose=False)

Read targets in tiles, assuming a “standard” data model.

Parameters:

• hpdirname (str) – Full path to a directory containing targets that have been partitioned by HEALPixel (e.g. as made by select_targets with the bundle_files option).

• tiles (ndarray, optional) – Array of tiles in the desimodel format, or None for all tiles from desimodel.io.load_tiles().

• columns (list, optional) – Only read in these target columns.

• header (bool, optional, defaults to False) – If True then return the header of either the hpdirname file, or the first file read from the hpdirname directory.

• verbose (bool, optional, defaults to False) – If True then log informational messages.

Returns:

An array of targets in the passed tiles.

Return type:

ndarray

Notes

• If header is True, then a second output (the file header is returned).

• $DESIMODEL must be set if tiles=None.

• Assumes that the data model has these characteristics:

  • one HEALPixel per file.

  • no extraneous FITS files in the directory.

  • every file is formatted to finish “hp-{}.fits”.

  • every file has the same, correct FILENSID in its header.

  • the data, and related header, are in FITS extension 1.

  • every file contains the ‘HPXPIXEL’ column at the nside stored in the file header as “HPXNSIDE”.

• If you aren’t sure if the data model you have will work, or if running this code triggers an exception, instead try running the relevant “slow” function with quick=``False`` as a check, e.g. desitarget.io.read_targets_in_tiles(). The output TARGETIDs from this function and that approach should be identical, although the output may be ordered differently.

• Based on a suggestion from Anand Raichoor.

desitarget.io.read_tractor(filename, header=False, columns=None, gaiasub=False)

Read a tractor catalogue or sweeps file.

Parameters:

• filename (str) – File name of one Tractor or sweeps file.

• header (bool, optional) – If True, return (data, header) instead of just data.

• columns (list, optional) – Specify the desired Tractor catalog columns to read; defaults to desitarget.io.tsdatamodel.dtype.names + most of the columns in desitarget.gaiamatch.gaiadatamodel.dtype.names, where tsdatamodel is, e.g., basetsdatamodel + dr9addedcols.

• gaiasub (boolean, optional, defaults to False) – If True, substitute Gaia EDR3 proper motion and parallax columns over the sweeps values. If True, then the GAIA_DIR environment variable must be set to find the Gaia sweeps files, and filename must be the full path to a DR9 sweeps file.

Returns:

Array with the tractor schema, uppercase field names.

Return type:

ndarray

desitarget.io.read_two_mtl_ledgers(filelist, unique=True, isodate=None, initial=False, leq=False, columns=None, tabform='ascii.basic', reorder=True)

Wrapper to read and merge two MTL ledger files.

Parameters:

• filelist (str) – A list of two strings, each as described for filename in read_one_mtl_ledger(). The two MTLs in the list are merged by matching on TARGETID and taking the highest-priority target.

• unique (bool, optional, defaults to True) – If True then only read targets with unique TARGETID, where the last occurrence of the target in the ledger is the one that is retained. If False then read the entire ledger.

• isodate (str, defaults to None) – A date in ISO format, such as returned by desitarget.mtl.get_utc_date() `. The ledger is restricted to entries strictly BEFORE `isodate() before being extracted. If None is passed then no date restrictions are applied.

• initial (bool, optional, defaults to False) – If True then only read targets with unique TARGETID, where the FIRST occurrence of the target in the ledger is retained. i.e. read the initial state of the ledger. Overrides unique.

• leq (bool, optional, defaults to False) – If True, restrict the ledger to entries BEFORE or EQUAL TO isodate instead of the default behavior of strictly before isodate. Only relevant if isodate is passed.

• columns (list, optional) – Only return these target columns.

• tabform (str, optional, defaults to ‘ascii.basic’) – Format to pass to the astropy Table.read() function. The default (‘ascii.basic’) is standard for reading and writing MTL files. But ‘ascii.ecsv’ is useful for some of the mock/alt-MTL work.

• reorder (bool, optional, defaults to True) – The original version of this function had a bug where if the two passed ledgers had different column orders the output could be mangled (see https://github.com/desihub/desitarget/issues/855). If reorder is True, then passed ledgers are first ordered according to a fixed MTL data model to fix this bug.

Returns:

A structured numpy array of the merged MTL. Extra columns are added to the output, indicating which of the MTLs in filelist was interested in each target.

Return type:

ndarray

desitarget.io.release_to_photsys(release)

Convert RELEASE to PHOTSYS using the releasedict lookup table.

Parameters:

release (int or ndarray) – RELEASE column from a numpy rec array of targets.

Returns:

‘N’ if the RELEASE corresponds to the northern photometric system (MzLS+BASS) and ‘S’ if it’s the southern system (DECaLS).

Return type:

str or ndarray

Notes

Flags an error if the system is not recognized.

desitarget.io.target_columns_from_header(hpdirname)

Grab the _TARGET column names from a TARGETS file or directory.

Parameters:

hpdirname (str) – Full path to either a directory containing targets that have been partitioned by HEALPixel (i.e. as made by select_targets with the bundle_files option). Or the name of a single file of targets.

Returns:

The names of the _TARGET columns, notably whether they are SV, main, or cmx _TARGET columns.

Return type:

list

desitarget.io.whitespace_fits_read(filename, **kwargs)

Use fitsio to read in a file and strip whitespace from all string columns.

Parameters:

• filename (str) – Name of the file to be read in by fitsio.

• kwargs (arguments that will be passed directly to fitsio.)

desitarget.io.write_gfas(targdir, data, indir=None, indir2=None, nside=None, nsidefile=None, hpxlist=None, extra=None)

Write a catalogue of Guide/Focus/Alignment targets.

Parameters:

• targdir (str) – Path to output target selection directory (the directory structure and file name are built on-the-fly from other inputs).

• data (ndarray) – Array of GFAs to write to file.

• indir (str, optional, defaults to None.) – Legacy Survey Data Release directory or directories, write to header of output file if passed (and if not None).

• indir2 (str, optional, defaults to None.) – Legacy Survey Data Release directory or directories, write to header of output file if passed (and if not None).

• nside (int, defaults to None.) – If passed, add a column to the GFAs array popluated with HEALPixels at resolution nside.

• nsidefile (int, optional, defaults to None) – Passed to indicate in the output file header that the targets have been limited to only certain HEALPixels at a given nside. Used in conjunction with hpxlist.

• hpxlist (list, optional, defaults to None) – Passed to indicate in the output file header that the targets have been limited to only this list of HEALPixels. Used in conjunction with nsidefile.

• extra (dict, optional) – If passed (and not None), write these extra dictionary keys and values to the output header.

Returns:

• int – The number of gfas that were written to file.

• str – The name of the file to which gfas were written.

desitarget.io.write_in_chunks(filename, data, nchunks, extname=None, header=None)

Write a FITS file in chunks to save memory.

Parameters:

• filename (str) – The output file.

• data (ndarray) – The numpy structured array of data to write.

• nchunks (:class`int`, optional, defaults to None) – The number of chunks in which to write the output file.

• extname – Passed through to fitsio.write().

• header – Passed through to fitsio.write().

• clobber – Passed through to fitsio.write().

• optional – Passed through to fitsio.write().

Return type:

Nothing, but writes the data to the filename in chunks.

Notes

• Always OVERWRITES existing files!

• Mostly deprecated, so was never updated to write units.

desitarget.io.write_masks(maskdir, data, maglim=None, maskepoch=None, nside=None, extra=None)

Write a catalogue of masks and associated pixel-level info.

Parameters:

• maskdir (str) – Path to output mask directory (the file names are built on-the-fly from other inputs).

• data (ndarray) – Array of masks to write to file. Must contain at least the columns “RA” and “DEC”.

• maglim (float, optional, defaults to None) – Magnitude limit to which the mask was made.

• maskepoch (float, optional, defaults to None) – Epoch at which the mask was made.

• nside (int, defaults to not splitting by HEALPixel.) – The HEALPix nside at which to write the output files.

• extra (dict, optional) – If passed (and not None), write these extra dictionary keys and values to the output header.

Returns:

• int – The total number of masks that were written.

• str – The name of the directory to which masks were written.

desitarget.io.write_mtl(mtldir, data, indir=None, survey='main', obscon=None, scnd=False, nsidefile=None, hpxlist=None, extra=None, override=False, ecsv=True, mixed=False, nowrite=False, append=False)

Write Merged Target List ledgers or files.

Parameters:

• mtldir (str) – Path to output MTL directory (the directory structure and file name are built on-the-fly from other inputs).

• data (ndarray) – numpy structured array of merged targets to write.

• indir (str, optional, defaults to None) – If passed, note as the input directory in the output file header.

• survey (str, optional, defaults to “main”) – Written to output file header as the keyword SURVEY.

• obscon (str, optional) – Name of the OBSCONDITIONS used to make the file (e.g. DARK).

• scnd (bool, defaults to False) – If True then these are secondary targets. Write scnd=True to the header and /secondary/ to the output directory structure.

• nsidefile (int, optional) – Passed to indicate in the output file header that the targets have been limited to only certain HEALPixels at a given nside. Used in conjunction with hpxlist.

• hpxlist (list, optional, defaults to None) – Passed to indicate in the output file header that the targets have been limited to only this list of HEALPixels. Used in conjunction with nsidefile.

• extra (dict, optional) – If passed (and not None), write these extra dictionary keys and values to the output header.

• override (bool, optional, defaults to False) – If True, this is an MTL override file. Any instance of “mtl” in the filename is replaced by “mtl-override” and the final part of the directory structure includes “override”.

• ecsv (bool, defaults to True) – If True write a .ecsv file, if False with a .fits file.

• mixed (bool, defaults to False) – If True allow data to be from different Data Releases and write out the largest data release integer to the file headers. Useful when writing targets from, e.g., DR9 of the Legacy Surveys and DR2 of Gaia to the same file.

• nowrite (bool, defaults to False) – If passed just return 0 and the name of the file. Don’t actually write anything. Useful for retrieving the filename that WOULD have been written.

• append (bool, optional, defaults to False) – If True then append to any existing ledgers rather than creating new ones. In this mode, if a ledger exists it will be appended to and if it doesn’t exist it will be created. Only currently coded for .ecsv ledgers.

Returns:

• int – The number of targets that were written to file.

• str – The name of the file to which targets were written.

desitarget.io.write_mtl_tile_file(filename, data)

Append new tiles to the end of the MTL tile file.

Parameters:

• filename (str) – The full path to the MTL tile file. If this doesn’t exist, then a new file is begun.

• data (:class`~numpy.ndarray`) – The data to append to the end of the MTL tile file, which should be in the format of desitarget.mtl.mtltilefiledm

Returns:

• int – The number of targets that were written to file.

• str – The name of the file to which targets were written.

desitarget.io.write_randoms(targdir, data, indir=None, hdr=None, nside=None, supp=False, nsidefile=None, hpxlist=None, resolve=True, north=None, extra=None, hpxsplit=False)

Write a catalogue of randoms and associated pixel-level info.

Parameters:

• targdir (str) – Path to output target selection directory (the directory structure and file name are built on-the-fly from other inputs).

• data (ndarray) – Array of randoms to write to file.

• indir (str, optional, defaults to None) – Name of input Legacy Survey Data Release directory, write to header of output file if passed (and if not None).

• hdr (str, optional, defaults to None) – If passed, use this header to start the header for filename.

• nside (int) – If passed, add a column to the randoms array popluated with HEALPixels at resolution nside.

• supp (bool, optional, defaults to False) – Written to the header of the output file to indicate whether this is a supplemental file (i.e. random locations that are outside the Legacy Surveys footprint).

• nsidefile (int, optional, defaults to None) – Passed to indicate in the output file header that the targets have been limited to only certain HEALPixels at a given nside. Used in conjunction with hpxlist.

• hpxlist (list, optional, defaults to None) – Passed to indicate in the output file header that the targets have been limited to only this list of HEALPixels. Used in conjunction with nsidefile.

• resolve (bool, optional, defaults to True) – Written to the output file header as RESOLVE. If True (False) output directory includes “resolve” (“noresolve”).

• north (bool, optional) – If passed (and not None), then, if True (False), REGION=north (south) is written to the output header and the output directory name is appended by “north” (“south”).

• extra (dict, optional) – If passed (and not None), write these extra dictionary keys and values to the output header.

• hpxsplit (bool, optional, defaults to False) – If True use the “INFILE” key in hdr to determine an extra, final, directory to add to the output path.

Returns:

• int – The number of randoms that were written to file.

• str – The name of the file to which randoms were written.

desitarget.io.write_randoms_in_hp(randoms, outdirname, nside, pixlist, hpx=None, verbose=True, infile=None, hdr=None)

Rewrite a random catalog split by HEALPixel.

Parameters:

• randoms (array) – Entries a from random catalog as made by, e.g., desitarget.randoms.select_randoms().

• outdirname (str) – Output directory to which to write the random catalog (the file names are constructed on the fly).

• nside (int) – (NESTED) HEALPixel nside that corresponds to pixlist.

• hpx (array, optional, defaults to None) – The HEALPixel occupied by each of randoms in the NESTED scheme at nside. If hpx isn’t passed it will be calculated from the required inputs. But, for large randoms array it may be quicker to calculate it in advance. Must contain one HEALPixel number for each row in randoms.

• pixlist (list or int) – HEALPixels at nside at which to write the split catalogs.

• verbose (bool, optional, defaults to True) – If True then log target and file information.

• infile (str, optional, defaults to None) – Name of input random catalog to add to the output file header.

• hdr (dict, optional, defaults to None) – Dictionary to write as the header of the output file. Note that hdr is a kwarg so will be modified-in-place.

Returns:

• int – The number of randoms that were written to file.

• str – The name of the file to which randoms were written.

Notes

• A new column HPXPIXEL is added to randoms (or overwritten if it already exists). HPXNSIDE=`nside` and FILENSID=`nside` and “HPXNEST”=``True`` are added to the output header (or overwritten, if they already exist).

desitarget.io.write_secondary(targdir, data, primhdr=None, scxdir=None, obscon=None, drint='X', subpriority=True, iteration=None, overlybright=False, matchrad=3.0)

Write a catalogue of secondary targets.

Parameters:

• targdir (str) – Path to output target selection directory (the directory structure and file name are built on-the-fly from other inputs).

• data (ndarray) – numpy structured array of secondary targets to write.

• primhdr (str, optional, defaults to None) – If passed, added to the header of the output catalogue.

• scxdir (str, optional, defaults to SCND_DIR) – Name of the directory that hosts secondary targets. The secondary targets are written back out to this directory in the sub-directory “outdata” and the scxdir is added to the header of the output filename.

• obscon (str, optional, defaults to None) – Can pass one of “DARK”, “BRIGHT” or “BACKUP”. If passed, don’t write the full set of secondary targets that do not match a primary, rather only write targets appropriate for passed observing conditions. The relevant PRIORITY_INIT and NUMOBS_INIT columns will be derived from, e.g., PRIORITY_INIT_DARK, etc. and filename will have “dark”, etc. appended to the lowest DIRECTORY in the input filename.

• drint (int, optional, defaults to X) – The data release (“dr”drint”-”) in the output filename.

• subpriority (bool, optional, defaults to True) – If True and a SUBPRIORITY column is in the input data, then SUBPRIORITY==0.0 entries are overwritten by a random float in the range 0 to 1, using seed 717.

• iteration (integer or str, optional, defaults to None) – Hardcode the survey name as “main”+`iteration`. Useful when in the context of the Main Survey but writing extra secondaries that can’t be merged with primaries. The random seed for SUBPRIORITY is also augmented by adding iteration to it.

• overlybright (bool, optional, defaults to False) – If True then run an additional, more rigorous, check that no targets are near bright (maglim < 16) Gaia stars.

• matchrad (float, optional, defaults to 3 arcsec) – The match radius around bright stars when using overlybright.

Returns:

• int – The number of secondary targets that do not match a primary target that were written to file.

• str – The name of the file to which such targets were written.

Notes

• Two sets of files are written:

  • The file of secondary targets that do not match a primary target is written to targdir. Such secondary targets are determined from having “PRIM_MATCH”=``False`` in data. Only targets with PRIORITY_INIT > -1 are written to this file (this allows duplicates to be resolved in, e.g., finalize().

  • Each secondary target that, presumably, was initially drawn from the “indata” subdirectory of scxdir is written to the “outdata” subdirectory of scxdir.

• Various columns and header keywords are updated when writing, so take care. For instance, pass subpriority=False unless you really want to update the SUBPRIORITY column.

desitarget.io.write_skies(targdir, data, indir=None, indir2=None, supp=False, apertures_arcsec=None, nskiespersqdeg=None, nside=None, nsidefile=None, hpxlist=None, extra=None, extradeps=None, mock=False, subpriority=True)

Write a target catalogue of sky locations.

Parameters:

• targdir (str) – Path to output target selection directory (the directory structure and file name are built on-the-fly from other inputs).

• data (ndarray) – Array of skies to write to file.

• indir (str, optional) – Name of input Legacy Survey Data Release directory/directories, write to header of output file if passed (and if not None).

• indir2 (str, optional) – Name of input Legacy Survey Data Release directory/directories, write to header of output file if passed (and if not None).

• supp (bool, optional, defaults to False) – Written to the header of the output file to indicate whether this is a file of supplemental skies (sky locations that are outside the Legacy Surveys footprint).

• apertures_arcsec (list or float, optional) – list of aperture radii in arcseconds to write each aperture as an individual line in the header, if passed (and if not None).

• nskiespersqdeg (float, optional) – Number of sky locations generated per sq. deg., write to header of output file if passed (and if not None).

• nside (int, optional) – If passed, add a column to the skies array popluated with HEALPixels at resolution nside.

• nsidefile (int, optional, defaults to None) – Passed to indicate in the output file header that the targets have been limited to only certain HEALPixels at a given nside. Used in conjunction with hpxlist.

• hpxlist (list or int, optional, defaults to None) – Passed to indicate in the output file header that the targets have been limited to only this list of HEALPixels. May also be a scalar integer. Used in conjunction with nsidefile.

• extra (dict, optional) – If passed (and not None), write these extra dictionary keys and values to the output header.

• extradeps (dict, optional) – If not None, add extra DEPNAMnn/DEPVERnn keywords to output header

• mock (bool, optional, defaults to False.) – If True then construct the file path for mock sky target catalogs.

• subpriority (bool, optional, defaults to True) – If True and a SUBPRIORITY column is in the input data, then SUBPRIORITY==0.0 entries are overwritten by a random float in the range 0 to 1, using either (a) if supp is False: seed 718 + 1e8*drint, or seed 718 + 1e8*drint + the first value in hpxlist, if hpxlist is passed and not None or (b) if supp is True seed 719 + 1e8*gaiadr + hp.nside2npix(1024) or seed 719 + 1e8*gaiadr + hp.nside2npix(1024) + first value in hpxlist, if hpxlist is passed and not None. Here, drint and gaiadr are Data Release numbers from the Legacy Surveys or Gaia that are derived by the code itself. If the drint term is less than 10 or is None, then the 1e8*drint term is omitted. Similarly if the gaiadr term is less than 3 or is None then the 1e8*drint term is omitted.

Returns:

• int – The number of skies that were written to file.

• str – The name of the file to which skies were written.

Notes

• Various columns and header keywords are updated when writing, so take care. For instance, pass subpriority=False unless you really want to update the SUBPRIORITY column.

• Because of the way random seeds are constructed for SUBPRIORITY, we require nsidefile to be less than 1024.

desitarget.io.write_targets(targdir, data, indir=None, indir2=None, nchunks=None, qso_selection=None, nside=None, survey='main', nsidefile=None, hpxlist=None, scndout=None, resolve=True, maskbits=True, obscon=None, mockdata=None, supp=False, extra=None, extradeps=None, nosec=False, infiles=None, checkbright=False, subpriority=True)

Write target catalogues.

Parameters:

• targdir (str) – Path to output target selection directory (the directory structure and file name are built on-the-fly from other inputs).

• data (ndarray) – numpy structured array of targets to save.

• indir (str, optional, default to None) – If passed, note these as the input directory, an additional input directory, and the QSO selection method in the output file header.

• indir2 (str, optional, default to None) – If passed, note these as the input directory, an additional input directory, and the QSO selection method in the output file header.

• qso_selection (str, optional, default to None) – If passed, note these as the input directory, an additional input directory, and the QSO selection method in the output file header.

• nchunks (:class`int`, optional, defaults to None) – The number of chunks in which to write the output file, to save memory. Send None to write everything at once.

• nside (int, optional, defaults to None) – If passed, add a column to the targets array popluated with HEALPixels in the nested scheme at resolution nside.

• survey (str, optional, defaults to “main”) – Written to output file header as the keyword SURVEY.

• nsidefile (int, optional, defaults to None) – Passed to indicate in the output file header that the targets have been limited to only certain HEALPixels at a given nside. Used in conjunction with hpxlist.

• hpxlist (list, optional, defaults to None) – Passed to indicate in the output file header that the targets have been limited to only this list of HEALPixels. Used in conjunction with nsidefile.

• resolve (bool, optional, default to True) – Written to the output file header as RESOLVE, MASKBITS.

• maskbits (bool, optional, default to True) – Written to the output file header as RESOLVE, MASKBITS.

• scndout (str, optional, defaults to None) – If passed, add to output header as SCNDOUT.

• obscon (str, optional, defaults to None) – Can pass one of “DARK” or “BRIGHT”. If passed, don’t write the full set of data, rather only write targets appropriate for “DARK” or “BRIGHT” observing conditions. The relevant PRIORITY_INIT and NUMOBS_INIT columns will be derived from PRIORITY_INIT_DARK, etc. and filename will have “bright” or “dark” appended to the lowest DIRECTORY in the input filename.

• mockdata (dict, optional, defaults to None) – Dictionary of mock data to write out (only used in desitarget.mock.build.targets_truth via select_mock_targets).

• supp (bool, optional, defaults to False) – Written to the header of the output file as “BACKUP” to indicate whether this is a file of backup targets (targets that are based only on Gaia data).

• extra (dict, optional) – If passed (and not None), write these extra dictionary keys and values to the output header.

• extradeps (dict, optional) – If not None, add extra DEPNAMnn/DEPVERnn keywords to output header

• nosec (bool, optional, defaults to False) – Written to the output file header as NOSEC. If both this kwarg and supp are True, add a SCND_TARGET column to the file.

• infiles (list or ~numpy.ndarray, optional) – If passed (and not None), write a second extension “INFILES” that contains the files in infiles and their SHA-256 checksums. If infiles is a list, func:~desitarget.io.get_checksums() is called to look-up the checksums, if infiles is a numpy array it’s assumed to be in the format returned by get_checksums().

• checkbright (bool, optional, defaults to False) – If True then log a warning about targets that are being written to file and that could be too bright.

• subpriority (bool, optional, defaults to True) – If True and a SUBPRIORITY column is in the input data, then SUBPRIORITY==0.0 entries are overwritten by a random float in the range 0 to 1, using either a seed of 716 + 1e8*drint, or a seed of 716 + 1e8*drint + the first value in hpxlist, if hpxlist is passed and not None. Here drint is the Data Release number derived by the function itself. If drint is less than 10 or is None, then the 1e8*drint term is omitted.

Returns:

• int – The number of targets that were written to file.

• str – The name of the file to which targets were written.

Notes

• Various columns and header keywords are updated when writing, so take care. For instance, pass subpriority=False unless you really want to update the SUBPRIORITY column.

desitarget.io.write_with_units(filename, data, extname=None, header=None, ecsv=False)

Write a FITS file with units from the desitarget data model.

Parameters:

• filename (str) – The output file.

• data (ndarray) – The numpy structured array of data to write.

• extname – Passed through to fitsio.write(). header can be either a FITShdr object or a dictionary.

• optional (header) – Passed through to fitsio.write(). header can be either a FITShdr object or a dictionary.

• ecsv (bool, optional, defaults to False) – If True then write as a .ecsv file instead of FITS.

Returns:

• Nothing, but writes the data to the filename with units

• added from the desitarget units yaml file (see /data/units.yaml).

Notes

• Always OVERWRITES existing files!

• Writes atomically. Any files that died mid-write will be appended by “.tmp”.

• If ecsv is True then a (potentially slow) Table conversion is applied to data.

desitarget.mock

This subpackage contains modules that handle mock data.

desitarget.mock.build

Build truth and targets catalogs, including spectra, for the mocks.

desitarget.mock.build._get_spectra_onepixel(specargs)

Filler function for the multiprocessing.

desitarget.mock.build._merge_file_tables(fileglob, ext, outfile=None, comm=None, addcols=None, overwrite=False)

parallel merge tables from individual files into an output file

Parameters:

• fileglob (str) – glob of files to combine (e.g. ‘/blat-.fits’)

• ext (str or int) – FITS file extension name or number

Options:

outfile (str): output file to write comm: MPI communicator object addcols: dict extra columns to add with fill values, e.g. dict(OBSCONDITIONS=1)

Returns merged table as np.ndarray

desitarget.mock.build.density_fluctuations(data, log, nside, nside_chunk, seed=None)

Determine the density of targets to generate, accounting for fluctuations due to reddening, imaging systematics, and large-scale structure.

Parameters:

• data (dict) – Data on the input mock targets (to be documented).

• log (desiutil.logger) – Logger object.

• nside (int) – Healpix resolution.

• nside_chunk (int) – Healpix resolution for chunking the sample.

• seed (int, optional) – Seed for the random number generator. Defaults to None.

Returns:

• indxperchunk (list) – Indices (in data) of the mock targets to generate per healpixel chunk.

• ntargperchunk (numpy.ndarray) – Number of targets to generate per healpixel chunk.

• areaperpixel (float) – Area per healpixel (used to construct useful log messages).

desitarget.mock.build.finish_catalog(targets, truth, objtruth, skytargets, skytruth, healpix, nside, log, seed=None, survey='main')

Add various mission-critical columns to the target catalog, including hpxpixel, brick_objid, targetid, subpriority, priority, and numobs.

Parameters:

• targets (astropy.table.Table) – Final set of targets.

• truth (astropy.table.Table) – Corresponding truth table for targets.

• objtruth (astropy.table.Table) – Corresponding objtype-specific truth table (if applicable).

• skytargets (astropy.table.Table) – Sky targets.

• skytruth (astropy.table.Table) – Corresponding truth table for sky targets.

• healpix (: int) – Healpixel number.

• nside (int) – Nside corresponding to healpix.

• log (desiutil.logger) – Logger object.

• seed (int, optional) – Seed for the random number generation. Defaults to None.

• survey (str, optional) – Specify which target masks yaml file to use. The options are main (main survey) and sv1 (first iteration of SV). Defaults to main.

Return type:

Updated versions of targets, truth, objtruth, skytargets, and skytruth.

desitarget.mock.build.get_contaminants_onepixel(params, healpix, nside, seed, nproc, log, nside_chunk, targets, truth, objtruth, trueflux, ContamStarsMock=None, ContamGalaxiesMock=None, no_spectra=False)

Generate spectra (in parallel) for a set of targets.

Parameters:

• params (dict) – Dictionary defining the type and number of contaminants.

• healpix (: int) – Healpixel number.

• nside (int) – Nside corresponding to healpix.

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

• nproc (int, optional) – Number of parallel processes to use.

• log (desiutil.logger) – Logger object.

• nside_chunk (int) – Healpix resolution for chunking the sample to avoid memory problems.

• targets (astropy.table.Table) – Target catalog.

• truth (astropy.table.Table) – Corresponding truth table.

• objtruth (astropy.table.Table) – Corresponding objtype-specific truth table (if applicable).

• trueflux (numpy.ndarray) – Array [npixel, ntarget] of observed-frame spectra. Only computed and returned for non-sky targets and if no_spectra=False.

• ContamStarsMock (desitarget.mock.mockmaker object) – Maker Class for generating stellar contaminants.

• ContamGalaxiesMock (desitarget.mock.mockmaker object) – Maker Class for generating extragalactic contaminants.

• no_spectra (bool, optional) – Do not generate spectra, e.g., for use with quicksurvey. Defaults to False.

Returns:

• targets (astropy.table.Table) – Target catalog.

• truth (astropy.table.Table) – Corresponding truth table.

• objtruth (astropy.table.Table) – Corresponding objtype-specific truth table (if applicable).

• trueflux (numpy.ndarray) – Corresponding noiseless spectra.

desitarget.mock.build.get_spectra(data, MakeMock, log, nside, nside_chunk, seed=None, nproc=1, sky=False, no_spectra=False, calib_only=False, contaminants=False)

Generate spectra (in parallel) for a set of targets.

Parameters:

• data (dict) – Data on the input mock targets (to be documented).

• MakeMock (desitarget.mock.mockmaker object) – Object to assign spectra to each target class.

• log (desiutil.logger) – Logger object.

• nside (int) – Healpix resolution corresponding to healpixels.

• nside_chunk (int) – Healpix resolution for chunking the sample to avoid memory problems.

• seed (int, optional) – Seed for the random number generator. Defaults to None.

• nproc (int, optional) – Number of parallel processes to use. Defaults to 1.

• sky (bool) – Processing sky targets (which are a special case). Defaults to False.

• no_spectra (bool, optional) – Do not generate spectra, e.g., for use with quicksurvey. Defaults to False.

• calib_only (bool, optional) – Use targets as calibration (standard star) targets, only. Defaults to False.

• contaminants (bool, optional) – Generate spectra for contaminants (mostly affects the log messages). Defaults to False.

Returns:

• targets (astropy.table.Table) – Target catalog.

• truth (astropy.table.Table) – Corresponding truth table.

• objtruth (astropy.table.Table) – Corresponding objtype-specific truth table (if applicable).

• trueflux (numpy.ndarray) – Corresponding noiseless spectra.

desitarget.mock.build.get_spectra_onepixel(data, indx, MakeMock, seed, log, ntarget, maxiter=1, no_spectra=False, calib_only=False)

Wrapper function to generate spectra for all targets on a single healpixel.

Parameters:

• data (dict) – Dictionary with all the mock data (candidate mock targets).

• indx (int or numpy.ndarray) – Indices of candidate mock targets to consider.

• MakeMock (desitarget.mock.mockmaker object) – Object to assign spectra to each target class.

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

• log (desiutil.logger) – Logger object.

• ntarget (int) – Desired number of targets to generate.

• maxiter (int) – Maximum number of iterations to generate targets.

• no_spectra (bool, optional) – Do not generate spectra, e.g., for use with quicksurvey. Defaults to False.

• calib_only (bool, optional) – Use targets as calibration (standard star) targets, only. Defaults to False.

Returns:

• targets (astropy.table.Table) – Target catalog.

• truth (astropy.table.Table) – Corresponding truth table.

• objtruth (astropy.table.Table) – Corresponding objtype-specific truth table (if applicable).

• trueflux (numpy.ndarray) – Array [npixel, ntarget] of observed-frame spectra. Only computed and returned for non-sky targets and if no_spectra=False.

desitarget.mock.build.initialize_targets_truth(params, healpixels=None, nside=None, output_dir='.', seed=None, verbose=False)

Initialize various objects needed to generate mock targets.

Parameters:

• params (dict) – Dictionary defining the mock from which to generate targets.

• healpixels (numpy.ndarray or int) – Generate mock targets within this set of healpix pixels.

• nside (int) – Healpix resolution corresponding to healpixels.

• output_dir (str, optional.) – Output directory. Defaults to ‘.’ (current directory).

• seed (int, optional) – Seed for the random number generator. Defaults to None.

• verbose (bool, optional) – Be verbose. Defaults to False.

Returns:

• log (desiutil.logger) – Logger object.

• healpixseeds (numpy.ndarray or int) – Array of random number seeds (one per healpixels pixel) needed to ensure reproducibility.

Raises:

ValueError – If params, healpixels, or nside are not defined. A ValueError is also raised if nside > 256, since this exceeds the number of bits that can be accommodated by desitarget.targets.encode_targetid.

desitarget.mock.build.join_targets_truth(mockdir, outdir=None, overwrite=False, comm=None)

Join individual healpixel targets and truth files into combined tables

Parameters:

mockdir – top level mock target directory

Options:

outdir: output directory, default to mockdir overwrite: rewrite outputs even if they already exist comm: MPI communicator; if not None, read data in parallel

desitarget.mock.build.read_mock(params, log=None, target_name='', seed=None, healpixels=None, nside=None, nside_chunk=128, MakeMock=None, dndz=None)

Read a mock catalog.

Parameters:

• params (dict) – Dictionary summary of the input configuration file, restricted to a particular target (e.g., ‘QSO’).

• log (desiutil.logger) – Logger object.

• target_name (str) – Target name; mock.mockmaker.[TARGET_NAME]Maker class to instantiate.

• seed (int, optional) – Seed for the random number generator. Defaults to None.

• healpixels (numpy.ndarray or int) – List of healpixels to read.

• nside (int) – Healpix resolution corresponding to healpixels.

• nside_chunk (int, optional) – Healpix resolution for chunking the sample to avoid memory problems. (NB: nside_chunk must be <= nside). Defaults to 128.

• dndz (dict, optional) – Expected redshift distributions for all target classes. Defaults to None.

Returns:

data – Parsed target data based on the input mock catalog (to be documented).

Return type:

dict

Raises:

ValueError – If the mock_density was not returned when expected.

desitarget.mock.build.targets_truth(params, healpixels=None, nside=None, output_dir='.', seed=None, nproc=1, nside_chunk=128, survey='main', verbose=False, no_spectra=False)

Generate truth and targets catalogs, and noiseless spectra.

Parameters:

• params (dict) – Target parameters.

• healpixels (numpy.ndarray or int) – Restrict the sample of mock targets analyzed to those lying inside this set (array) of healpix pixels.

• nside (int) – Healpix resolution corresponding to healpixels.

• output_dir (str, optional) – Output directory. Defaults to ‘.’ (current directory).

• seed (int) – Seed for the random number generation. Defaults to None.

• nproc (int, optional) – Number of parallel processes to use. Defaults to 1 (i.e., no multiprocessing).

• nside_chunk (int, optional) – Healpix resolution for chunking the sample to avoid memory problems. (NB: nside_chunk must be <= nside). Defaults to 128.

• survey (str, optional) – Specify which target masks yaml file to use. The options are main (main survey) and sv1 (first iteration of SV). Defaults to main.

• verbose (bool, optional) – Be verbose. Defaults to False.

• no_spectra (bool, optional) – Do not generate spectra, e.g., for use with quicksurvey.

Returns:

• Files ‘targets.fits’, ‘truth.fits’, ‘sky.fits’, ‘standards-dark.fits’, and

• ’standards-bright.fits’ written to output_dir for the given list of

• healpixels.

desitarget.mock.io

Code to find the location of the mock data.

desitarget.mock.io.findfile(filetype, nside, pixnum, basedir='.', ext='fits', obscon=None)

Returns standardized filepath

Parameters:

• filetype – (str) file prefix, e.g. ‘sky’ or ‘targets’

• nside – (int) healpix nside 2**k with 0<k<30

• pixnum – (int) healpix NESTED pixel number for this nside

Optional:

basedir: (str) base directory ext: (str) file extension obscon: (str) e.g. ‘dark’, ‘bright’ to add extra dir grouping

desitarget.mock.io.get_healpix_dir(nside, pixnum, basedir='.')

Returns standardized path

Parameters:

• nside – (int) healpix nside 2**k with 0<k<30

• pixnum – (int) healpix NESTED pixel number for this nside

Optional:

basedir: (str) base directory

Note: may standardize with functions in desispec.io, but separate for now

desitarget.mock.sky.random_sky(nside=2048, allsky=True, tiles=None, maxiter=20, outfile=None)

Returns sky locations within healpixels covering tiles

Options:

nside (int): healpixel nside; coverage is uniform at this scale allsky (bool): generate sky positions over the full sky tiles: DESI tiles to cover, for desimodel.footprint.tiles2pix(); only used if allsky=False. maxiter (int): maximum number of iterations to ensure coverage

Generates sky locations that are more uniform than true random, such that every healpixel has a point within it. Note that this should not be used for mock randoms.

nside=2048 corresponds to about half of a DESI positioner patrol area and results in ~18M sky locations over the full footprint.

desitarget.mtl

Merged target lists.

desitarget.mtl._get_mtl_nside()

Grab the HEALPixel nside to be used for MTL ledger files.

Returns:

The HEALPixel nside number for MTL file creation and retrieval.

Return type:

int

desitarget.mtl.add_to_iso_date(isodate, secs)

Convenience function to add seconds to an ISO date.

Parameters:

• isodate (str) – Date in STRICT ISO format, appropriate for a TIMESTAMP. As produced by, e.g., desitarget.mtl.get_utc_iso_date().

• secs (int) – Number of seconds to add to isodate.

Returns:

Date in STRICT ISO format with secs added.

Return type:

str

desitarget.mtl.add_to_ledgers(targs, mtldir=None, pixlist=None, obscon='DARK', numproc=1, updatedonefiles=True)

Add new targets to MTL ledger files for HEALPixels, in parallel.

Parameters:

• targs (str or ~numpy.ndarray) – Full path to a file containing targets to be added to ledgers, or the targets themselves. A string is interpreted as a filename, anything else is interpreted as an array of targets.

• mtldir (str, optional, defaults to None) – Full path to the directory that hosts the MTL ledgers and the MTL tile file. If None, then look up the MTL directory from the $MTL_DIR environment variable.

• pixlist (list or int, defaults to None) – (Nested) HEALPixels for which to write the MTLs at the default nside (which is _get_mtl_nside()). Defaults to None, which runs all of the pixels at _get_mtl_nside() that are present in the input targs.

• obscon (str, optional, defaults to “DARK”) – A string matching ONE obscondition in the desitarget bitmask yaml file (i.e. in desitarget.targetmask.obsconditions), e.g. “DARK” Governs how priorities are set based on “obsconditions”. Also governs the sub-directory to which the ledgers are added.

• numproc (int, optional, defaults to 1 for serial) – Number of processes to parallelize across.

• updatedonefiles (bool, optional, defaults to True) – If False then do NOT write a timestamp to the MTL override “done” files indicating an update has occurred. USE WITH CAUTION. In general, the alt-MTL schema NEEDS TO KNOW WHEN UPDATES HAPPENED.

Returns:

• Nothing, but appends the targs to the appropriate ledgers in

• the mtldir.

desitarget.mtl.add_to_ledgers_in_hp(targets, pixlist, mtldir=None, obscon='DARK', timestamp=None, verbose=True, updatedonefiles=False)

Add new targets to an existing set of ledgers.

Parameters:

• targets (array) – Targets made by, e.g. desitarget.streams.cuts.select_targets().

• pixlist (list or int) – HEALPixels at _get_mtl_nside() in which to add to MTLs.

• mtldir (str, optional, defaults to None) – Full path to the directory that hosts the MTL ledgers and the MTL tile file. If None, then look up the MTL directory from the $MTL_DIR environment variable.

• obscon (str, optional, defaults to “DARK”) – A string matching ONE obscondition in the desitarget bitmask yaml file (i.e. in desitarget.targetmask.obsconditions). Governs the sub-directory for which the ledgers are appended.

• timestamp (str, optional) – A timestamp to use in place of that assigned by make_mtl.

• verbose (bool, optional, defaults to True) – If True then log target and file information.

• updatedonefiles (bool, optional, defaults to True) – If False then do NOT write a timestamp to the MTL override “done” files indicating an update has occurred.

Returns:

• Nothing, but appends the targets to the appropriate ledgers in

• the mtldir.

Notes

• Where there is a matching TARGETID, the priority and number of observations are both set to the higher number and the bits are merged across target classes.

desitarget.mtl.check_archiving(obscon, survey='main', zcatdir=None, mtldir=None)

Check the previous archiving state of tiles.

Parameters:

• obscon (str) – A string matching ONE observing condition. Allowed options are “DARK”, “BRIGHT”, “DARK1B” and “BRIGHT1B”, “BACKUP”.

• survey (str, optional, defaults to “main”) – Used to look up the correct ledger, in combination with obscon. Options are 'main' and 'svX’ (where X is 1, 2, 3 etc.) for the main survey and different iterations of SV, respectively.

• zcatdir (str, optional) – Full path to the directory that hosts redshift catalogs. Defaults to the directory stored in the $ZCAT_DIR environment variable.

• mtldir (str, optional, defaults to None) – Full path to the directory that hosts the MTL ledgers and the MTL tile file. If None, then look up the MTL directory from the $MTL_DIR environment variable.

Notes

• The basic check is that the latest archive date for tiles in the “archive” sub-directory of the redshift catalog directory matches the ARCHIVEDATE recorded in the tiles-specstatus.ecsv file.

• The check is limited to BRIGHT/DARK main survey tiles.

• Based on work by Anand Raichoor.

desitarget.mtl.check_timestamp(timestamp)

Check whether a timestamp is in a valid datetime format.

Parameters:

timestamp (str) – A string that should be a valid datetime string with a timezone.

Returns:

The input timestamp string.

Return type:

str

Notes

• Triggers an exception if the string is not a valid datetime string or if the timezone was not included in the string.

desitarget.mtl.days_between_nights(date1, date2)

Find the number of days between two dates in YYYYMMDD format

Parameters:

• date1 (str or int or array_like) – Two dates or arrays of dates in YYYYMMDD format.

• date2 (str or int or array_like) – Two dates or arrays of dates in YYYYMMDD format.

Returns:

Number of days between the dates. date2 is assumed to be the later date, so +ve answers are returned if date2 > date1.

Return type:

array

desitarget.mtl.find_non_overlap_tiles(obscon, mtldir=None, isodate=None, check=False)

Find tiles in the MTL ledgers that do not overlap any future tile.

Parameters:

• obscon (str) – A string matching ONE obscondition in the desitarget bitmask yaml file (i.e. in desitarget.targetmask.obsconditions), e.g. “DARK” Used to construct the directory to find the Main Survey ledgers.

• mtldir (str, optional, defaults to None) – Full path to the directory that hosts the MTL ledgers and the MTL tile file. If None, then look up the MTL directory from the $MTL_DIR environment variable.

• isodate (str, optional, defaults to None) – A date in ISO format, such as returned by desitarget.mtl.get_utc_date(). Only tiles processed AFTER OR EXACTLY ON isodate are considered. If None then no date restrictions are applied.

• check (bool, optional, defaults to False) – If True, then instead of a list of non-overlapping tiles, return a dictionary whose keys are the list of non-overlapping tiles and whose values are dictionaries who, in turn, have keys corresponding to any past overlapping tiles and values that are the TIMESTAMP for that past overlapping tile.

Returns:

A table of tiles (in the standard DESI format) that weren’t covered by a future, overlapping tile, sorted by TILEID. A dictionary is returned instead if check is passed as True.

Return type:

Table or dict

Notes

• Requires both the ops and mtl parts of the operations SVN trunk to be checked out in the standard location relative to mtldir.

• Only works for Main Survey tiles, because we only look in the tiles-main.ecsv file and in $MTL_DIR/main.

desitarget.mtl.force_overrides(obscon, survey='main', secondary=False, mtldir=None, pixlist=None)

Force override ledgers to be processed and added to the MTL ledgers.

Parameters:

• obscon (str) – A string matching ONE obscondition in the desitarget bitmask yaml file (i.e. in desitarget.targetmask.obsconditions), e.g. “DARK” Governs how priorities are set when merging targets.

• survey (str, optional, defaults to “main”) – Used to look up the correct ledger, in combination with obscon. Options are 'main' and 'svX’ (where X is 1, 2, 3 etc.) for the main survey and different iterations of SV, respectively.

• secondary (bool, optional, defaults to False) – If True then force overrides for secondary targets instead of primaries for passed survey and obscon.

• mtldir (str, optional, defaults to None) – Full path to the directory that hosts the MTL ledgers and the MTL tile file. If None, then look up the MTL directory from the $MTL_DIR environment variable.

• pixlist (list, optional, defaults to None) – A list of HEALPixels corresponding to the ledgers to be updated. If None is sent, then all possible ledgers are updated at the default MTL nside (which is _get_mtl_nside()).

Returns:

The directory containing the ledgers that were updated.

Return type:

str

desitarget.mtl.get_bricks_file_name()

Convenience function to get name of the dr9-or-dr11 brick file.

Returns:

The name of the brick file.

Return type:

str

desitarget.mtl.get_local_iso_date()

Convenience function to grab the local date in STRICT ISO format.

Returns:

UTC date in STRICT ISO format, appropriate for a TIMESTAMP.

Return type:

str

desitarget.mtl.get_mtl_dir(mtldir=None)

Convenience function to grab the $MTL_DIR environment variable.

Parameters:

mtldir (str, optional, defaults to $MTL_DIR) – If mtldir is passed, it is returned from this function. If it’s not passed, the $MTL_DIR environment variable is returned.

Returns:

If mtldir is passed, it is returned from this function. If it’s not passed, the directory stored in the $MTL_DIR environment variable is returned.

Return type:

str

desitarget.mtl.get_mtl_ledger_format()

Grab the file format for MTL ledger files.

Returns:

The file format for MTL ledgers. Should be “ecsv” or “fits”.

Return type:

str

desitarget.mtl.get_mtl_tile_file_name(secondary=False, override=False, veto=False)

Convenience function to grab the name of the MTL tile file.

Parameters:

• secondary (bool, optional, defaults to False) – If True return the name of the MTL tile file for secondary targets instead of the standard, primary MTL tile file.

• override (bool, optional, defaults to False) – If True return the name of the override tile file instead of the mtl tile file.

• veto (bool, optional, defaults to False) – If True return the name of the dynamic veto file instead of the mtl tile file. This option always takes precedence when passed as True.

Returns:

The name of the MTL tile file.

Return type:

str

Notes

• Only one of override or veto can be passed.

desitarget.mtl.get_utc_date(survey='sv3')

Convenience function to grab the UTC date.

Parameters:

survey (str, optional, defaults to “sv3”) – Used to construct the right ISO format for an iteration of DESI. Options are 'main' 'cmx', 'svX’ (for X of 1, 2, etc.) for the main survey, commissioning and iterations of SV.

Returns:

The UTC date, appropriate for making a TIMESTAMP.

Return type:

str

Notes

• This is spun off into its own function to have a consistent way to record time across the entire desitarget package.

• The survey input defaults to “sv3” for backwards compatibility (we became stricter about the format for the main survey).

desitarget.mtl.get_utc_iso_date()

Convenience function to grab the UTC date in STRICT ISO format.

Returns:

UTC date in STRICT ISO format, appropriate for a TIMESTAMP.

Return type:

str

desitarget.mtl.get_veto_dir(obscon, survey='main', mtldir=None)

Convenience function to grab the name of the ZTILE file.

obsconstr

A string matching ONE observing condition. For example “DARK”, “BRIGHT”, “DARK1B” and “BRIGHT.

surveystr, optional, defaults to “main”

To look up the right veto directory. Examples might be``’main’`` or 'svX’ (where X is 1, 2, 3 etc.) for the main survey and different iterations of SV, respectively.

mtldirstr, optional, defaults to None

Full path to the directory that hosts the MTL ledgers and the MTL tile file. If None, then look up the MTL directory from the $MTL_DIR environment variable.

Returns:

The name of the dynamic veto directory.

Return type:

str

desitarget.mtl.get_zcat_dir(zcatdir=None)

Convenience function to grab the $ZCAT_DIR environment variable.

Parameters:

zcatdir (str, optional, defaults to $ZCAT_DIR) – If zcatdir is passed, it is returned from this function. If it’s not passed, the $ZCAT_DIR environment variable is returned.

Returns:

If zcatdir is passed, it is returned from this function. If it’s not passed, the directory stored in the $ZCAT_DIR environment variable is returned.

Return type:

str

desitarget.mtl.get_ztile_file_name(survey='main')

Convenience function to grab the name of the ZTILE file.

surveystr, optional, defaults to “main”

To look up the correct ZTILE filename. Options are 'main' and 'svX’ (where X is 1, 2, 3 etc.) for the main survey and different iterations of SV, respectively.

Returns:

The name of the ZTILE file.

Return type:

str

desitarget.mtl.inflate_ledger(mtl, hpdirname, columns=None, header=False, strictcols=False, quick=False)

Add a fuller set of target columns to an MTL array.

Parameters:

• mtl (array or ~astropy.table.Table) – A Merged Target List in array or Table form. Must contain the columns “RA”, “DEC” and “TARGETID”

• hpdirname (str) – Full path to a directory containing targets that have been partitioned by HEALPixel (i.e. as made by select_targets with the bundle_files option).

• columns (list or str, optional) – Only return these target columns. If None or not passed then return all of the target columns.

• header (bool, optional, defaults to False) – If True then also return the header of the last file read from the hpdirname directory.

• strictcols (bool, optional, defaults to False) – If True then strictly return only the columns in columns, otherwise, inflate the ledger with the new columns. Ignored if columns is set to None.

• quick (bool, optional, defaults to False) – If True, assume the fidelity of the data model. This is much faster but makes fewer error checks. If quick is True then strictcols is ignored and any columns shared by mtl and the target files in hpdirname are BOTH returned using the astropy Table convention. e.g., if “RA” is in both the target files and mtl, the returned array will have “RA_1” for the added column from the target files and “RA_2” for the original mtl column.

Returns:

The original MTL with the fuller set of columns.

Return type:

array

Notes

• For most uses, you WILL want to pass quick`=``True`.

• Will run more quickly if the targets in mtl are clustered.

• “TARGETID” is ALWAYS returned, even if it isn’t in columns, unless strictcols`==``True`.

• All TARGETIDs in the mtl must be present in the hpdirname, directory, otherwise an exception is thrown.

• If quick`=``False` then any column in mtl that is also in columns will be OVERWRITTEN. So (for quick`=``False`), be careful not to pass columns=None if you only intend to ADD columns to mtl rather than also SUBSTITUTING some columns.

desitarget.mtl.loop_ledger(obscon, survey='main', zcatdir=None, mtldir=None, numobs_from_ledger=True, secondary=False, reprocess=False, ext=False, veto=True)

Execute full MTL loop, including reading files, updating ledgers.

Parameters:

• obscon (str) – A string matching ONE obscondition in the desitarget bitmask yaml file (i.e. in desitarget.targetmask.obsconditions), e.g. “DARK” Governs how priorities are set when merging targets.

• survey (str, optional, defaults to “main”) – Used to look up the correct ledger, in combination with obscon. Options are 'main' and 'svX’ (where X is 1, 2, 3 etc.) for the main survey and different iterations of SV, respectively.

• zcatdir (str, optional, defaults to None) – Full path to the directory that hosts redshift catalogs. If this is None, look up the redshift catalog directory from the $ZCAT_DIR environment variable.

• mtldir (str, optional, defaults to None) – Full path to the directory that hosts the MTL ledgers and the MTL tile file. If None, then look up the MTL directory from the $MTL_DIR environment variable.

• numobs_from_ledger (bool, optional, defaults to True) – If True then inherit the number of observations so far from the ledger rather than expecting it to have a reasonable value in the zcat.

• secondary (bool, optional, defaults to False) – If True then process secondary targets instead of primaries for passed survey and obscon.

• reprocess (bool, optional, defaults to False) – If True find reprocessed tiles (tiles with an ARCHIVEDATE in the tiles-specstatus file later than their TIMESTAMP in the mtl-done-tiles file) instead of tiles that are newly done and process using special reprocessing logic.

• ext (bool, optional, defaults to False) – If True then we’re operating in DESI 1B mode for DARK or BRIGHT tiles. The tiles looked up will be, e.g., DARK1B tiles, but the ledgers (and rules) used for updating will be for DARK. In this mode, the tile file is not updated indicating that a tile has been considered, because, e.g., DARK1B tiles should only be marked as considered once the DARK1B ledgers are done.

• veto (bool, optional, defaults to True) – If True then veto targets based on files in the veto directory. If False then skip the vetoing step.

Returns:

• str – The directory containing the ledger that was updated.

• str – The name of the MTL tile file that was updated.

• str – Name of ZTILE file used to link TILEIDs to observing conditions to determine if tiles were “done” (that they had zdone=True).

• array – Information for the tiles that were processed.

Notes

• Assumes all of the relevant ledgers have already been made by, e.g., make_ledger().

• If survey is ‘main’ the code assumes the file with the zdone status for spectro tiles is mtldir/../ops/tiles-specstatus.ecsv (i.e. it is in the ops directory parallel to the mtl directory). If survey is ‘svX’ the code assumes it is zcatdir/tiles.csv.

desitarget.mtl.make_ledger(hpdirname, outdirname, pixlist=None, obscon='DARK', numproc=1, timestamp=None, append=False, tcnames=None, dr=None)

Make initial MTL ledger files for HEALPixels, in parallel.

Parameters:

• hpdirname (str) – Full path to either a directory containing targets that have been partitioned by HEALPixel (i.e. as made by select_targets with the bundle_files option). Or the name of a single file of targets.

• outdirname (str) – Output directory to which to write the MTL (the file name is constructed on the fly).

• pixlist (list or int, defaults to None) – (Nested) HEALPixels for which to write the MTLs at the default nside (which is _get_mtl_nside()). Defaults to None, which runs all of the pixels at _get_mtl_nside().

• obscon (str, optional, defaults to “DARK”) – A string matching ONE obscondition in the desitarget bitmask yaml file (i.e. in desitarget.targetmask.obsconditions), e.g. “GRAY” Governs how priorities are set based on “obsconditions”. Also governs the sub-directory to which the ledger is written.

• numproc (int, optional, defaults to 1 for serial) – Number of processes to parallelize across.

• timestamp (str, optional) – A timestamp to use in place of that assigned by make_mtl.

• append (bool, optional, defaults to False) – If True then append to any existing ledgers rather than creating new ones. In this mode, if a ledger exists it will be appended to and if it doesn’t exist it will be created.

• tcnames (list, defaults to processing all target classes) – A list of strings, e.g. [‘QSO’,’LRG’]. If passed, produce ledgers for only those target classes. The passed classes must be from the DESI_TARGET column, which must exist in the target files associated with hpdirname.

• dr (int, optional, defaults to None) – If passed, limit targets to a Data Release of the Legacy Surveys. For example, pass 11 to limit targets to official DR11 bricks. Expects outdirname/survey-bricks-dr.fits to exist.

Return type:

Nothing, but writes the full HEALPixel-split ledger to outdirname.

Notes

• For _get_mtl_nside()=32, takes about 25 minutes with numproc=12. numproc>12 can run into memory issues.

• For _get_mtl_nside()=16, takes about 50 minutes with numproc=8. numproc>8 can run into memory issues.

desitarget.mtl.make_ledger_in_hp(targets, outdirname, nside, pixlist, obscon='DARK', indirname=None, verbose=True, scnd=False, timestamp=None, append=False)

Make an initial MTL ledger file for targets in a set of HEALPixels.

Parameters:

• targets (array) – Targets made by, e.g. desitarget.cuts.select_targets().

• outdirname (str) – Output directory to which to write the MTLs (the file names are constructed on the fly).

• nside (int) – (NESTED) HEALPixel nside that corresponds to pixlist.

• pixlist (list or int) – HEALPixels at nside at which to write the MTLs.

• obscon (str, optional, defaults to “DARK”) – A string matching ONE obscondition in the desitarget bitmask yaml file (i.e. in desitarget.targetmask.obsconditions), e.g. “GRAY” Governs how priorities are set when merging targets. Also governs the sub-directory to which the ledger is written.

• indirname (str) – A directory associated with the targets. Written to the headers of the output MTL files.

• verbose (bool, optional, defaults to True) – If True then log target and file information.

• scnd (bool, defaults to False) – If True then this is a ledger of secondary targets.

• timestamp (str, optional) – A timestamp to use in place of that assigned by make_mtl.

• append (bool, optional, defaults to False) – If True then append to any existing ledgers rather than creating new ones. In this mode, if a ledger exists it will be appended to and if it doesn’t exist it will be created.

Returns:

• Nothing, but writes the targets out to outdirname split across

• each HEALPixel in pixlist.

desitarget.mtl.make_mtl(targets, obscon, zcat=None, scnd=None, trim=False, trimcols=False, trimtozcat=False, ext=False)

Add zcat columns to a targets table, update priorities and NUMOBS.

Parameters:

• targets (array or ~astropy.table.Table) – A numpy rec array or astropy Table with at least the columns TARGETID, DESI_TARGET, BGS_TARGET, MWS_TARGET (or the corresponding columns for SV or commissioning) NUMOBS_INIT and PRIORITY_INIT. targets must also contain PRIORITY if zcat is not None (i.e. if this isn’t the first time through MTL and/or if targets is itself an mtl array). PRIORITY is needed to “lock in” the state of Ly-Alpha QSOs. targets may also contain SCND_TARGET (or the corresponding columns for SV) if secondary targets are under consideration.

• obscon (str) – A combination of strings that are in the desitarget bitmask yaml file (specifically in desitarget.targetmask.obsconditions), e.g. “DARK|GRAY”. Governs the behavior of how priorities are set based on “obsconditions” in the desitarget bitmask yaml file.

• zcat (Table, optional) – Redshift catalog table with columns TARGETID, NUMOBS, Z, ZWARN, ZTILEID, and possibly the extra columns in msaddcols at the top of the module.

• scnd (array, ~astropy.table.Table, optional) – TYPICALLY, we have a separate secondary targets (they have their own “ledger”). So passing associated secondaries is DEPRECATED (but still works). scnd is kept for backwards compatibility. A set of secondary targets associated with the targets. As with the target must include at least TARGETID, NUMOBS_INIT, PRIORITY_INIT or the corresponding SV columns. The secondary targets will be padded to have the same columns as the targets, and concatenated with them.

• trim (bool, optional) – If True (default), don’t include targets that don’t need any more observations. If False, include every input target.

• trimcols (bool, optional, defaults to False) – Only pass through columns in targets that are actually needed for fiberassign (see desitarget.mtl.mtldatamodel).

• trimtozcat (bool, optional, defaults to False) – Only return targets that have been UPDATED (i.e. the targets with a match in zcat). Returns all targets if zcat is None. See important Notes about trimtozcat`=``False`!!!

• ext (bool, optional, defaults to False) – If True then we’re operating in DESI 1B mode for DARK or BRIGHT tiles. When calculating priorities and numbers of observations special 1B rules will be used.

Returns:

MTL Table with targets columns plus:

• NUMOBS_MORE - number of additional observations requested

• PRIORITY - target priority (larger number = higher priority)

• TARGET_STATE - the observing state that corresponds to PRIORITY

• OBSCONDITIONS - replaces old GRAYLAYER

• TIMESTAMP - time that (this) make_mtl() function was run

• VERSION - version of desitarget used to run make_mtl()

Return type:

Table

Notes

• Sources in the zcat with ZWARN of BAD_SPECQA|BAD_PETALQA|NODATA are always ignored.

• As sources with BAD_SPECQA|BAD_PETALQA|NODATA are ignored they will have ridiculous z-entries if trimtozcat`=``False` is passed!

• The input zcat MAY BE MODIFIED. If a desideratum is that zcat remains unaltered, make sure to copy zcat before passing it.

desitarget.mtl.make_zcat(zcatdir, tiles, obscon, survey, allow_overlaps=False)

Make a catalog of redshifts used to inform the MTL loop.

Parameters:

• zcatdir (str) – Full path to the “daily” directory that hosts redshift catalogs.

• tiles (array) – Numpy array of tiles to be processed. Must contain at least: * TILEID - unique tile identifier. * ZDATE - final night processed to complete the tile (YYYYMMDD).

• obscon (str) – A string matching ONE obscondition in the desitarget bitmask yaml file (i.e. desitarget.targetmask.obsconditions), e.g. “DARK”. Governs how ZWARN is updated using DELTACHI2 when survey is “sv3” (in make_zcat_rr_backstop()).

• survey (str, optional, defaults to “main”) – Used to update ZWARN using DELTACHI2 for a given survey type. Options are 'main' and 'svX’ (where X is 1, 2, 3 etc.) for the main survey and different iterations of SV, respectively.

• allow_overlaps (:class`bool`, optional, defaults to False) – If True then allow the zcat to contain duplicate TARGETIDs. Duplicate TARGETIDs should not exist for the “standard” MTL loop, because tiles should never overlap, but could be a feature of reprocessing tiles.

Returns:

A zcat in the official format (zcatdatamodel) compiled from the tiles in zcatdir.

Return type:

Table

Notes

• For surveys prior to “main” this is just a wrapper on make_zcat_rr_backstop().

desitarget.mtl.make_zcat_rr_backstop(zcatdir, tiles, obscon, survey)

Make a simple zcat using only redrock outputs.

Parameters:

• zcatdir (str) – Full path to the “daily” directory that hosts redshift catalogs.

• tiles (array) – Numpy array of tiles to be processed. Must contain at least: * TILEID - unique tile identifier. * ZDATE - final night processed to complete the tile (YYYYMMDD).

• obscon (str) – A string matching ONE obscondition in the desitarget bitmask yaml file (i.e. desitarget.targetmask.obsconditions), e.g. “DARK”. Governs how ZWARN is updated using DELTACHI2.

• survey (str, optional, defaults to “main”) – Used to update ZWARN using DELTACHI2 for a given survey type. Options are 'main' and 'svX’ (where X is 1, 2, 3 etc.) for the main survey and different iterations of SV, respectively.

Returns:

A zcat in the official format (zcatdatamodel) compiled from the tiles in zcatdir.

Return type:

Table

Notes

• How the zcat is constructed could certainly change once we have the final schema in place.

desitarget.mtl.match_ledger_to_targets(mtl, targets)

Add a full set of target columns to an MTL array.

Parameters:

• mtl (array or ~astropy.table.Table) – A Merged Target List in array or Table form. Must contain the column “TARGETID”.

• targets (str) – An array of DESI targets, as made by, e.g., select_targets. Must contain the column “TARGETID”.

Returns:

The passed MTL array with all target columns added.

Return type:

array

Notes

• See also inflate_ledger().

• All TARGETIDs in the mtl must be present in targets, otherwise an exception is thrown.

• Speed-ups to inflate_ledger() suggested by Anand Raichoor.

desitarget.mtl.process_overrides(ledgerfn, tabform='ascii.basic')

Recover MTL entries from override ledgers and update those ledgers.

Parameters:

• ledgerfn (str) – Name of the override ledger to process.

• tabform (str, optional, defaults to ‘ascii.basic’) – Format to pass to the astropy Table.read() function. The default (‘ascii.basic’) is standard for reading and writing MTL files. But ‘ascii.ecsv’ is useful for some of the mock/alt-MTL work.

Returns:

MTL entries from override ledger with NUMOVERRIDE column removed, TIMESTAMP updated to now, the second part of TARGET_STATE updated to be OVERRIDE, and the git VERSION updated.

Return type:

Table

Notes

• Rewrites entries to the override ledger with NUMOVERRIDE updated to be NUMOVERRIDE - 1, TIMESTAMP updated to now, the second part of TARGET_STATE updated to OVERRIDE, the git VERSION updated, and the ZTILEID updated to -1.

• Will only update entries for which NUMOVERRIDE > 0.

desitarget.mtl.process_vetoes(obscon, survey='main', mtldir=None, tabform='ascii.basic')

Stop targets in ledgers based on dynamically updated veto files

obsconstr

A string matching ONE observing condition. For example “DARK”, “BRIGHT”, “DARK1B” and “BRIGHT.

surveystr, optional, defaults to “main”

To look up the right veto directory. Examples might be``’main’`` or 'svX’ (where X is 1, 2, 3 etc.) for the main survey and different iterations of SV, respectively.

mtldirstr, optional, defaults to None

Full path to the directory that hosts the MTL ledgers and the MTL tile file. If None, then look up the MTL directory from the $MTL_DIR environment variable.

tabformstr, optional, defaults to ‘ascii.basic’

Format to pass to the astropy Table.read() function. The default (‘ascii.basic’) is standard for reading and writing MTL files. But ‘ascii.ecsv’ is useful for some of the mock/alt-MTL work.

Return type:

Nothing, but the relevant ledgers are updated based on vetoes.

Notes

Nothing is done if veto files for the passed obscon don’t exist.

desitarget.mtl.purge_tiles(tiles, obscon, mtldir=None, secondary=False, verbose=True)

Utterly remove tiles from MTL ledgers and associated mtl-done files.

Parameters:

• tiles (Table) – A Table of tiles (in the standard DESI format) to be removed from the MTL ledgers and associated mtl-done files.

• obscon (str) – A string matching ONE obscondition in the desitarget bitmask yaml file (i.e. in desitarget.targetmask.obsconditions), e.g. “DARK” Used to construct the directory to find the Main Survey ledgers.

• mtldir (str, optional, defaults to None) – Full path to the directory that hosts the MTL ledgers and the MTL tile file. If None, then look up the MTL directory from the $MTL_DIR environment variable.

• secondary (bool, optional, defaults to False) – If True then purge secondary targets instead of primaries for passed obscon.

• verbose (bool, optional, defaults to True) – If True then log extra information.

Returns:

• Table – A Table of all of the entries removed from the ledgers.

• Table – A Table of all of the entries removed from an mtl-done file.

Notes

• Requires the mtl part of the operations SVN trunk to be checked out in the standard location relative to mtldir.

• Only works for Main Survey tiles, as we only look in $MTL_DIR/main.

desitarget.mtl.remove_overrides(mtl)

Remove all targets that share a TARGETID with an OVERRIDE target

Parameters:

mtl (array or ~astropy.table.Table) – An array of targets from a Merged Target List. Must contain at least the column TARGET_STATE. Can contain duplicate TARGETIDs.

Returns:

• array or ~astropy.table.Table – The original mtl but all targets that have a TARGETID for which one entry has the string “OVERRIDE” in TARGET_STATE are removed.

• array or ~astropy.table.Table – The targets that were removed.

desitarget.mtl.reprocess_ledger(hpdirname, zcat, obscon='DARK')

Reprocess HEALPixel-split ledgers for targets with new redshifts.

Parameters:

• hpdirname (str) – Full path to a directory containing an MTL ledger that has been partitioned by HEALPixel (i.e. as made by make_ledger).

• zcat (Table, optional) – Redshift catalog table with columns TARGETID, NUMOBS, Z, ZWARN, ZTILEID, and msaddcols at the top of the code for the Main Survey.

• obscon (str, optional, defaults to “DARK”) – A string matching ONE obscondition in the desitarget bitmask yaml file (i.e. in desitarget.targetmask.obsconditions), e.g. “DARK” Governs how priorities are set using “obsconditions”. Basically a check on whether the files in hpdirname are as expected.

Returns:

A dictionary where the keys are the integer TILEIDs and the values are the TIMESTAMP at which that tile was reprocessed.

Return type:

dict

desitarget.mtl.standard_off_columns(mtl)

Add column entries to an mtl Table when turning off targets.

Parameters:

mtl (Table) – An astropy Table. Must contain the columns TIMESTAMP, TARGET_STATE, VERSION, ZTILEID and PRIORITY.

Returns:

The input table with TIMESTAMP updated to now, the second part of TARGET_STATE updated to be OFF, the git VERSION updated, the ZTILEID set to -1 and the PRIORITY set to 0.

Return type:

Table

desitarget.mtl.standard_override_columns(mtl)

Add some standard column entries to an mtl Table.

Parameters:

mtl (Table) – An astropy Table. Must contain the columns TIMESTAMP, TARGET_STATE, VERSION and ZTILEID.

Returns:

The input table with TIMESTAMP updated to now, the second part of TARGET_STATE updated to be OVERRIDE, the git VERSION updated, and ZTILEID set to -1.

Return type:

Table

desitarget.mtl.survey_data_model(dm, survey='main')

Construct the appropriate data model for a given survey.

Parameters:

• dm (array) – A data model related to MTL. Typically one of zcatdatamodel or mtldatamodel.

• survey (str, optional, defaults to “main”) – Used to construct the right data model for an iteration of DESI. Options are 'main' 'cmx', 'svX’ (for X of 1, 2, etc.) for the main survey, commissioning and iterations of SV.

Returns:

The approriate data model. If survey is ‘main’ this will be the passed dm with any columns from msaddcols added. If survey is sv-like, this will just be the input dm.

Return type:

array

desitarget.mtl.tiles_to_be_processed(zcatdir, mtltilefn, obscon, survey, reprocess=False)

Find tiles that are “done” but aren’t yet in the MTL tile record.

Parameters:

• zcatdir (str) – Full path to the directory that hosts redshift catalogs.

• mtltilefn (str) – Full path to the file of tiles that have been processed by MTL.

• obscon (str) – A string matching ONE obscondition in the desitarget bitmask yaml file (i.e. in desitarget.targetmask.obsconditions), e.g. “DARK” Governs how priorities are set when merging targets.

• survey (str) – Used to look up the correct ledger, in combination with obscon. Options are 'main' and 'svX’ (where X is 1, 2, 3 etc.) for the main survey and different iterations of SV, respectively.

• reprocess (bool, optional, defaults to False) – If True find reprocessed tiles (tiles with an ARCHIVEDATE in the tiles-specstatus file later than their TIMESTAMP in the mtl-done-tiles file) instead of tiles that are newly done.

Returns:

An array of tiles that are yet to be processed and written to the mtl tile file.

Return type:

array

Notes

• If survey is ‘main’ the code assumes the file with zdone for spectro tiles is mtltilefn/../../ops/tiles-specstatus.ecsv (i.e. it is in the ops directory parallel to the mtl directory). If survey is ‘svX’ the code assumes it is zcatdir/tiles.csv.

desitarget.mtl.turn_off_dr11(pixlist=None, mtldir=None, obscon='DARK', verbose=True, numproc=1, updatedonefile=True)

Set targets in DR11 bricks to PRIORITY 0 in all MTLs, in parallel.

Parameters:

• pixlist (list or int, optional, default to None) – HEALPixels at _get_mtl_nside() in which to process MTLs. Default is to run all HEALPixels at _get_mtl_nside().

• mtldir (str, optional, defaults to None) – Full path to the directory that hosts the MTLs. If None, then look up the MTL directory from the $MTL_DIR environment variable. If dr11brickids is not passed then this directory must contain the file of bricks that are in DR11, which should be named the same as the output from get_bricks_file_name().

• obscon (str, optional, defaults to “DARK”) – A string matching ONE obscondition in the desitarget bitmask yaml file (i.e. in desitarget.targetmask.obsconditions). Governs the sub-directory for which the ledgers are processed.

• verbose (bool, optional, defaults to True) – If True then log extra target and file information.

• numproc (int, optional, defaults to 1 for serial) – Number of processes to parallelize across.

• updatedonefile (bool, optional, defaults to True) – If False then do NOT write a timestamp to the MTL dr11 “done” file indicating an update has occurred.

Return type:

Nothing, but updates the targets in all ledgers in the mtldir.

desitarget.mtl.turn_off_dr11_hp(pixlist, bricks=None, dr11brickids=None, mtldir=None, obscon='DARK', verbose=True, updatedonefile=True)

Set targets in DR11 bricks to PRIORITY 0 in MTLs, in HEALPixels.

Parameters:

• pixlist (list or int) – HEALPixels at _get_mtl_nside() in which to process MTLs.

• bricks (class, optional, defaults to None) – Legacy Surveys bricks object. If parallelizing across multiple pixels this can be passed as a speed-up as it takes a little time to initialize. If not passed, the function initializes it.

• dr11brickids (array, optional, defaults to None) – List of BRICKIDs that are in DR11. If this is not passed, then these are read from the dr9-or-dr11 brick file in mtldir.

• mtldir (str, optional, defaults to None) – Full path to the directory that hosts the MTLs. If None, then look up the MTL directory from the $MTL_DIR environment variable. If dr11brickids is not passed then this directory must contain the file of bricks that are in DR11, which should be named the same as the output from get_bricks_file_name().

• obscon (str, optional, defaults to “DARK”) – A string matching ONE obscondition in the desitarget bitmask yaml file (i.e. in desitarget.targetmask.obsconditions). Governs the sub-directory for which the ledgers are processed.

• verbose (bool, optional, defaults to True) – If True then log target and file information.

• updatedonefile (bool, optional, defaults to True) – If False then do NOT write a timestamp to the MTL dr11 “done” file indicating an update has occurred.

Returns:

• Nothing, but updates the targets in the appropriate ledgers in

• the mtldir.

desitarget.mtl.update_ledger(hpdirname, zcat, targets=None, obscon='DARK', numobs_from_ledger=False, tabform='ascii.basic', ext=False)

Update relevant HEALPixel-split ledger files for some targets.

Parameters:

• hpdirname (str) – Full path to a directory containing an MTL ledger that has been partitioned by HEALPixel (i.e. as made by make_ledger).

• zcat (Table, optional) – Redshift catalog table with columns TARGETID, NUMOBS, Z, ZWARN, ZTILEID, and msaddcols at the top of the code for the Main Survey.

• targets (array or ~astropy.table.Table, optional) – A numpy rec array or astropy Table with at least the columns RA, DEC, TARGETID, DESI_TARGET, NUMOBS_INIT, and PRIORITY_INIT. If None, then assume the zcat includes RA and DEC and look up targets in the ledger.

• obscon (str, optional, defaults to “DARK”) – A string matching ONE obscondition in the desitarget bitmask yaml file (i.e. in desitarget.targetmask.obsconditions), e.g. “DARK” Governs how priorities are set using “obsconditions”. Basically a check on whether the files in hpdirname are as expected.

• numobs_from_ledger (bool, optional, defaults to True) – If True then inherit the number of observations so far from the ledger rather than expecting it to have a reasonable value in the zcat.

• tabform (str, optional, defaults to ‘ascii.basic’) – Format to pass to the astropy Table.read() function. The default (‘ascii.basic’) is standard for reading and writing MTL files. But ‘ascii.ecsv’ is useful for some of the mock/alt-MTL work.

• ext (bool, optional, defaults to False) – If True then we’re operating in DESI 1B mode for DARK or BRIGHT tiles. When calculating priorities and numbers of observations special 1B rules will be used.

Return type:

Nothing, but relevant ledger files are updated.

desitarget.mtl.update_lya_1b(obscon='DARK', mtldir=None, timestamp=None, donefile=True)

Effectively add two observations for LyA quasars for DESI-1B.

Parameters:

• obscon (str, optional, defaults to DARK) – A string matching ONE obscondition in the desitarget bitmask yaml file (i.e. in desitarget.targetmask.obsconditions), e.g. “DARK” Used to construct the directory to find the Main Survey ledgers. It’s likely we’ll only ever want to do this for DARK, but worth retaining the option for BRIGHT, too.

• mtldir (str, optional, defaults to None) – Full path to the directory that hosts the MTL ledgers and the MTL tile file. If None, then look up the MTL directory from the $MTL_DIR environment variable.

• timestamp (str, defaults to None) – A date-like string or array of strings in either UTC or strict UTC/ISO format. If None, then the timestamp corresponding to now is used.

• donefile (bool, defaults to True) – If True then update the mtl-done-overrides.ecsv (i.e the OVERRIDE done file) to indicate the change. The special nature of this update is that TILEID, ZDATE and ARCHIVEDATE are all set to -1.

Return type:

Nothing, but relevant ledger files are updated.

Notes

• This will only be run once but is coded as a standalone function so it can be used by the alt-MTLs as well as the data MTLs.

• The algorithm is to look up the the highest-priority state (other than UNOBS) for each quasar target, revert to that state, and add two observations to NUMOBS_MORE and NUMOBS_INIT.

• Every ledger in the relevant MTL+obscon+main directory is updated.

desitarget.mtl.utc_date_to_night(timestamp)

Convert a UTC/ISO date into a DESI night (YYYYMMDD) format.

Parameters:

timestamp (array or str) – A date-like string or array of strings in either UTC or strict UTC/ISO format.

Returns:

An array of nights in the DESI YYYYMMDD format, where each entry corresponds to each entry in timestamp.

Return type:

array

Notes

• This function is sufficiently sloppy that it can handle both STRICT ISO format (as generated by, e.g., desitarget.mtl.get_utc_iso_date()) and general UTC format (as generated by, e.g., desitarget.mtl.get_utc_date()).

desitarget.myRF

This module computes the Random Forest probability and it stores the RF with our own persistency.

class desitarget.myRF.myRF(data, modelDir, numberOfTrees=200, version=2)

Class for I/O operations and probability calculation for Random Forest

desitarget.photo

Implements the photometric transforms between SDSS and DECam using g,r,z documented in DESI-1788v1 https://desi.lbl.gov/DocDB/cgi-bin/private/ShowDocument?docid=1788

desitarget.photo.cfht2decam(g_cfht, r_cfht, i_cfht, z_cfht)

Converts CFHT magnitudes to DECam magnitudes

Parameters:

[griz]_cfht – CFHT magnitudes (float or arrays of floats)

Returns:

g_decam, r_decam, z_decam

Note: CFHT griz are inputs, but only grz (no i) are output

desitarget.photo.decam2cfht(g_decam, r_decam, z_decam)

Not yet implemented

desitarget.photo.decam2sdss(g_decam, r_decam, z_decam)

Not yet implemented

desitarget.photo.sdss2decam(g_sdss, r_sdss, i_sdss, z_sdss)

Converts SDSS magnitudes to DECam magnitudes

Parameters:

[griz]_sdss – SDSS magnitudes (float or arrays of floats)

Returns:

g_decam, r_decam, z_decam

Note: SDSS griz are inputs, but only grz (no i) are output

desitarget.randoms

Monte Carlo Legacy Surveys imaging at the pixel level to model the imaging footprint

desitarget.randoms.add_default_mtl(randoms, seed)

Add default columns that are added by MTL.

Parameters:

• randoms (ndarray) – A random catalog as made by, e.g., select_randoms() with nomtl=True or select_randoms_bricks() with nomtl=False. This function adds the default MTL information.

• seed (int) – A seed for the random generator that sets the SUBPRIORITY.

Returns:

The random catalog after being passed through MTL.

Return type:

array

Notes

• Typically you will need to run finalize_randoms() first, to populate the columns for the target bits.

desitarget.randoms.dr8_quantities_at_positions_in_a_brick(ras, decs, brickname, drdir, aprad=0.75)

Wrap quantities_at_positions_in_a_brick for DR8 and beyond.

Notes

• See quantities_at_positions_in_a_brick() for details. This wrapper looks for TWO coadd directories in drdir (one for DECaLS, one for MzLS/BASS) and, if it finds two, creates randoms for both surveys within the the passed brick. The wrapper also defaults to the behavior for only having one survey.

desitarget.randoms.dr_extension(drdir)

Extension information for files in a Legacy Survey coadd directory

Parameters:

drdir (str) – The root directory for a Data Release from the Legacy Surveys e.g. /global/project/projectdirs/cosmo/data/legacysurvey/dr7.

Returns:

• str – Whether the file extension is ‘gz’ or ‘fz’.

• int – Corresponding FITS extension number to be read (0 or 1).

Notes

• If the directory structure seems wrong or can’t be found then the post-DR4 convention (.fz files) is returned.

desitarget.randoms.finalize_randoms(randoms)

Add the standard “final” columns that are also added in targeting.

Parameters:

randoms (ndarray) – A random catalog as made by, e.g., select_randoms() with nomtl=True or select_randoms_bricks() with nomtl=False. This function adds the default MTL information.

Returns:

The random catalog after the “final” targeting columns (such as “DESI_TARGET”, etc.) have been added.

Return type:

array

Notes

• Typically used in conjunction with add_default_mtl()

desitarget.randoms.get_dust(ras, decs, scaling=1, dustdir=None)

Get SFD E(B-V) values at a set of RA/Dec locations

Parameters:

• ra (numpy.array) – Right Ascension in degrees

• dec (numpy.array) – Declination in degrees

• scaling (float) – Pass 1 for the SFD98 dust maps. A scaling of 0.86 corresponds to the recalibration from Schlafly & Finkbeiner (2011).

• dustdir (str, optional, defaults to $DUST_DIR+’/maps’) – The root directory pointing to SFD dust maps. If not sent the code will try to use $DUST_DIR+’/maps’ before failing.

Returns:

E(B-V) values from the SFD dust maps at the passed locations

Return type:

numpy.array

desitarget.randoms.get_quantities_in_a_brick(ramin, ramax, decmin, decmax, brickname, density=100000, dustdir=None, aprad=0.75, zeros=False, drdir=None, seed=1)

NOBS, DEPTHS etc. (per-band) for random points in a brick of the Legacy Surveys

Parameters:

• ramin (float) – The minimum “edge” of the brick in Right Ascension

• ramax (float) – The maximum “edge” of the brick in Right Ascension

• decmin (float) – The minimum “edge” of the brick in Declination

• decmax (float) – The maximum “edge” of the brick in Declination

• brickname (array) – Brick names that corresponds to the brick edges, e.g., ‘1351p320’

• density (int, optional, defaults to 100,000) – The number of random points to return per sq. deg. As a typical brick is ~0.25 x 0.25 sq. deg. about (0.0625*density) points will be returned

• dustdir (str, optional, defaults to $DUST_DIR+’/maps’) – The root directory pointing to SFD dust maps. If not sent the code will try to use $DUST_DIR+’/maps’ before failing.

• aprad (float, optional, defaults to 0.75) – Radii in arcsec of aperture for which to derive sky/fiber fluxes. Defaults to the DESI fiber radius. If aprad < 1e-8 is passed, the code to produce these values is skipped, as a speed-up, and apflux_ output values are set to zero.

• zeros (bool, optional, defaults to False) – If True don’t look up pixel-level info for the brick, just return zeros. The only quantities populated are those that don’t need pixels (RA, DEC, BRICKID, BRICKNAME, EBV) and the NOBS_ quantities (which are set to zero).

• drdir (str, optional, defaults to None) – The root directory pointing to a DR from the Legacy Surveys e.g. /global/project/projectdirs/cosmo/data/legacysurvey/dr7. Only necessary to pass if zeros is False.

• seed (int, optional, defaults to 1) – See randoms_in_a_brick_from_edges().

Returns:

a numpy structured array with the following columns:

RELEASE:

The Legacy Surveys release number.

OBJID:

A unique (to each brick) source identifier.

BRICKID:

ID that corresponds to the passed brick name.

BRICKNAME:

Passed brick name.

RA, DEC:

Right Ascension, Declination of a random location.

NOBS_G, R, I, Z:

Number of observations in g, r, z-band.

PSFDEPTH_G, R, I, Z:

PSF depth at this location in g, r, z.

GALDEPTH_G, R, I, Z:

Galaxy depth in g, r, z.

PSFDEPTH_W1, W2:

(PSF) depth in W1, W2 (AB mag system).

PSFSIZE_G, R, I, Z:

Weighted average PSF FWHM (arcsec).

APFLUX_G, R, I, Z:

Sky background extracted in aprad. Will be zero if aprad < 1e-8 is passed.

APFLUX_IVAR_G, R, I, Z:

Inverse variance of sky background. Will be zero if aprad < 1e-8 is passed.

MASKBITS:

Mask information. See, e.g. the Legacy Surveys bitmasks.

WISEMASK_W1:

Mask information. See, e.g. the Legacy Surveys bitmasks.

WISEMASK_W2:

Mask information. See, e.g. the Legacy Surveys bitmasks.

EBV:

E(B-V) at this location from the SFD dust maps.

PHOTSYS:

Resolved north/south (‘N’ for an MzLS/BASS location, ‘S’ for a DECaLS location).

Return type:

ndarray

desitarget.randoms.get_targ_dens(targets, Mx, nside=256)

The density of targets in HEALPixels.

Parameters:

• targets (ndarray or str) – A corresponding (same Legacy Surveys Data Release) target catalog as made by, e.g., desitarget.cuts.select_targets(), or the name of such a file.

• Mx (list or ~numpy.array) – The targeting bitmasks associated with the passed targets, assumed to be a desi, bgs and mws mask in that order (for either SV or the main survey).

• nside (int, optional, defaults to nside=256 (~0.0525 sq. deg. or “brick-sized”)) – The resolution (HEALPixel nside number) at which to build the map (NESTED scheme).

Returns:

An array of target densities with one column for every bit returned by desitarget.QA._load_targdens(). The array contains the density of those targets in pixels at the passed nside

Return type:

ndarray

desitarget.randoms.hp_with_nobs_in_a_brick(ramin, ramax, decmin, decmax, brickname, drdir, density=100000, nside=256)

Given a brick’s edges/name, count randoms with NOBS > 1 in HEALPixels touching that brick.

Parameters:

• ramin (float) – The minimum “edge” of the brick in Right Ascension.

• ramax (float) – The maximum “edge” of the brick in Right Ascension

• decmin (float) – The minimum “edge” of the brick in Declination.

• decmax (float) – The maximum “edge” of the brick in Declination.

• brickname (array) – Brick names that corresponds to the brick edges, e.g., ‘1351p320’.

• drdir (str) – The root directory pointing to a Data Release from the Legacy Surveys e.g. /global/project/projectdirs/cosmo/data/legacysurvey/dr7.

• density (int, optional, defaults to 100,000) – The number of random points to return per sq. deg. As a typical brick is ~0.25 x 0.25 sq. deg. about (0.0625*density) points will be returned.

• nside (int, optional, defaults to nside=256 (~0.0525 sq. deg. or “brick-sized”)) – The resolution (HEALPixel NESTED nside number) at which to build the map.

Returns:

a numpy structured array with the following columns:

HPXPIXEL:

Integer numbers of (only) those HEALPixels that overlap the passed brick

HPXCOUNT:

Numbers of random points with one or more observations (NOBS > 0) in the passed Data Release of the Legacy Surveys for each returned HPXPIXEL.

Return type:

ndarray

Notes

• The HEALPixel numbering uses the NESTED scheme.

• In the event that there are no pixels with one or more observations in the passed brick, and empty structured array will be returned.

desitarget.randoms.pixmap(randoms, targets, rand_density, nside=256, gaialoc=None)

HEALPix map of useful quantities for a Legacy Surveys Data Release

Parameters:

• randoms (ndarray or str) – Catalog or file of randoms as made by select_randoms() or quantities_at_positions_in_a_brick(). Must contain the columns ‘RA’, ‘DEC’, ‘EBV’, ‘PSFDEPTH_W1/W2/G/R/Z’, ‘NOBS_G/R/Z’ ‘GALDEPTH_G/R/Z’, ‘PSFSIZE_G/R/Z’, ‘MASKBITS’.

• targets (ndarray or str) – Corresponding (i.e. same Data Release) catalog or file of targets as made by, e.g., desitarget.cuts.select_targets(), or the the name of a directory containing HEALPix-split targets that can be read by desitarget.io.read_targets_in_box().

• rand_density (int) – Number of random points per sq. deg. at which the random catalog was generated (see also select_randoms()).

• nside (int, optional, defaults to nside=256) – Resolution (HEALPix nside) at which to build the (NESTED) map. The default corresponds to ~0.0525 sq. deg. (or “brick-sized”)

• gaialoc (str, optional, defaults to None) – Name of a FITS file that already contains a column “STARDENS”, which is simply read in. If None, the stellar density is constructed from files in $GAIA_DIR.

Returns:

• ndarray –

  An array of useful information that includes

  • HPXPIXEL: HEALPixel integers at the passed nside.

  • FRACAREA: Fraction of pixel with at least one observation

    in any band. Made with pixweight().

  • STARDENS: The stellar density in a pixel from Gaia. Made

    with stellar_density().

  • EBV: E(B-V) in pixel from the SFD dust map, from the

    median of EBV values in the passed randoms.

  • PSFDEPTH_G, R, Z: PSF depth in the pixel, from the median

    of PSFDEPTH values in randoms.

  • GALDEPTH_G, R, Z: Galaxy depth in the pixel, from the

    median of GALDEPTH values in randoms.

  • PSFDEPTH_W1, W2: (AB PSF) depth in the pixel, from the

    median of values in the passed randoms.

  • PSFSIZE_G, R, Z: Weighted average PSF FWHM, in arcsec, in

    the pixel, from the median of PSFSIZE values in the passed random catalog.

  • FRACAREA_X: Fraction of pixel with at least one observation

    in any band with MASKBITS==X (bitwise OR, so, e.g. if X=7 then fraction for 2^0 | 2^1 | 2^2).

  • One column for every bit that is returned by desitarget.QA._load_targdens(). Each column contains the target density in the pixel.

• str – Survey to which targets corresponds, e.g., ‘main’, ‘svX’, etc.

Notes

• If gaialoc is None then $GAIA_DIR must be set.

desitarget.randoms.pixweight(randoms, density, nobsgrz=[0, 0, 0], nside=256, outarea=True, maskbits=None)

Fraction of area covered in HEALPixels by a random catalog.

Parameters:

• randoms (ndarray or str) – A random catalog as made by, e.g., select_randoms() or quantities_at_positions_in_a_brick(), or a file that contains such a catalog. Must contain the columns RA, DEC, NOBS_G, NOBS_R, NOBS_Z, MASKBITS.

• density (int) – The number of random points per sq. deg. At which the random catalog was generated (see also select_randoms()).

• nobsgrz (list, optional, defaults to [0,0,0]) – The number of observations in each of g AND r AND z that must be EXCEEDED to include a random point in the count. The default is to include areas that have at least one observation in each band ([0,0,0]). nobsgrz = [0,-1,-1] would count areas with at least one (more than zero) observations in g-band but any number of observations (more than -1) in r-band and z-band.

• nside (int, optional, defaults to nside=256) – The resolution (HEALPixel NESTED nside number) at which to build the map (default nside=256 is ~0.0525 sq. deg. or “brick-sized”)

• outarea (boolean, optional, defaults to True) – Print the total area of the survey for passed values to screen.

• maskbits (int, optional, defaults to None) – If not None then restrict to only locations with these values of maskbits NOT set (bit inclusive, so for, e.g., 7, restrict to random points with none of 2**0, 2**1 or 2**2 set).

Returns:

The weight for EACH pixel in the sky at the passed nside.

Return type:

ndarray

Notes

• WEIGHT=1 means >=1 pointings across the entire pixel.

• WEIGHT=0 means zero observations within it (e.g., perhaps the pixel is completely outside of the LS DR footprint).

• 0 < WEIGHT < 1 for pixels that partially cover the LS DR area with one or more observations.

• The index of the returned array is the HEALPixel integer.

desitarget.randoms.pre_or_post_dr8(drdir)

Whether the imaging surveys directory structure is before or after DR8

Parameters:

drdir (str) – The root directory pointing to a Data Release from the Legacy Surveys e.g. /global/project/projectdirs/cosmo/data/legacysurvey/dr7.

Returns:

For DR8, this just returns the original directory as a list. For DR8 this returns a list of two directories, one corresponding to DECaLS and one corresponding to BASS/MzLS.

Return type:

list

Notes

• If the directory structure seems wrong or missing then the DR8 (and after) convention of a north/south split is assumed.

desitarget.randoms.quantities_at_positions_in_a_brick(ras, decs, brickname, drdir, aprad=0.75, justlist=False)

Observational quantities (per-band) at positions in a Legacy Surveys brick.

Parameters:

• ras (array) – Right Ascensions of interest (degrees).

• decs (array) – Declinations of interest (degrees).

• brickname (str) – Name of brick which contains RA/Dec positions, e.g., ‘1351p320’.

• drdir (str) – The root directory pointing to a Data Release from the Legacy Surveys e.g. /global/project/projectdirs/cosmo/data/legacysurvey/dr7.

• aprad (float, optional, defaults to 0.75) – Radii in arcsec of aperture for which to derive sky/fiber fluxes. Defaults to the DESI fiber radius. If aprad < 1e-8 is passed, the code to produce these values is skipped, as a speed-up, and apflux_ output values are set to zero.

• justlist (bool, optional, defaults to False) – If True, return a MAXIMAL list of all POSSIBLE files needed to run for brickname and drdir. Overrides other inputs, but ra/dec still have to be passed as something (e.g., [1], [1]).

Returns:

The number of observations (nobs_x), PSF depth (psfdepth_x) galaxy depth (galdepth_x), PSF size (psfsize_x), sky background (apflux_x) and inverse variance (apflux_ivar_x) at each passed position in each band x=g,r,z. Plus, the psfdepth_w1 and _w2 depths and the maskbits, wisemask_w1 and _w2 information at each passed position for the brick. Also adds a unique objid for each random, a release if a release number can be determined from the input drdir, and the photometric system photsys (“N” or “S” for north or south).

Return type:

dictionary

Notes

• First version copied shamelessly from Anand Raichoor.

desitarget.randoms.randoms_in_a_brick_from_edges(ramin, ramax, decmin, decmax, density=100000, poisson=True, wrap=True, seed=1)

For brick edges, return random (RA/Dec) positions in the brick.

Parameters:

• ramin (float) – The minimum “edge” of the brick in Right Ascension (degrees).

• ramax (float) – The maximum “edge” of the brick in Right Ascension (degrees).

• decmin (float) – The minimum “edge” of the brick in Declination (degrees).

• decmax (float) – The maximum “edge” of the brick in Declination (degrees).

• density (int, optional, defaults to 100,000) – The number of random points to return per sq. deg.

• poisson (boolean, optional, defaults to True) – Modify the number of random points so that instead of simply being brick area x density, the number is drawn from a Poisson distribution with an expectation of brick area x density.

• wrap (boolean, optional, defaults to True) – If True, bricks with ramax-ramin > 350o are assumed to wrap, which is corrected by subtracting 360o from ramax, as is reasonable for small bricks. False turns of this correction.

• seed (int, optional, defaults to 1) –

  Random seed to use when shuffling across brick boundaries. The actual np.random.seed defaults to:

  seed*int(1e7)+int(4*ramin)*1000+int(4*(decmin+90))
  

Returns:

• array – Right Ascensions of random points in brick (degrees).

• array – Declinations of random points in brick (degrees).

desitarget.randoms.randoms_in_a_brick_from_name(brickname, drdir, density=100000)

For a given brick name, return random (RA/Dec) positions in the brick.

Parameters:

• brickname (str) – Name of brick in which to generate random points.

• drdir (str) – The root directory pointing to a Data Release from the Legacy Surveys e.g. /global/project/projectdirs/cosmo/data/legacysurvey/dr7.

• density (int, optional, defaults to 100,000) – The number of random points to return per sq. deg. As a typical brick is ~0.25 x 0.25 sq. deg. about (0.0625*density) points will be returned.

Returns:

• array – Right Ascensions of random points in brick.

• array – Declinations of random points in brick.

Notes

• First version copied shamelessly from Anand Raichoor.

desitarget.randoms.rewrite_randoms_in_hp(fn, outdn, nside, verbose=True, ntest=None)

Rewrite randoms in HEALPixels, in files that can use io functions.

Parameters:

• fn (str) – The filename of a monolithic random catalog to be rewritten split across HEALPixels. For full functionality, include the entire directory string to be searched for the data release number.

• outdn (str) – Output directory to which to write the files. The sub-directory structure and filenames are built on-the-fly from the header of fn (which must correspond to a typical random catalog).

• nside (int) – The NESTED HEALPixel resolution at which to write files.

• verbose (bool, optional, defaults to True) – If True then log extra information.

• ntest (int, optional, default to None) – If passed (and not None) then read the first ntest randoms instead of the entire catalog. Useful for testing.

Return type:

Nothing, but rewrites the randoms in fn split across HEALPixels.

Notes

• Really just a simple wrapper on io.write_randoms_in_hp() that also reads the input file.

desitarget.randoms.select_randoms(drdir, density=100000, numproc=32, nside=None, pixlist=None, bundlebricks=None, nchunks=10, brickspersec=2.5, extra=None, nomtl=True, dustdir=None, aprad=0.75, seed=1)

NOBS, DEPTHs (per-band), MASKs for random points in a Legacy Surveys DR.

Parameters:

• drdir (str) – Root directory for a Data Release from the Legacy Surveys e.g. /global/project/projectdirs/cosmo/data/legacysurvey/dr7.

• density (int, optional, defaults to 100,000) – Number of random points to return per sq. deg. As a brick is ~0.25 x 0.25 sq. deg. ~0.0625*density points will be returned.

• numproc (int, optional, defaults to 32) – The number of processes over which to parallelize.

• nside (int, optional, defaults to None) – (NESTED) HEALPixel nside to be used with the pixlist and bundlebricks input.

• pixlist (list or int, optional, defaults to None) – Bricks will only be processed if the brick CENTER is within the HEALpixels in this list, at the input nside. Uses the HEALPix NESTED scheme. Useful for parallelizing. If pixlist is None then all bricks in the input survey will be processed.

• bundlebricks (int, defaults to None) – If not None, then instead of selecting randoms, print a slurm script to balance the bricks at bundlebricks bricks per node.

• nchunks (int, optional, defaults to 10) – Number of smaller catalogs to split the random catalog into inside the bundlebricks slurm script.

• brickspersec (float, optional, defaults to 2.5) – The rough number of bricks processed per second (parallelized across a chosen number of nodes). Used with bundlebricks to estimate time to completion when parallelizing across pixels.

• extra (str, optional) – Extra command line flags to be passed to the executable lines in the output slurm script. Used in conjunction with bundlefiles.

• nomtl (bool, optional, defaults to True) – If True then do NOT add MTL quantities to the output array.

• dustdir (str, optional, defaults to $DUST_DIR+’maps’) – The root directory pointing to SFD dust maps. If None the code will try to use $DUST_DIR+’maps’) before failing.

• aprad (float, optional, defaults to 0.75) – Radii in arcsec of aperture for which to derive sky/fiber fluxes. Defaults to the DESI fiber radius. If aprad < 1e-8 is passed, the code to produce these values is skipped, as a speed-up, and apflux_ output values are set to zero.

• seed (int, optional, defaults to 1) – Random seed to use when shuffling across brick boundaries. The actual np.random.seed defaults to 615+`seed`. See also use in randoms_in_a_brick_from_edges().

Returns:

• ndarray – a numpy structured array with the same columns as returned by get_quantities_in_a_brick() that includes all of the randoms resolved by the north/south divide.

• ndarray – as above but just for randoms in northern bricks.

• ndarray – as above but just for randoms in southern bricks.

desitarget.randoms.select_randoms_bricks(brickdict, bricknames, numproc=32, drdir=None, zeros=False, nomtl=True, cnts=True, density=None, dustdir=None, aprad=None, seed=1)

Parallel-process a random catalog for a set of brick names.

Parameters:

• brickdict (dict) – Look-up dictionary for a set of bricks, as made by, e.g. get_brick_info().

• bricknames (array) – The names of the bricks in brickdict to process.

• drdir (str, optional, defaults to None) – See get_quantities_in_a_brick().

• zeros (bool, optional, defaults to False) – See get_quantities_in_a_brick().

• nomtl (bool, optional, defaults to True) – If True then do NOT add MTL quantities to the output array.

• cnts (bool, optional, defaults to True) – See get_brick_info().

• seed (int, optional, defaults to 1) – See randoms_in_a_brick_from_edges().

Returns:

a numpy structured array with the same columns as returned by get_quantities_in_a_brick(). If zeros and nomtl are both False additional columns are returned, as added by finalize().

Return type:

ndarray

Notes

• See select_randoms() for definitions of numproc, density, dustdir, aprad.

desitarget.randoms.stellar_density(nside=256)

Make a HEALPixel map of stellar density based on Gaia.

Parameters:

nside (int, optional, defaults to nside=256 (~0.0525 sq. deg. or “brick-sized”)) – The resolution (HEALPixel NESTED nside number) at which to build the map.

Notes

• The environment variable $GAIA_DIR must be set.

desitarget.randoms.supplement_randoms(donebns, density=10000, numproc=32, dustdir=None, seed=1)

Random catalogs of “zeros” for missing bricks.

Parameters:

• donebns (ndarray) – Names of bricks that have been “completed”. Bricks NOT in donebns will be returned without any pixel-level quantities. Need not be a unique set (bricks can be repeated in donebns).

• density (int, optional, defaults to 10,000) – Number of random points per sq. deg. A typical brick is ~0.25 x 0.25 sq. deg. so ~(0.0625*density) points will be returned.

• seed (int, optional, defaults to 1) – See randoms_in_a_brick_from_edges(). A seed of 615 + seed is also used to shuffle randoms across brick boundaries.

Returns:

a numpy structured array with the same columns returned by get_quantities_in_a_brick() when that function is passed zeros=True.

Return type:

ndarray

Notes

• See select_randoms() for definitions of numproc, dustdir.

desitarget.secondary

Modules dealing with target selection for secondary targets.

Note that the environment variable SCND_DIR should be set, and that directory should contain files of two flavors:

1. In $SCND_DIR/indata: .fits or .txt files defining the secondary targets with columns corresponding to secondary.indatamodel.

   For .txt files the first N columns must correspond to the N columns in secondary.indatamodel, and other columns can be anything. The # may be used as a comment card.

   For .fits files, a subset of the columns must correspond to the columns in secondary.indatamodel, other columns can be anything.

2. In $SCND_DIR/docs: .ipynb (notebook) or .txt files containing a description of how each input data file was constructed.

Only one secondary target file of each type should be in the indata and docs directories. So, if, e.g. $SCND_DIR/indata/blat.fits exists then $SCND_DIR/indata/blat.txt should not.

Example files can be found in the NERSC directory:

/global/cfs/cdirs/desi/target/secondary

Note that the OVERRIDE column in the data model means “do not just accept an existing target, override it and make a new TARGETID.” It should be True (override) or False (do not override) for each target. In .txt files it should be 1 or 0 instead of True/False, and will be loaded from the text file as the corresponding Boolean.

desitarget.secondary._check_files(scxdir, scnd_mask, bits2files=True)

Retrieve input files from the scx directory with error checking.

Parameters:

• scxdir (str) – Directory produced by _check_files().

• scnd_mask (desiutil.bitmask.BitMask) – A mask corresponding to a set of secondary targets, e.g, could be from desitarget.targetmask import scnd_mask for the main survey mask.

• bits2files (bool, optional, defaults to True) – If True check that all of the files in scxdir have a corresponding bit scnd_mask AND all of the bits need to have a corresponding file. If False, only check that all of the files have a corresponding bit.

Return type:

None

Notes

• Checks that each file name has one corresponding bit in the secondary_mask.

• Checks for only valid file extensions in the input directories.

• Checks that there are no duplicate files in the scxdir/indata or in the scxdir/docs directory.

• Checks that every file in the scxdir/indata directory has a corresponding informational file in scxdir/docs.

desitarget.secondary._get_scxdir(scxdir=None, survey='')

Retrieve the base secondary directory with error checking.

Parameters:

• scxdir (str, optional, defaults to SCND_DIR) – Directory containing secondary target files to which to match. If not specified, the directory is taken to be the value of the SCND_DIR environment variable.

• survey (str, optional, defaults to “” for the Main Survey.) – Flavor of survey that we’re processing, e.g., “sv1”. Don’t pass anything for “main” (the Main Survey).

Returns:

The base secondary directory, after checking it’s format.

Return type:

str

desitarget.secondary.add_primary_info(scxtargs, priminfodir)

Add TARGETIDs to secondaries from directory of primary matches.

Parameters:

• scxtargs (ndarray) – An array of secondary targets, must contain the columns SCND_TARGET, SCND_ORDER and TARGETID.

• priminfodir (list or str) – Location of the directory that has previously matched primary and secondary targets to recover the unique primary TARGETIDs.

Returns:

The array of secondary targets, with the TARGETID column populated for matches to secondary targets

Return type:

ndarray

Notes

• The input scxtargs is modified, so be careful to make a copy if you want that variable to remain unchanged!

desitarget.secondary.check_file_format(filename, docfilename=None, new_program=True)

Check a (circa 2024) input secondary file is correctly formatted.

Parameters:

• filename (str) – The full path to the file to check.

• docfilename (str, optional) – If passed, then also check the format of the documentation file. Again, this should be the full path to the documentation file.

• new_program (bool, optional, defaults to True) – Pass False if your targets correspond to an existing program. Passing False will skip the check that you aren’t duplicating an existing target bit-name.

Returns:

True if the file is correctly formatted.

Return type:

bool

Notes

• This specifically checks the 2024 file format from the second DESI call for secondary targets

desitarget.secondary.duplicates(seq)

Locations of duplicates in an array or list.

Parameters:

seq (list or ~numpy.ndarray or str) – A sequence, e.g., [1, 2, 3, 2] or “adfgtarga”

Returns:

A generator of the duplicated values in the sequence and an array of the indexes for each duplicate, see Examples.

Return type:

generator

Notes

• h/t https://stackoverflow.com/questions/5419204/index-of-duplicates-items-in-a-python-list

Examples

>>> for i in duplicates("adfgtarga"):
...     print(i)
('a', array([0, 5, 8]))
('g', array([3, 7]))

desitarget.secondary.finalize_secondary(scxtargs, scnd_mask, survey='main', sep=1.0, darkbright=False)

Assign secondary targets a realistic TARGETID, finalize columns.

Parameters:

• scxtargs (ndarray) – An array of secondary targets, must contain the columns RA, DEC and TARGETID. TARGETID should be -1 for objects that lack a TARGETID.

• scnd_mask (desiutil.bitmask.BitMask) – A mask corresponding to a set of secondary targets, e.g, could be from desitarget.targetmask import scnd_mask for the main survey mask.

• survey (str, optional, defaults to “main”) – string indicating whether we are working in the context of the Main Survey (main) or SV (e.g. sv1, sv2 etc.). Used to set the RELEASE number in the TARGETID (see Notes).

• sep (float, defaults to 1 arcsecond) – The separation at which to match secondary targets to themselves in ARCSECONDS.

• darkbright (bool, optional, defaults to False) – If sent, then split NUMOBS_INIT and PRIORITY_INIT into NUMOBS_INIT_DARK, NUMOBS_INIT_BRIGHT, PRIORITY_INIT_DARK and PRIORITY_INIT_BRIGHT and calculate values appropriate to “BRIGHT” and “DARK|GRAY” observing conditions.

Returns:

The array of secondary targets, with the TARGETID bit updated to be unique and reasonable and the SCND_TARGET column renamed based on the flavor of scnd_mask.

Return type:

ndarray

Notes

• Secondaries without OVERRIDE are also matched to themselves Such matches are given the same TARGETID (that of the primary if they match a primary) and the bitwise or of SCND_TARGET and OBSCONDITIONS bits across matches. The highest PRIORITY_INIT is retained, and others are set to -1. Only secondaries with priorities that are not -1 are written to the main file. If multiple matching secondary targets have the same (highest) priority, the first one encountered retains its PRIORITY_INIT

• The secondary TARGETID is designed to be reproducible. It combines BRICKID based on location, OBJID based on the order of the targets in the secondary file (SCND_ORDER) and RELEASE from the secondary bit number (SCND_TARGET) and the input survey. RELEASE is set to ((X-1)*100)+np.log2(scnd_bit) with X from the survey string survey=svX and scnd_bit from SCND_TARGET. For the main survey (survey=”main”) X-1 is 5. For a second iteration of the main survey (survey=”main2”) X-1=6.

• The input scxtargs is modified, so be careful to make a copy if you want that variable to remain unchanged!

desitarget.secondary.match_secondary(primtargs, scxdir, scndout, sep=1.0, pix=None, nside=None, swfiles=None)

Match secondary targets to primary targets and update bits.

Parameters:

• primtargs (ndarray) – An array of primary targets.

• scndout (:class`~numpy.ndarray`) – Name of a sub-directory to which to write the information in desitarget.secondary.outdatamodel with TARGETID and (the highest) PRIORITY_INIT updated with matching primary info.

• scxdir (str, optional, defaults to None) – Name of the directory that hosts secondary targets.

• sep (float, defaults to 1 arcsecond) – The separation at which to match in ARCSECONDS.

• pix (list, optional, defaults to None) – Limit secondary targets to (NESTED) HEALpixels that touch pix at the supplied nside, as a speed-up.

• nside (int, optional, defaults to None) – The (NESTED) HEALPixel nside to be used with pixlist.

• swfiles (list, optional, defaults to None) – A list of files (typically sweep files). If passed and not None then once all of the primary TARGETS have been matched and the relevant bit information updated, use these files to find additional sources from which to derive a primary TARGETID.

Returns:

The array of primary targets, with the SCND_TARGET bit populated for matches to secondary targets

Return type:

ndarray

desitarget.secondary.match_to_main_survey(ras, decs, sep=1.0)

Standalone code to match RA/Dec positions to Main Survey targets.

Parameters:

• ras (array or list) – Right Ascensions of interest (degrees).

• decs (array or list) – Declinations of interest (degrees).

• sep (float, defaults to 1 arcsecond) – Separation (arcsec) to match ras/decs to Main Survey targets.

Returns:

An array that includes 6 columns:

RA: The input ras DEC: The input decs BRIGHT: True for locations matching a bright-time target. DARK: True for locations matching a dark-time target. BRIGHTSEC: True for matching a bright-time secondary. DARKSEC: True for matching a dark-time secondary.

Return type:

array

Notes

• Must have set up the correct environment by running, e.g., source /global/common/software/desi/desi_environment.sh

• Prints summary statistics of the number of matches to screen.

desitarget.secondary.read_files(scxdir, scnd_mask, subset=False)

Read in all secondary files and concatenate them into one array.

Parameters:

• scxdir (str) – Directory produced by _check_files().

• scnd_mask (desiutil.bitmask.BitMask, optional) – A mask corresponding to a set of secondary targets, e.g, could be from desitarget.targetmask import scnd_mask for the main survey mask.

• subset (bool, optional, defaults to False) – If True then scxdir only contains a subset of the bits in scnd_mask, and that’s OK. Otherwise, strictly expect scxdir to contain one file for each (non-TOO) bit in scnd_mask.

Returns:

All secondary targets concatenated as one array with columns that correspond to desitarget.secondary.outdatamodel.

Return type:

ndarray

desitarget.secondary.select_secondary(priminfodir, sep=1.0, scxdir=None, darkbright=False, nomerge=False)

Process secondary targets and update relevant bits.

Parameters:

• priminfodir (list or str) – Location of the directory that has previously matched primary and secondary targets to recover the unique primary TARGETIDs. The first file in this directory should have a header keyword SURVEY indicating whether we are working in the context of the Main Survey (main) or SV (e.g. sv1, sv2 etc.).

• sep (float, defaults to 1 arcsecond) – The separation at which to match in ARCSECONDS.

• scxdir (str, optional, defaults to SCND_DIR) – The name of the directory that hosts secondary targets.

• darkbright (bool, optional, defaults to False) – If sent, then split NUMOBS_INIT and PRIORITY_INIT into NUMOBS_INIT_DARK, NUMOBS_INIT_BRIGHT, PRIORITY_INIT_DARK and PRIORITY_INIT_BRIGHT and calculate values appropriate to “BRIGHT” and “DARK|GRAY” observing conditions.

• nomerge (bool, optional, defaults to False) – Pass this to NEVER merge primaries and secondaries. All of the secondaries will be updated to have OVERRIDE=True. In this mode, scxdir is ASSUMED to terminate in a directory /mainX, where X is the iteration of secondary-target-updates after going on-sky with the main survey (e.g. /main2 for the first update of secondary targets). In this mode, all of the files in (e.g.) /main2 must have a corresponding bit in the main scnd_mask, but not all bits need to have a corresponding file. In this mode, priminfodir is ignored, so could be passed as anything (e.g. as None).

Returns:

All secondary targets from scxdir with columns from outdatamodel at the top of this module added. All of these columns are populated, except SUBPRIORITY.

Return type:

ndarray

desitarget.secondary.too_bright(objs, matchrad=3.0)

Check if secondary targets are too bright for DESI to observe.

Parameters:

• data (ndarray) –

  Structured array of secondary targets. Must contain the columns:

  RA, DEC:

  Right Ascension, Declination in degrees.

  PMRA, PMDEC:

  Right Ascension, Declination proper motions (Gaia DR3 units).

  REF_EPOCH:

  Reference epoch for coordinates (e.g. 2014.5).

  FLUX_G, FLUX_R, FLUX_Z

  Legacy Surveys fluxes, or similar. Can be set to zero or a very low number for missing values.

• matchrad (float, optional, defaults to 3 arcsec) – The matching radius around very bright stars in arcseconds.

Returns:

A Boolean array where objects that are Too Bright are True and others are False.

Return type:

array

Notes

• The environment variable $GAIA_DIR must be set.

desitarget.skybricks

Dynamic lookup of whether a given RA,Dec location is a good place to put a sky fiber.

class desitarget.skybricks.Skybricks(skybricks_dir=None)

This class handles dynamic lookup of whether a given (RA,Dec) should make a good location for a sky fiber.

lookup_tile(tilera, tiledec, tileradius, ras, decs)

Looks up a set of RA,Dec positions that are all within a given tile (disk on the sky).

Parameters:

• tilera (float) – tile center RA (deg)

• tiledec (float) – tile center Dec (deg)

• tileradius (float) – tile radius (deg)

• ras (ndarray) – array of RA locations to look up

• decs (ndarray) – array of Dec locations to look up

Returns:

Boolean array, same length as ras/decs inputs, of good_sky values. (True = good place to put a sky fiber)

Return type:

array

desitarget.skybricks._radec2kd(ra, dec)

Creates a scipy KDTree from the given ra, dec arrays (in deg).

desitarget.skybricks._radec2xyz(ra, dec)

Converts arrays from ra, dec (in deg) to XYZ unit-sphere coordinates.

desitarget.skyfibers

Module to assign sky fibers at the pixel-level for target selection

desitarget.skyfibers.density_of_sky_fibers(margin=1.5)

Use positioner patrol size to determine sky fiber density for DESI.

Parameters:

margin (float, optional, defaults to 1.5) – Factor of extra sky positions to generate. So, for margin=10, 10x as many sky positions as the default requirements will be generated.

Returns:

The density of sky fibers to generate in per sq. deg.

Return type:

float

desitarget.skyfibers.get_brick_info(drdirs, counts=False, allbricks=False)

Retrieve brick names and coordinates from Legacy Surveys directories.

Parameters:

• drdirs (list or str) – A list of strings, each of which corresponds to a directory pointing to a Data Release from the Legacy Surveys. Can be of length one. e.g. [‘/global/project/projectdirs/cosmo/data/legacysurvey/dr7’]. or ‘/global/project/projectdirs/cosmo/data/legacysurvey/dr7’ Can be None if allbricks is passed.

• counts (bool, optional, defaults to False) – If True also return a count of the number of times each brick appears ([RAcen, DECcen, RAmin, RAmax, DECmin, DECmax, CNT]).

• allbricks (bool, optional, defaults to False) – If True ignore drdirs and simply return a dictionary of ALL of the bricks.

Returns:

UNIQUE bricks covered by the Data Release(s). Keys are brick names and values are a list of the brick center and the brick corners ([RAcen, DECcen, RAmin, RAmax, DECmin, DECmax]).

Return type:

dict

Notes

• Tries a few different ways in case the survey bricks files have not yet been created.

desitarget.skyfibers.get_supp_skies(ras, decs, radius=2.0, dr='dr2')

Random locations, avoid Gaia, format, return supplemental skies.

Parameters:

• ras (ndarray) – Right Ascensions of sky locations (degrees).

• decs (ndarray) – Declinations of sky locations (degrees).

• radius (float, optional, defaults to 2) – Radius at which to avoid (all) Gaia sources (arcseconds).

• dr (str, optional, defaults to “dr2”) – Name of a Gaia data release from which to draw sources. Passed to find_gaia_files().

Returns:

A structured array of supplemental sky positions in the DESI sky target format that avoid Gaia sources by radius.

Return type:

ndarray

Notes

• Written to be used when ras and decs are within a single Gaia-file HEALPixel, but should work for all cases.

desitarget.skyfibers.make_skies_for_a_brick(survey, brickname, nskiespersqdeg=None, bands=['g', 'r', 'z'], apertures_arcsec=[0.75], write=False)

Generate skies for one brick in the typical format for DESI sky targets.

Parameters:

• survey (object) – LegacySurveyData object for a given Data Release of the Legacy Surveys; see LegacySurveyData() for details.

• brickname (str) – Name of the brick in which to generate sky locations.

• nskiespersqdeg (float, optional) – The minimum DENSITY of sky fibers to generate. Defaults to reading from io() with a margin of 4x.

• bands (list, optional, defaults to [‘g’, ‘r’, ‘z’]) – List of bands to be used to define good sky locations.

• apertures_arcsec (list, optional, defaults to [0.75]) – Radii in arcsec of apertures for which to derive flux at a sky location.

• write (boolean, defaults to False) – If True, write the skyfibers object (which is in the format of the output from sky_fibers_for_brick()) to file. The file name is derived from the input survey object and is in the form: %(survey.survey_dir)/metrics/%(brick).3s/skies-%(brick)s.fits.gz which is returned by survey.find_file(‘skies’).

Returns:

a structured array of sky positions in the DESI sky target format for a brick.

Return type:

ndarray

Notes

• The code generates unique OBJIDs based on an integer counter for the numbers of objects (objs) passed. So, it will fail if the length of objs is longer than the number of bits reserved for OBJID in desitarget.targetmask.

• The generated sky fiber locations will cover the pixel-based brick grid, which extends beyond the “true” geometric brick boundaries.

desitarget.skyfibers.model_density_of_sky_fibers(margin=1.5)

Use desihub products to find required density of sky fibers for DESI.

Parameters:

margin (float, optional, defaults to 1.5) – Factor of extra sky positions to generate. So, for margin=10, 10x as many sky positions as the default requirements will be generated.

Returns:

The density of sky fibers to generate in per sq. deg.

Return type:

float

desitarget.skyfibers.plot_good_bad_skies(survey, brickname, skies, outplotdir='.', bands=['g', 'r', 'z'])

Plot good/bad sky locations against the background of a Legacy Surveys image

Parameters:

• survey (object) – LegacySurveyData object for a given Data Release of the Legacy Surveys; see LegacySurveyData() for details.

• brickname (str) – Name of the brick from this DR of the Legacy Surveys to plot as an image.

• skies (ndarray) – Array of sky locations and aperture fluxes, as, e.g., returned by make_skies_for_a_brick() or select_skies()

• outplotdir (str, optional, defaults to ‘.’) – Output directory name to which to save the plot, passed to matplotlib’s savefig routine. The actual plot is name outplotdir/skies-brickname-bands.png

• bands (list, optional, defaults to [‘g’, ‘r’, ‘z’]) – List of bands to plot in the image (i.e. default is to plot a 3-color grz composite). This is particularly useful when the code fails because a Legacy Surveys image-BAND.fits file is not found, in which case that particular band can be redacted from the bands list.

Returns:

• Nothing, but a plot of the Legacy Surveys image for the Data Release corresponding

• to the survey object and the brick corresponding to brickname is written to

• outplotname. The plot contains the Legacy Surveys imaging with good sky locations

• plotted in green and bad sky locations in red.

Notes

• The array skies must contain at least the columns ‘BRICKNAME’, ‘RA’, ‘DEC’, and ‘DESI_TARGET’, but can contain multiple different values of ‘BRICKNAME’, provided that one of them corresponds to the passed brickname.

• If the passed survey object doesn’t correspond to the Data Release from which the passed skies array was derived, then the sky locations could be plotted at slightly incorrect positions. If the skies array was read from file, this can be checked by making survey that “DEPVER02” in the file header corresponds to the directory survey.survey_dir.

desitarget.skyfibers.repartition_skies(skydirname, numproc=1)

Rewrite a skies directory so each file actually only contains sky locations in the HEALPixels that are listed in the file header.

Parameters:

• skydirname (str) – Full path to a directory containing files of skies that have been partitioned by HEALPixel (i.e. as made by select_skies with the bundle_files option).

• numproc (int, optional, defaults to 1) – The number of processes over which to parallelize writing files.

Returns:

• Nothing, but rewrites the input directory such that each file only

• contains the HEALPixels listed in the file header.

Notes

• Necessary as although the targets and GFAs are parallelized to run in exact HEALPixel boundaries, skies are parallelized across bricks that have CENTERS in a given HEALPixel.

• The original files, before the rewrite, are retained in a directory called “unpartitioned” in the original directory. The file names are appended by “-unpartitioned”.

• Takes about 25 (6.5, 5, 3.5) minutes for numproc=1 (8, 16, 32).

desitarget.skyfibers.select_skies(survey, numproc=16, nskiespersqdeg=None, bands=['g', 'r', 'z'], apertures_arcsec=[0.75], nside=None, pixlist=None, writebricks=False)

Generate skies in parallel for bricks in a Legacy Surveys DR.

Parameters:

• survey (object) – LegacySurveyData object for a given Data Release of the Legacy Surveys; see LegacySurveyData() for details.

• numproc (int, optional, defaults to 16) – The number of processes over which to parallelize.

• nskiespersqdeg (float, optional) – The minimum DENSITY of sky fibers to generate. Defaults to reading from io() with a margin of 4x.

• bands (list, optional, defaults to [‘g’, ‘r’, ‘z’]) – List of bands to be used to define good sky locations.

• apertures_arcsec (list, optional, defaults to [0.75]) – Radii in arcsec of apertures for which to derive flux at a sky location.

• nside (int, optional, defaults to None) – The HEALPixel nside number to be used with the pixlist input.

• pixlist (list or int, optional, defaults to None) – Bricks will only be processed if the CENTER of the brick lies within the bounds of pixels that are in this list of integers, at the supplied HEALPixel nside. Uses the HEALPix NESTED scheme. Useful for parallelizing. If pixlist is None then all bricks in the passed survey will be processed.

• writebricks (boolean, defaults to False) – If True, write the skyfibers object for EACH brick (in the format of the output from sky_fibers_for_brick()) to file. The file name is derived from the input survey object and is in the form: %(survey.survey_dir)/metrics/%(brick).3s/skies-%(brick)s.fits.gz which is returned by survey.find_file(‘skies’).

Returns:

a structured array of sky positions in the DESI sky target format for all bricks in a Legacy Surveys Data Release.

Return type:

ndarray

Notes

• Some core code in this module was initially written by Dustin Lang (@dstndstn).

desitarget.skyfibers.sky_fiber_locations(skypix, gridsize=300)

The core worker function for sky_fibers_for_brick

Parameters:

• skypix (array) – NxN boolean array of pixels.

• gridsize (int, optional, defaults to 300) – Resolution (in pixels) at which to split the skypix array in order to find sky locations. For example, if skypix is a 3600x3600 array of pixels, gridsize=300 will return (3600/300) x (3600/300) = 12x12 = 144 locations.

Notes

• Implements the core trick of iteratively eroding the map of good sky locations to produce a distance-from-blobs map, and then return the max values in that map in each cell of a grid.

• Initial version written by Dustin Lang (@dstndstn).

desitarget.skyfibers.sky_fiber_plots(survey, brickname, skyfibers, basefn, bands=['g', 'r', 'z'])

Make QA plots for sky locations produced by sky_fibers_for_brick

Parameters:

• survey (object) – LegacySurveyData object for a given Data Release of the Legacy Surveys; see LegacySurveyData() for details.

• brickname (str) – Name of the brick from this DR of the Legacy Surveys to plot as an image.

• skyfibers (object) – skyfibers object returned by sky_fibers_for_brick()

• basefn (str) – Base name for the output plot files.

• bands (list, optional, defaults to [‘g’, ‘r’, ‘z’]) – List of bands to plot in the image (i.e. default is to plot a 3-color grz composite). This is particularly useful when a Legacy Surveys image-BAND.fits file is not found, in which case that particular band can be redacted from the bands list.

Returns:

• basefn + ‘-1.png’ : Sky Fiber Positions on the full image

• basefn + ‘-2.png’ : Postage stamps around each sky fiber position

• basefn + ‘-3.png’ : Aperture flux at each radius for each sky fiber

Return type:

Nothing, but plots are written to

Notes

• Initial version written by Dustin Lang (@dstndstn).

desitarget.skyfibers.sky_fibers_for_brick(survey, brickname, nskies=144, bands=['g', 'r', 'z'], apertures_arcsec=[0.5, 0.75, 1.0, 1.5, 2.0, 3.5, 5.0, 7.0])

Produce DESI sky fiber locations in a brick, derived at the pixel-level

Parameters:

• survey (object) – LegacySurveyData object for a given Data Release of the Legacy Surveys; see LegacySurveyData() for details.

• brickname (str) – Name of the brick in which to generate sky locations.

• nskies (float, optional, defaults to 144 (12 x 12)) – The minimum DENSITY of sky fibers to generate

• bands (list, optional, defaults to [‘g’, ‘r’, ‘z’]) – List of bands to be used to define good sky locations.

• apertures_arcsec (list, optional, defaults to [0.5,0.75,1.,1.5,2.,3.5,5.,7.]) – Radii in arcsec of apertures for which to derive flux at a sky location.

Returns:

A FITS table that includes: - the brickid - the brickname - the x and y pixel positions of the fiber location from the blobs file - the distance to the nearest blob at this fiber location - the RA and Dec positions of the fiber location - the aperture flux and ivar at the passed apertures_arcsec

Return type:

object

Notes

• Initial version written by Dustin Lang (@dstndstn).

• The generated sky fiber locations will cover the pixel-based brick grid, which extends beyond the “true” geometric brick boundaries.

desitarget.skyfibers.supplement_skies(nskiespersqdeg=None, numproc=16, gaiadir=None, nside=None, pixlist=None, mindec=-30.0, mingalb=10.0, radius=2.0, dr='dr2')

Generate supplemental sky locations using Gaia-G-band avoidance.

Parameters:

• nskiespersqdeg (float, optional) – The minimum DENSITY of sky fibers to generate. Defaults to reading from io() with a margin of 4x.

• numproc (int, optional, defaults to 16) – The number of processes over which to parallelize.

• gaiadir (str, optional, defaults to $GAIA_DIR) – The GAIA_DIR environment variable is set to this directory. If None is passed, then it’s assumed to already exist.

• nside (int, optional, defaults to None) – (NESTED) HEALPix nside to use with pixlist.

• pixlist (list or int, optional, defaults to None) – Only return targets in a set of (NESTED) HEALpixels at the supplied nside. Useful for parallelizing across nodes. The first entry sets RELEASE for TARGETIDs, and must be < 1000 (to prevent confusion with DR1 and above).

• mindec (float, optional, defaults to -30) – Minimum declination (o) to include for output sky locations.

• mingalb (float, optional, defaults to 10) – Closest latitude to Galactic plane for output sky locations (e.g. send 10 to limit to areas beyond -10o <= b < 10o).

• radius (float, optional, defaults to 2) – Radius at which to avoid (all) Gaia sources (arcseconds).

• dr (str, optional, defaults to “dr2”) – Name of a Gaia data release from which to draw sources. Passed to find_gaia_files().

Returns:

a structured array of supplemental sky positions in the DESI sky target format within the passed mindec and mingalb limits.

Return type:

ndarray

Notes

• The environment variable $GAIA_DIR must be set, or gaiadir must be passed.

desitarget.skyhealpixs

Dynamic lookup of whether a given RA,Dec location is a good place to put a sky fiber. Scripts based on desitarget.skybricks, adapted for healpix split.

class desitarget.skyhealpixs.Skyhealpixs(skyhealpixs_dir=None, nside=64, nest=True)

This class handles dynamic lookup of whether a given (RA,Dec) should make a good location for a sky fiber.

lookup_position(ras, decs)

Looks up a set of RA,Dec positions that are all within a given tile (disk on the sky).

Parameters:

• ras (ndarray) – array of RA locations to look up

• decs (ndarray) – array of Dec locations to look up

Returns:

Boolean array, same length as ras/decs inputs, of good_sky values. (True = good place to put a sky fiber)

Return type:

array

desitarget.skyutilities

This subpackage contains dependencies for running desitarget.skyfibers

desitarget.skyutilities.astrometry

This subpackage contains dependencies from astrometry.net for desitarget.skyfibers

desitarget.skyutilities.astrometry.fits

Module so desitarget sky fiber code doesn’t need explicit astrometry.net dependencies

desitarget.skyutilities.astrometry.fits.fits_table(dataorfn=None, rows=None, hdunum=1, hdu=None, ext=None, header='default', columns=None, column_map=None, lower=True, mmap=True, normalize=True, use_fitsio=True, tabledata_class=<class 'desitarget.skyutilities.astrometry.fits.tabledata'>)

If ‘columns’ (a list of strings) is passed, only those columns will be read; otherwise all columns will be read.

desitarget.skyutilities.astrometry.fits.table_fields(dataorfn=None, rows=None, hdunum=1, hdu=None, ext=None, header='default', columns=None, column_map=None, lower=True, mmap=True, normalize=True, use_fitsio=True, tabledata_class=<class 'desitarget.skyutilities.astrometry.fits.tabledata'>)

If ‘columns’ (a list of strings) is passed, only those columns will be read; otherwise all columns will be read.

desitarget.skyutilities.legacypipe

This subpackage contains dependencies from legacypipe for desitarget.skyfibers

desitarget.skyutilities.legacypipe.util

Module so desitarget sky fiber code doesn’t need explicit legacypipe dependencies

class desitarget.skyutilities.legacypipe.util.LegacySurveyData(survey_dir=None)

A class describing the contents of a LEGACY_SURVEY_DIR directory – tables of CCDs and of bricks, and calibration data. Methods for dealing with the CCDs and bricks tables.

This class is also responsible for creating LegacySurveyImage objects (eg, DecamImage objects), which then allow data to be read from disk.

find_file(filetype, brick=None, brickpre=None, band='%(band)s', output=False)

Returns the filename of a Legacy Survey file.

filetypestring, type of file to find, including:

“tractor” – Tractor catalogs “depth” – PSF depth maps “galdepth” – Canonical galaxy depth maps “nexp” – number-of-exposure maps

brick : string, brick name such as “0001p000”

output: True if we are about to write this file; will use self.outdir as the base directory rather than self.survey_dir.

Returns: path to the specified file (whether or not it exists).

get_brick_by_name(brickname)

Returns a brick (as one row in a table) by name (string).

get_bricks()

Returns a table of bricks. The caller owns the table.

For read-only purposes, see get_bricks_readonly(), which uses a cached version.

get_bricks_readonly()

Returns a read-only (shared) copy of the table of bricks.

desitarget.skyutilities.legacypipe.util.get_rgb(imgs, bands, mnmx=None, arcsinh=None)

Given a list of images in the given bands, returns a scaled RGB image.

Parameters:

• imgs (list) – List of numpy arrays, all the same size, in nanomaggies.

• bands (list) – List of strings, e.g., ['g','r','z'].

• mnmx (tuple()) – (min,max), values that will become black/white after scaling. Default is (-3,10).

• arcsinh (float, optional) – Use nonlinear scaling as in SDSS.

Returns:

(H,W,3) numpy array with values between 0 and 1.

Return type:

array-like

desitarget.streams.cuts

Target selection cuts for the DESI MWS Stellar Stream programs.

Borrows heavily from Sergey Koposov.

desitarget.streams.cuts.is_in_C19(objs, streamname)

Whether a target lies within the C-19 stellar stream.

Parameters:

objs (array_like) – Numpy rec array with at least the Legacy Surveys/Gaia columns: RA, DEC, PARALLAX, PMRA, PMDEC, PARALLAX_IVAR, PMRA_IVAR, PMDEC_IVAR, EBV, FLUX_G, FLUX_R, FLUX_Z, PSEUDOCOLOUR, TYPE, ASTROMETRIC_PARAMS_SOLVED, NU_EFF_USED_IN_ASTROMETRY, ECL_LAT, PHOT_G_MEAN_MAG.

Returns:

• array_like – True if the object is a bright “BRIGHT_PM1” target.

• array_like – True if the object is a bright “BRIGHT_PM2” target.

• array_like – True if the object is a bright “BRIGHT_PM3” target.

• array_like – True if the object is a faint “FAINT_CMD” target.

• array_like – True if the object is a white dwarf “FILLER” target.

desitarget.streams.cuts.is_in_GD1(objs, streamname)

Whether a target lies within the GD1 stellar stream.

Parameters:

objs (array_like) – Numpy rec array with at least the Legacy Surveys/Gaia columns: RA, DEC, PARALLAX, PMRA, PMDEC, PARALLAX_IVAR, PMRA_IVAR, PMDEC_IVAR, EBV, FLUX_G, FLUX_R, FLUX_Z, PSEUDOCOLOUR, TYPE, ASTROMETRIC_PARAMS_SOLVED, NU_EFF_USED_IN_ASTROMETRY, ECL_LAT, PHOT_G_MEAN_MAG.

Returns:

• array_like – True if the object is a bright “BRIGHT_PM1” target.

• array_like – True if the object is a bright “BRIGHT_PM2” target.

• array_like – True if the object is a bright “BRIGHT_PM3” target.

• array_like – True if the object is a faint “FAINT_CMD” target.

• array_like – True if the object is a white dwarf “FILLER” target.

desitarget.streams.cuts.is_in_ORPHAN(objs, streamname)

Whether a target lies within the Orphan stellar stream.

Parameters:

objs (array_like) – Numpy rec array with at least the Legacy Surveys/Gaia columns: RA, DEC, PARALLAX, PMRA, PMDEC, PARALLAX_IVAR, PMRA_IVAR, PMDEC_IVAR, EBV, FLUX_G, FLUX_R, FLUX_Z, PSEUDOCOLOUR, TYPE, ASTROMETRIC_PARAMS_SOLVED, NU_EFF_USED_IN_ASTROMETRY, ECL_LAT, PHOT_G_MEAN_MAG.

Returns:

• array_like – True if the object is a bright “BRIGHT_PM” target.

• array_like – True if the object is a faint “FAINT_CMD” target.

• array_like – True if the object is a white dwarf “FILLER” target.

Notes

Based on Sergey Koposov’s is_in_GD1() code.

desitarget.streams.cuts.is_in_PAL5(objs, streamname)

Whether a target lies within the Palomar 5 stellar stream.

Parameters:

objs (array_like) – Numpy rec array with at least the Legacy Surveys/Gaia columns: RA, DEC, PARALLAX, PMRA, PMDEC, PARALLAX_IVAR, PMRA_IVAR, PMDEC_IVAR, EBV, FLUX_G, FLUX_R, FLUX_Z, PSEUDOCOLOUR, TYPE, ASTROMETRIC_PARAMS_SOLVED, NU_EFF_USED_IN_ASTROMETRY, ECL_LAT, PHOT_G_MEAN_MAG.

Returns:

• array_like – True if the object is a bright “BRIGHT_PM1” target.

• array_like – True if the object is a bright “BRIGHT_PM2” target.

• array_like – True if the object is a bright “BRIGHT_PM3” target.

• array_like – True if the object is a faint “FAINT_CMD” target.

• array_like – True if the object is a white dwarf “FILLER” target.

desitarget.streams.cuts.is_in_dwarf(objs, dwarf_name)

Performs target selection on a source catalog for a given dwarf galaxy.

Parameters:

• objs (array_like) – Numpy rec array with at least the Legacy Surveys/Gaia columns: RA, DEC, PARALLAX, PMRA, PMDEC, PARALLAX_IVAR, PMRA_IVAR, PMDEC_IVAR, EBV, FLUX_G, FLUX_R, FLUX_Z, PSEUDOCOLOUR, TYPE, ASTROMETRIC_PARAMS_SOLVED, NU_EFF_USED_IN_ASTROMETRY, ECL_LAT, PHOT_G_MEAN_MAG.

• dwarf_name (str) – Name of a dwarf galaxy that appears in the ../data/dwarfs.yaml file. Possibilities include ‘BOOTES_1’, ‘CANES_VENATICI_1’, ‘DRACO_1’, ‘SEXTANS_1’, and ‘URSA_MINOR_1’.

Returns:

• array_like – True if the object is a bright “BRIGHT_PM1” target.

• array_like – True if the object is a bright “BRIGHT_PM2” target.

• array_like – True if the object is a bright “BRIGHT_PM3” target.

• array_like – True if the object is a faint “PM_ONLY” target.

• array_like – True if the object is a faint “FAINT_CMD” target.

• array_like – True if the object is a white dwarf “FILLER” target.

desitarget.streams.cuts.select_targets(swdir, targnames_in=None, readpertarg=False, addnors=True, readcache=True, numproc=1, mindec=-20, nside=None, pixint=None)

Process files from an input directory to select targets.

Parameters:

• swdir (str) – Root directory of Legacy Surveys sweep files for a given data release for ONE of EITHER north or south, e.g. “/global/cfs/cdirs/cosmo/data/legacysurvey/dr9/south/sweep/9.0”.

• targnames_in (list) – A list of MWS extension target classes to process. Defaults to all MWS extension target classes. This will get sorted by rank.

• readpertarg (bool, optional, defaults to False) – When set, read each stream’s data individually instead of looping through all possible sweeps files. This is likely quickest and most useful when working with a single stream. For multiple streams it may cause issues when duplicate targets are selected.

• addnors (bool) – If True then if swdir contains “north” add sweep files from the south by substituting “south” in place of “north” (and vice versa, i.e. if swdir contains “south” add sweep files from the north by substituting “north” in place of “south”).

• readcache (bool, optional, defaults to True) – If True read all data from previously made cache files, in cases where such files exist. If False don’t read from caches AND OVERWRITE any cached files, if they exist. Caches are stored in the $TARG_DIR/streamcache/drX/ directory, where drX is the Legacy Surveys Data Release (parsed from swdir).

• numproc (int, optional, defaults to 1 for serial) – The number of parallel processes to use. numproc of 16 is a good balance between speed and file I/O.

• mindec (float or int, optional, defaults to -20 (20oS)) – Hard limit on data (objects south of this are not returned).

• nside (int, optional, defaults to None) – (NESTED) HEALPixel nside used with pixint. Only used if readpertarg is False.

• pixint (int, optional, defaults to None) – Only read and cache targets in (NESTED) HEALpixels at nside. For parallelizing. Only used if readpertarg is False.

Returns:

Targets in the input swdir which pass the cuts with added targeting columns such as TARGETID, and DESI_TARGET, BGS_TARGET, MWS_TARGET (i.e. target selection bitmasks).

Return type:

ndarray

desitarget.streams.cuts.set_target_bits(objs, targmwext_names=['GD1', 'BOOTES_1'])

Select stream and dwarf targets, returning target mask arrays.

Parameters:

• objs (ndarray) – numpy structured array with UPPERCASE columns needed for stream target selection. See, e.g., is_in_GD1() for column names.

• targmwext_names (list) – A list of stream names to process. Default is available streams.

Returns:

(desi_target, bgs_target, mws_target, scnd_target) where each element is an array of target selection bitmasks for each object.

Return type:

ndarray

Notes

• See ../data/targetmask.yaml for the definition of each bit.

desitarget.streams.gaia_dr3_parallax_zero_point.zpt._calc_zpt(phot_g_mean_mag, nu_eff_used_in_astrometry, pseudocolour, sinBeta, source_type)

Compute the zero-point parallax for an array of stars.

WARNING! This function is meant to be auxiliary, therefore it assumes that the inputs are well formatted (see get_zpt()) and that all the sources have the same value for astrometric_params_solved. That is, either all are 5p (source_type: 5) or 6p (source_type: 6). Never 2p.

desitarget.streams.gaia_dr3_parallax_zero_point.zpt._read_table(file, sep=',')

Extract the coefficients and interpolation limits from the input file provided.

The first and second rows are assumed to be the indices that govern, respectively, the colour and sinBeta interpolations.

From the third rows onwards, all belong to the G magnitude interpolation: first column, the phot_g_mean_mag boundaries. The rest of columns, the interpolation coefficients.

desitarget.streams.gaia_dr3_parallax_zero_point.zpt.get_zpt(phot_g_mean_mag, nu_eff_used_in_astrometry, pseudocolour, ecl_lat, astrometric_params_solved, _warnings=True)

Returns the parallax zero point [mas] for a source of given G magnitude, effective wavenumber (nuEff) [1/micron], pseudocolour (pc) [1/micron], and ecl_lat [degrees]. It also needs the astrometric_params_solved to discern between 5-p and 6-p solutions. Valid for 5- and 6-parameter solutions with 6<G<21 and 1.1<nuEff<1.9, 1.24<pc<1.72. Outside these ranges, the function can return a very imprecise zero-point.

The inputs can be either floats or an iterable (ndarray, list or tuple). In case of the later, their shape must be the same and equal to (N,), where N is the number of sources.

Usage: parallax_corrected = parallax_catalogue - zero_point

Original code: @LL 2020-07-14

NOTE: if any of the inputs values is NaN, the output will be NaN. Also, if the warnings are turned off and the source probided falls outside the valid range specified above, its zero-point will be NaN.

Input:

phot_g_mean_mag [mag] nu_eff_used_in_astrometry [1/micron] pseudocolour [1/micron] ecl_lat [degrees] astrometric_params_solved (3 -> 2p, 31 -> 5p, 95 -> 6p)

Output:

correction in mas (milliarcsecond, not micro).

desitarget.streams.gaia_dr3_parallax_zero_point.zpt.load_tables(file5=PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/desitarget/checkouts/latest/py/desitarget/streams/gaia_dr3_parallax_zero_point/coefficients/z5_200720.txt'), file6=PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/desitarget/checkouts/latest/py/desitarget/streams/gaia_dr3_parallax_zero_point/coefficients/z6_200720.txt'), sep=',')

Initialises the tables containing the coefficients of the interpolations for the Z5 and Z6 functions.

NOTE: USE THE DEFAULT VALUES unless you are very sure of what you are doing.

Inputs

file5: path to the file with the Z5 coefficients (.txt or similar) file6: path to the file with the Z6 coefficients (.txt or similar) sep (optional): separator used to split the lines (default, comma)

desitarget.streams.gaia_dr3_parallax_zero_point.zpt.zpt_wrapper(pandas_row)

Compute the parallax zero-point with get_zpt function for each row of the pandas DataFrame. It assumes that the DataFrame has:

• phot_g_mean_mag: apparent magnitude in the G band

• nu_eff_used_in_astrometry: effective wavenumber for a 5-parameter solution

• pseudocolour: effective wavenumber for a 6-parameter solution

• ecl_lat: ecliptic latitude in degrees

• astrometric_params_solved (3 -> 2p, 31 -> 5p, 95 -> 6p)

Errors are set to False, therefore stars that are NOT inside the valid range of the interpolators will receive a NaN.

Example: df.apply(zpt_wrapper,axis=1)

desitarget.streams.io

Reading/writing data for the MWS Stellar Stream programs.

desitarget.streams.io.read_data_per_stream(swdir, rapol, decpol, mind, maxd, stream_name, readcache=True, addnors=True, test=False, numproc=1, mindec=-20, nside=None, pixint=None, readall=False)

Assemble the data needed for a particular stream program.

Parameters:

• swdir (str) – Root directory of Legacy Surveys sweep files for a given data release for ONE of EITHER north or south, e.g. “/global/cfs/cdirs/cosmo/data/legacysurvey/dr9/south/sweep/9.0”.

• rapol (float) – Pole in the stream coordinate system in DEGREES.

• decpol (float) – Pole in the stream coordinate system in DEGREES.

• mind (float or int) – Minimum and maximum angular distance from the pole of the stream coordinate system to search for members in DEGREES.

• maxd (float or int) – Minimum and maximum angular distance from the pole of the stream coordinate system to search for members in DEGREES.

• stream_name (str) – Name of a stream. Used to make the cached filename, e.g. “GD1”.

• readcache (bool, optional, defaults to True) – If True read from a previously constructed and cached file automatically, IF such a file exists. If False don’t read a cache file AND OVERWRITE the cache file, if it exists. Caches are stored in the $TARG_DIR/streamcache/drX/ directory, where drX is the Legacy Surveys Data Release (parsed from swdir).

• addnors (bool, optional, defaults to True) – If True then if swdir contains “north” add sweep files from the south by substituting “south” in place of “north” (and vice versa, i.e. if swdir contains “south” add sweep files from the north by substituting “north” in place of “south”).

• test (bool, optional, defaults to False) – Read a subset of the data for testing purposes.

• numproc (int, optional, defaults to 1 for serial) – The number of parallel processes to use. numproc of 16 is a good balance between speed and file I/O.

• mindec (float or int, optional, defaults to -20 (20oS)) – Hard limit on data (objects south of this are not returned).

• nside (int, optional, defaults to None) – (NESTED) HEALPixel nside used with pixint. Only used if readall is True.

• pixint (int, optional, defaults to None) – Only read and cache targets in (NESTED) HEALpixels at nside. Useful for parallelizing. Only used if readall is True.

• readall (bool, optional, defaults to False) – Ignore all inputs except addnors, nside and pixint and instead read and cache the sweep files in the appropriate pixels Reads _all_ sweep files if nside and pixint are None.

Returns:

True for stream members.

Return type:

array_like or boolean

Notes

• Example values for, e.g., GD1:

  swdir = “/global/cfs/cdirs/cosmo/data/legacysurvey/dr9/south/sweep/9.0” rapol, decpol = 34.5987, 29.7331 mind, maxd = 80, 100

• The $TARG_DIR environment variable must be set to read/write from a cache. If $TARG_DIR is not set, caching is completely ignored.

• This is useful for a single stream. Caching all of the sweeps using the readall kwarg is likely best for multiple large streams.

desitarget.streams.io.read_data_per_stream_one_file(filename, rapol, decpol, mind, maxd, mindec=-20.0, readall=False)

Assemble the data needed for a stream program from one file

Parameters:

• swdir (str) – Name of a Legacy Surveys sweep file.

• rapol (float) – Pole in the stream coordinate system in DEGREES.

• decpol (float) – Pole in the stream coordinate system in DEGREES.

• mind (float or int) – Minimum and maximum angular distance from the pole of the stream coordinate system to search for members in DEGREES.

• maxd (float or int) – Minimum and maximum angular distance from the pole of the stream coordinate system to search for members in DEGREES.

• mindec (float or int, optional, defaults to -20 (20oS)) – Hard limit on data (objects south of this are not returned).

• readall (bool, optional, defaults to False) – Ignore the stream-related inputs (decpol, mind, maxd) and instead read _all_ of the sweep files.

Returns:

An array of objects from the filename that are in the stream, with matched Gaia information.

Return type:

array_like

desitarget.streams.io.write_targets(dirname, targs, header, nside=None, pixint=None, subpriority=True, nsidecol=None, addstandards=False, backupdir=None)

Write stream and dwarf targets to a FITS file.

Parameters:

• dirname (str) – The output directory name. Filenames are constructed from other inputs.

• targs (ndarray) – The numpy structured array of data to write.

• header (dict) – Header for output file. Can be a FITShdr object or dictionary. Pass {} if you have no additional header information.

• nside (int, optional, defaults to None) – Passed to indicate in the output file header that the targets have been limited to only certain HEALPixels at a given nside. Used in conjunction with pixint.

• pixint (int, optional, defaults to None) – Passed to indicate in the output file header and name that the targets have been limited to only this list of HEALPixels. Used in conjunction with nside.

• subpriority (bool, optional, defaults to True) – If True and a SUBPRIORITY column is in the input targs, then SUBPRIORITY==0.0 entries are overwritten by a random float in the range 0 to 1, using a seed of 816.

• nsidecol (int, optional, defaults to None) – If passed, add a column to the targets array popluated with HEALPixels in the nested scheme at resolution nsidecol.

• addstandards (bool, optional, defaults to False) – If True then add standard stars from the BACKUP program by reading them from a directory of BACKUP files.

• backupdir (str, optional, defaults to None) – Use this as the directory that hosts the BACKUP target files if addstandards is True. If None is passed, defaults to: $TARG_DIR/gaiadr2/2.2.0/targets/main/resolve/backup

Returns:

• int – The number of targets that were written to file.

• str – The name of the file to which targets were written. This is None if zero targets were written to file (if the length of targs is zero).

Notes

• Must contain at least the columns:

  GAIA_PHOT_G_MEAN_MAG, GAIA_PHOT_BP_MEAN_MAG, GAIA_PHOT_RP_MEAN_MAG and FIBERTOTFLUX_G, FIBERTOTFLUX_R, FIBERTOTFLUX_Z, RELEASE

• Always OVERWRITES existing files!

• Writes atomically. Any output files that died mid-write will be appended by “.tmp”.

• Units are automatically added from the desitarget units yaml file (see /data/units.yaml).

• Mostly wraps write_with_units().

• nsidecol and nside may be confusing as these are called nside

  and nsidefile in write_targets().

desitarget.streams.targets

Manipulate/add target bitmasks/priorities/numbers of observations for stream targets.

desitarget.streams.targets.finalize(targets, desi_target, bgs_target, mws_target, scnd_target)

Return new targets array with added/renamed columns

Parameters:

• targets (ndarray) – numpy structured array of targets.

• desi_target (ndarray) – 1D array of target selection bit flags.

• bgs_target (ndarray) – 1D array of target selection bit flags.

• mws_target (ndarray) – 1D array of target selection bit flags.

• scnd_target (ndarray) – 1D array of target selection bit flags.

Returns:

new targets structured array with the following additions:

• renaming OBJID -> BRICK_OBJID (it is only unique within a brick).

• renaming TYPE -> MORPHTYPE (used downstream in other contexts).

• Adding new columns:

  • TARGETID: unique ID across all bricks or Gaia files.

  • DESI_TARGET: dark time survey target selection flags.

  • MWS_TARGET: bright time MWS target selection flags.

  • BGS_TARGET: bright time BGS target selection flags.

  • SCND_TARGET: stream secondary target selection flags.

  • PRIORITY_INIT: initial priority for observing target.

  • SUBPRIORITY: a placeholder column that is set to zero.

  • NUMOBS_INIT: initial number of observations for target.

  • OBSCONDITIONS: bitmask of observation conditions.

Return type:

ndarray

Notes

• SUBPRIORITY is the only column that isn’t populated. This is because it’s easier to populate it in a reproducible fashion when collecting targets rather than on a per-brick basis when this function is called. It’s set to all zeros.

• NUMOBS_INIT and PRIORITY_INIT are split into DARK/BRIGHT/BACKUP versions, as these surveys are effectively separate.

desitarget.streams.utilities

Utilities for the DESI MWS Stellar Stream programs.

Borrows heavily from Sergey Koposov’s astrolibpy routines.

desitarget.streams.utilities.apply_plx_zpt(D)

Apply zero-point correction to Gaia parallax

Parameters:

D (ndarray) – Numpy structured array of Gaia information that contains at least the columns RA, ASTROMETRIC_PARAMS_SOLVED, PHOT_G_MEAN_MAG, NU_EFF_USED_IN_ASTRONOMY, PSEUDOCOLOUR, ECL_LAT, PARALLAX PARALLAX_ERROR. PARALLAX_IVAR will be used instead of PARALLAX_ERROR if PARALLAX_ERROR is not present.

Returns:

Zero-point corrected parallax.

Return type:

array_like or float

desitarget.streams.utilities.betw(x, x1, x2)

Whether x lies in the range x1 <= x < x2.

Parameters:

• x (ndarray or int or float) – Value(s) that need checked against x1, x2.

• x1 (ndarray or int or float) – Lower range to check against (inclusive).

• x2 (ndarray or int or float) – Upper range to check against (exclusive).

Returns:

True for values of x that lie in the range x1 <= x < x2. If any input is an array then the output will be a Boolean array.

Return type:

array_like or boolean

Notes

• Very permissive. Arrays can be checked against other arrays, scalars against scalars and arrays against arrays. For example, if all the inputs are arrays the calculation will be element-wise. If x1 and x2 are floats and x is array-like then each element of x will be checked against the range. If x and x2 are floats and x1 is an array, all possible x1->x2 ranges will be checked.

desitarget.streams.utilities.cmd_sel_func(dwarf_name, D, rgb_color_tol=0.2, rgb_mag_tol=0.0, rgb_grmin=-0.5, rgb_grmax=1.5, rgb_rmin=16, rgb_rmax=23, hb_color_tol=0.1, hb_mag_tol=0.5, hb_grmin=-0.5, hb_grmax=0.5, hb_rmin=16, hb_rmax=23)

Select dwarf galaxy members using CMD cuts.

Parameters:

• dwarf_name (str) – Name of a dwarf galaxy that appears in the ../data/dwarfs.yaml file. Possibilities include ‘DRACO_1’.

• D (ndarray) – Numpy structured array of Gaia information that contains at least the columns FLUX_G, FLUX_R, FLUX_Z, FLUX_IVAR_G, FLUX_IVAR_R, FLUX_IVAR_Z, and EBV.

• rgb_color_tol (float or int) – Width of RGB cmd selection, defaults to 0.2.

• rgb_mag_tol (float or int) – Height of RGB cmd selection, defaults to 0.0. WARNING: Non-zero values lead to unexpected behavior at the tip of the RGB

• rgb_grmin (float or int) – Minimum extinction-corrected g-r for RGB selection, defaults to -0.5.

• rgb_grmax (float or int) – Maximum extinction-corrected g-r for RGB selection, defaults to 1.5.

• rgb_rmin (float or int) – Bright limit for RGB selection, defaults to 16.

• rgb_rmax (float or int) – Faint limit for RGB selection, defaults to 23.

• hb_color_tol (float or int) – Width of HB cmd selection, defaults to 0.1.

• hb_mag_tol (float or int) – Height of HB cmd selection, defaults to 0.5.

• hb_grmin (float or int) – Minimum extinction-corrected g-r for HB selection, defaults to -0.5.

• hb_grmax (float or int) – Maximum extinction-corrected g-r for HB selection, defaults to 0.5.

• hb_rmin (float or int) – Bright limit for HB selection, defaults to 16.

• hb_rmax (float or int) – Faint limit for HB selection, defaults to 23.

• show_magerr_plot (bool) – Show log10(rmag error) vs. rmag relationship

Returns:

True for dwarf members.

Return type:

array_like or boolean

desitarget.streams.utilities.correct_pm(ra, dec, pmra, pmdec, dist)

Correct proper motions for the Sun’s motion.

Parameters:

• ra (ndarray or float) – Right Ascension, Declination in DEGREES.

• dec (ndarray or float) – Right Ascension, Declination in DEGREES.

• pmra (ndarray or float) – Proper motion in Right Ascension, Declination in mas/yr. pmra includes the cosine term.

• pmdec (ndarray or float) – Proper motion in Right Ascension, Declination in mas/yr. pmra includes the cosine term.

• dist (float) – Distance in kpc.

Returns:

A tuple of the the new (pmra, pmdec) values in DEGREES. If ra, dec, etc. are passed as arrays this will be a tuple of arrays. If the input arrays are length zero, the input pmra, pmdec are returned unaltered

Return type:

tuple

desitarget.streams.utilities.cosd(x)

Return cos(x) for an angle x in degrees.

desitarget.streams.utilities.dwarf_plx_sel_func(dist, D, plx_sys=0.05, mult=2.5, keep_all_neg=False, min_plx_plxerr=-5)

Select dwarf members using parallax, padded by some error. NOTE: This is a slight alteration on the GD1 parallax selection, as it will select anything with a negative parallax regardless of the distance to the galaxy

Parameters:

• dist (ndarray or float) – Distance of possible stream members.

• D (ndarray) – Numpy structured array of Gaia information that contains at least the columns RA, ASTROMETRIC_PARAMS_SOLVED, PHOT_G_MEAN_MAG, NU_EFF_USED_IN_ASTRONOMY, PSEUDOCOLOUR, ECL_LAT, PARALLAX PARALLAX_ERROR. PARALLAX_IVAR will be used instead of PARALLAX_ERROR if PARALLAX_ERROR is not present.

• plx_sys (float) – Extra offset with which to pad mult * parallax_error.

• mult (float or int) – Multiple of the parallax error to use for padding.

• keep_all_neg (bool) – If true, keep all targets with negative parallaxes.

• min_plx_plxerr (float) – Minimum allowable parallax/parallax error, defaults to -5. Useful if keep_all_neg = True.

Returns:

True for stream members.

Return type:

array_like or boolean

desitarget.streams.utilities.errors_to_ivars(objs, colnames=[])

Convert errors to ivars, correctly dealing with NaNs.

Parameters:

• objs (ndarray) – Array that contains the columns to be converted from errors to inverse variances.

• colnames (list) – The names of the columns to convert.

Returns:

The input objs, modified so that any columns in colnames are converted from errors to inverse variances and occurrences of “ERROR” in column names are converted to “IVAR”.

Return type:

ndarray

Notes

• Column names are assumed to be upper case for the conversion of ERROR->IVAR in the column names.

• No copy is made to save memory. So objs will be modified in place and calls like a = errors_to_ivars(b, colnames=[“X”]) will alter values in b as well as returning a.

desitarget.streams.utilities.fromrect(x, y, z)

Convert equatorial coordinates to Cartesian coordinates.

Parameters:

• x (ndarray or float) – Cartesian coordinates.

• y (ndarray or float) – Cartesian coordinates.

• z (ndarray or float) – Cartesian coordinates.

Returns:

A tuple of the RA, Dec converted values in DEGREES. If x, y, z are passed as arrays this will be a tuple of RA, Dec arrays.

Return type:

tuple

desitarget.streams.utilities.get_CMD_interpolator(stream_name)

Isochrones via interpolating over points in color-magnitude space.

Parameters:

stream_name (str) – Name of a stream that appears in the ../data/streams.yaml file. Possibilities include ‘GD1’.

Returns:

A scipy interpolated UnivariateSpline.

Return type:

UnivariateSpline

desitarget.streams.utilities.get_plx_error(D)

Gets parallax error from inverse variance if necessary.

Parameters:

D (ndarray) – Numpy structured array of Gaia information that contains either the column PARALLAX_ERROR or the column PARALLAX_IVAR.

Returns:

Parallax error.

Return type:

array_like or float

desitarget.streams.utilities.get_targmwext_parameters(targmwext_name)

Look up information for a given stream or dwarf

Parameters:

targmwext_name (str) – Name of a stream that appears in the ../data/streams.yaml file or ../data/dwarf.yaml Possibilities include ‘GD1’.

Returns:

A dictionary of stream parameters for the passed targmwext_name. Includes isochrones and positional information.

Return type:

dict

Notes

• Parameters for each stream are in the ../data/streams.yaml file.

• Parameters for each dwarf are in the ../data/dwarfs.yaml file.

desitarget.streams.utilities.ivars_to_errors(objs, colnames=[])

Convert inverse variances to errors without dividing by zero.

Parameters:

• objs (ndarray) – Array that contains the columns to be converted from inverse variances to errors.

• colnames (list) – The names of the columns to convert.

Returns:

The input objs, modified so that any columns in colnames are converted from inverse variances to errors and occurrences of “IVAR” in column names are converted to “ERROR”.

Return type:

ndarray

Notes

• Column names are assumed to be upper case for the conversion of IVAR->ERROR in the column names.

• No copy is made to save memory. So objs will be modified in place and calls like a = ivars_to_errors(b, colnames=[“X”]) will alter values in b as well as returning a.

desitarget.streams.utilities.oldpop_bhb_sel(gmag, rmag, distance)

Select stream members with the CMD properties of BHBs belonging to the stream.

Parameters:

• distance (ndarray or float) – Distance of possible stream members, in kpc.

• gmag (ndarray or float) – extinction-corrected g magnitude of candidates

• rmag (ndarray or float) – extinction-corrected r magnitude of candidates

Returns:

True for stream members.

Return type:

array_like or boolean

Notes

Selects BHB for an old metal-poor population. This uses an M92 horizontal branch distance (kpc) to the stream at the phi1 location of each star (i.e., distance to each star if it were in the stream.

desitarget.streams.utilities.plx_sel_func(dist, D, mult, plx_sys=0.05)

Select stream members using parallax, padded by some error.

Parameters:

• dist (ndarray or float) – Distance of possible stream members.

• D (ndarray) – Numpy structured array of Gaia information that contains at least the columns RA, ASTROMETRIC_PARAMS_SOLVED, PHOT_G_MEAN_MAG, NU_EFF_USED_IN_ASTRONOMY, PSEUDOCOLOUR, ECL_LAT, PARALLAX PARALLAX_ERROR. PARALLAX_IVAR will be used instead of PARALLAX_ERROR if PARALLAX_ERROR is not present.

• mult (float or int) – Multiple of the parallax error to use for padding.

• plx_sys (float) – Extra offset with which to pad mult * parallax_error.

Returns:

True for stream members.

Return type:

array_like or boolean

desitarget.streams.utilities.pm0_sel_func(pmra0, pmdec0, D, pad=2, mult=2.5)

Select dwarf members using proper motion, using a PM range

around the systemtic PM of the dwarf padded by some error.

Parameters:

• pmra0 (ndarray or float) – Systemic proper motions of dwarf galaxy.

• pmdec0 (ndarray or float) – Systemic proper motions of dwarf galaxy.

• D (ndarray) – Numpy structured array of Gaia information that contains at least the columns PMRA, PMDEC, PMRA_ERROR, and PMDEC_ERROR.

• pad (: float or int, defaults to 2) – Extra offset with which to pad mult * proper_motion_error.

• mult (float or int, defaults to 2.5) – Multiple of the proper motion error to use for padding.

Returns:

True for dwarf members.

Return type:

array_like or boolean

desitarget.streams.utilities.pm12_distdep_sel_func(pm1track, pm2track, pmfi1, pmfi2, pm_err, dist, velpad, mult=2.5)

Select stream members in stream coordinate, using a proper motion range defined by a

velocity width, padded by some multiple of the error.

Parameters:

• pm1track (ndarray or float) – Allowed proper motions of stream targets, RA-sense.

• pm2track (ndarray or float) – Allowed proper motions of stream targets, Dec-sense.

• pmfi1 (ndarray or float) – Proper motion in stream coordinates of possible targets, derived from RA.

• pmfi2 (ndarray or float) – Proper motion in stream coordinates of possible targets, derived from Dec.

• pm_err (ndarray or float) – Proper motion error in stream coordinates of possible targets, combined across pmfi1 and pmfi2 errors.

• pad (: float or int) – Width of PM selection in km/s, with mult * proper_motion_error

• mult (float or int, defaults to 2.5) – Multiple of the proper motion error to use for padding.

Returns:

True for stream members.

Return type:

array_like or boolean

desitarget.streams.utilities.pm12_sel_func(pm1track, pm2track, pmfi1, pmfi2, pm_err, pad=2, mult=2.5)

Select stream members in stream coordinates, using proper motion,

padded by some error. This works with PM_RA,PM_Dec, too

Parameters:

• pm1track (ndarray or float) – Allowed proper motions of stream targets, RA-sense.

• pm2track (ndarray or float) – Allowed proper motions of stream targets, Dec-sense.

• pmfi1 (ndarray or float) – Proper motion in stream coordinates of possible targets, derived from RA.

• pmfi2 (ndarray or float) – Proper motion in stream coordinates of possible targets, derived from Dec.

• pm_err (ndarray or float) – Proper motion error in stream coordinates of possible targets, combined across pmfi1 and pmfi2 errors.

• pad (: float or int, optional) – Extra offset with which to pad mult times proper_motion_error.

• mult (float or int, optional) – Multiple of the proper motion error to use for padding.

Returns:

An array with values that are True for stream members.

Return type:

array-like

desitarget.streams.utilities.rotate_pm(ra, dec, pmra, pmdec, rapol, decpol, ra0, revert=False)

Rotate proper motions to a new spherical coordinate system.

Parameters:

• ra (ndarray or float) – Right Ascension, Declination in DEGREES.

• dec (ndarray or float) – Right Ascension, Declination in DEGREES.

• pmra (ndarray or float) – Proper motion in Right Ascension, Declination in mas/yr.

• pmdec (ndarray or float) – Proper motion in Right Ascension, Declination in mas/yr.

• pmdec – Proper motion in Declination in mas/yr.

• rapol (float) – Pole of the new coordinate system in DEGREES.

• decpol (float) – Pole of the new coordinate system in DEGREES.

• ra0 (float) – Zero latitude of the new coordinate system in DEGREES.

• revert (bool, optional, defaults to False) – Reverse the rotation.

Returns:

A tuple of the the new pmra, pmdec values in DEGREES. If ra, dec, etc. are passed as arrays this will be a tuple of arrays.

Return type:

tuple

desitarget.streams.utilities.rotation_matrix(rapol, decpol, ra0)

Return the rotation matrix corresponding to the pole of rapol, decpol and with the zero of the new latitude corresponding to ra=ra0. The resulting matrix needs to be np.dot’ed with a vector to forward transform that vector.

Parameters:

• rapol (float) – Pole of the new coordinate system in DEGREES.

• decpol (float) – Pole of the new coordinate system in DEGREES.

• ra0 (float) – Zero latitude of the new coordinate system in DEGREES.

Returns:

3x3 Rotation matrix.

Return type:

ndarray

desitarget.streams.utilities.simple_plx_sel(dist, D, multfac, plxlim, plx_sys=0.05)

Select stream members using a parallax upper limit, padded by some error.

Parameters:

• dist (ndarray or float) – Distance of possible stream members.

• D (ndarray) – Numpy structured array of Gaia information that contains at least the columns RA, ASTROMETRIC_PARAMS_SOLVED, PHOT_G_MEAN_MAG, NU_EFF_USED_IN_ASTRONOMY, PSEUDOCOLOUR, ECL_LAT, PARALLAX PARALLAX_ERROR. PARALLAX_IVAR will be used instead of PARALLAX_ERROR if PARALLAX_ERROR is not present.

• mult (float or int) – Multiple of the parallax error to use for padding.

• plx_sys (float) – Extra offset with which to pad mult * parallax_error.

• plxlim (float select possible stream members with plx < plx_lim, plus pad)

Returns:

True for stream members.

Return type:

array_like or boolean

desitarget.streams.utilities.sind(x)

Return sin(x) for an angle x in degrees.

desitarget.streams.utilities.sort_targmwext_by_rank(in_targmwextlist)

Return a list of all the stream and dwarf names in in_targmwextlist

ordered by their priority as given in TARGMWEXT_RANK. Smaller numbers are higher priority.

Parameters:

in_targmwextlist (:class:string`) – List of dwarf and stream objects to be sorted

Returns:

Sorted list of dwarf and stream objects

Return type:

string

desitarget.streams.utilities.spatial_sel_func(ra0, dec0, maxd, D)

Selects dwarf members within a given radius. Currently redundant with the pre-selection used in generating the input catalog.

Parameters:

• ra0 (float) – Central coordinates of dwarf galaxy in DEGREES.

• dec0 (float) – Central coordinates of dwarf galaxy in DEGREES.

• D (ndarray) – Numpy structured array of Gaia information that contains at least the columns RA and DEC.

• maxd (ndarray or float) – Maximum distance of possible targets to dwarf.

Returns:

True for dwarf members.

Return type:

array_like or boolean

desitarget.streams.utilities.sphere_rotate(ra, dec, rapol, decpol, ra0, revert=False)

Rotate ra, dec to a new spherical coordinate system.

Parameters:

• ra (ndarray or float) – Right Ascension in DEGREES.

• dec (ndarray or float) – Declination in DEGREES.

• rapol (float) – Pole of the new coordinate system in DEGREES.

• decpol (float) – Pole of the new coordinate system in DEGREES.

• ra0 (float) – Zero latitude of the new coordinate system in DEGREES.

• revert (bool, optional, defaults to False) – Reverse the rotation.

Returns:

A tuple of the the new RA, Dec values in DEGREES. If ra, dec are passed as arrays this will be a tuple of RA, Dec arrays.

Return type:

tuple

desitarget.streams.utilities.stream_distance(fi1, stream_name, stream)

The distance to members of a stellar stream.

Parameters:

• fi1 (ndarray or float) – Phi1 stream coordinate of possible targets, derived from RA.

• stream_name (str) – Name of a stream, e.g. “GD1”.

Returns:

The distance to the passed members of the stream.

Return type:

array_like or float

Notes

• Output type is the same as that of the passed fi1.

desitarget.streams.utilities.targmwext_resolve(targmwext_name, mws_target, ibright_pm1, ibright_pm2, ibright_pm3, ipm_only, ifaint_cmd, ifiller)

Resolve ambiguity with target subclass bits in the mwstarget mask using TARGMWEXT_RANK.

Parameters:

• targmwext_name (ndarray or float CMR FIX THIS IS A STRING) – Name of the stream or dwarf galaxy being selected

• mws_target (ndarray or float) – Numpy 1d array of target bits as set by PREVIOUS selections

• ibright_pm1 (array_like or boolean) – Numpy 1d array, True for objects that pass the bright_pm1 selection criteria

• ibright_pm2 (array_like or boolean) – Numpy 1d array, True for objects that pass the bright_pm2 selection criteria

• ibright_pm3 (array_like or boolean) – Numpy 1d array, True for objects that pass the bright_pm3 selection criteria

• ipm_only (array_like or boolean) – Numpy 1d array, True for objects that pass pm_only. Use for dwarfs but not streams

• ifaint_cmd (array_like or boolean) – Numpy 1d array, True for objects that pass faint_cmd. Use for streams but not dwarfs

• ifiller (array_like or boolean) – Numpy 1d array, True for objects that pass the filler selection criteria.

Returns:

• array_like – True if the object is a “BRIGHT_PM1” target and has priorty for duplicates

• array_like – True if the object is a “BRIGHT_PM2” target and has priorty for duplicates

• array_like – True if the object is a “BRIGHT_PM3” target and has priorty for duplicates

• array_like – True if the object is a “PM_ONLY” target and has priorty for duplicates

• array_like – True if the object is a “FAINT_CMD” target and has priorty for duplicates

• array_like – True if the object is a “FILLER” target and has priorty for duplicates

Notes

• See ../data/targetmask.yaml for the definition of the target bits and targmwext_priority.

• Smaller numbers are higher priority.

• Streams and dwarfs are selected in rank order and targets selected for lower ranking streams that are also selected in higher ranking dwarfs are only selected if their target subclass outranks the target subclass they were selected as for the higher ranking object. All dwarfs outrank streams. GD1 is the highest ranking stream, Orphan the second. Ranking of subtarget classes: bright_pm1, bright_pm2, bright_pm3, pm_only, faint_cmd, filler We make assumptions, which avoid the brute-force implementation of these priorities: * brightpm[123] never overlap in magnitude, so an object can’t be, e.g., pm1 and pm2 in different stream/dwarfs * pm_only can only overlap with brightpm[12] * faint_cmd and filler can only overlap with each other and bright_pm3

  The bright_pm1, bright_pm2 and bright_pm3 and pm_only outrank faint_cmd and filler. The only overlaps possible and their relative rankings are: 1) bright_pm3 outranks faint_cmd and filler. bright_pm1 and bright_pm2 are too bright to overlap with either of the faint selections. 2) faint_cmd outranks filler. 3) pm_only can only overlap bright_pm1 and bright_pm2 (and it is only used for dwarfs)

  Note that the magnitude ranges of bright_pm[123] are always the same so that, e.g., bright_pm1 and bright_pm2 can neve be set for the same object. See <insert pointer to Nathan’s document>.

desitarget.streams.utilities.torect(ra, dec)

Convert equatorial coordinates to Cartesian coordinates.

Parameters:

• ra (ndarray or float) – Right Ascension in DEGREES.

• dec (ndarray or float) – Declination in DEGREES.

Returns:

A tuple of the x, y, z converted values. If ra, dec are passed as arrays this will be a tuple of x, y, z, arrays.

Return type:

tuple

Get what subpriority was used by fiberassign

desitarget.subpriority.get_fiberassign_subpriorities(fiberassignfiles)

Return table of TARGETID, SUBPRIORITY used in input fiberassign files

Parameters:

fiberassignfiles – list of input fiberassign files

Returns: dict[dark|bright|sky] = ndarray with columns TARGETID, SUBPRIORITY for targets matching that observing condition (or sky targets)

desitarget.subpriority.override_subpriority(targets, override)

Override SUBPRIORITY column in targets for those in override table

Parameters:

• targets – table with columns TARGETID and SUBPRIORITY

• override – table with columns TARGETID and SUBPRIORITY

Returns:

indices of targets table rows that were changed

Modifies targets table in-place without copying memory. Rows in targets that aren’t in override are unchanged. Rows in override that aren’t in targets are ignored.

desitarget.sv1.sv1_cuts

Target Selection for DESI Survey Validation derived from the SV wiki.

A collection of helpful (static) methods to check whether an object’s flux passes a given selection criterion (e.g. LRG, ELG or QSO).

desitarget.sv1.sv1_cuts.isBACKUP(ra=None, dec=None, gaiagmag=None, primary=None)

BACKUP targets based on Gaia magnitudes.

Parameters:

• ra (array_like or None) – Right Ascension and Declination in degrees.

• dec (array_like or None) – Right Ascension and Declination in degrees.

• gaiagmag (array_like or None) – Gaia-based g MAGNITUDE (not Galactic-extinction-corrected). (same units as the Gaia data model).

• primary (array_like or None) – True for objects that should be passed through the selection.

Returns:

• array_like – True if and only if the object is a bright “BACKUP” target.

• array_like – True if and only if the object is a faint “BACKUP” target.

• array_like – True if and only if the object is a very faint “BACKUP” target.

Notes

• Current version (10/24/19) is version 114 on the SV wiki.

desitarget.sv1.sv1_cuts.isBGS(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, rfiberflux=None, gnobs=None, rnobs=None, znobs=None, gfracmasked=None, rfracmasked=None, zfracmasked=None, gfracflux=None, rfracflux=None, zfracflux=None, gfracin=None, rfracin=None, zfracin=None, gfluxivar=None, rfluxivar=None, zfluxivar=None, maskbits=None, Grr=None, w1snr=None, gaiagmag=None, objtype=None, primary=None, south=True, targtype=None)

Definition of BGS target classes. Returns a boolean array.

Parameters:

• south (boolean, defaults to True) – Use cuts appropriate to the Northern imaging surveys (BASS/MzLS) if south=False, otherwise use cuts appropriate to the Southern imaging survey (DECaLS).

• targtype (str, optional, defaults to faint) – Pass bright to use colors appropriate to the BGS_BRIGHT selection or faint to use colors appropriate to the BGS_FAINT selection or faint_ext to use colors appropriate to the BGS_FAINT_EXTENDED selection or lowq to use colors appropriate to the BGS_LOW_QUALITY selection or fibmag to use colors appropriate to the BGS_FIBER_MAGNITUDE selection.

Returns:

True if and only if the object is a BGS target of type targtype.

Return type:

array_like

Notes

• Current version (10/14/19) is version 105 on the SV wiki.

• See set_target_bits() for other parameters.

desitarget.sv1.sv1_cuts.isBGS_colors(rflux=None, rfiberflux=None, south=True, targtype=None, primary=None)

Standard set of masking cuts used by all BGS target selection classes (see, e.g., isBGS() for parameters).

desitarget.sv1.sv1_cuts.isELG(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, gsnr=None, rsnr=None, zsnr=None, gfiberflux=None, gnobs=None, rnobs=None, znobs=None, maskbits=None, south=True, primary=None)

Definition of ELG target classes. Returns a boolean array.

Parameters:

south (boolean, defaults to True) – If False, use cuts for the Northern imaging (BASS/MzLS) otherwise use cuts for the Southern imaging survey (DECaLS).

Returns:

True if and only if the object is an ELG target.

Return type:

array_like

Notes

• Current version (12/09/20) is version 145 on the SV wiki.

• See set_target_bits() for other parameters.

desitarget.sv1.sv1_cuts.isELG_colors(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, gfiberflux=None, primary=None, south=True)

Color cuts for ELG target selection classes (see, e.g., desitarget.cuts.set_target_bits() for parameters).

desitarget.sv1.sv1_cuts.isGAIA_STD(ra=None, dec=None, galb=None, gaiaaen=None, pmra=None, pmdec=None, parallax=None, parallaxovererror=None, ebv=None, gaiabprpfactor=None, gaiasigma5dmax=None, gaiagmag=None, gaiabmag=None, gaiarmag=None, gaiadupsource=None, gaiaparamssolved=None, primary=None, test=False, nside=2)

Standards based solely on Gaia data.

Parameters:

• ebv (array_like) – E(B-V) values from the SFD dust maps.

• test (bool, optional, defaults to False) – If True, then we’re running unit tests and don’t have to find and read every possible Gaia file.

• nside (int, optional, defaults to 2) – (NESTED) HEALPix nside, if targets are being parallelized. The default of 2 should be benign for serial processing.

Returns:

• array_like – True if the object is a bright “GAIA_STD_FAINT” target.

• array_like – True if the object is a faint “GAIA_STD_BRIGHT” target.

• array_like – True if the object is a white dwarf “GAIA_STD_WD” target.

Notes

• See set_target_bits() for other parameters.

• Current version (01/28/21) is version 154 on the SV wiki.

desitarget.sv1.sv1_cuts.isLRG(gflux=None, rflux=None, zflux=None, w1flux=None, zfiberflux=None, rfluxivar=None, zfluxivar=None, w1fluxivar=None, gnobs=None, rnobs=None, znobs=None, maskbits=None, primary=None, south=True)

Target Definition of LRG. Returns a boolean array.

Parameters:

south (boolean, defaults to True) – Use cuts appropriate to the Northern imaging surveys (BASS/MzLS) if south=False, otherwise use cuts appropriate to the Southern imaging survey (DECaLS).

Returns:

• array_like – True if and only if the object is an LRG target.

• array_like – True for a 4 PASS nominal optical + nominal IR LRG.

• array_like – True for a 4 PASS object in the LRG SV superset.

• array_like – True for an 8 PASS nominal optical + nominal IR LRG.

• array_like – True for an 8 PASS object in the LRG SV superset.

Notes

• Current version (12/07/2020) is version 140 on the SV wiki.

• See set_target_bits() for other parameters.

desitarget.sv1.sv1_cuts.isLRG_colors(gflux=None, rflux=None, zflux=None, w1flux=None, zfiberflux=None, south=True, primary=None)

See isLRG() for details.

desitarget.sv1.sv1_cuts.isMWS_WD(primary=None, gaia=None, galb=None, astrometricexcessnoise=None, pmra=None, pmdec=None, parallax=None, parallaxovererror=None, photbprpexcessfactor=None, astrometricsigma5dmax=None, gaiagmag=None, gaiabmag=None, gaiarmag=None)

Set bits for WHITE DWARF Milky Way Survey targets.

:param see set_target_bits() for parameters.:

Returns:

mask – True if and only if the object is a MWS-WD target.

Return type:

array_like.

Notes

• Current version (08/01/18) is version 121 on the wiki.

desitarget.sv1.sv1_cuts.isMWS_bhb(primary=None, objtype=None, gaia=None, gaiaaen=None, gaiadupsource=None, gaiagmag=None, gflux=None, rflux=None, zflux=None, w1flux=None, w1snr=None, gnobs=None, rnobs=None, znobs=None, gfracmasked=None, rfracmasked=None, zfracmasked=None, parallax=None, parallaxerr=None)

Set bits for BHB Milky Way Survey targets (SV selection)

:param see set_target_bits() for other parameters.:

Returns:

mask – True if and only if the object is a MWS-BHB target.

Return type:

array_like.

Notes

• Criteria supplied by Sergey Koposov

• gflux, rflux, zflux, w1flux have been corrected for extinction (unlike other MWS selections, which use obs_flux).

• Current version (12/21/20) is version 149 on the SV wiki.

desitarget.sv1.sv1_cuts.isMWS_main_sv(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, gnobs=None, rnobs=None, gfracmasked=None, rfracmasked=None, pmra=None, pmdec=None, parallax=None, obs_rflux=None, objtype=None, gaia=None, gaiagmag=None, gaiabmag=None, gaiarmag=None, gaiaaen=None, gaiadupsource=None, primary=None, south=True)

Set bits for main MWS SV targets.

:param see set_target_bits() for parameters.:

Returns:

array_like.

True if and only if the object is a MWS_MAIN_BROAD target.

mask2array_like.

True if and only if the object is a MWS_MAIN_FAINT target.

Return type:

mask1

Notes

• as of 26/7/19, based on version 79 on the wiki.

• for SV, no astrometric selection or colour separation

desitarget.sv1.sv1_cuts.isMWS_nearby(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, objtype=None, gaia=None, primary=None, pmra=None, pmdec=None, parallax=None, parallaxerr=None, obs_rflux=None, gaiagmag=None, gaiabmag=None, gaiarmag=None)

Set bits for NEARBY Milky Way Survey targets.

:param see set_target_bits() for parameters.:

Returns:

mask – True if and only if the object is a MWS-NEARBY target.

Return type:

array_like.

Notes

• Current version (09/20/18) is version 129 on the wiki.

desitarget.sv1.sv1_cuts.isQSO_color_high_z(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, south=True)

Color cut to select Highz QSO (z>~2.)

desitarget.sv1.sv1_cuts.isQSO_colors(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, primary=None, south=True)

Test if sources have quasar-like colors in a color box. (see, e.g., isQSO_cuts()).

desitarget.sv1.sv1_cuts.isQSO_cuts(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, w1snr=None, w2snr=None, dchisq=None, maskbits=None, objtype=None, gnobs=None, rnobs=None, znobs=None, primary=None, south=True)

Definition of QSO target classes from color cuts. Returns a boolean array.

Parameters:

south (boolean, defaults to True) – Use cuts appropriate to the Northern imaging surveys (BASS/MzLS) if south=False, otherwise use cuts appropriate to the Southern imaging survey (DECaLS).

Returns:

True for objects that pass the quasar color/morphology/logic cuts.

Return type:

array_like

Notes

• Current version (09/25/19) is version 100 on the SV wiki.

• See set_target_bits() for other parameters.

desitarget.sv1.sv1_cuts.isQSO_highz_faint(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, objtype=None, release=None, dchisq=None, gnobs=None, rnobs=None, znobs=None, ra=None, dec=None, maskbits=None, primary=None, south=True)

Definition of QSO target for highz (z>2.0) faint QSOs. Returns a boolean array.

Parameters:

south (boolean, defaults to True) – Use cuts appropriate to the Northern imaging surveys (BASS/MzLS) if south=False, otherwise use cuts appropriate to the Southern imaging survey (DECaLS).

Returns:

True for objects that pass the quasar color/morphology/logic cuts.

Return type:

array_like

Notes

• Current version (09/25/19) is version 100 on the SV wiki.

• See set_target_bits() for other parameters.

desitarget.sv1.sv1_cuts.isQSO_randomforest(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, objtype=None, release=None, dchisq=None, maskbits=None, gnobs=None, rnobs=None, znobs=None, ra=None, dec=None, primary=None, south=True)

Definition of QSO target class using random forest. Returns a boolean array.

Parameters:

south (boolean, defaults to True) – Use cuts appropriate to the Northern imaging surveys (BASS/MzLS) if south=False, otherwise use cuts appropriate to the Southern imaging survey (DECaLS).

Returns:

True for objects that pass the quasar color/morphology/logic cuts.

Return type:

array_like

Notes

• Current version (09/25/19) is version 100 on the SV wiki.

• See set_target_bits() for other parameters.

desitarget.sv1.sv1_cuts.isQSOz5_colors(gflux=None, rflux=None, zflux=None, gsnr=None, rsnr=None, zsnr=None, w1flux=None, w2flux=None, primary=None, south=True)

Color cut to select z~5 quasar targets. (See isQSOz5_cuts()).

desitarget.sv1.sv1_cuts.isQSOz5_cuts(gflux=None, rflux=None, zflux=None, gsnr=None, rsnr=None, zsnr=None, gnobs=None, rnobs=None, znobs=None, w1flux=None, w2flux=None, w1snr=None, w2snr=None, dchisq=None, maskbits=None, objtype=None, primary=None, south=True)

Definition of z~5 QSO targets from color cuts. Returns a boolean array.

Parameters:

south (boolean, defaults to True) – Use cuts appropriate to the Northern imaging surveys (BASS/MzLS) if south=False, otherwise use cuts appropriate to the Southern imaging survey (DECaLS).

Returns:

True for objects that pass the quasar color/morphology/logic cuts.

Return type:

array_like

Notes

• Current version (03/11/20) is version 126 on the SV wiki.

• See set_target_bits() for other parameters.

desitarget.sv1.sv1_cuts.isSTD(gflux=None, rflux=None, zflux=None, primary=None, gfracflux=None, rfracflux=None, zfracflux=None, gfracmasked=None, rfracmasked=None, zfracmasked=None, gnobs=None, rnobs=None, znobs=None, gfluxivar=None, rfluxivar=None, zfluxivar=None, objtype=None, gaia=None, astrometricexcessnoise=None, paramssolved=None, pmra=None, pmdec=None, parallax=None, dupsource=None, gaiagmag=None, gaiabmag=None, gaiarmag=None, bright=False)

Select STD targets using color cuts and photometric quality cuts.

Parameters:

bright (boolean, defaults to False) – if True apply magnitude cuts for “bright” conditions; otherwise, choose “normal” brightness standards. Cut is performed on gaiagmag.

Returns:

True if and only if the object is a STD star.

Return type:

array_like

Notes

• Current version (11/05/18) is version 24 on the SV wiki.

• See set_target_bits() for other parameters.

desitarget.sv1.sv1_cuts.isSTD_colors(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, primary=None)

Select STD stars based on Legacy Surveys color cuts. Returns a boolean array. see isSTD() for other details.

desitarget.sv1.sv1_cuts.isSTD_gaia(primary=None, gaia=None, astrometricexcessnoise=None, pmra=None, pmdec=None, parallax=None, dupsource=None, paramssolved=None, gaiagmag=None, gaiabmag=None, gaiarmag=None)

Gaia quality cuts used to define STD star targets see isSTD() for other details.

desitarget.sv1.sv1_cuts.notinBGS_mask(gflux=None, rflux=None, zflux=None, gnobs=None, rnobs=None, znobs=None, primary=None, gfracmasked=None, rfracmasked=None, zfracmasked=None, gfracflux=None, rfracflux=None, zfracflux=None, gfracin=None, rfracin=None, zfracin=None, w1snr=None, gfluxivar=None, rfluxivar=None, zfluxivar=None, Grr=None, gaiagmag=None, maskbits=None, objtype=None, targtype=None)

Standard set of masking cuts used by all BGS target selection classes (see, e.g., isBGS_faint() for parameters).

desitarget.sv1.sv1_cuts.notinELG_mask(maskbits=None, gsnr=None, rsnr=None, zsnr=None, gnobs=None, rnobs=None, znobs=None, primary=None)

Standard set of masking cuts used by all ELG target selection classes. (see set_target_bits() for parameters).

desitarget.sv1.sv1_cuts.notinLRG_mask(primary=None, rflux=None, zflux=None, w1flux=None, zfiberflux=None, gnobs=None, rnobs=None, znobs=None, rfluxivar=None, zfluxivar=None, w1fluxivar=None, maskbits=None)

See isLRG() for details.

Returns:

True if and only if the object is NOT masked for poor quality.

Return type:

array_like

desitarget.sv1.sv1_cuts.notinMWS_main_sv_mask(gaia=None, gfracmasked=None, gnobs=None, gflux=None, rfracmasked=None, rnobs=None, rflux=None, gaiadupsource=None, primary=None)

Standard set of masking-based cuts used by MWS target selection classes (see, e.g., isMWS_main() for parameters).

desitarget.sv1.sv1_cuts.set_target_bits(photsys_north, photsys_south, obs_rflux, gflux, rflux, zflux, w1flux, w2flux, gfiberflux, rfiberflux, zfiberflux, gfibertotflux, rfibertotflux, zfibertotflux, objtype, release, ra, dec, gfluxivar, rfluxivar, zfluxivar, w1fluxivar, gnobs, rnobs, znobs, gfracflux, rfracflux, zfracflux, gfracmasked, rfracmasked, zfracmasked, gfracin, rfracin, zfracin, gallmask, rallmask, zallmask, gsnr, rsnr, zsnr, w1snr, w2snr, deltaChi2, dchisq, gaia, pmra, pmdec, parallax, parallaxovererror, parallaxerr, gaiagmag, gaiabmag, gaiarmag, gaiaaen, gaiadupsource, gaiaparamssolved, gaiabprpfactor, gaiasigma5dmax, galb, tcnames, qso_optical_cuts, qso_selection, maskbits, Grr, refcat, primary, resolvetargs=True)

Perform target selection on parameters, return target mask arrays.

Returns:

(desi_target, bgs_target, mws_target) where each element is an ndarray of target selection bitmask flags for each object.

Return type:

ndarray

Notes

• Units for Gaia quantities are the same as the Gaia data model.

• See set_target_bits() for parameters.

desitarget.sv1.sv1_targetmask

This looks more like a script than an actual module.

desitarget.sv2.sv2_cuts

Target Selection for DESI Survey Validation derived from the SV2 wiki.

A collection of helpful (static) methods to check whether an object’s flux passes a given selection criterion (e.g. LRG, ELG or QSO).

desitarget.sv2.sv2_cuts._check_BGS_targtype(targtype)

Fail if targtype is not one of the strings ‘bright’, ‘faint’ or ‘wise’.

desitarget.sv2.sv2_cuts._is_row(table)

Return True/False if this is a row of a table instead of a full table.

supports numpy.ndarray, astropy.io.fits.FITS_rec, and astropy.table.Table

desitarget.sv2.sv2_cuts._isonnorthphotsys(photsys)

If the object is from the northen photometric system

desitarget.sv2.sv2_cuts._psflike(psftype)

If the object is PSF

desitarget.sv2.sv2_cuts.isBACKUP(ra=None, dec=None, gaiagmag=None, primary=None)

BACKUP targets based on Gaia magnitudes.

Parameters:

• ra (array_like or None) – Right Ascension and Declination in degrees.

• dec (array_like or None) – Right Ascension and Declination in degrees.

• gaiagmag (array_like or None) – Gaia-based g MAGNITUDE (not Galactic-extinction-corrected). (same units as the Gaia data model).

• primary (array_like or None) – True for objects that should be passed through the selection.

Returns:

• array_like – True if and only if the object is a bright “BACKUP” target.

• array_like – True if and only if the object is a faint “BACKUP” target.

• array_like – True if and only if the object is a very faint “BACKUP” target.

Notes

• Current version (03/09/21) is version 1 on the SV2 wiki.

desitarget.sv2.sv2_cuts.isBGS(rfiberflux=None, gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, gnobs=None, rnobs=None, znobs=None, gfracmasked=None, rfracmasked=None, zfracmasked=None, gfracflux=None, rfracflux=None, zfracflux=None, gfracin=None, rfracin=None, zfracin=None, gfluxivar=None, rfluxivar=None, zfluxivar=None, maskbits=None, Grr=None, refcat=None, w1snr=None, gaiagmag=None, objtype=None, primary=None, south=True, targtype=None)

Definition of BGS target classes. Returns a boolean array.

Parameters:

targtype (str, optional, defaults to faint) – Pass bright to use colors appropriate to the BGS_BRIGHT selection or faint to use colors appropriate to the BGS_FAINT selection or wise to use colors appropriate to the BGS_WISE selection.

Returns:

True if and only if the object is a BGS target of type targtype.

Return type:

array_like

Notes

• Current version (03/09/21) is version 1 on the SV2 wiki.

• See set_target_bits() for other parameters.

desitarget.sv2.sv2_cuts.isBGS_colors(rfiberflux=None, gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, south=True, targtype=None, primary=None)

Standard set of color-based cuts used by all BGS target selection classes (see, e.g., isBGS() for parameters).

desitarget.sv2.sv2_cuts.isBGS_lslga(gflux=None, rflux=None, zflux=None, w1flux=None, refcat=None, maskbits=None, south=True, targtype=None)

Module to recover the LSLGA objects in all BGS target selection classes (see, e.g., isBGS() for parameters).

desitarget.sv2.sv2_cuts.isELG(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, gfiberflux=None, gsnr=None, rsnr=None, zsnr=None, gnobs=None, rnobs=None, znobs=None, maskbits=None, south=True, primary=None)

Definition of ELG target classes. Returns a boolean array. (see set_target_bits() for parameters).

Notes: - Current version (03/16/21) is version 5 on the SV2 wiki.

desitarget.sv2.sv2_cuts.isELG_colors(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, gfiberflux=None, south=True, primary=None)

Color cuts for ELG target selection classes (see, e.g., set_target_bits() for parameters).

desitarget.sv2.sv2_cuts.isGAIA_STD(ra=None, dec=None, galb=None, gaiaaen=None, pmra=None, pmdec=None, parallax=None, parallaxovererror=None, ebv=None, gaiabprpfactor=None, gaiasigma5dmax=None, gaiagmag=None, gaiabmag=None, gaiarmag=None, gaiadupsource=None, gaiaparamssolved=None, primary=None, test=False, nside=2)

Standards based solely on Gaia data.

Parameters:

• ebv (array_like) – E(B-V) values from the SFD dust maps.

• test (bool, optional, defaults to False) – If True, then we’re running unit tests and don’t have to find and read every possible Gaia file.

• nside (int, optional, defaults to 2) – (NESTED) HEALPix nside, if targets are being parallelized. The default of 2 should be benign for serial processing.

Returns:

• array_like – True if the object is a bright “GAIA_STD_FAINT” target.

• array_like – True if the object is a faint “GAIA_STD_BRIGHT” target.

• array_like – True if the object is a white dwarf “GAIA_STD_WD” target.

Notes

• Current version (03/09/21) is version 1 on the SV2 wiki.

• See set_target_bits() for other parameters.

desitarget.sv2.sv2_cuts.isLRG(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, zfiberflux=None, rfluxivar=None, zfluxivar=None, w1fluxivar=None, gaiagmag=None, gnobs=None, rnobs=None, znobs=None, maskbits=None, primary=None, south=True)

Parameters:

south (boolean, defaults to True) – Use cuts appropriate to the Northern imaging surveys (BASS/MzLS) if south=False, otherwise use cuts appropriate to the Southern imaging survey (DECaLS).

Returns:

True if and only if the object is an LRG target.

Return type:

array_like

Notes

• Current version (03/09/21) is version 1 on the SV2 wiki.

• See set_target_bits() for other parameters.

desitarget.sv2.sv2_cuts.isLRG_colors(gflux=None, rflux=None, zflux=None, w1flux=None, zfiberflux=None, ggood=None, w2flux=None, primary=None, south=True)

(see, e.g., isLRG()).

Notes

• the ggood and w2flux inputs are an attempt to maintain backwards-compatibility with the mocks.

desitarget.sv2.sv2_cuts.isMWSSTAR_colors(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, primary=None, south=True)

A reasonable range of g-r for MWS targets. Returns a boolean array.

Parameters:

• gflux – array_like The flux in nano-maggies of g, r, z, w1, and w2 bands.

• rflux – array_like The flux in nano-maggies of g, r, z, w1, and w2 bands.

• zflux – array_like The flux in nano-maggies of g, r, z, w1, and w2 bands.

• w1flux – array_like The flux in nano-maggies of g, r, z, w1, and w2 bands.

• w2flux – array_like The flux in nano-maggies of g, r, z, w1, and w2 bands.

• primary – array_like or None Set to True for objects to initially consider as possible targets. Defaults to everything being True.

• south – boolean, defaults to True Use color-cuts based on photometry from the “south” (DECaLS) as opposed to the “north” (MzLS+BASS).

Returns:

boolean array, True if the object has colors like an old stellar population, which is what we expect for the main MWS sample

Return type:

mask

Notes

The full MWS target selection also includes PSF-like and fracflux cuts and will include Gaia information; this function is only to enforce a reasonable range of color/TEFF when simulating data.

desitarget.sv2.sv2_cuts.isMWS_WD(primary=None, gaia=None, galb=None, astrometricexcessnoise=None, pmra=None, pmdec=None, parallax=None, parallaxovererror=None, photbprpexcessfactor=None, astrometricsigma5dmax=None, gaiagmag=None, gaiabmag=None, gaiarmag=None, paramssolved=None)

Set bits for WHITE DWARF Milky Way Survey targets.

:param see set_target_bits() for parameters.:

Returns:

array_like.

True if and only if the object is a MWS-WD target.

Return type:

mask

Notes: - Current version (03/09/21) is version 1 on the SV2 wiki.

desitarget.sv2.sv2_cuts.isMWS_bhb(primary=None, objtype=None, gaia=None, gaiaaen=None, gaiadupsource=None, gaiagmag=None, gflux=None, rflux=None, zflux=None, w1flux=None, w1snr=None, maskbits=None, gnobs=None, rnobs=None, znobs=None, gfracmasked=None, rfracmasked=None, zfracmasked=None, parallax=None, parallaxerr=None)

Set bits for BHB Milky Way Survey targets

:param see set_target_bits() for other parameters.:

Returns:

mask – True if and only if the object is a MWS-BHB target.

Return type:

array_like.

Notes

• Criteria supplied by Sergey Koposov

• gflux, rflux, zflux, w1flux have been corrected for extinction (unlike other MWS selections, which use obs_flux).

• Current version (03/09/21) is version 1 on the SV2 wiki.

desitarget.sv2.sv2_cuts.isMWS_main(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, gnobs=None, rnobs=None, gfracmasked=None, rfracmasked=None, pmra=None, pmdec=None, parallax=None, parallaxerr=None, obs_rflux=None, objtype=None, gaia=None, gaiagmag=None, gaiabmag=None, gaiarmag=None, gaiaaen=None, gaiadupsource=None, paramssolved=None, primary=None, south=True, maskbits=None)

Set bits for main MWS targets.

:param see set_target_bits() for parameters.:

Returns:

array_like.

True if and only if the object is a MWS_BROAD target.

mask2array_like.

True if and only if the object is a MWS_MAIN_RED target.

mask3array_like.

True if and only if the object is a MWS_MAIN_BLUE target.

Return type:

mask1

Notes: - Current version (03/09/21) is version 1 on the SV2 wiki.

desitarget.sv2.sv2_cuts.isMWS_main_colors(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, pmra=None, pmdec=None, parallax=None, parallaxerr=None, obs_rflux=None, objtype=None, paramssolved=None, gaiagmag=None, gaiabmag=None, gaiarmag=None, gaiaaen=None, primary=None, south=True)

Set of color-based cuts used by MWS target selection classes (see, e.g., isMWS_main() for parameters).

desitarget.sv2.sv2_cuts.isMWS_nearby(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, objtype=None, gaia=None, primary=None, paramssolved=None, pmra=None, pmdec=None, parallax=None, parallaxerr=None, obs_rflux=None, gaiagmag=None, gaiabmag=None, gaiarmag=None)

Set bits for NEARBY Milky Way Survey targets.

:param see set_target_bits() for parameters.:

Returns:

array_like.

True if and only if the object is a MWS-NEARBY target.

Return type:

mask

Notes: - Current version (03/09/21) is version 1 on the SV2 wiki.

desitarget.sv2.sv2_cuts.isQSO_colors(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, optical=False, south=True)

Tests if sources have quasar-like colors in a color box. (see, e.g., isQSO_cuts()).

desitarget.sv2.sv2_cuts.isQSO_cuts(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, w1snr=None, w2snr=None, deltaChi2=None, maskbits=None, gnobs=None, rnobs=None, znobs=None, release=None, objtype=None, primary=None, optical=False, south=True)

Definition of QSO target classes from color cuts. Returns a boolean array.

Parameters:

• optical (boolean, defaults to False) – Apply just optical color-cuts.

• south (boolean, defaults to True) – Use cuts appropriate to the Northern imaging surveys (BASS/MzLS) if south=False, otherwise use cuts appropriate to the Southern imaging survey (DECaLS).

Returns:

True for objects that pass the quasar color/morphology/logic cuts.

Return type:

array_like

Notes

• Current version (03/09/21) is version 1 on the SV2 wiki.

• See set_target_bits() for other parameters.

desitarget.sv2.sv2_cuts.isQSO_randomforest(gflux=None, rflux=None, zflux=None, maskbits=None, w1flux=None, w2flux=None, objtype=None, release=None, gnobs=None, rnobs=None, znobs=None, deltaChi2=None, primary=None, ra=None, dec=None, south=True, return_probs=False)

Define QSO targets from a Random Forest. Returns a boolean array.

Parameters:

• south (boolean, defaults to True) – If False, shift photometry to the Northern (BASS/MzLS) imaging system.

• return_probs (boolean, defaults to False) – If True, return the QSO/high-z QSO probabilities in addition to the QSO target booleans. Only coded up for DR8 or later of the Legacy Surveys. Will return arrays of zeros for earlier DRs.

Returns:

• array_like – True for objects that are Random Forest quasar targets.

• array_like – True for objects that are high-z RF quasar targets.

• array_like – The (float) probability that a target is a quasar. Only returned if return_probs is True.

• array_like – The (float) probability that a target is a high-z quasar. Only returned if return_probs is True.

Notes

• Current version (03/16/21) is version 8 on the SV2 wiki.

• See set_target_bits() for other parameters.

desitarget.sv2.sv2_cuts.isSTD(gflux=None, rflux=None, zflux=None, primary=None, gfracflux=None, rfracflux=None, zfracflux=None, gfracmasked=None, rfracmasked=None, zfracmasked=None, gnobs=None, rnobs=None, znobs=None, gfluxivar=None, rfluxivar=None, zfluxivar=None, objtype=None, gaia=None, astrometricexcessnoise=None, paramssolved=None, pmra=None, pmdec=None, parallax=None, dupsource=None, gaiagmag=None, gaiabmag=None, gaiarmag=None, bright=False, usegaia=True, maskbits=None, south=True)

Select STD targets using color cuts and photometric quality cuts (PSF-like and fracflux). See isSTD_colors() for additional info.

Parameters:

• gflux – array_like The flux in nano-maggies of g, r, z bands.

• rflux – array_like The flux in nano-maggies of g, r, z bands.

• zflux – array_like The flux in nano-maggies of g, r, z bands.

• primary – array_like or None Set to True for objects to initially consider as possible targets. Defaults to everything being True.

• gfracflux – array_like Profile-weighted fraction of the flux from other sources divided by the total flux in g, r and z bands.

• rfracflux – array_like Profile-weighted fraction of the flux from other sources divided by the total flux in g, r and z bands.

• zfracflux – array_like Profile-weighted fraction of the flux from other sources divided by the total flux in g, r and z bands.

• gfracmasked – array_like Fraction of masked pixels in the g, r and z bands.

• rfracmasked – array_like Fraction of masked pixels in the g, r and z bands.

• zfracmasked – array_like Fraction of masked pixels in the g, r and z bands.

• gnobs – array_like The number of observations (in the central pixel) in g, r and z.

• rnobs – array_like The number of observations (in the central pixel) in g, r and z.

• znobs – array_like The number of observations (in the central pixel) in g, r and z.

• gfluxivar – array_like The flux inverse variances in g, r, and z bands.

• rfluxivar – array_like The flux inverse variances in g, r, and z bands.

• zfluxivar – array_like The flux inverse variances in g, r, and z bands.

• objtype – array_like or None The TYPE column of the catalogue to restrict to point sources.

• gaia – boolean array_like or None True if there is a match between this object in the Legacy Surveys and in Gaia.

• astrometricexcessnoise – array_like or None Excess noise of the source in Gaia.

• paramssolved – array_like or None How many parameters were solved for in Gaia.

• pmra – array_like or None Gaia-based proper motion in RA and Dec and parallax

• pmdec – array_like or None Gaia-based proper motion in RA and Dec and parallax

• parallax – array_like or None Gaia-based proper motion in RA and Dec and parallax

• dupsource – array_like or None Whether the source is a duplicate in Gaia.

• gaiagmag – array_like or None Gaia-based g-, b- and r-band MAGNITUDES.

• gaiabmag – array_like or None Gaia-based g-, b- and r-band MAGNITUDES.

• gaiarmag – array_like or None Gaia-based g-, b- and r-band MAGNITUDES.

• bright – boolean, defaults to False if True apply magnitude cuts for “bright” conditions; otherwise, choose “normal” brightness standards. Cut is performed on gaiagmag.

• usegaia – boolean, defaults to True if True then call isSTD_gaia() to set the logic cuts. If Gaia is not available (perhaps if you’re using mocks) then send False, in which case we use the LS r-band magnitude as a proxy for the Gaia G-band magnitude (ignoring—incorrectly—that we have already corrected for Galactic extinction.)

• south – boolean, defaults to True Use color-cuts based on photometry from the “south” (DECaLS) as opposed to the “north” (MzLS+BASS).

Returns:

boolean array, True if the object has colors like a STD star.

Return type:

mask

Notes: - Gaia-based quantities are as in the Gaia data model. - Current version (03/09/21) is version 1 on the SV2 wiki.

desitarget.sv2.sv2_cuts.isSTD_colors(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, primary=None, south=True)

Select STD stars based on Legacy Surveys color cuts. Returns a boolean array.

Parameters:

• gflux – array_like The flux in nano-maggies of g, r, z, w1, and w2 bands.

• rflux – array_like The flux in nano-maggies of g, r, z, w1, and w2 bands.

• zflux – array_like The flux in nano-maggies of g, r, z, w1, and w2 bands.

• w1flux – array_like The flux in nano-maggies of g, r, z, w1, and w2 bands.

• w2flux – array_like The flux in nano-maggies of g, r, z, w1, and w2 bands.

• primary – array_like or None Set to True for objects to initially consider as possible targets. Defaults to everything being True.

• south – boolean, defaults to True Use color-cuts based on photometry from the “south” (DECaLS) as opposed to the “north” (MzLS+BASS).

Returns:

boolean array, True if the object has colors like a STD star target

Return type:

mask

Notes

• Current version (03/09/21) is version 1 on the SV2 wiki.

desitarget.sv2.sv2_cuts.isSTD_gaia(primary=None, gaia=None, astrometricexcessnoise=None, pmra=None, pmdec=None, parallax=None, dupsource=None, paramssolved=None, gaiagmag=None, gaiabmag=None, gaiarmag=None)

Gaia quality cuts used to define STD star targets.

Parameters:

• primary – array_like or None Set to True for objects to initially consider as possible targets. Defaults to everything being True.

• gaia – boolean array_like or None True if there is a match between this object in the Legacy Surveys and in Gaia.

• astrometricexcessnoise – array_like or None Excess noise of the source in Gaia (as in the Gaia data model).

• pmra – array_like or None Gaia-based proper motion in RA and Dec and parallax (same units as the Gaia data model).

• pmdec – array_like or None Gaia-based proper motion in RA and Dec and parallax (same units as the Gaia data model).

• parallax – array_like or None Gaia-based proper motion in RA and Dec and parallax (same units as the Gaia data model).

• dupsource – array_like or None Whether the source is a duplicate in Gaia (as in the Gaia data model).

• paramssolved – array_like or None How many parameters were solved for in Gaia (as in the Gaia data model).

• gaiagmag – array_like or None Gaia-based g, b and r MAGNITUDES (not Galactic-extinction-corrected). (same units as the Gaia data model).

• gaiabmag – array_like or None Gaia-based g, b and r MAGNITUDES (not Galactic-extinction-corrected). (same units as the Gaia data model).

• gaiarmag – array_like or None Gaia-based g, b and r MAGNITUDES (not Galactic-extinction-corrected). (same units as the Gaia data model).

Returns:

boolean array, True if the object passes Gaia quality cuts.

Return type:

mask

Notes

• Current version (03/09/21) is version 1 on the SV2 wiki.

desitarget.sv2.sv2_cuts.notinBGS_mask(gnobs=None, rnobs=None, znobs=None, primary=None, gfracmasked=None, rfracmasked=None, zfracmasked=None, gfracflux=None, rfracflux=None, zfracflux=None, gfracin=None, rfracin=None, zfracin=None, w1snr=None, gfluxivar=None, rfluxivar=None, zfluxivar=None, Grr=None, gaiagmag=None, maskbits=None, targtype=None)

Standard set of masking cuts used by all BGS target selection classes (see, e.g., isBGS() for parameters).

desitarget.sv2.sv2_cuts.notinELG_mask(maskbits=None, gsnr=None, rsnr=None, zsnr=None, gnobs=None, rnobs=None, znobs=None, primary=None)

Standard set of masking cuts used by all ELG target selection classes. (see set_target_bits() for parameters).

desitarget.sv2.sv2_cuts.notinLRG_mask(primary=None, rflux=None, zflux=None, w1flux=None, zfiberflux=None, gnobs=None, rnobs=None, znobs=None, rfluxivar=None, zfluxivar=None, w1fluxivar=None, gaiagmag=None, maskbits=None)

See isLRG() for details.

Returns:

True if and only if the object is NOT masked for poor quality.

Return type:

array_like

desitarget.sv2.sv2_cuts.notinMWS_main_mask(gaia=None, gfracmasked=None, gnobs=None, gflux=None, rfracmasked=None, rnobs=None, rflux=None, maskbits=None, gaiadupsource=None, primary=None)

Standard set of masking-based cuts used by MWS target selection classes (see, e.g., isMWS_main() for parameters).

desitarget.sv2.sv2_cuts.set_target_bits(photsys_north, photsys_south, obs_rflux, gflux, rflux, zflux, w1flux, w2flux, gfiberflux, rfiberflux, zfiberflux, gfibertotflux, rfibertotflux, zfibertotflux, objtype, release, ra, dec, gfluxivar, rfluxivar, zfluxivar, w1fluxivar, gnobs, rnobs, znobs, gfracflux, rfracflux, zfracflux, gfracmasked, rfracmasked, zfracmasked, gfracin, rfracin, zfracin, gallmask, rallmask, zallmask, gsnr, rsnr, zsnr, w1snr, w2snr, deltaChi2, dchisq, gaia, pmra, pmdec, parallax, parallaxovererror, parallaxerr, gaiagmag, gaiabmag, gaiarmag, gaiaaen, gaiadupsource, gaiaparamssolved, gaiabprpfactor, gaiasigma5dmax, galb, tcnames, qso_optical_cuts, qso_selection, maskbits, Grr, refcat, primary, resolvetargs=True)

Perform target selection on parameters, return target mask arrays.

Parameters:

• photsys_north (ndarray) – True for objects that were drawn from northern (MzLS/BASS) or southern (DECaLS) imaging, respectively.

• photsys_south (ndarray) – True for objects that were drawn from northern (MzLS/BASS) or southern (DECaLS) imaging, respectively.

• obs_rflux (ndarray) – rflux but WITHOUT any Galactic extinction correction.

• gflux (ndarray) – The flux in nano-maggies of g, r, z, W1 and W2 bands. Corrected for Galactic extinction.

• rflux (ndarray) – The flux in nano-maggies of g, r, z, W1 and W2 bands. Corrected for Galactic extinction.

• zflux (ndarray) – The flux in nano-maggies of g, r, z, W1 and W2 bands. Corrected for Galactic extinction.

• w1flux (ndarray) – The flux in nano-maggies of g, r, z, W1 and W2 bands. Corrected for Galactic extinction.

• w2flux (ndarray) – The flux in nano-maggies of g, r, z, W1 and W2 bands. Corrected for Galactic extinction.

• gfiberflux (ndarray) – Predicted fiber flux from object in 1 arcsecond seeing in g/r/z. Corrected for Galactic extinction.

• rfiberflux (ndarray) – Predicted fiber flux from object in 1 arcsecond seeing in g/r/z. Corrected for Galactic extinction.

• zfiberflux (ndarray) – Predicted fiber flux from object in 1 arcsecond seeing in g/r/z. Corrected for Galactic extinction.

• gfibertotflux (ndarray) – Predicted fiber flux from ALL sources at object’s location in 1 arcsecond seeing in g/r/z. NOT corrected for Galactic extinction.

• rfibertotflux (ndarray) – Predicted fiber flux from ALL sources at object’s location in 1 arcsecond seeing in g/r/z. NOT corrected for Galactic extinction.

• zfibertotflux (ndarray) – Predicted fiber flux from ALL sources at object’s location in 1 arcsecond seeing in g/r/z. NOT corrected for Galactic extinction.

• objtype (ndarray) – The Legacy Surveys imaging TYPE and RELEASE columns.

• release (ndarray) – The Legacy Surveys imaging TYPE and RELEASE columns.

• gfluxivar (ndarray) – The flux inverse variances in g, r, z and W1 bands.

• rfluxivar (ndarray) – The flux inverse variances in g, r, z and W1 bands.

• zfluxivar (ndarray) – The flux inverse variances in g, r, z and W1 bands.

• w1fluxivar (ndarray) – The flux inverse variances in g, r, z and W1 bands.

• gnobs (ndarray) – The number of observations (in the central pixel) in g, r and z.

• rnobs (ndarray) – The number of observations (in the central pixel) in g, r and z.

• znobs (ndarray) – The number of observations (in the central pixel) in g, r and z.

• gfracflux (ndarray) – Profile-weighted fraction of the flux from other sources divided by the total flux in g, r and z bands.

• rfracflux (ndarray) – Profile-weighted fraction of the flux from other sources divided by the total flux in g, r and z bands.

• zfracflux (ndarray) – Profile-weighted fraction of the flux from other sources divided by the total flux in g, r and z bands.

• gfracmasked (ndarray) – Fraction of masked pixels in the g, r and z bands.

• rfracmasked (ndarray) – Fraction of masked pixels in the g, r and z bands.

• zfracmasked (ndarray) – Fraction of masked pixels in the g, r and z bands.

• gallmask (ndarray) – Bitwise mask set if the central pixel from all images satisfy each condition in g, r, z.

• rallmask (ndarray) – Bitwise mask set if the central pixel from all images satisfy each condition in g, r, z.

• zallmask (ndarray) – Bitwise mask set if the central pixel from all images satisfy each condition in g, r, z.

• gsnr (ndarray) – Signal-to-noise in g, r, z, W1 and W2 defined as the flux per band divided by sigma (flux x sqrt of the inverse variance).

• rsnr (ndarray) – Signal-to-noise in g, r, z, W1 and W2 defined as the flux per band divided by sigma (flux x sqrt of the inverse variance).

• zsnr (ndarray) – Signal-to-noise in g, r, z, W1 and W2 defined as the flux per band divided by sigma (flux x sqrt of the inverse variance).

• w1snr (ndarray) – Signal-to-noise in g, r, z, W1 and W2 defined as the flux per band divided by sigma (flux x sqrt of the inverse variance).

• w2snr (ndarray) – Signal-to-noise in g, r, z, W1 and W2 defined as the flux per band divided by sigma (flux x sqrt of the inverse variance).

• deltaChi2 (ndarray) – chi2 difference between PSF and SIMP, dchisq_PSF - dchisq_SIMP.

• dchisq (ndarray) – Difference in chi2 between successively more-complex model fits. Columns are model fits, in order, of PSF, REX, EXP, DEV, COMP.

• gaia (ndarray) – True if there is a match between this object in the Legacy Surveys and in Gaia.

• pmra (ndarray) – Gaia-based proper motion in RA and Dec, and parallax and error.

• pmdec (ndarray) – Gaia-based proper motion in RA and Dec, and parallax and error.

• parallax (ndarray) – Gaia-based proper motion in RA and Dec, and parallax and error.

• parallaxovererror (ndarray) – Gaia-based proper motion in RA and Dec, and parallax and error.

• gaiagmag (ndarray) – Gaia-based g-, b- and r-band MAGNITUDES.

• gaiabmag (ndarray) – Gaia-based g-, b- and r-band MAGNITUDES.

• gaiarmag (ndarray) – Gaia-based g-, b- and r-band MAGNITUDES.

• gaiaaen (ndarray) – Gaia-based measures of Astrometric Excess Noise, whether the source is a duplicate, and how many parameters were solved for.

• gaiadupsource (ndarray) – Gaia-based measures of Astrometric Excess Noise, whether the source is a duplicate, and how many parameters were solved for.

• gaiaparamssolved (ndarray) – Gaia-based measures of Astrometric Excess Noise, whether the source is a duplicate, and how many parameters were solved for.

• gaiabprpfactor (ndarray) – Gaia_based BP/RP excess factor and longest semi-major axis of 5-d error ellipsoid.

• gaiasigma5dmax (ndarray) – Gaia_based BP/RP excess factor and longest semi-major axis of 5-d error ellipsoid.

• galb (ndarray) – Galactic latitude (degrees).

• tcnames (list, defaults to running all target classes) – A list of strings, e.g. [‘QSO’,’LRG’]. If passed, process only only those specific target classes. A useful speed-up for tests. Options include [“ELG”, “QSO”, “LRG”, “MWS”, “BGS”, “STD”].

• qso_optical_cuts (boolean defaults to False) – Apply just optical color-cuts when selecting QSOs with qso_selection="colorcuts".

• qso_selection (str, optional, defaults to ‘randomforest’) – The algorithm to use for QSO selection; valid options are ‘colorcuts’ and ‘randomforest’

• maskbits (boolean array_like or None) – General Legacy Surveys mask bits.

• Grr (array_like or None) – Gaia G band magnitude minus observational r magnitude.

• primary (ndarray) – True for objects that should be considered when setting bits.

• survey (str, defaults to 'main') – Specifies which target masks yaml file and target selection cuts to use. Options are 'main' and 'svX’ (X is 1, 2, etc.) for the main survey and different iterations of SV, respectively.

• resolvetargs (boolean, optional, defaults to True) – If True, if only northern (southern) sources are passed then only apply the northern (southern) cuts to those sources.

• ra (ndarray) – The Ra, Dec position of objects

• dec (ndarray) – The Ra, Dec position of objects

Returns:

(desi_target, bgs_target, mws_target) where each element is an ndarray of target selection bitmask flags for each object.

Return type:

ndarray

Notes

• Gaia quantities have units as for the Gaia data model.

desitarget.sv2.sv2_cuts.shift_photo_north(gflux=None, rflux=None, zflux=None)

Convert fluxes in the northern (BASS/MzLS) to the southern (DECaLS) system.

Parameters:

• gflux (array_like or float) – The flux in nano-maggies of g, r, z bands.

• rflux (array_like or float) – The flux in nano-maggies of g, r, z bands.

• zflux (array_like or float) – The flux in nano-maggies of g, r, z bands.

Return type:

The equivalent fluxes shifted to the southern system.

Notes

• see also https://desi.lbl.gov/DocDB/cgi-bin/private/RetrieveFile?docid=3390;filename=Raichoor_DESI_05Dec2017.pdf;version=1

• Update for DR9 https://desi.lbl.gov/trac/attachment/wiki/TargetSelectionWG/TargetSelection/North_vs_South_dr9.png

desitarget.sv2.sv2_targetmask

This looks more like a script than an actual module.

desitarget.sv3.sv3_cuts

Target Selection for DESI Survey Validation derived from the SV3 wiki.

A collection of helpful (static) methods to check whether an object’s flux passes a given selection criterion (e.g. LRG, ELG or QSO).

desitarget.sv3.sv3_cuts.MWS_too_bright(gaiagmag=None, zfibertotflux=None)

Whether a target is too bright to include for MWS observations.

Parameters:

• gaiagmag (ndarray) – Gaia-based g-band MAGNITUDE.

• zfibertotflux (ndarray) – Predicted fiber flux from ALL sources at object’s location in 1 arcsecond seeing in z. NOT corrected for Galactic extinction.

Returns:

True if and only if the object is FAINTER than the MWS bright-cut limits.

Return type:

array_like

Notes

• Current version (04/02/21) is version 17 on the SV3 wiki.

desitarget.sv3.sv3_cuts._check_BGS_targtype(targtype)

Fail if targtype is not one of the strings ‘bright’, ‘faint’ or ‘wise’.

desitarget.sv3.sv3_cuts._is_row(table)

Return True/False if this is a row of a table instead of a full table.

supports numpy.ndarray, astropy.io.fits.FITS_rec, and astropy.table.Table

desitarget.sv3.sv3_cuts._isonnorthphotsys(photsys)

If the object is from the northen photometric system

desitarget.sv3.sv3_cuts._psflike(psftype)

If the object is PSF

desitarget.sv3.sv3_cuts.isBACKUP(ra=None, dec=None, gaiagmag=None, primary=None)

BACKUP targets based on Gaia magnitudes.

Parameters:

• ra (array_like or None) – Right Ascension and Declination in degrees.

• dec (array_like or None) – Right Ascension and Declination in degrees.

• gaiagmag (array_like or None) – Gaia-based g MAGNITUDE (not Galactic-extinction-corrected). (same units as the Gaia data model).

• primary (array_like or None) – True for objects that should be passed through the selection.

Returns:

• array_like – True if and only if the object is a bright “BACKUP” target.

• array_like – True if and only if the object is a faint “BACKUP” target.

• array_like – True if and only if the object is a very faint “BACKUP” target.

Notes

• Current version (03/20/21) is version 1 on the SV3 wiki.

desitarget.sv3.sv3_cuts.isBGS(rfiberflux=None, gflux=None, rflux=None, zflux=None, rfibertotflux=None, w1flux=None, w2flux=None, gnobs=None, rnobs=None, znobs=None, gfluxivar=None, rfluxivar=None, zfluxivar=None, maskbits=None, Grr=None, refcat=None, w1snr=None, w2snr=None, gaiagmag=None, objtype=None, primary=None, south=True, targtype=None)

Definition of BGS target classes. Returns a boolean array.

Parameters:

targtype (str, optional, defaults to faint) – Pass bright to use colors appropriate to the BGS_BRIGHT selection or faint to use colors appropriate to the BGS_FAINT selection or wise to use colors appropriate to the BGS_WISE selection.

Returns:

True if and only if the object is a BGS target of type targtype.

Return type:

array_like

Notes

• Current version (03/29/21) is version 13 on the SV3 wiki.

• See set_target_bits() for other parameters.

desitarget.sv3.sv3_cuts.isBGS_colors(rfiberflux=None, gflux=None, rflux=None, zflux=None, w1flux=None, rfibertotflux=None, maskbits=None, south=True, targtype=None, primary=None)

Standard set of color-based cuts used by all BGS target selection classes (see, e.g., isBGS() for parameters).

desitarget.sv3.sv3_cuts.isBGS_sga(gflux=None, rflux=None, zflux=None, w1flux=None, refcat=None, rfibertotflux=None, rfiberflux=None, maskbits=None, south=True, targtype=None)

Module to recover the SGA objects in all BGS target selection classes (see, e.g., isBGS() for parameters).

desitarget.sv3.sv3_cuts.isBGS_wise(rfiberflux=None, gflux=None, rflux=None, zflux=None, w1flux=None, rfibertotflux=None, w2flux=None, refcat=None, maskbits=None, w1snr=None, w2snr=None, Grr=None, gaiagmag=None, gfluxivar=None, rfluxivar=None, zfluxivar=None, gnobs=None, rnobs=None, znobs=None, south=True, targtype=None, objtype=None, primary=None)

Standard set of color-based cuts used by all BGS target selection classes (see, e.g., isBGS() for parameters).

desitarget.sv3.sv3_cuts.isELG(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, gfiberflux=None, gsnr=None, rsnr=None, zsnr=None, gnobs=None, rnobs=None, znobs=None, maskbits=None, south=True, primary=None)

Definition of ELG target classes. Returns a boolean array. (see set_target_bits() for parameters).

Notes: - Current version (03/27/21) is version 8 on the SV3 wiki.

desitarget.sv3.sv3_cuts.isELG_colors(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, gfiberflux=None, south=True, primary=None)

Color cuts for ELG target selection classes (see, e.g., set_target_bits() for parameters).

desitarget.sv3.sv3_cuts.isGAIA_STD(ra=None, dec=None, galb=None, gaiaaen=None, pmra=None, pmdec=None, parallax=None, parallaxovererror=None, ebv=None, gaiabprpfactor=None, gaiasigma5dmax=None, gaiagmag=None, gaiabmag=None, gaiarmag=None, gaiadupsource=None, gaiaparamssolved=None, primary=None, test=False, nside=2)

Standards based solely on Gaia data.

Parameters:

• ebv (array_like) – E(B-V) values from the SFD dust maps.

• test (bool, optional, defaults to False) – If True, then we’re running unit tests and don’t have to find and read every possible Gaia file.

• nside (int, optional, defaults to 2) – (NESTED) HEALPix nside, if targets are being parallelized. The default of 2 should be benign for serial processing.

Returns:

• array_like – True if the object is a bright “GAIA_STD_FAINT” target.

• array_like – True if the object is a faint “GAIA_STD_BRIGHT” target.

• array_like – True if the object is a white dwarf “GAIA_STD_WD” target.

Notes

• Current version (03/20/21) is version 1 on the SV3 wiki.

• See set_target_bits() for other parameters.

desitarget.sv3.sv3_cuts.isLRG(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, zfiberflux=None, rfluxivar=None, zfluxivar=None, w1fluxivar=None, gaiagmag=None, gnobs=None, rnobs=None, znobs=None, maskbits=None, zfibertotflux=None, primary=None, south=True)

Parameters:

south (boolean, defaults to True) – Use cuts appropriate to the Northern imaging surveys (BASS/MzLS) if south=False, otherwise use cuts appropriate to the Southern imaging survey (DECaLS).

Returns:

True if and only if the object is an LRG target.

Return type:

array_like

Notes

• Current version (03/31/21) is version 15 on the SV3 wiki.

• See set_target_bits() for other parameters.

desitarget.sv3.sv3_cuts.isLRG_colors(gflux=None, rflux=None, zflux=None, w1flux=None, zfiberflux=None, ggood=None, w2flux=None, primary=None, south=True)

(see, e.g., isLRG()).

Notes

• the ggood and w2flux inputs are an attempt to maintain backwards-compatibility with the mocks.

desitarget.sv3.sv3_cuts.isMWSSTAR_colors(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, primary=None, south=True)

A reasonable range of g-r for MWS targets. Returns a boolean array.

Parameters:

• gflux – array_like The flux in nano-maggies of g, r, z, w1, and w2 bands.

• rflux – array_like The flux in nano-maggies of g, r, z, w1, and w2 bands.

• zflux – array_like The flux in nano-maggies of g, r, z, w1, and w2 bands.

• w1flux – array_like The flux in nano-maggies of g, r, z, w1, and w2 bands.

• w2flux – array_like The flux in nano-maggies of g, r, z, w1, and w2 bands.

• primary – array_like or None Set to True for objects to initially consider as possible targets. Defaults to everything being True.

• south – boolean, defaults to True Use color-cuts based on photometry from the “south” (DECaLS) as opposed to the “north” (MzLS+BASS).

Returns:

boolean array, True if the object has colors like an old stellar population, which is what we expect for the main MWS sample

Return type:

mask

Notes

The full MWS target selection also includes PSF-like and fracflux cuts and will include Gaia information; this function is only to enforce a reasonable range of color/TEFF when simulating data.

desitarget.sv3.sv3_cuts.isMWS_WD(primary=None, gaia=None, galb=None, astrometricexcessnoise=None, pmra=None, pmdec=None, parallax=None, parallaxovererror=None, photbprpexcessfactor=None, astrometricsigma5dmax=None, gaiagmag=None, gaiabmag=None, gaiarmag=None, paramssolved=None)

Set bits for WHITE DWARF Milky Way Survey targets.

:param see set_target_bits() for parameters.:

Returns:

array_like.

True if and only if the object is a MWS-WD target.

Return type:

mask

Notes: - Current version (03/20/21) is version 1 on the SV3 wiki.

desitarget.sv3.sv3_cuts.isMWS_bhb(primary=None, objtype=None, gaia=None, gaiaaen=None, gaiadupsource=None, gaiagmag=None, gflux=None, rflux=None, zflux=None, w1flux=None, w1snr=None, maskbits=None, gnobs=None, rnobs=None, znobs=None, gfracmasked=None, rfracmasked=None, zfracmasked=None, parallax=None, parallaxerr=None)

Set bits for BHB Milky Way Survey targets

:param see set_target_bits() for other parameters.:

Returns:

mask – True if and only if the object is a MWS-BHB target.

Return type:

array_like.

Notes

• Criteria supplied by Sergey Koposov

• gflux, rflux, zflux, w1flux have been corrected for extinction (unlike other MWS selections, which use obs_flux).

• Current version (03/20/21) is version 1 on the SV3 wiki.

desitarget.sv3.sv3_cuts.isMWS_main(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, gnobs=None, rnobs=None, gfracmasked=None, rfracmasked=None, pmra=None, pmdec=None, parallax=None, parallaxerr=None, obs_rflux=None, objtype=None, gaia=None, gaiagmag=None, gaiabmag=None, gaiarmag=None, gaiaaen=None, gaiadupsource=None, paramssolved=None, primary=None, south=True, maskbits=None)

Set bits for main MWS targets.

:param see set_target_bits() for parameters.:

Returns:

array_like.

True if and only if the object is a MWS_BROAD target.

mask2array_like.

True if and only if the object is a MWS_MAIN_RED target.

mask3array_like.

True if and only if the object is a MWS_MAIN_BLUE target.

Return type:

mask1

Notes: - Current version (03/20/21) is version 1 on the SV3 wiki.

desitarget.sv3.sv3_cuts.isMWS_main_colors(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, pmra=None, pmdec=None, parallax=None, parallaxerr=None, obs_rflux=None, objtype=None, paramssolved=None, gaiagmag=None, gaiabmag=None, gaiarmag=None, gaiaaen=None, primary=None, south=True)

Set of color-based cuts used by MWS target selection classes (see, e.g., isMWS_main() for parameters).

desitarget.sv3.sv3_cuts.isMWS_nearby(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, objtype=None, gaia=None, primary=None, paramssolved=None, pmra=None, pmdec=None, parallax=None, parallaxerr=None, obs_rflux=None, gaiagmag=None, gaiabmag=None, gaiarmag=None)

Set bits for NEARBY Milky Way Survey targets.

:param see set_target_bits() for parameters.:

Returns:

array_like.

True if and only if the object is a MWS-NEARBY target.

Return type:

mask

Notes: - Current version (03/20/21) is version 1 on the SV3 wiki.

desitarget.sv3.sv3_cuts.isQSO_colors(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, optical=False, south=True)

Tests if sources have quasar-like colors in a color box. (see, e.g., isQSO_cuts()).

desitarget.sv3.sv3_cuts.isQSO_cuts(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, w1snr=None, w2snr=None, deltaChi2=None, maskbits=None, gnobs=None, rnobs=None, znobs=None, release=None, objtype=None, primary=None, optical=False, south=True)

Definition of QSO target classes from color cuts. Returns a boolean array.

Parameters:

• optical (boolean, defaults to False) – Apply just optical color-cuts.

• south (boolean, defaults to True) – Use cuts appropriate to the Northern imaging surveys (BASS/MzLS) if south=False, otherwise use cuts appropriate to the Southern imaging survey (DECaLS).

Returns:

True for objects that pass the quasar color/morphology/logic cuts.

Return type:

array_like

Notes

• Current version (03/20/21) is version 1 on the SV3 wiki.

• See set_target_bits() for other parameters.

desitarget.sv3.sv3_cuts.isQSO_randomforest(gflux=None, rflux=None, zflux=None, maskbits=None, w1flux=None, w2flux=None, objtype=None, release=None, gnobs=None, rnobs=None, znobs=None, deltaChi2=None, primary=None, ra=None, dec=None, south=True, return_probs=False)

Define QSO targets from a Random Forest. Returns a boolean array.

Parameters:

• south (boolean, defaults to True) – If False, shift photometry to the Northern (BASS/MzLS) imaging system.

• return_probs (boolean, defaults to False) – If True, return the QSO/high-z QSO probabilities in addition to the QSO target booleans. Only coded up for DR8 or later of the Legacy Surveys. Will return arrays of zeros for earlier DRs.

Returns:

• array_like – True for objects that are Random Forest quasar targets.

• array_like – True for objects that are high-z RF quasar targets.

• array_like – The (float) probability that a target is a quasar. Only returned if return_probs is True.

• array_like – The (float) probability that a target is a high-z quasar. Only returned if return_probs is True.

Notes

• Current version (03/27/21) is version 8 on the SV3 wiki.

• See set_target_bits() for other parameters.

desitarget.sv3.sv3_cuts.isSTD(gflux=None, rflux=None, zflux=None, primary=None, gfracflux=None, rfracflux=None, zfracflux=None, gfracmasked=None, rfracmasked=None, zfracmasked=None, gnobs=None, rnobs=None, znobs=None, gfluxivar=None, rfluxivar=None, zfluxivar=None, objtype=None, gaia=None, astrometricexcessnoise=None, paramssolved=None, pmra=None, pmdec=None, parallax=None, dupsource=None, gaiagmag=None, gaiabmag=None, gaiarmag=None, bright=False, usegaia=True, maskbits=None, south=True)

Select STD targets using color cuts and photometric quality cuts (PSF-like and fracflux). See isSTD_colors() for additional info.

Parameters:

• gflux – array_like The flux in nano-maggies of g, r, z bands.

• rflux – array_like The flux in nano-maggies of g, r, z bands.

• zflux – array_like The flux in nano-maggies of g, r, z bands.

• primary – array_like or None Set to True for objects to initially consider as possible targets. Defaults to everything being True.

• gfracflux – array_like Profile-weighted fraction of the flux from other sources divided by the total flux in g, r and z bands.

• rfracflux – array_like Profile-weighted fraction of the flux from other sources divided by the total flux in g, r and z bands.

• zfracflux – array_like Profile-weighted fraction of the flux from other sources divided by the total flux in g, r and z bands.

• gfracmasked – array_like Fraction of masked pixels in the g, r and z bands.

• rfracmasked – array_like Fraction of masked pixels in the g, r and z bands.

• zfracmasked – array_like Fraction of masked pixels in the g, r and z bands.

• gnobs – array_like The number of observations (in the central pixel) in g, r and z.

• rnobs – array_like The number of observations (in the central pixel) in g, r and z.

• znobs – array_like The number of observations (in the central pixel) in g, r and z.

• gfluxivar – array_like The flux inverse variances in g, r, and z bands.

• rfluxivar – array_like The flux inverse variances in g, r, and z bands.

• zfluxivar – array_like The flux inverse variances in g, r, and z bands.

• objtype – array_like or None The TYPE column of the catalogue to restrict to point sources.

• gaia – boolean array_like or None True if there is a match between this object in the Legacy Surveys and in Gaia.

• astrometricexcessnoise – array_like or None Excess noise of the source in Gaia.

• paramssolved – array_like or None How many parameters were solved for in Gaia.

• pmra – array_like or None Gaia-based proper motion in RA and Dec and parallax

• pmdec – array_like or None Gaia-based proper motion in RA and Dec and parallax

• parallax – array_like or None Gaia-based proper motion in RA and Dec and parallax

• dupsource – array_like or None Whether the source is a duplicate in Gaia.

• gaiagmag – array_like or None Gaia-based g-, b- and r-band MAGNITUDES.

• gaiabmag – array_like or None Gaia-based g-, b- and r-band MAGNITUDES.

• gaiarmag – array_like or None Gaia-based g-, b- and r-band MAGNITUDES.

• bright – boolean, defaults to False if True apply magnitude cuts for “bright” conditions; otherwise, choose “normal” brightness standards. Cut is performed on gaiagmag.

• usegaia – boolean, defaults to True if True then call isSTD_gaia() to set the logic cuts. If Gaia is not available (perhaps if you’re using mocks) then send False, in which case we use the LS r-band magnitude as a proxy for the Gaia G-band magnitude (ignoring—incorrectly—that we have already corrected for Galactic extinction.)

• south – boolean, defaults to True Use color-cuts based on photometry from the “south” (DECaLS) as opposed to the “north” (MzLS+BASS).

Returns:

boolean array, True if the object has colors like a STD star.

Return type:

mask

Notes: - Gaia-based quantities are as in the Gaia data model. - Current version (03/20/21) is version 1 on the SV3 wiki.

desitarget.sv3.sv3_cuts.isSTD_colors(gflux=None, rflux=None, zflux=None, w1flux=None, w2flux=None, primary=None, south=True)

Select STD stars based on Legacy Surveys color cuts. Returns a boolean array.

Parameters:

• gflux – array_like The flux in nano-maggies of g, r, z, w1, and w2 bands.

• rflux – array_like The flux in nano-maggies of g, r, z, w1, and w2 bands.

• zflux – array_like The flux in nano-maggies of g, r, z, w1, and w2 bands.

• w1flux – array_like The flux in nano-maggies of g, r, z, w1, and w2 bands.

• w2flux – array_like The flux in nano-maggies of g, r, z, w1, and w2 bands.

• primary – array_like or None Set to True for objects to initially consider as possible targets. Defaults to everything being True.

• south – boolean, defaults to True Use color-cuts based on photometry from the “south” (DECaLS) as opposed to the “north” (MzLS+BASS).

Returns:

boolean array, True if the object has colors like a STD star target

Return type:

mask

Notes: - Current version (03/20/21) is version 1 on the SV3 wiki.

desitarget.sv3.sv3_cuts.isSTD_gaia(primary=None, gaia=None, astrometricexcessnoise=None, pmra=None, pmdec=None, parallax=None, dupsource=None, paramssolved=None, gaiagmag=None, gaiabmag=None, gaiarmag=None)

Gaia quality cuts used to define STD star targets.

Parameters:

• primary – array_like or None Set to True for objects to initially consider as possible targets. Defaults to everything being True.

• gaia – boolean array_like or None True if there is a match between this object in the Legacy Surveys and in Gaia.

• astrometricexcessnoise – array_like or None Excess noise of the source in Gaia (as in the Gaia data model).

• pmra – array_like or None Gaia-based proper motion in RA and Dec and parallax (same units as the Gaia data model).

• pmdec – array_like or None Gaia-based proper motion in RA and Dec and parallax (same units as the Gaia data model).

• parallax – array_like or None Gaia-based proper motion in RA and Dec and parallax (same units as the Gaia data model).

• dupsource – array_like or None Whether the source is a duplicate in Gaia (as in the Gaia data model).

• paramssolved – array_like or None How many parameters were solved for in Gaia (as in the Gaia data model).

• gaiagmag – array_like or None Gaia-based g, b and r MAGNITUDES (not Galactic-extinction-corrected). (same units as the Gaia data model).

• gaiabmag – array_like or None Gaia-based g, b and r MAGNITUDES (not Galactic-extinction-corrected). (same units as the Gaia data model).

• gaiarmag – array_like or None Gaia-based g, b and r MAGNITUDES (not Galactic-extinction-corrected). (same units as the Gaia data model).

Returns:

boolean array, True if the object passes Gaia quality cuts.

Return type:

mask

Notes: - Current version (03/20/21) is version 1 on the SV3 wiki.

desitarget.sv3.sv3_cuts.notinBGS_mask(gnobs=None, rnobs=None, znobs=None, primary=None, gfluxivar=None, rfluxivar=None, zfluxivar=None, Grr=None, gaiagmag=None, maskbits=None, targtype=None)

Standard set of masking cuts used by all BGS target selection classes (see, e.g., isBGS() for parameters).

desitarget.sv3.sv3_cuts.notinELG_mask(maskbits=None, gsnr=None, rsnr=None, zsnr=None, gnobs=None, rnobs=None, znobs=None, primary=None)

Standard set of masking cuts used by all ELG target selection classes. (see set_target_bits() for parameters).

desitarget.sv3.sv3_cuts.notinLRG_mask(primary=None, rflux=None, zflux=None, w1flux=None, zfiberflux=None, gnobs=None, rnobs=None, znobs=None, rfluxivar=None, zfluxivar=None, w1fluxivar=None, gaiagmag=None, maskbits=None, zfibertotflux=None)

See isLRG() for details.

Returns:

True if and only if the object is NOT masked for poor quality.

Return type:

array_like

desitarget.sv3.sv3_cuts.notinMWS_main_mask(gaia=None, gfracmasked=None, gnobs=None, gflux=None, rfracmasked=None, rnobs=None, rflux=None, maskbits=None, gaiadupsource=None, primary=None)

Standard set of masking-based cuts used by MWS target selection classes (see, e.g., isMWS_main() for parameters).

desitarget.sv3.sv3_cuts.set_target_bits(photsys_north, photsys_south, obs_rflux, gflux, rflux, zflux, w1flux, w2flux, gfiberflux, rfiberflux, zfiberflux, gfibertotflux, rfibertotflux, zfibertotflux, objtype, release, ra, dec, gfluxivar, rfluxivar, zfluxivar, w1fluxivar, gnobs, rnobs, znobs, gfracflux, rfracflux, zfracflux, gfracmasked, rfracmasked, zfracmasked, gfracin, rfracin, zfracin, gallmask, rallmask, zallmask, gsnr, rsnr, zsnr, w1snr, w2snr, deltaChi2, dchisq, gaia, pmra, pmdec, parallax, parallaxovererror, parallaxerr, gaiagmag, gaiabmag, gaiarmag, gaiaaen, gaiadupsource, gaiaparamssolved, gaiabprpfactor, gaiasigma5dmax, galb, tcnames, qso_optical_cuts, qso_selection, maskbits, Grr, refcat, primary, resolvetargs=True)

Perform target selection on parameters, return target mask arrays.

Parameters:

• photsys_north (ndarray) – True for objects that were drawn from northern (MzLS/BASS) or southern (DECaLS) imaging, respectively.

• photsys_south (ndarray) – True for objects that were drawn from northern (MzLS/BASS) or southern (DECaLS) imaging, respectively.

• obs_rflux (ndarray) – rflux but WITHOUT any Galactic extinction correction.

• gflux (ndarray) – The flux in nano-maggies of g, r, z, W1 and W2 bands. Corrected for Galactic extinction.

• rflux (ndarray) – The flux in nano-maggies of g, r, z, W1 and W2 bands. Corrected for Galactic extinction.

• zflux (ndarray) – The flux in nano-maggies of g, r, z, W1 and W2 bands. Corrected for Galactic extinction.

• w1flux (ndarray) – The flux in nano-maggies of g, r, z, W1 and W2 bands. Corrected for Galactic extinction.

• w2flux (ndarray) – The flux in nano-maggies of g, r, z, W1 and W2 bands. Corrected for Galactic extinction.

• gfiberflux (ndarray) – Predicted fiber flux from object in 1 arcsecond seeing in g/r/z. Corrected for Galactic extinction.

• rfiberflux (ndarray) – Predicted fiber flux from object in 1 arcsecond seeing in g/r/z. Corrected for Galactic extinction.

• zfiberflux (ndarray) – Predicted fiber flux from object in 1 arcsecond seeing in g/r/z. Corrected for Galactic extinction.

• gfibertotflux (ndarray) – Predicted fiber flux from ALL sources at object’s location in 1 arcsecond seeing in g/r/z. NOT corrected for Galactic extinction.

• rfibertotflux (ndarray) – Predicted fiber flux from ALL sources at object’s location in 1 arcsecond seeing in g/r/z. NOT corrected for Galactic extinction.

• zfibertotflux (ndarray) – Predicted fiber flux from ALL sources at object’s location in 1 arcsecond seeing in g/r/z. NOT corrected for Galactic extinction.

• objtype (ndarray) – The Legacy Surveys imaging TYPE and RELEASE columns.

• release (ndarray) – The Legacy Surveys imaging TYPE and RELEASE columns.

• gfluxivar (ndarray) – The flux inverse variances in g, r, z and W1 bands.

• rfluxivar (ndarray) – The flux inverse variances in g, r, z and W1 bands.

• zfluxivar (ndarray) – The flux inverse variances in g, r, z and W1 bands.

• w1fluxivar (ndarray) – The flux inverse variances in g, r, z and W1 bands.

• gnobs (ndarray) – The number of observations (in the central pixel) in g, r and z.

• rnobs (ndarray) – The number of observations (in the central pixel) in g, r and z.

• znobs (ndarray) – The number of observations (in the central pixel) in g, r and z.

• gfracflux (ndarray) – Profile-weighted fraction of the flux from other sources divided by the total flux in g, r and z bands.

• rfracflux (ndarray) – Profile-weighted fraction of the flux from other sources divided by the total flux in g, r and z bands.

• zfracflux (ndarray) – Profile-weighted fraction of the flux from other sources divided by the total flux in g, r and z bands.

• gfracmasked (ndarray) – Fraction of masked pixels in the g, r and z bands.

• rfracmasked (ndarray) – Fraction of masked pixels in the g, r and z bands.

• zfracmasked (ndarray) – Fraction of masked pixels in the g, r and z bands.

• gallmask (ndarray) – Bitwise mask set if the central pixel from all images satisfy each condition in g, r, z.

• rallmask (ndarray) – Bitwise mask set if the central pixel from all images satisfy each condition in g, r, z.

• zallmask (ndarray) – Bitwise mask set if the central pixel from all images satisfy each condition in g, r, z.

• gsnr (ndarray) – Signal-to-noise in g, r, z, W1 and W2 defined as the flux per band divided by sigma (flux x sqrt of the inverse variance).

• rsnr (ndarray) – Signal-to-noise in g, r, z, W1 and W2 defined as the flux per band divided by sigma (flux x sqrt of the inverse variance).

• zsnr (ndarray) – Signal-to-noise in g, r, z, W1 and W2 defined as the flux per band divided by sigma (flux x sqrt of the inverse variance).

• w1snr (ndarray) – Signal-to-noise in g, r, z, W1 and W2 defined as the flux per band divided by sigma (flux x sqrt of the inverse variance).

• w2snr (ndarray) – Signal-to-noise in g, r, z, W1 and W2 defined as the flux per band divided by sigma (flux x sqrt of the inverse variance).

• deltaChi2 (ndarray) – chi2 difference between PSF and SIMP, dchisq_PSF - dchisq_SIMP.

• dchisq (ndarray) – Difference in chi2 between successively more-complex model fits. Columns are model fits, in order, of PSF, REX, EXP, DEV, COMP.

• gaia (ndarray) – True if there is a match between this object in the Legacy Surveys and in Gaia.

• pmra (ndarray) – Gaia-based proper motion in RA and Dec, and parallax and error.

• pmdec (ndarray) – Gaia-based proper motion in RA and Dec, and parallax and error.

• parallax (ndarray) – Gaia-based proper motion in RA and Dec, and parallax and error.

• parallaxovererror (ndarray) – Gaia-based proper motion in RA and Dec, and parallax and error.

• gaiagmag (ndarray) – Gaia-based g-, b- and r-band MAGNITUDES.

• gaiabmag (ndarray) – Gaia-based g-, b- and r-band MAGNITUDES.

• gaiarmag (ndarray) – Gaia-based g-, b- and r-band MAGNITUDES.

• gaiaaen (ndarray) – Gaia-based measures of Astrometric Excess Noise, whether the source is a duplicate, and how many parameters were solved for.

• gaiadupsource (ndarray) – Gaia-based measures of Astrometric Excess Noise, whether the source is a duplicate, and how many parameters were solved for.

• gaiaparamssolved (ndarray) – Gaia-based measures of Astrometric Excess Noise, whether the source is a duplicate, and how many parameters were solved for.

• gaiabprpfactor (ndarray) – Gaia_based BP/RP excess factor and longest semi-major axis of 5-d error ellipsoid.

• gaiasigma5dmax (ndarray) – Gaia_based BP/RP excess factor and longest semi-major axis of 5-d error ellipsoid.

• galb (ndarray) – Galactic latitude (degrees).

• tcnames (list, defaults to running all target classes) – A list of strings, e.g. [‘QSO’,’LRG’]. If passed, process only only those specific target classes. A useful speed-up for tests. Options include [“ELG”, “QSO”, “LRG”, “MWS”, “BGS”, “STD”].

• qso_optical_cuts (boolean defaults to False) – Apply just optical color-cuts when selecting QSOs with qso_selection="colorcuts".

• qso_selection (str, optional, defaults to ‘randomforest’) – The algorithm to use for QSO selection; valid options are ‘colorcuts’ and ‘randomforest’

• maskbits (boolean array_like or None) – General Legacy Surveys mask bits.

• Grr (array_like or None) – Gaia G band magnitude minus observational r magnitude.

• primary (ndarray) – True for objects that should be considered when setting bits.

• survey (str, defaults to 'main') – Specifies which target masks yaml file and target selection cuts to use. Options are 'main' and 'svX’ (X is 1, 2, etc.) for the main survey and different iterations of SV, respectively.

• resolvetargs (boolean, optional, defaults to True) – If True, if only northern (southern) sources are passed then only apply the northern (southern) cuts to those sources.

• ra (ndarray) – The Ra, Dec position of objects

• dec (ndarray) – The Ra, Dec position of objects

Returns:

(desi_target, bgs_target, mws_target) where each element is an ndarray of target selection bitmask flags for each object.

Return type:

ndarray

Notes

• Gaia quantities have units as for the Gaia data model.

desitarget.sv3.sv3_cuts.shift_photo_north(gflux=None, rflux=None, zflux=None)

Convert fluxes in the northern (BASS/MzLS) to the southern (DECaLS) system.

Parameters:

• gflux (array_like or float) – The flux in nano-maggies of g, r, z bands.

• rflux (array_like or float) – The flux in nano-maggies of g, r, z bands.

• zflux (array_like or float) – The flux in nano-maggies of g, r, z bands.

Return type:

The equivalent fluxes shifted to the southern system.

Notes

• see also https://desi.lbl.gov/DocDB/cgi-bin/private/RetrieveFile?docid=3390;filename=Raichoor_DESI_05Dec2017.pdf;version=1

• Update for DR9 https://desi.lbl.gov/trac/attachment/wiki/TargetSelectionWG/TargetSelection/North_vs_South_dr9.png

desitarget.sv3.sv3_targetmask

This looks more like a script than an actual module.

desitarget.targetmask

This looks more like a script than an actual module.

desitarget.targetmask._load_mask_priorities(bitdefs, handle='priorities', prename='')

Priorities and NUMOBS are defined in the yaml file, but they aren’t a bitmask and so require some extra processing.

desitarget.targetmask.load_mask_bits(prefix='')

Load bit definitions from yaml file.

desitarget.targets

Presumably this defines targets.

desitarget.targets._cmx_calc_priority(targets, priority, obscon, unobs, done, zgood, zwarn, cmx_mask, obsconditions)

Special-case logic for target priorities in CMX.

Parameters:

• targets (ndarray) – numpy structured array or astropy Table of targets. Must include the column CMX_TARGET.

• priority (ndarray) – Initial priority values set, in calc_priorities().

• obscon (str) – A combination of strings that are in the desitarget bitmask yaml file (specifically in desitarget.targetmask.obsconditions), e.g. “DARK|GRAY”. Governs the behavior of how priorities are set based on “obsconditions” in the desitarget bitmask yaml file.

• unobs (ndarray) – Boolean flag on targets indicating state UNOBS.

• done (ndarray) – Boolean flag on targets indicating state DONE.

• zgood (ndarray) – Boolean flag on targets indicating state ZGOOD.

• zwarn (ndarray) – Boolean flag on targets indicating state ZWARN.

• cmx_mask (BitMask) – The CMX target bitmask.

• obscondtions (BitMask) – The CMX obsconditions bitmask.

Returns:

The updated priority values.

Return type:

ndarray

Notes

• Intended to be called only from within calc_priority(), where any pre-processing of the target state flags (uobs, done, zgood, zwarn) is handled.

desitarget.targets.calc_numobs_more(targets, zcat, obscon, ext=False)

Calculate target NUMOBS_MORE from masks, observation/redshift status.

Parameters:

• targets (ndarray) – numpy structured array or astropy Table of targets. Must include the columns DESI_TARGET, BGS_TARGET, MWS_TARGET (or their SV/cmx equivalents) TARGETID and NUMOBS_INIT. For Main Survey targets, must also contain PRIORITY if this isn’t the first time through MTL (used to “lock in” the state of Ly-Alpha QSOs).

• zcat (ndarray) – numpy structured array or Table of redshift info. Must include Z, ZWARN, NUMOBS and TARGETID and BE SORTED ON TARGETID to match targets row-by-row. May also contain NUMOBS_MORE if this isn’t the first time through MTL and NUMOBS > 0.

• obscon (str) – A combination of strings that are in the desitarget bitmask yaml file (specifically in desitarget.targetmask.obsconditions), e.g. “DARK”. Governs the behavior of how priorities are set based on “obsconditions” in the desitarget bitmask yaml file.

• ext (bool, optional, defaults to False) – If True then we’re operating in DESI 1B mode for DARK or BRIGHT tiles. When calculating priorities and numbers of observations special 1B rules will be used.

Returns:

Integer array of number of additional observations (NUMOBS_MORE).

Return type:

array

Notes

• Will automatically detect if the passed targets are main survey, commissioning or SV and behave accordingly.

• Most targets are updated to NUMOBS_MORE = NUMOBS_INIT-NUMOBS. Special case for the main survey is QSOs below the midz, which get 1 extra observation.

desitarget.targets.calc_priority(targets, zcat, obscon, state=False, ext=False)

Calculate target priorities from masks, observation/redshift status.

Parameters:

• targets (ndarray) – numpy structured array or astropy Table of targets. Must include the columns DESI_TARGET, BGS_TARGET, MWS_TARGET (or their SV/cmx equivalents) and TARGETID. For Main Survey targets, must also contain PRIORITY if this isn’t the first time through MTL, which is used to “lock in” the state of Lyman-Alpha quasars.

• zcat (ndarray) – numpy structured array or Table of redshift info. Must include Z, ZWARN, NUMOBS and TARGETID and BE SORTED ON TARGETID to match targets row-by-row. May also contain NUMOBS_MORE if this isn’t the first time through MTL and NUMOBS > 0.

• obscon (str) – A combination of strings that are in the desitarget bitmask yaml file (specifically in desitarget.targetmask.obsconditions), e.g. “DARK|GRAY”. Governs the behavior of how priorities are set based on “obsconditions” in the desitarget bitmask yaml file.

• state (bool) – If True then also return a string denoting the state that was set. The state is a string combining the observational state (e.g. “DONE”, “MORE_ZGOOD”) from the targeting yaml file and the target type (e.g. “ELG”, “LRG”).

• ext (bool, optional, defaults to False) – If True then we’re operating in DESI 1B mode for DARK or BRIGHT tiles. When calculating priorities and numbers of observations special 1B rules will be used.

Returns:

• array – integer array of priorities.

• array – string array of states. Only returned if state`=``True`

Notes

• If a target passes multiple selections, highest priority wins.

• Will automatically detect if the passed targets are main survey, commissioning or SV and behave accordingly.

desitarget.targets.decode_negative_targetid(targetid)

TODO: document

desitarget.targets.decode_targetid(targetid)

break a DESI TARGETID into its constituent parts.

:param int or ndarray: The TARGETID for DESI, encoded according to the bits listed in

desitarget.targetid_mask().

Returns:

• int or ndarray – The OBJID from Legacy Surveys imaging or the row within a Gaia HEALPixel file in $GAIA_DIR/healpix if gaia is not None.

• int or ndarray – The BRICKID from Legacy Surveys imaging. or the Gaia HEALPixel chunk number for files in $GAIA_DIR/healpix if gaia is not None.

• int or ndarray – The RELEASE from Legacy Surveys imaging. Or, if < 1000, the secondary target class bit flag number from ‘data/targetmask.yaml’. Or, if < 1000 and sky is not None, the HEALPixel processing number for SUPP_SKIES.

• int or ndarray – 1 if this object is a mock object (generated from mocks or from a random catalog, not from real survey data), 0 otherwise

• int or ndarray – 1 if this object is a blank sky object, 0 otherwise

• int or ndarray – The Gaia Data Release number (e.g. will be 2 for Gaia DR2). A value of 1 does NOT mean DR1. Rather it has the specific meaning of a DESI first-light commissioning target.

Notes

• if a 1-D array is passed, then an integer is returned. Otherwise an array is returned.

• see also DocDB 2348.

desitarget.targets.encode_negative_targetid(ra, dec, group=1)

Create negative 64-bit TARGETID from (ra,dec) unique to ~1.2 milliarcsec

Parameters:

• ra (float or ndarray) – Right Ascension in degrees 0 <= ra <= 360

• dec (float or ndarray) – Declination in degrees -90 <= dec <= 90

• group (int, optional (default 1)) – group number 1-15 to encode

Returns:

negative TARGETID derived from (ra,dec)

Return type:

int64 or ndarray

desitarget.targets.encode_targetid(objid=None, brickid=None, release=None, mock=None, sky=None, gaiadr=None)

Create the DESI TARGETID from input source and imaging info.

Parameters:

• objid (int or ndarray, optional) – The OBJID from Legacy Surveys imaging or the row within a Gaia HEALPixel file in $GAIA_DIR/healpix if gaia is not None.

• brickid (int or ndarray, optional) – The BRICKID from Legacy Surveys imaging. or the Gaia HEALPixel chunk number for files in $GAIA_DIR/healpix if gaia is not None.

• release (int or ndarray, optional) – The RELEASE from Legacy Surveys imaging. Or, if < 1000, the secondary target class bit flag number from ‘data/targetmask.yaml’. Or, if < 1000 and sky is not None, the HEALPixel processing number for SUPP_SKIES.

• mock (int or ndarray, optional) – 1 if this object is a mock object (generated from mocks or from a random catalog, not from real survey data), 0 otherwise

• sky (int or ndarray, optional) – 1 if this object is a blank sky object, 0 otherwise

• gaiadr (int or ndarray, optional) – The Gaia Data Release number (e.g. send 2 for Gaia DR2). A value of 1 does NOT mean DR1. Rather it has the specific meaning of a DESI first-light commissioning target.

Returns:

The TARGETID for DESI, encoded according to the bits listed in desitarget.targetid_mask(). If an integer is passed, then an integer is returned, otherwise an array is returned.

Return type:

int or ~numpy.ndarray

Notes

• Has maximum flexibility so that mixes of integers and arrays can be passed, in case some value like BRICKID or SKY is the same for a set of objects. Consider, e.g.:

  print(

  targets.decode_targetid(

  targets.encode_targetid(objid=np.array([234,12]),

  brickid=np.array([234,12]), release=4000, sky=[1,0])) )

(array([234,12]), array([234,12]), array([4000,4000]),

array([0,0]), array([1,0]), array([0, 0]))

• See also DocDB 2348.

desitarget.targets.finalize(targets, desi_target, bgs_target, mws_target, sky=False, randoms=False, survey='main', darkbright=False, gaiadr=None, gdr=None, targetid=None, forcerelease=False)

Return new targets array with added/renamed columns

Parameters:

• targets (ndarray) – numpy structured array of targets.

• desi_target (ndarray) – 1D array of target selection bit flags.

• bgs_target (ndarray) – 1D array of target selection bit flags.

• mws_target (ndarray) – 1D array of target selection bit flags.

• sky (bool, defaults to False) – Pass True for sky targets, False otherwise.

• randoms (bool, defaults to False) – True if targets is a random catalog, False otherwise.

• survey (str, defaults to main) – Specifies which target masks yaml file to use. Options are main, cmx and svX (where X = 1, 2, 3 etc.) for the main survey, commissioning and an iteration of SV.

• darkbright (bool, optional, defaults to False) – If sent, then split NUMOBS_INIT and PRIORITY_INIT into NUMOBS_INIT_DARK, NUMOBS_INIT_BRIGHT, PRIORITY_INIT_DARK and PRIORITY_INIT_BRIGHT and calculate values appropriate to “BRIGHT” and “DARK|GRAY” observing conditions. Will also split by, e.g. DARK1B for the extension.

• gaiadr (int, optional, defaults to None) – If passed and not None, then build the TARGETID from the “GAIA_OBJID” and “GAIA_BRICKID” columns in the passed targets, and set the gaiadr part of TARGETID to whatever is passed. “RELEASE” is set to zero.

• gdr (int, defaults to None) – An alternate version of gaiadr where the “OBJID”, “BRICKID” and “RELEASE” columns are used as normal, but gdr is sent to desitarget.targets.encode_targetid() as the gaiadr bit.

• targetid (int64, optional, defaults to None) – In the mocks we compute TARGETID outside this function.

Returns:

new targets structured array with the following additions:

• renaming OBJID -> BRICK_OBJID (it is only unique within a brick).

• renaming TYPE -> MORPHTYPE (used downstream in other contexts).

• Adding new columns:

  • TARGETID: unique ID across all bricks or Gaia files.

  • DESI_TARGET: dark time survey target selection flags.

  • MWS_TARGET: bright time MWS target selection flags.

  • BGS_TARGET: bright time BGS target selection flags.

  • PRIORITY_INIT: initial priority for observing target.

  • SUBPRIORITY: a placeholder column that is set to zero.

  • NUMOBS_INIT: initial number of observations for target.

  • OBSCONDITIONS: bitmask of observation conditions.

Return type:

ndarray

Notes

• SUBPRIORITY is the only column that isn’t populated. This is because it’s easier to populate it in a reproducible fashion when collecting targets rather than on a per-brick basis when this function is called. It’s set to all zeros.

• Only one of gaiadr and gdr can be input.

desitarget.targets.initial_priority_numobs(targets, scnd=False, obscon='DARK|GRAY|BRIGHT|BACKUP|TWILIGHT12|TWILIGHT18')

highest initial priority and numobs for an array of target bits.

Parameters:

• targets (ndarray) – An array of targets generated by, e.g., cuts. Must include at least (all of) the columns DESI_TARGET, BGS_TARGET, MWS_TARGET or corresponding cmx or SV columns.

• scnd (bool, optional, defaults to False) – If True then make all of the comparisons on the SCND_TARGET column instead of DESI_TARGET, BGS_TARGET and MWS_TARGET.

• obscon (str, optional, defaults to almost all OBSCONDITIONS) – A combination of strings that are in the desitarget bitmask yaml file (specifically in desitarget.targetmask.obsconditions).

Returns:

• ndarray – An array of integers corresponding to the highest initial priority for each target consistent with the constraints on observational conditions imposed by obscon.

• ndarray – An array of integers corresponding to the largest number of observations for each target consistent with the constraints on observational conditions imposed by obscon.

Notes

• the initial priority for each target bit is in the file, e.g., data/targetmask.yaml. It can be retrieved using, for example, desi_mask[“ELG”].priorities[“UNOBS”].

• the input obscon string can be converted to a bitmask using desitarget.targetmask.obsconditions.mask(blat).

desitarget.targets.main_cmx_or_sv(targets, rename=False, scnd=False)

whether a target array is main survey, commissioning, or SV.

Parameters:

• targets (ndarray) – An array of targets generated by, e.g., cuts must include at least (all of) the columns DESI_TARGET, MWS_TARGET and BGS_TARGET or the corresponding commissioning or SV columns.

• rename (bool, optional, defaults to False) – If True then also return a copy of targets with the input _TARGET columns renamed to reflect the main survey format.

• scnd (bool, optional, defaults to False) – If True, add the secondary target information to the output.

Returns:

• list – A list of strings corresponding to the target columns names. For the main survey this would be [DESI_TARGET, BGS_TARGET, MWS_TARGET], for commissioning it would just be [CMX_TARGET], for SV1 it would be [SV1_DESI_TARGET, SV1_BGS_TARGET, SV1_MWS_TARGET]. Also includes, e.g. SCND_TARGET, if scnd is passed as True.

• list – A list of the masks that correspond to each column from the relevant main/cmx/sv yaml file. Also includes the relevant SCND_MASK, if scnd is passed as True.

• str – The string ‘main’, ‘cmx’ or ‘svX’ (where X = 1, 2, 3 etc.) for the main survey, commissioning and an iteration of SV. Specifies which type of file was sent.

• ndarray, optional, if rename is True – A copy of the input targets array with the _TARGET columns renamed to DESI_TARGET, and (if they exist) BGS_TARGET, MWS_TARGET.

desitarget.targets.resolve(targets)

Resolve which targets are primary in imaging overlap regions.

Parameters:

targets (ndarray) – Rec array of targets. Must have columns “RA” and “DEC” and either “RELEASE” or “PHOTSYS” or “TARGETID”.

Returns:

The original target list trimmed to only objects from the “northern” photometry in the northern imaging area and objects from “southern” photometry in the southern imaging area.

Return type:

ndarray

desitarget.targets.set_obsconditions(targets, scnd=False)

set the OBSCONDITIONS mask for each target bit.

Parameters:

• targets (ndarray) – An array of targets generated by, e.g., cuts. Must include at least (all of) the columns DESI_TARGET, BGS_TARGET, MWS_TARGET or corresponding cmx or SV columns.

• scnd (bool, optional, defaults to False) – If True then make all of the comparisons on the SCND_TARGET column instead of DESI_TARGET, BGS_TARGET and MWS_TARGET.

Returns:

The OBSCONDITIONS bitmask for the passed targets.

Return type:

ndarray

Notes

• the OBSCONDITIONS for each target bit is in the file, e.g. data/targetmask.yaml. It can be retrieved using, for example, obsconditions.mask(desi_mask[“ELG”].obsconditions).

desitarget.targets.switch_main_cmx_or_sv(revamp, archetype)

change the data model of a set of targets to match another.

Parameters:

• revamp (ndarray) – An array of targets generated by, e.g., cuts must include columns DESI_TARGET, MWS_TARGET and BGS_TARGET or the corresponding commissioning or SV columns.

• archetype (ndarray) – Like revamp but with a different flavor of DESI_TARGET, MWS_TARGET and BGS_TARGET columns. For instance, revamp might have the Main Survey columns and archetype might have the SV1 columns.

Returns:

revamp but with the flavor of DESI_TARGET, MWS_TARGET and BGS_TARGET updated to match that of archetype

Return type:

ndarray

desitarget.train

Tools for RF training QSO targets selection.

desitarget.train.data_collection

Tools for RF training QSO targets selection.

desitarget.train.data_preparation

Tools for RF training QSO targets selection.

desitarget.train.train_test_RF

Tools for RF training QSO targets selection.

Permet de convertir un RandomForestClassifier de sk-learn sous la forme requise par desi_target dans la classe myRF.

Contient également un petit test pour vérifier si le script fonctionne correctement !

Ce Code n’a plus de soucis avec la version de joblib et fonctionne donc avec les versions récentes de scikit-learn

Fonctionne (testé) avec : scikit_learn : 0.22.1 et joblib : 0.14.1

desitarget.train.train_test_RF.utils

Tools for RF training QSO targets selection.

desitarget.train.train_test_RF.util.funcs.shift_photo_north(gflux=None, rflux=None, zflux=None)

Convert fluxes in the northern (BASS/MzLS) to the southern (DECaLS) system. :param gflux: The flux in nano-maggies of g, r, z bands. :type gflux: array_like or float :param rflux: The flux in nano-maggies of g, r, z bands. :type rflux: array_like or float :param zflux: The flux in nano-maggies of g, r, z bands. :type zflux: array_like or float

Return type:

The equivalent fluxes shifted to the southern system.

Notes

• see also https://desi.lbl.gov/DocDB/cgi-bin/private/RetrieveFile?docid=3390;filename=Raichoor_DESI_05Dec2017.pdf;version=1

desitarget.tychomatch

Useful Tycho catalog matching and manipulation routines.

desitarget.tychomatch.find_tycho_files(objs, neighbors=True, radec=False)

Find full paths to Tycho healpix files for objects by RA/Dec.

Parameters:

• objs (ndarray) – Array of objects. Must contain the columns “RA” and “DEC”.

• neighbors (bool, optional, defaults to True) – Also return all pixels that touch the files of interest to prevent edge effects (e.g. if a Tycho source is 1 arcsec away from a primary source and so in an adjacent pixel).

• radec (bool, optional, defaults to False) – If True then the passed objs is an [RA, Dec] list instead of a rec array that contains “RA” and “DEC”.

Returns:

A list of all Tycho files to read to account for objects at the passed locations.

Return type:

list

Notes

• The environment variable $TYCHO_DIR must be set.

desitarget.tychomatch.find_tycho_files_hp(nside, pixlist, neighbors=True)

Find full paths to Tycho healpix files in a set of HEALPixels.

Parameters:

• nside (int) – (NESTED) HEALPixel nside.

• pixlist (list or int) – A set of HEALPixels at nside.

• neighbors (bool, optional, defaults to True) – Also return files corresponding to all neighbors that touch the pixels in pixlist to prevent edge effects (e.g. a Tycho source is 1 arcsec outside of pixlist and so in an adjacent pixel).

Returns:

A list of all Tycho files that need to be read in to account for objects in the passed list of pixels.

Return type:

list

Notes

• The environment variable $TYCHO_DIR must be set.

desitarget.tychomatch.get_tycho_dir()

Convenience function to grab the Tycho environment variable.

Returns:

The directory stored in the $TYCHO_DIR environment variable.

Return type:

str

desitarget.tychomatch.get_tycho_nside()

Grab the HEALPixel nside to be used throughout this module.

Returns:

The HEALPixel nside number for Tycho file creation and retrieval.

Return type:

int

desitarget.tychomatch.grab_tycho(cosmodir='/global/cfs/cdirs/cosmo/staging/tycho2/')

Retrieve the cosmo versions of the Tycho files at NERSC.

Parameters:

cosmodir (str) – The NERSC directory that hosts the Tycho files.

Returns:

But the Tycho fits file, README are written to $TYCHO_DIR/fits.

Return type:

None

Notes

• The environment variable $TYCHO_DIR must be set.

• The fits file is “cleaned up” to conform to DESI Data Systems standards (e.g. all columns are converted to upper-case).

desitarget.tychomatch.make_tycho_files()

Make the HEALPix-split Tycho files in one fell swoop.

Returns:

But produces:

• A FITS file with appropriate header and columns from tychodatamodel, and a README in $TYCHO_DIR/fits.

• FITS files reorganized by HEALPixel in $TYCHO_DIR/healpix.

The HEALPixel sense is nested with nside=get_tycho_nside(), and each file in $TYCHO_DIR/healpix is called healpix-xxxxx.fits, where xxxxx corresponds to the HEALPixel number.

Return type:

None

Notes

• The environment variable $TYCHO_DIR must be set.

desitarget.tychomatch.match_to_tycho(objs, matchrad=1.0, radec=False)

Match objects to Tycho healpixel files.

Parameters:

• objs (ndarray) – Must contain at least “RA” and “DEC”.

• matchrad (float, optional, defaults to 1 arcsec) – The radius at which to match in arcseconds.

• radec (bool, optional, defaults to False) – If True then the passed objs is an [RA, Dec] list instead of a rec array.

Returns:

The matching Tycho information for each object. The returned format is as for desitarget.tychomatch.tychodatamodel with an extra column “TYCHO_SEP” which is the matching distance in ARCSECONDS.

Return type:

ndarray

Notes

• For objects with NO match in Tycho, the “TYC1”, “TYC2” and “TYCHO_SEP” columns are -1, and other columns are zero.

• Retrieves the CLOSEST match to Tycho for each passed object.

• Because this reads in HEALPixel split files, it’s (far) faster for objects that are clumped rather than widely distributed.

desitarget.tychomatch.tycho_fits_to_healpix()

Convert files in $TYCHO_DIR/fits to files in $TYCHO_DIR/healpix.

Returns:

But the archived Tycho FITS files in $TYCHO_DIR/fits are rearranged by HEALPixel in the directory $TYCHO_DIR/healpix. The HEALPixel sense is nested with nside=get_tycho_nside(), and each file in $TYCHO_DIR/healpix is called healpix-xxxxx.fits, where xxxxx corresponds to the HEALPixel number.

Return type:

None

Notes

• The environment variable $TYCHO_DIR must be set.

desitarget.uratmatch

Useful URAT matching and manipulation routines.

desitarget.uratmatch._get_urat_nside()

Grab the HEALPixel nside to be used throughout this module.

Returns:

The HEALPixel nside number for URAT file creation and retrieval.

Return type:

int

desitarget.uratmatch.find_urat_files(objs, neighbors=True, radec=False)

Find full paths to URAT healpix files for objects by RA/Dec.

Parameters:

• objs (ndarray) – Array of objects. Must contain the columns “RA” and “DEC”.

• neighbors (bool, optional, defaults to True) – Also return all pixels that touch the files of interest to prevent edge effects (e.g. if a URAT source is 1 arcsec away from a primary source and so in an adjacent pixel).

• radec (bool, optional, defaults to False) – If True then the passed objs is an [RA, Dec] list instead of a rec array that contains “RA” and “DEC”.

Returns:

A list of all URAT files to read to account for objects at the passed locations.

Return type:

list

Notes

• The environment variable $URAT_DIR must be set.

desitarget.uratmatch.get_urat_dir()

Convenience function to grab the URAT environment variable.

Returns:

The directory stored in the $URAT_DIR environment variable.

Return type:

str

desitarget.uratmatch.make_urat_files(numproc=5, download=False)

Make the HEALPix-split URAT files in one fell swoop.

Parameters:

• numproc (int, optional, defaults to 5) – The number of parallel processes to use.

• download (bool, optional, defaults to False) – If True then wget the URAT binary files from Vizier.

Returns:

But produces: - URAT DR1 binary files in $URAT_DIR/binary (if download=True). - URAT CSV files with all URAT columns in $URAT_DIR/csv. - FITS files with columns from uratdatamodel in $URAT_DIR/fits. - FITS files reorganized by HEALPixel in $URAT_DIR/healpix.

The HEALPixel sense is nested with nside=_get_urat_nside(), and each file in $URAT_DIR/healpix is called healpix-xxxxx.fits, where xxxxx corresponds to the HEALPixel number.

Return type:

Nothing

Notes

• The environment variable $URAT_DIR must be set.

• if numproc==1, use the serial, instead of the parallel, code.

• Runs in about 2 hours with numproc=25 if download is True.

• Runs in about 1 hour with numproc=25 if download is False.

desitarget.uratmatch.match_to_urat(objs, matchrad=1.0, radec=False)

Match objects to URAT healpix files and return URAT information.

Parameters:

• objs (ndarray) – Must contain at least “RA” and “DEC”.

• matchrad (float, optional, defaults to 1 arcsec) – The radius at which to match in arcseconds.

• radec (bool, optional, defaults to False) – If True then the passed objs is an [RA, Dec] list instead of a rec array.

Returns:

The matching URAT information for each object. The returned format is as for desitarget.uratmatch.uratdatamodel with an extra column “URAT_SEP” which is the matching distance in ARCSECONDS.

Return type:

ndarray

Notes

• For objects that do NOT have a match in URAT, the “URAT_ID” and “URAT_SEP” columns are -1, and other columns are zero.

• Retrieves the CLOSEST match to URAT for each passed object.

• Because this reads in HEALPixel split files, it’s (far) faster for objects that are clumped rather than widely distributed.

desitarget.uratmatch.scrape_urat(url='http://cdsarc.u-strasbg.fr/ftp/I/329/URAT1/v12/', nfiletest=None)

Retrieve the binary versions of the URAT files.

Parameters:

• url (str) – The web directory that hosts the archived binary URAT files.

• nfiletest (int, optional, defaults to None) – If an integer is sent, only retrieve this number of files, for testing.

Returns:

But the archived URAT files are written to $URAT_DIR/binary.

Return type:

Nothing

Notes

• The environment variable $URAT_DIR must be set.

• Runs in about 50 minutes for 575 URAT files.

desitarget.uratmatch.urat_binary_to_csv()

Convert files in $URAT_DIR/binary to files in $URAT_DIR/csv.

Returns:

But the archived URAT binary files in $URAT_DIR/binary are converted to CSV files in the $URAT_DIR/csv.

Return type:

Nothing

Notes

• The environment variable $URAT_DIR must be set.

• Relies on the executable urat/fortran/v1dump, which is only tested at NERSC and might need compiled by the user.

• Runs in about 40 minutes for 575 files.

desitarget.uratmatch.urat_csv_to_fits(numproc=5)

Convert files in $URAT_DIR/csv to files in $URAT_DIR/fits.

Parameters:

numproc (int, optional, defaults to 5) – The number of parallel processes to use.

Returns:

But the archived URAT CSV files in $URAT_DIR/csv are converted to FITS files in the directory $URAT_DIR/fits. Also, a look-up table is written to $URAT_DIR/fits/hpx-to-files.pickle for which each index is an nside=_get_urat_nside(), nested scheme HEALPixel and each entry is a list of the FITS files that touch that HEAPixel.

Return type:

Nothing

Notes

• The environment variable $URAT_DIR must be set.

• if numproc==1, use the serial code instead of the parallel code.

• Runs in about 10 minutes with numproc=25 for 575 files.

desitarget.uratmatch.urat_fits_to_healpix(numproc=5)

Convert files in $URAT_DIR/fits to files in $URAT_DIR/healpix.

Parameters:

numproc (int, optional, defaults to 5) – The number of parallel processes to use.

Returns:

But the archived URAT FITS files in $URAT_DIR/fits are rearranged by HEALPixel in the directory $URAT_DIR/healpix. The HEALPixel sense is nested with nside=_get_urat_nside(), and each file in $URAT_DIR/healpix is called healpix-xxxxx.fits, where xxxxx corresponds to the HEALPixel number.

Return type:

Nothing

Notes

• The environment variable $URAT_DIR must be set.

• if numproc==1, use the serial code instead of the parallel code.

• Runs in about 10 minutes with numproc=25.