• Introduction
• Compilation
• Running
• Configurations
• Acknowledgements
• References

brickmask is a tool for assigning bit codes defined on Legacy Survey brick pixels^1,2 to a catalogue with sky coordinates: J2000 right ascension (RA) and declination (Dec) in degrees.

A common usage of brickmask is to mark objects to be removed based on the veto masks defined on brick pixels. The input catalogue can be either a plain ASCII file, or in the FITS format. Besides, a collection of FITS-format maskbits files has to be provided. The input objects are then located in the bricks and assigned the corresponding bit codes. Optionally, an extra attribute specifying subsample IDs of the maskbits can be appended to the input catalogue as well.

This program is compliant with the ISO C99 and IEEE POSIX.1-2008 standards, and supports Message Passing Interface (MPI) parallelisation. It is written by Cheng Zhao (赵成), and is distributed under the MIT license.

This tool was originally developed for the Extended Baryon Oscillation Spectroscopic Survey (eBOSS) Emission-line Galaxy (ELG) masks (see [1],[2]). It is also compatible with the veto masks used for the Dark Energy Spectroscopic Instrument (DESI). If you use this tool in research work that results in publications, please cite the following paper:

Zhao et al., 2021, The completed SDSS-IV extended Baryon Oscillation Spectroscopic Survey: 1000 multi-tracer mock catalogues with redshift evolution and systematics for galaxies and quasars of the final data release, MNRAS, 503(1):1149–1173 (arXiv:2007.08997)

<sub>1. see e.g. http://legacysurvey.org/dr9/files/#survey-bricks-fits-gz ↩
2. e.g. https://www.legacysurvey.org/dr9/bitmasks ↩</sub>

_[TOC]

The only mandatory external library required by this program is CFITSIO, for reading/writing FITS files. If CFITSIO is already installed in the standard library paths, such as /usr/lib, one should be able to compile brickmask simply with the command

make

Otherwise, the CFITSIO installation path has to be set via CFITSIO_DIR in Makefile. In this case, the header file fitsio.h has to be available in CFITSIO_DIR/include, and the library file (libcfitsio.so) must be present in CFITSIO_DIR/lib.

To enable MPI support, a compiler wrapper for MPI programs (such as mpicc) must be available, and the option USE_MPI in Makefile should be set to T.

The other optional compilation flags (can be set via CFLAGS) are summarised below:

<sub>3. See https://data.sdss.org/datamodel/files/EBOSS_LSS/catalogs/DR16/ELGmask/mask.html. Note also that there are additional eBOSS ELG masks that should be set using the script eBOSS_ELG_extra.py. ↩
4. The low-level FITS image reader is ∼ 4 times faster than the default reader for plain images, but only marginally faster for gzipped images. Note that it should never be enabled for maskbits compressed with algorithms other than gzip (such as .fits.fz files). ↩</sub>

_[TOC]

If the CFITSIO library is installed in a custom directory, the path to the library file (libcfitsio.so) has to be included in the environment variable LD_LIBRARY_PATH before running this program, e.g.

export LD_LIBRARY_PATH=/Custom_CFITSIO_DIR/lib:$LD_LIBRARY_PATH

Moreover, if MPI is enabled, the code should be run with an MPI executable, such as mpirun or srun.

Once the program is run successfully, it looks for the configuration file set via the -c command line option, or brickmask.conf by default (see CONFIG.md for details). Configuration parameters can also be set via command line options, which override the entries in the configuration file. A list of all command line options can be found with the -h/--help option.

_[TOC]

Detailed descriptions of all configuration parameters can be found in CONFIG.md.

Apart from parameters that can be supplied via command line options and the configuration file, there are also some runtime settings defined as macros in define.h. For instance, BRICKMASK_FITS_SUBID indicates the column name of subsample IDs for the FITS-format output catalogue.

_[TOC]

I thank Dr. Anand Raichoor for helpful discussions on the development and debugging of this tool, and Dr. Arnaud de Mattia for sharing the original script for assigning extra maskbit codes for eBOSS ELGs.

_[TOC]

[1] Raichoor et al., 2021, The completed SDSS-IV extended Baryon Oscillation Spectroscopic Survey: large-scale structure catalogues and measurement of the isotropic BAO between redshift 0.6 and 1.1 for the Emission Line Galaxy Sample, MNRAS, 500(3):3254–3274 (arXiv:2007.09007)

[2] Zhao et al., 2021, The completed SDSS-IV extended Baryon Oscillation Spectroscopic Survey: 1000 multi-tracer mock catalogues with redshift evolution and systematics for galaxies and quasars of the final data release, MNRAS, 503(1):1149–1173 (arXiv:2007.08997)

_[TOC]