rads.config package

Submodules

• rads.config.ast module
• rads.config.builders module
• rads.config.grammar module
• rads.config.loader module
• rads.config.text_parsers module
• rads.config.tree module
• rads.config.utility module
• rads.config.xml_parsers module
  • Exceptions
  • Parser Combinators (class based API)
  • Parser Combinators (function based API)

Module contents

PyRADS configuration file API.

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

Bases: object

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.Config(pre_config: rads.config.tree.PreConfig, satellites: Mapping[str, rads.config.tree.Satellite])

Bases: object

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.Constant(value: Union[int, float])

Bases: object

dataclass: Numerical constant for the data field.

value

The constant numerical value.

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

Bases: object

dataclass: Cycle range ‘inclusive’.

first

First cycle of the range.

last

Last cycle of the range.

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

Bases: object

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.MultiBitFlag(bit: int, length: int)

Bases: rads.config.tree.Flags

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.NetCDFAttribute(name: str, variable: Optional[str] = None, branch: Optional[str] = None)

Bases: object

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)

Bases: object

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.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)

Bases: object

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.Range(min: N, max: N)

Bases: typing.Generic

dataclass: Numerical range (inclusive).

min

Minimum value in range.

max

Maximum value in range.

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

Bases: object

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.Repeat(days: float, passes: int, longitude_drift: Optional[float] = None)

Bases: object

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.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>)

Bases: object

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.SingleBitFlag(bit: int)

Bases: rads.config.tree.Flags

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.SubCycles(lengths: Sequence[int], start: Optional[int] = None)

Bases: object

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.

class rads.config.SurfaceType

Bases: rads.config.tree.Flags

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.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)

Bases: typing.Generic

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.