Rules and Rulesets¶

Rules and Rulesets are used to specify the conditions for a successfull target observation. The Ruleset combines the results from the evaluation of one or several Rules which specify the condition within a continuous wavelength range.

class qmostetc.RulesRepository(rulesets_fname, rules_fname)¶

Repository of rules and rulesets

This object is created with the configuration files for 4MOST rulesets and the according rules. It then can be used to retrieve the ruleset with a specified name, readily initialized with the required rules. These files need to be created by the surveys, accompanying the target catalog.

Parameters:

rulesets_fnamestr: File name for the ruleset file.
rules_fnamestr: File name for the rules file.

Examples

Get a ruleset from the repository:

>>> from qmostetc import QMostObservatory
>>> qmost = QMostObservatory('lrs')
>>> repo = RulesRepository('qmostetc/tests/rulesets.csv',
...                        'qmostetc/tests/rules.csv')
>>> ruleset = repo.ruleset('Test1LR', qmost)
>>> print(ruleset)
Ruleset("Test1LR", "Seng1_LR_blue and Seng2_LR_red", 1.0)

ruleset(name, obsdict)¶

Return the specified ruleset

Parameters:

namestr or pathlib.Path: Ruleset name
obsdictQMostObservatory or dict: Dictionary of observatories; usually a QMostObservatory. This is required to create the rules.

Returns:

Ruleset: Ruleset with all rules set accordingly

rule(name, obsdict)¶

Return a specified rule

Parameters:

namestr or pathlib.Path: Rule name
obsdictQMostObservatory or dict: Dictionary of observatories; usually a QMostObservatory. This is required to create the rule.

Returns:

Rule: Rule for the specified name and observatory.

Rules¶

class qmostetc.Rule(observatory, name, delta_l, l_min, l_max, var='snr', metric=<function mean>, ref_value=None, op=<function Rule.<lambda>>)¶

A single independent logical test on a section of a spectrum

A Rule is carried out over a single contiguous wavelength interval of an 1d spectrum defined by its min and max value. The wavelength range should be withinthe wavelength range covered by one of the spectrograph channels.

Usually, the rules are read in from a CSV file.

Its evaluation returns a single float or boolean value.

Parameters:

observatorySimpleObservatory: Observatory to fullfill this observation.
namestr: Name of the rule
delta_lastropy.units.Quantity: Width where the signal should be binned [nm].
l_minastropy.units.Quantity: Minimum wavelength for which the rule should be computed [nm].
l_maxastropy.units.Quantity: Maximum wavelength for which the rule should be computed [nm]
varstr: Variable name: one of target, sky, noise, bg_noise_flux or snr (default: snr).
metriccallable: Function to apply to the data to derive a single value from the variable array (default: numpy.mean()).
ref_valuefloat or astropy.units.Quantity: Reference value to be compared to. If the reference value is None, the value is returned by itself.
opcallable: Comparison function. Takes the value as first, the reference as second argumend and returns a boolean.

Examples

Create a rule:

>>> from qmostetc import QMostObservatory
>>> qmost = QMostObservatory('lrs')
>>> r = Rule(qmost['blue'], 'LR_blue', 1.*u.AA, 5150.*u.AA, 5200.*u.AA, 'snr', np.median, 10.0)
>>> print(r)
Rule("LR_blue", 1.0 Angstrom, 5150.0 Angstrom, 5200.0 Angstrom, "snr", median, 10.0)
>>> print(r.eval_type)
<class 'bool'>
>>> r = Rule(qmost['blue'], 'GalHalo', 1.*u.AA, 4200.*u.AA, 5000.*u.AA, 'snr')
>>> print(r)
Rule("GalHalo", 1.0 Angstrom, 4200.0 Angstrom, 5000.0 Angstrom, "snr", mean, None)
>>> r.eval_type
<class 'float'>

Attributes:

observatorySimpleObservatory: Observatory to fullfill this observation.
namestr: Rule Name
delta_lastropy.units.Quantity: Width where the signal should be binned [nm].
l_minastropy.units.Quantity: Minimum wavelength for which the rule should be computed [nm].
l_maxastropy.units.Quantity: Maximum wavelength for which the rule should be computed [nm].
eval_typetype: bool if the evaluation returns a boolean value, or float if the evaluation returns a floating point value

eval(value, ignore_reference=False, acquired=None)¶

Evaluate a success criterion

Compute the science success criterion

Parameters:

valueastropy.units.Quantity: Array to evaluate.
ignore_referencebool: If set to False (default) and a reference value was given in the constructor, the calculated metric is compared with the reference and the result is returned as a bool. If set to True, then always the calculated metric is returned as float.
acquiredastropy.units.Quantity or float: If specified, this contains a single value with the pre-acquired amount for this value. This is used to calculate the remaining exposure time after some completed exposures.

Returns:

bool or float: Evaluation result

Examples

Evaluate a sample observation:

>>> from qmostetc import SEDTemplate, QMostObservatory
>>> qmost = QMostObservatory('hrs')
>>> rule = Rule(qmost['green'], 'LR_green', 1.0*u.AA, 5150.*u.AA, 5200.*u.AA, 'snr', np.median, 10.0)
>>> obs = rule.observatory(45*u.deg, 1.3*u.arcsec, 'gray')
>>> pck = SEDTemplate('Pickles_G0V')
>>> flux = pck(15*u.ABmag, 'GAIA2r.G')
>>> obs.set_target(flux, 'point')
>>> snr = obs.expose(300*u.s, 1, 'snr')
>>> rule.eval(snr)
True

static read(obsdict, filepath)¶

Read the rules from the rulelist file

Parameters:

filepathstr: Full path to the rule file

Returns:

list: List of Rules

Examples

Read in the test file provided with the package:

>>> from qmostetc import QMostObservatory
>>> qmost = QMostObservatory('lrs')
>>> for rule in Rule.read(qmost, 'qmostetc/tests/rules.csv'):
...     print(rule)
Rule("Seng1_LR_blue", 1.0 Angstrom, 5150.0 Angstrom, 5200.0 Angstrom, "snr", median, 10.0)
Rule("Seng2_LR_red", 1.0 Angstrom, 8490.0 Angstrom, 8675.0 Angstrom, "snr", median, 10.0)
Rule("GalHaloLR_blue", 1.0 Angstrom, 4200.0 Angstrom, 5000.0 Angstrom, "snr", median, None)
Rule("GalHaloLR_red", 1.0 Angstrom, 7200.0 Angstrom, 9000.0 Angstrom, "snr", median, None)

Rulesets¶

class qmostetc.Ruleset(name, expression, value=None)¶

A set of tests

That set must be satisfied for a target to be considered successfully observed. The Ruleset combines the evaluation result of several Rules. The evaluation expression if given as a Python expression. Aside from usual operations, it can use some common functions:

absolute value: abs(x)

sine, cosine, tangent: sin(x), cos(x), tan(x)

arc sine, arc cosine, arc tangent: arcsin(x), arccos(x), arctan(x), arctan2(x, y)

hyperbolic sine, hyperbolic cosine, hyperbolic tangent: sinh(x), cosh(x), tanh(x)

exponential, square root, natural log, common log: exp(x), sqrt(x), log(x), log10(x)

round to nearest int, round up to int, round down to int: round(x), ceil(x), floor(x)

random [0.0,1.0): random()

minimum, maximum: :obj`min(x)`, max(x)

Parameters:

namestr: Unique identifier for the Ruleset.
expressionstr: Python expression using the results of one or more named Rules.
valuefloat: Numeric value that defines the minimum threshold for a target to be considered “successfully observed”. This value is not required if the expression already returns a boolean.

Attributes:

namestr: Unique identifier for the Ruleset.
valuefloat: Numeric value that defines the minimum threshold for a target to be considered “successfully observed”.
expressioncode: Compiled python expression using the results of one or more named Rules.
rulesdict (str, Rule): Dictionary of the used rules. Initially, the keys are derived from the specified expression, while he value for each rule is None. The rules are later filled with set_rules().

eval(var)¶

Evaluate the success criterion

Compute the summarized science success criterion for this ruleset. The function takes the individual results of the rules and combines them with the given expression.

Parameters:

vardict: Dictionary of individual results of the rules, with the rule name as key.

Returns:

bool: Science success

set_rules(rules)¶

Set the rules required by the ruleset.

From the given list of rules, those rules are selected that are required to evaluate the ruleset. The rules need to be complete, so that an evaluation may run. This is checked, and an NameError is raised if not. If one of the selected rules or the combining expression has the wrong syntax, a SyntaxError is raised.

Parameters:

ruleslist: List of available rules

Examples

Create a new, empty ruleset, and then set the rules:

>>> from qmostetc import QMostObservatory
>>> qmost = QMostObservatory('lrs')
>>> rules = [Rule(qmost["blue"], "LR_blue", 1*u.AA, 5150*u.AA, 5200*u.AA, "snr", np.median, 10.0),
...          Rule(qmost["red"], "LR_red", 1*u.AA, 8490*u.AA, 8675*u.AA, "snr", np.median, 10.0),
...          Rule(qmost["blue"], "GalHaloB", 1*u.AA, 4200*u.AA, 5000*u.AA, "snr", np.median),
...          Rule(qmost["red"], "GalHaloR", 1*u.AA, 7200*u.AA, 9000*u.AA, "snr", np.median)]
>>> ruleset = Ruleset('TestLR', '(GalHaloB)+(GalHaloR**2)', 2.5)
>>> ruleset.set_rules(rules)
>>> for rule in ruleset.rules.values():
...     print(rule)
Rule("GalHaloB", 1.0 Angstrom, 4200.0 Angstrom, 5000.0 Angstrom, "snr", median, None)
Rule("GalHaloR", 1.0 Angstrom, 7200.0 Angstrom, 9000.0 Angstrom, "snr", median, None)

etc(airmass, seeing, moon_brightness=None)¶

Create an ETC for the specified observing conditions

Parameters:

airmassfloat or astropy.units.Quantity: Airmass to use (default 1.0). The airmass may also be given as zenith angle [deg].
seeingastropy.units.Quantity: Optical seeing as a single Quantity at zenith [deg].
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. If not specified here, the sky spectrum must be given later with QMostETC.set_moon_brightness() or with QMostETC.set_sky().

Returns:

QMostETC: ETC class to calculate the exposure time for the specified ambient conditions.

Examples

Calculate the exposure time for a certain rule on the green LRS spectrograph with a Pickles like target:

>>> from qmostetc import SEDTemplate, QMostObservatory
>>> 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)
>>> pck = SEDTemplate('Pickles_G0V')
>>> flux = pck(20*u.ABmag, 'GAIA2r.G')
>>> etc = ruleset.etc(45*u.deg, 1.3*u.arcsec, 'dark')
>>> etc.set_target(flux, 'point')
>>> texp = etc.get_exptime(maxdit=30*u.min)
>>> print(f"Exposure time: {texp.to('min'):.0f}")
Exposure time: 248 min

static read(filepath)¶

Read the rulesets

Parameters:

fpfile_like: Input file, opened with open()

Returns:

list: List of rulesets

Examples

Open the example ruleset that is provided with the package:

>>> for ruleset in Ruleset.read('qmostetc/tests/rulesets.csv'):
...     print(ruleset)  
Ruleset("Test1LR", ...)
Ruleset("Test12LR", ...)

Rules and Rulesets¶

Rules¶

Rulesets¶

Page Contents

Previous topic

Next topic

This Page

Navigation

Rules and Rulesets¶

Rules¶

Rulesets¶