rads.config

These dataclasses make up the configuration tree returned by rads.load_config(). They are documented here to aid in modification of the returned configuration or for scratch construction of a rads.config.Config object.

class rads.config.Config(pre_config: rads.config.tree.PreConfig, satellites: Mapping[str, rads.config.tree.Satellite])

dataclass: PyRADS configuration.

Parameters

• pre_config – The pre-configuration object to use when loading this configuration object.

• satellites – A mapping of 2 character satellite names to satellite descriptor objects.

dataroot

Path to the RADS data root.

config_files

Paths to the XML configuration files used to load this configuration.

The order is the same as they were loaded.

satellites

Mapping from 2 character satellite ID’s to satellite descriptors.

See Satellite.

full_string() → str

Get full human friendly string representation.

Unlike __str__() this prints the full representation of the satellites.

Returns

Human readable string representation of the PyRADS configuration.

class rads.config.Satellite(id: str, id3: str, name: str, names: Sequence[str], dt1hz: float, inclination: float, frequency: Sequence[float], phases: Sequence[rads.config.tree.Phase] = <factory>, aliases: Mapping[str, Sequence[str]] = <factory>, variables: Mapping[str, rads.config.tree.Variable[float][float]] = <factory>)

dataclass: Satellite descriptor.

id

2 character satellite ID.

id3

3 character satellite ID.

name

Satellite name.

Note

While PyRADS places no restrictions on the length of this field to maintain compatibility with RADS it should be no longer than 8 characters.

names

Alternate satellite names.

dt1hz

Time step of 1-Hz data (in seconds).

inclination

Orbital inclination in degrees.

frequency

List of altimeter frequencies.

phases

Mapping from 1 character phase ID’s to lists of mission phases.

Note

This being a mapping to a list of mission phases is a necessary evil brought about by satellites such as Sentinel-3B which change orbit during a mission phase.

See Phase.

aliases

Mapping from pseudo variables to a list of RADS variables.

When the pseudo variable is accessed any of the RADS variables listed here can be used. In particular, the first one available will be used.

variables

Mapping from variable name identifiers to variable descriptors.

These are all the variables supported by the satellite.

See Variable.

full_string() → str

Get full human friendly string representation.

Unlike __str__() this prints the full representation of the phases, aliases, and variables.

Returns

Human readable string representation of the configuration for the satellite.

class rads.config.Phase(id: str, mission: str, cycles: rads.config.tree.Cycles, repeat: rads.config.tree.Repeat, reference_pass: rads.config.tree.ReferencePass, start_time: datetime.datetime, end_time: Optional[datetime.datetime] = None, subcycles: Optional[rads.config.tree.SubCycles] = None)

dataclass: Mission phase.

id

Single letter ID of the mission phase.

mission

Descriptive name of the mission phase.

cycles

Cycle range.

See Cycles.

repeat

Repeat cycle (not sub cycle) information.

See Repeat.

reference_pass

Equator crossing reference pass.

See ReferencePass.

start_time

Date and time the mission phase began.

end_time = None

Date and time the mission phase ended. This is only provided for the last mission phase of a given satellite (if that satellite has been decommissioned). In all other instances it is None.

subcycles = None

Sub cycle information for satellites with sub cycles, None otherwise.

See SubCycles.

class rads.config.Variable(id: str, name: str, data: Union[rads.config.tree.Constant, rads.rpn.CompleteExpression, rads.config.tree.Flags, rads.config.tree.Grid, rads.config.tree.NetCDFAttribute, rads.config.tree.NetCDFVariable], units: Union[cf_units.Unit, str] = cf_units.Unit, standard_name: Optional[str] = None, source: str = '', comment: str = '', flag_values: Optional[Sequence[str]] = None, flag_masks: Optional[Sequence[str]] = None, limits: Optional[rads.config.tree.Range[~N][N]] = None, plot_range: Optional[rads.config.tree.Range[~N][N]] = None, quality_flag: Optional[Sequence[str]] = None, dimensions: int = 1, format: Optional[str] = None, compress: Optional[rads.config.tree.Compress] = None, default: Optional[float] = None)

dataclass: A RADS variable descriptor.

id

Name identifier of the variable.

name

Descriptive name of the variable

data

What data backs the variable.

This can be any of the following:

• Constant - a numeric constant

• CompleteExpression - a mathematical combination of other RADS variables.

• Flags - an integer or boolean extracted from the “flags” RADS variable.

• Grid - an interpolated grid (provided by an external NetCDF file)

• NetCDFAttribute - a NetCDF attribute in the pass file

• NetCDFVariable - a NetCDF variable in the pass file

units

The variable’s units.

There are three units used by RADS that are not supported by cf_units.Unit. The following table gives the mapping:

Unit String	cf_units.Unit
db	Unit("no_unit")
decibel	Unit("no_unit")
yymmddhhmmss	Unit("unknown")

See cf_units.Unit.

standard_name = None

CF-1.7 compliant “standard_name”.

source = ''

Documentation of the source of the variable.

comment = ''

Comment string for the variable.

flag_values = None

List of the meanings of the integers of a enumerated flag variable.

This is mutually exclusive with flag_masks.

flag_masks = None

List of the meanings of the bits (LSB to MSB) for a bit flag variable.

This is mutually exclusive with flag_values.

limits = None

Valid range of the variable.

If outside this range the variable’s data is considered bad and should be masked out.

See Range.

plot_range = None

Recommended plotting range for the variable.

See Range.

quality_flag = None

List of RADS variables that when bad make this variable bad as well.

dimensions = 1

Dimensionality of the variable.

format = None

Recommended format string to use when printing the variable’s value.

compress = None

Compression scheme used for the variable.

See Compress.

default = None

Default numerical or boolean value to use when data sources is unavailable.

Phase Nodes

class rads.config.Cycles(first: int, last: int)

dataclass: Cycle range ‘inclusive’.

first

First cycle of the range.

last

Last cycle of the range.

class rads.config.Repeat(days: float, passes: int, longitude_drift: Optional[float] = None)

dataclass: Length of the repeat cycle.

Note

With many satellites now using non exact repeats this is of questionable use since it is frequently disconnected from numbered cycles (which are actually sub cycles).

days

Number of days in a repeat cycle.

passes

Number of passes in a repeat cycle.

longitude_drift = None

Longitudinal drift per repeat cycle.

class rads.config.ReferencePass(time: datetime.datetime, longitude: float, cycle_number: int, pass_number: int, absolute_orbit_number: int = 1)

dataclass: Reference equator crossing.

This stores information related to a reference equator crossing used to fix the satellite in time and space.

time

Equator crossing time of the reference pass in UTC.

longitude

Longitude of the equator crossing of the reference pass.

cycle_number

Cycle number of the reference pass.

pass_number

Pass number of the reference pass.

absolute_orbit_number = 1

Absolute orbit number of reference pass.

class rads.config.SubCycles(lengths: Sequence[int], start: Optional[int] = None)

dataclass: Lengths of sub cycles.

lengths

List of the number of passes for each sub cycle.

start = None

Start cycle of the sub cycle sequence. Can be None, in which case the sub cycle sequence starts with the first cycle of the phase.

Variable Nodes

class rads.config.Constant(value: Union[int, float])

dataclass: Numerical constant for the data field.

value

The constant numerical value.

class rads.rpn.CompleteExpression(tokens: Union[str, Iterable[Union[float, str, rads.rpn.Token]]])

Reverse Polish Notation expression that can be evaluated.

Parameters

tokens –

A Reverse Polish Notation expression given as a sequence of tokens or a string of tokens.

Note

This parameter is very forgiving. If given a sequence of tokens and some of the elements are not Tokens then then an attempt will be made to convert them to Tokens. Because of this both numbers and strings can be given in the sequence of tokens.

Raises

ValueError – If the sequence or string of tokens represents an invalid expression. This exception also indicates which token makes the expression invalid.

complete() → rads.rpn.CompleteExpression

Return this expression as it is already complete.

Returns

This complete expression.

eval(environment: Optional[Mapping[str, Union[float, numpy.generic, numpy.ndarray]]] = None) → Union[float, numpy.generic, numpy.ndarray]

Evaluate the expression and return a numerical or logical result.

Parameters

environment –

A mapping to lookup variables in when evaluating the expression. If not provided an empty mapping will be used, this is fine as long as the expression does not contain any variables. This can be ascertained by checking the with the variables attribute:

if not expression.variables:
    expression.eval()

If the evaluation is lengthy or there are side effects to key lookup in the environment it may be beneficial to check for any missing variables first:

missing_vars = expression.variables.difference(environment)

Returns

The numeric or logical result of the expression.

Raises

• TypeError –

  If there is a type mismatch with one of the operators and a value.

  Note

  While this class includes a static syntax checker that runs upon initialization it does not know the type of variables in the given environment ahead of time.

• KeyError – If the expression contains a variable that is not within the given environment.

• IndexError, ValueError, RuntimeError, ZeroDivisionError – If arguments to operators in the expression do not have the proper dimensions or values for the operators to produce a result. See the documentation of each operator for specifics.

class rads.config.SingleBitFlag(bit: int)

dataclass: A single bit flag.

This type of flag is used for extracting true/false from a given bit.

This indicates that a single bit in the “flags” RADS variable is to be used as the data for the RADS variable.

Raises

• TypeError – If bit is not an integer.

• ValueError – If bit is negative.

bit

Bit index (starting at 0) where the flag is located.

extract(flags: Union[int, numpy.generic, numpy.ndarray]) → Union[int, numpy.generic, numpy.ndarray]

Extract the flag value from a number or array.

Parameters

flags – Integer or array of integers to extract flag value from.

Returns

A bool or an array of booleans which is the value of the extracted flag.

class rads.config.MultiBitFlag(bit: int, length: int)

dataclass: A single bit flag.

This type of flag is used for extracting true/false from a given bit.

This indicates that 2 or more continuous bits in the “flags” RADS variable are to be used as the data for the RADS variable.

Raises

• TypeError – If bit or length are not integers.

• ValueError – If bit is negative or length is less than 2.

bit

Bit index (starting at 0) where the flag is located.

length

Length of the flag in bits.

extract(flags: Union[int, numpy.generic, numpy.ndarray]) → Union[int, numpy.generic, numpy.ndarray]

Extract the flag value from a number or array.

Parameters

flags – Integer or array of integers to extract flag value from.

Returns

An integer or an array of integers which is the value of the extracted flag.

class rads.config.SurfaceType

dataclass: Surface type flag.

This is special flag that is based on the 3, 4, and 5 bits (zero indexed) of the underlying data and results in one of the following numerical values:

• 0 - ocean

• 2 - enclosed sea or lake

• 3 - land

• 4 - continental ice

This indicates that the surface type integer (above) is to be extracted from the “flags” RADS variable and used as the data for the RADS variable.

extract(flags: Union[int, numpy.generic, numpy.ndarray]) → Union[int, numpy.generic, numpy.ndarray]

Extract the flag value from a number or array.

Parameters

flags – Integer or array of integers to extract flag value from.

Returns

The surface type integer or an array of surface type integers.

class rads.config.Grid(file: str, x: str = 'lon', y: str = 'lat', method: str = 'linear')

dataclass: Grid file for the data field.

This indicates that the value of the grid in the NetCDF file is to be interpolated to provide data for the RADS variable.

file

NetCDF file containing the grid. This file can only contain one 2-dimensional variable.

x = 'lon'

Name of the RADS variable giving the x-coordinate for interpolation.

y = 'lat'

Name of the RADS variable giving the y-coordinate for interpolation.

method = 'linear'

Interpolation method to lookup values in the grid.

The options are:

• “linear” - bilinear interpolation

• “spline” - cubic spline interpolation

• “nearest” - nearest neighbor lookup

class rads.config.NetCDFAttribute(name: str, variable: Optional[str] = None, branch: Optional[str] = None)

dataclass: NetCDF attribute for the data field.

This indicates that the value of the NetCDF attribute from the pass file is to be used as the data for the RADS variable.

name

Name of the NetCDF attribute.

variable = None

Variable that the attribute is under. None for global.

branch = None

Postfix to append to 2 character mission folder when loading the file.

Note

PyRADS supports an unlimited number of branches. However, to maintain compatibility with RADS no more than 4 should be used.

class rads.config.NetCDFVariable(name: str, branch: Optional[str] = None)

dataclass: NetCDF variable for the data field.

This indicates that the value of the NetCDF variable from the pass file is to be used as the data for the RADS variable.

name

Name of hte NetCDF variable.

branch = None

Postfix to append to 2 character mission folder when loading the file.

Note

PyRADS supports an unlimited number of branches. However, to maintain compatibility with RADS no more than 4 should be used.

class rads.config.Compress(type: numpy.dtype, scale_factor: Union[int, float] = 1, add_offset: Union[int, float] = 0)

dataclass: Variable compression.

This can usally be ignored by the end user, but may prove useful if extracting and saving data into another file.

To store the variable x:

x_store = ((x - add_offset) * scale_factor).astype(type)

To unpack the variable x:

x = (x_store/scale_factor + add_offset).astype(np.float64)

type

Type of stored data as a Numpy type.

scale_factor = 1

Scale factor of stored data.

add_offset = 0

Add offset of stored data.

class rads.config.Range(min: N, max: N)

dataclass: Numerical range (inclusive).

min

Minimum value in range.

max

Maximum value in range.