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])[source] 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[source] 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[typing.Union[int, float, bool]][Union[int, float, bool]]] = <factory>)[source] 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[source] 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)[source] 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: Union[int, float, bool, None] = None)[source] 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 constantCompleteExpression
- 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 fileNetCDFVariable
- 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
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)[source] 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)[source] 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)[source] 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)[source] 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])[source] dataclass: Numerical constant for the data field.
-
value
The constant numerical value.
-
-
class
rads.rpn.
CompleteExpression
(tokens: Union[str, Iterable[Union[int, float, bool, str, rads.rpn.Token]]])[source] 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.
- 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[source] Return this expression as it is already complete.
- Returns
This complete expression.
-
eval
(environment: Optional[Mapping[str, Union[int, float, bool, numpy.generic, numpy.ndarray]]] = None) → Union[int, float, bool, numpy.generic, numpy.ndarray][source] 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
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)[source] 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][source] 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)[source] 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][source] 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
[source] 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][source] 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')[source] 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)[source] 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)[source] 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)[source] 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)[source] dataclass: Numerical range (inclusive).
-
min
Minimum value in range.
-
max
Maximum value in range.
-