Package: rgbloom
rgbloomThis Python code retrieves RGB magnitudes computed from low resolution
spectra published inGaiaDR3, following the methodology described inCarrasco et al. (2023).  These magnitudes are given in the standard
system defined byCardiel et al. (2021a).The code presented here is an updated version ofrgblues, which originally provided RGB
magnitudes fromGaiaEDR3 photometric data, as explained inCardiel et al.
(2021b).The RGB magnitudes provided byCarrasco et al. (2023)are considered more
reliable as they are directly computed from the source spectrum, without the
need for any approximate calibration or constraints on source colour or
extinction. Moreover, the number of sources with RGB estimates has
significantly increased from approximately 15 million to around 200 million
objects (referred to as the 200M sample).  However, it is important to note
that the sky coverage of the 200M sample is still limited in some high Galactic
latitudes. For this reason,rgbloomalso provides RGB estimates for sources
that do not belong to the 200M sample making use of the polynomial calibrations
ofCardiel et al. (2021b), which can be useful for users requiring
calibrated RGB sources at those particular sky regions.The codergbloomperforms a cone search defined by right ascension and
declination coordinates on the sky, along with a specified search radius.  This
cone search is performed making use of the Astroquery coordinated package of
astropy.Please note that a live internet connection is required for the code to
function properly.Installing the codeIn order to keep your current Python installation clean, it is highly
recommended to first build Python 3virtual environment.Creating and activating the Python virtual environment$python3-mvenvvenv_rgb
$.venv_rgb/bin/activate(venv_rgb)$Installing the packageWe recommend installing the latest stable version, which is available via
thePyPI respository:(venv_rgb)$pipinstallrgbloomThe latest development version is available throughGitHub:(venv_rgb)$pipinstallgit+https://github.com/guaix-ucm/rgbloom.git@main#egg=rgbloomExecuting the programJust execute it from the command line. For example(venv_rgb)$rgbloom56.6624.101.012The last instruction executes the program providing the
four positional arguments: right ascension, declination, search radius and
limitingGaiaG magnitude.Note that the coordinates and search radius
must be given in decimal degrees.Whenever the code is executed, it will download certain auxiliary files to your
computer if they haven't been downloaded in a previous run. These files are
stored in a cache directory, and the location of this directory will be
displayed in the terminal output. You don't need to be concerned about the
specific location unless you want to delete these files to free up disk space.The execution of this example should led to the following output in the
terminal (except for the absolute path where the auxiliary downloaded files
are stored):Welcome to rgbloom version 1.7
        ==============================

Downloading data from 'http://nartex.fis.ucm.es/~ncl/rgbphot/gaiaDR3/reference_healpix8.csv' to file '/Users/cardiel/Library/Caches/pooch/635cd722cf61b23bd8eee20635e4d580-reference_healpix8.csv'.
<STEP1> Starting cone search in Gaia DR3... (please wait)
  INFO: Query finished. [astroquery.utils.tap.core]
        --> 310 objects found
        --> 23 objects classified as VARIABLE
<STEP2> Estimating RGB magnitudes in DR3 query using C21 polynomials OK!
<STEP3> Retrieving objects from the 200M sample in the enclosing HEALPIx level-8 tables
Downloading data from 'http://nartex.fis.ucm.es/~ncl/rgbphot/gaiaDR3/RGBsynthetic_NOVARIABLES/sortida_XpContinuousMeanSpectrum_006602-007952_RGB_NOVARIABLES_final.csv.gz' to file '/Users/cardiel/Library/Caches/pooch/2d94d5acfcb380d6dff1eaa207caa086-sortida_XpContinuousMeanSpectrum_006602-007952_RGB_NOVARIABLES_final.csv.gz'.
        * Required file: /Users/cardiel/Library/Caches/pooch/2d94d5acfcb380d6dff1eaa207caa086-sortida_XpContinuousMeanSpectrum_006602-007952_RGB_NOVARIABLES_final.csv.gz
          md5:f9cf7ed0f84eecda13ef6a408d291b96
        --> Number of objects: 100553
        --> Total number of objects: 100553
<STEP4> Cross-matching DR3 with 200M sample
        --> Number of objects in the 200M subsample............: 100553
        --> Number of objects in DR3 query.....................: 310
        --> Number of DR3 objects within the 200M sample.......: 248
        --> Number of DR3 objects no present in the 200M sample: 62
<STEP5> Saving output CSV files
        --> file rgbloom_200m.csv saved
        --> file rgbloom_no200m.csv saved
<STEP6> Generating PDF plot
End of programThergbloomscript executes the following steps:Step 1: cone search inGaiaDR3, gathering the following parameters:source_id,ra,dec,phot_g_mean_mag,phot_bp_mean_mag,phot_rp_mean_magandphot_variable_flagStep 2: initial RGB magnitude estimation using the polynomial
transformations given in Eqs. (2)-(4) ofCardiel et al. (2021b).
These values are only provided for objects in the field of view
that do not belong to the 200M sample.Step 3: downloading of the RGB magnitude estimates corresponding to
the 200M sample objects within the HEALPIx level-8 tables enclosing
the region of the sky defined in the initial cone search.Step 4: cross-matching between the DR3 and 200M subsamples to identify objects
with RGB estimates derived from the low resolutionGaiaDR3 spectra.Step 5: generation of the output files. Two files (in CSV format) are
generated:rgbloom_200m.csv: objects belonging to the 200M sample
with RGB magnitudes computed as described inCarrasco et al. (2023).
This CSV file provides the following columns:number: consecutive number of the object in the CSV file (used in the final plot)source_id: identification inGaiaDR3ra: right ascension (fromGaiaDR3)dec: declination (fromGaiaDR3)RGB_B: blue RGB magnitude estimateRGB_G: green RGB magnitude estimateRGB_R: red RGB magnitude estimateerrRGB_B: uncertainty in the blue RGB magnitude estimateerrRGB_G: uncertainty in the green RGB magnitude estimateerrRGB_R: uncertainty in the red RGB magnitude estimateobjtype: type of source, according to the classification provided byGaiaDR3 (seedescription ofGAIA_SOURCEtable for details):1: object flagged asNON_SINGLE_STAR2: object flagged asIN_QSO_CANDIDATES3: object flagged asIN_GALAXY_CANDIDATES0: none of the aboveqlflag: global quality flag:0: reliable source1: suspicious source (blending, contamination, non-stellar
identification)rgbloom_no200m.csv: objects not included in the 200M sample, which
RGB magnitudes are estimated using the approximate polynomial
calibrations ofCardiel et al. (2021b).
This CSV file contains the following columns:number: consecutive number of the object in the CSV file (used in the final plot)source_id: identification inGaiaDR3ra: right ascension (fromGaiaDR3)dec: declination (fromGaiaDR3)phot_variable_flag: photometric variability flag (fromGaiaDR3)bp_rp: G_BP-G_RP colour (fromGaiaDR3)RGB_B: blue RGB magnitude estimateRGB_G: green RGB magnitude estimateRGB_R: red RGB magnitude estimateThe list of objects in these two files is sorted by right ascension.Step 6: generation of a finding chart plot (in PDF format):rgbloom.pdf.
The execution of the previous example generates a cone search around thePleiadesstar cluster:In this
plot (seePDF
file) the
object symbol size is scaled based on the Gaia G magnitude, and are color
coded based on theGaiaG_BP - G_RP colour. Objects brighter than a
predefined threshold are represented by larger star symbols. To aid in object
identification, the consecutive identification numbers from the two filesrgbloom_200m.csvandrgbloom_no200m.csv, are displayed in red and black,
respectively. As these files are sorted by right ascension, the
identification numbers increase sequentially on the chart.In the case of less reliable sources inrgbloom_20m.csv(whereqlflag=1),
the corresponding identification numbers are enclosed within a rectangle with
a light-gray border. It is worth noting that when the--nonumbersparameter
is used in the command line, the identification numbers will not be
displayed.Starting from version 1.5, it is now possible to label each object with its magnitude
instead of the objetc number in the CSV files. This can be achieved using the--display_mag <magname>option, where<magname>can be any of the following:RGB_B,RGB_R,RGB_R,Gaia_G,Gaia_BP,Gaia_RP,Gaia_BP-RP. When this option is used,
the displayed RGB magnitudes for objects outside the 200M sample
correspond to the estimates calculated using the polynomial calibrations derived
byCardiel et al. (2021b), and are shown between parenthesis.In the case of objects that do not belong to the 200M sample (i.e., those inrgbloom_no200m.csv), a blue square
has been overplotted on the sources flagged as variable inGaiaDR3, and a
grey diamond on objects outside theGaia-0.5 < G_BP - G_RP < 2.0 colour
interval.Note that the three output files, consisting of one PDF file and two CSV files,
share the same root name, which is by defaultrgbloom. However, you can easily
modify this by using the optional argument--basename <newbasename>in the
command line. This allows you to specify a new base name for the output files
according to your preference.Additional helpSome auxiliary optional arguments are also available. See description
invoking the script help:$rgbloom--helpusage: rgbloom [-h] [--basename BASENAME] [--brightlimit BRIGHTLIMIT]
               [--symbsize SYMBSIZE] [--max_symbsize MAX_SYMBSIZE]
               [--min_symbsize MIN_SYMBSIZE] [--mag_power MAG_POWER]
               [--display_mag {None,RGB_B,RGB_G,RGB_R,Gaia_G,Gaia_BP,Gaia_RP,Gaia_BP_RP}]
               [--num_fontsize NUM_FONTSIZE] [--nonumbers] [--noplot]
               [--nocolor] [--verbose]
               ra_center dec_center search_radius g_limit

RGB predictions from Gaia DR3 spectrophotometry (version 1.6)

positional arguments:
  ra_center             right Ascension (decimal degrees)
  dec_center            declination (decimal degrees)
  search_radius         search radius (decimal degrees)
  g_limit               limiting Gaia G magnitude

optional arguments:
  -h, --help            show this help message and exit
  --basename BASENAME   file basename for output files
  --brightlimit BRIGHTLIMIT
                        objects brighter than this Gaia G limit are displayed
                        with star symbols (default=8.0)
  --symbsize SYMBSIZE   global multiplying factor for symbol size
                        (default=1.0)
  --max_symbsize MAX_SYMBSIZE
                        maximum symbol size in chart (default=1000)
  --min_symbsize MIN_SYMBSIZE
                        minimum symbol size in chart (default=10)
  --mag_power MAG_POWER
                        power to scale symbol sizes in chart (default=3)
  --display_mag {None,RGB_B,RGB_G,RGB_R,Gaia_G,Gaia_BP,Gaia_RP,Gaia_BP_RP}
                        display selected magnitude instead of object number
  --num_fontsize NUM_FONTSIZE
                        font size for numbers in chart (default=5)
  --nonumbers           do not display object identification number in PDF
                        chart
  --noplot              skip PDF chart generation
  --nocolor             do not use colors in PDF chart
  --verbose             increase program verbosity```CitationIf you find this Python package useful,
please citeCardiel et al. (2021a)(to quote the use of the standard RGB system)
andCarrasco et al. (2023)(where the computation of the RGB magnitudes
from the low resolution spectra published inGaiaDR3 is explained).Related informationYou can visit theRGB Photometryweb page at
the Universidad Complutense de Madrid.BibliographyCardiel et al. (2021a),
MNRAS,https://ui.adsabs.harvard.edu/abs/2021MNRAS.504.3730C/abstractCardiel et al. (2021b),
MNRAS,https://ui.adsabs.harvard.edu/abs/2021MNRAS.507..318C/abstractCarrasco et al. (2023), Remote Sensing,https://www.mdpi.com/2072-4292/15/7/1767