Target catalog processing¶

class qmostetc.TargetCatalog(table, rules_repository, template_dir, reddening_binning=<Quantity 0.1 mag>, redshift_binning=0.05)¶

Main class for the 4MOST ETC, abstracting a target catalog

The convenient way to create a TargetCatalog is the static TargetCatalog.read() method.

Examples

Process the example catalog that is provided with the package. This is basically a simple ETC:

>>> from qmostetc import TargetCatalog
>>> cat = TargetCatalog.read('qmostetc/tests/targets.fits',
...                          'qmostetc/tests/rulesets.csv',
...                          'qmostetc/tests/rules.csv',
...                          'qmostetc/tests')
>>> cat.process()
>>> cat.table['NAME', 'TEXP_D', 'TEXP_G', 'TEXP_B', 'TEXP_S'].pprint()
  NAME  TEXP_D TEXP_G TEXP_B  TEXP_S
         min    min    min     min
------- ------ ------ ------ -------
example 117.04 170.67 467.56 1018.38

>>> cat.table['NAME', 'MAG', 'FIBER_MAG', 'FIBER_MAG_RED'].pprint()
  NAME  MAG  FIBER_MAG FIBER_MAG_RED
        mag     mag         mag
------- ---- --------- -------------
example 20.0     21.22         20.96

Attributes:

tableastropy.table.QTable: Target catalog. This catalog will get columns appended during process().
rules_repositoryRulesRepository: Rules repository to build the ETC rules.
template_dirpathlib.Path: SED template directory. This directory is used to search for spectral templates for the targets.
reddening_binningastropy.units.Quantity: Binning accuracy of the template reddening [mag]. Set to None to switch off binning and use the exact value.
redshift_binningfloat: Binning accuracy of the redshift binning. Set to None to switch off binning and use the exact value.

get_target(row)¶

Create a Target from the specified row in the target table.

This target can then be used to calculate the exposure time.

Parameters:

rowastropy.table.Row: Table row of the Target catalog

Returns:

Target: The target built from the row

Examples

Process the first row of the example catalog:

>>> from qmostetc import TargetCatalog
>>> cat = TargetCatalog.read('qmostetc/tests/targets.fits',
...                          'qmostetc/tests/rulesets.csv',
...                          'qmostetc/tests/rules.csv',
...                          'qmostetc/tests')
>>> target = cat.get_target(cat.table[0])
>>> texp = target.get_exptime('grey')
>>> print(f'{target.name}: {texp.to("min"):.0f}')
example: 161 min

check_consistency(table=None)¶

Check the catalog for consistency

The following tests are done:

presence and proper units of the required columns
availability of all target templates
availability of all filters and magtypes
used rules and rulesets

Errors are printed on stdout and returned as a list of strings. Some summary statistics (number of entries, number of target/magtype combinations, number of rulesets) is also printed.

Parameters:

tableastropy.table.QTable: Table to check. If not specified, the table of the catalog (TargetCatalog.table) is used.

Returns:

list: The list of error strings from the consistency check. If the string is empty, the table will process.

Examples

Check the example catalog provided with the package:

>>> from qmostetc import TargetCatalog
>>> cat = TargetCatalog.read('qmostetc/tests/targets.fits',
...                          'qmostetc/tests/rulesets.csv',
...                          'qmostetc/tests/rules.csv',
...                          'qmostetc/tests')
>>> errors = cat.check_consistency()
Total 1 entries
Total 1 target/magtype/redshift combinations
Total 1 rulesets
>>> print(errors)
[]

process(table=None)¶

Process the complete catalog

This adds the columns TEXP_D, TEXP_G, TEXP_B and TEXP_S to the table, containing the exposure times for dark, grey, bright and superbright nights accordingly.

The maximum exposure time per exposure (maxdit) is set to the following values:

brightness	maxdit
dark	20 min
grey	15 min
bright	7 min
superbright	4 min

The special ruleset DONOTOBSERVE will inhibit the processing and instead set the exposure times to 0.0. On error, the exposure times will be negative.

Parameters:

tableastropy.table.QTable: Table to process. If not specified, the table of the catalog (TargetCatalog.table) is used.

static format_version_check(table)¶

Check and return the format version of the table.

Parameters:

tableastropy.table.QTable: Table to check.

Returns:

packaging.version.Version: Format version of the table

Raises:

ValueError: Unsupported catalog format version

Warns:

FormatDeprecationWarning: Format version is deprecated

static read(catalog_file, ruleset_file, rules_file, template_dir=None)¶

Read a target catalog

Parameters:

catalog_filestr or pathlib.Path: File name of the catalog file
ruleset_filestr or pathlib.Path: File name of the Ruleset file
rules_filestr or pathlib.Path: File name of the Rules file
template_dirstr or pathlib.Path: Directory with SED template files

Returns:

TargetCatalog: The target catalog

class qmostetc.Target(name, observatory, ruleset, template, mag, flt, declination, target_shape, sersic_radius=None, sersic_index=None)¶

Entry in the ETC target catalogue.

The usual way to use this is to read a catalog file with TargetCatalog.read() and to iterate over the rows.

Parameters:

namestr: Target name
observatoryQMostObservatory: Observatory/Spectrograph (LRS or HRS) to use
rulesetRuleset: Name of the Ruleset containing the spectral success criteria that should be applied to test if this target has been successfully observed.
templateSEDTemplate: Spectral template describing the predicted spectral shape of this target
magastropy.units.Quantity: Apparent magnitude for the target (already reddened). The unit depends on the target shape: [ABMag] or [VEGAMag] for point or sersic shapes, [ABMag/arcsec²] or [VEGAMag/arcsec²] for flat target shape.
fltstr: Identifier for the magnitude (filter) type. The list of accepted filters can be retrieved with the Filter.list() function.
declinationastropy.units.Quantity: Target declination [deg]
target_shapestr: Target spacial shape type. One of point, flat, or sersic. For Sersic opject type, the radius and index need to be given.
sersic_radiusastropy.units.Quantity: Sersic radius [arcsec]. Required if the target shape is sersic.
sersic_indexint: Sersic index. Required if the target shape is sersic.

Examples

Create a target from scratch and get the exposure time for it. Instead of creating the target, the ruleset and the rules manually, they are usually read in by the function TargetCatalog.read().

>>> from qmostetc import SEDTemplate, QMostObservatory, Ruleset, Rule
>>> qmost = QMostObservatory('lrs')
>>> rules = [Rule(qmost['green'], 'snG', 1*u.nm, 590.*u.nm, 610.*u.nm, 'snr', np.mean, 50.)]
>>> ruleset = Ruleset('example', 'snG', 1.)
>>> ruleset.set_rules(rules)
>>> pickles = SEDTemplate('Pickles_G0V')
>>> target = Target('example', qmost, ruleset, pickles, 20*u.ABmag, 'GAIA2r.G', 32*u.deg, 'point')
>>> texp = target.get_exptime(['dark', 'grey', 'bright'])
>>> print(f"Exposure time: {texp[0].to('min'):.0f}")
Exposure time: 158 min

get_arm_mag(arm_name, mag_unit=Unit('mag(AB)'))¶

Calculate the target magnitude within one spectrograph arm

Parameters:

arm_namestr: Spectrograph arm name. One of blue, green, red.
mag_unitastropy.units.Unit: Magnitude unit to use. Either ABmag or VEGAMag.

Returns:

astropy.units.Quantity: The target amplitude in with the arm spectrograph efficiency as filter. The return value always has the unit mag or mag/arcsec² to allow its inclusion in the output table.

get_exptime(moon_brightness, seeing=<Quantity 0.8 arcsec>, maxdit=<Quantity 30. min>, fibermags=False)¶

Calculate the exposure time for this entry

Parameters:

moon_brightnessstr or astropy.units.Quantity

Moon brightness. One of 'superbright', 'bright', 'gray' or 'dark'. Alternatively, the moon-target separation [deg] can be given directly here.

Instead of a single value, also a list may be given, f.e. ['dark', 'gray', 'bright']. In this case, the result is an array of corresponding times.

seeingastropy.units.Quantity

Optical seeing as a single Quantity at zenith [arcsec]. Default: 0.8”

maxditastropy.units.Quantity

Maximum exposure time per exposure [min]. The full exposure is assumed to be split into exposures of with that exposure time as maximum. If not given (default), the maximum exposure time 30 min.

fibermagsbool

If True, also the mean loss for the fiber mags is returned.

Returns:

astropy.units.Quantity: Calculated exposure time(s) to pass the specified rules [s].
astropy.units.Quantity: Calculated mean loss [mag] if fibermags was set to True.

get_etc(moon_brightness, seeing=<Quantity 0.8 arcsec>)¶

Return an exposure time calculator for the target

The returned object may either used to get the exposure time, or to retrieve the spectra for the used rules.

Parameters:

moon_brightnessstr or astropy.units.Quantity: Moon brightness. One of 'superbright', 'bright', 'gray' or 'dark'. Alternatively, the moon-target separation [deg] can be given directly here.
seeingastropy.units.Quantity: Optical seeing as a single Quantity at zenith [arcsec]. Default: 0.8”

Returns:

QMostETC: Exposure time calculator for the target

Examples

Retrieve the rule specific exposure table for the calculated exposure time:

>>> from qmostetc import SEDTemplate, QMostObservatory, Ruleset, Rule
>>> qmost = QMostObservatory('lrs')
>>> rules = [Rule(qmost['green'], 'snG', 1*u.nm, 590.*u.nm, 610.*u.nm, 'snr', np.mean, 50.)]
>>> ruleset = Ruleset('example', 'snG', 1.)
>>> ruleset.set_rules(rules)
>>> pickles = SEDTemplate('Pickles_G0V')
>>> target = Target('example', qmost, ruleset, pickles, 20*u.ABmag, 'GAIA2r.G', 32*u.deg, 'point')
>>> etc = target.get_etc('dark')
>>> texp = etc.get_exptime()
>>> tbl = etc.expose(texp)
>>> tbl.pprint()  
    wavelength          binwidth       ...       noise        rule
        nm                 nm          ...        adu
----------------- -------------------- ... ------------------ ----
590.0326478411431  0.03357360058043923 ... 25.231246264800767  snG
590.0662212441114  0.03357320535621966 ...  25.26277849505939  snG
              ...                  ... ...                ...  ...
609.9903259757637  0.03328556379744896 ... 25.711985455649025  snG
Length = 598 rows

get_observation(moon_brightness, seeing=<Quantity 0.8 arcsec>)¶

Return a complete observation for the target

Parameters:

moon_brightnessstr or astropy.units.Quantity: Moon brightness. One of 'superbright', 'bright', 'gray' or 'dark'. Alternatively, the moon-target separation [deg] can be given directly here.
seeingastropy.units.Quantity: Optical seeing as a single Quantity at zenith [arcsec]. Default: 0.8”

Returns:

QMostObservation: Full observation for this target.

Examples

Retrieve the complete exposure table for the calculated exposure time:

>>> from qmostetc import SEDTemplate, QMostObservatory, Ruleset, Rule
>>> qmost = QMostObservatory('lrs')
>>> rules = [Rule(qmost['green'], 'snG', 1*u.nm, 590.*u.nm, 610.*u.nm, 'snr', np.mean, 50.)]
>>> ruleset = Ruleset('example', 'snG', 1.)
>>> ruleset.set_rules(rules)
>>> pickles = SEDTemplate('Pickles_G0V')
>>> target = Target('example', qmost, ruleset, pickles, 20*u.ABmag, 'GAIA2r.G', 32*u.deg, 'point')
>>> texp = target.get_exptime('dark')
>>> tbl = target.get_observation('dark').expose(texp)
>>> tbl.pprint()  
    wavelength           binwidth      ...        noise        arm
        nm                  nm         ...         adu
----------------- -------------------- ... ------------------ ----
367.1301553502918  0.03173727926241554 ...  8.233223496737377 blue
367.1618925465504  0.03173711325484874 ...  8.280396713670427 blue
              ...                  ... ...                ...  ...
952.433732234933   0.03978621234023194 ...  15.59629820482557  red
Length = 18432 rows

class qmostetc.FormatDeprecationWarning¶

Warning about deprecated catalog format

The ETC processes only a limited range of catalog formats. Using old, but still supporded format versions will emit this warning to encourage the user migrating to the latest version.

Target catalog processing¶

Page Contents

Previous topic

Next topic

This Page

Navigation

Target catalog processing¶