pysiral.l1data

Created on Tue Jul 07 14:10:34 2015

@author: Stefan

L1bdata is a data container that unifies radar altimeter L1b orbit data from different missions. It allows subsetting and merging of adjacent orbit segments. L1bdata can be stored as a netCDF file, thus allowing faster access to pre-processed subsets of RA orbit data for L2 processing.

The scope of the L1bdata container comprises:

Metadata:

descriptors of RA source data
period and geographical location
processing history (subsetted, merged)
software version

Waveform Data

waveform echo power dimension: (n_records, n_range_bins)
range for each range bin to the satellite in meters dimension: (n_records, n_range_bins)
radar mode flag for each waveform:
- 0: LRM
- 1: SAR
- 2: SIN
(this is necessary for merging CryoSat-2 SAR and SIN adjacent orbit segments)
summarizing flag from source data
0: invalid 1: valid
optional: Additional named flags

Time-Orbit Information

timestamp in UTC
longitude, latitude (of satellite/nadir point)
altitude (of satellite above WGS84 reference ellipsoid)

All parameter are of dimension (n_records).

Range Corrections

A list of range corrections (usually from RA source data files). The list of correction is not predefined, but usally contains range corrections for:

dry troposphere
wet troposphere
ionosphere
inverse barometric / dynamic atmosphere
ocean tide
solid earth tide
long period tide
pole tide
tidal loading

All parameter are of dimension (n_records) and of unit meter

Classifier

A list of optional named parameters that can be used for waveform classification in the L2 processor. (e.g. stack parameter from the CryoSat-2 l1b files)

All parameter are of dimension (n_records)

Surface Type

Attributes

DATE2NUM_UNIT

Classes

`Level1bData`	Unified L1b Data Class
`L1bdataNCFile`	Unified L1b Data Class
`L1bMetaData`	Container for L1B Metadata information
`L1bTimeOrbit`	Container for Time and Orbit Information of L1b Data
`L1bRangeCorrections`	Container for Range Correction Information
`L1bClassifiers`	Containier for parameters that can be used as classifiers
`L1bWaveforms`	Container for Echo Power Waveforms

Module Contents

pysiral.l1data.DATE2NUM_UNIT = 'seconds since 1970-01-01 00:00:00.0'

class pysiral.l1data.Level1bData

Bases: object

Unified L1b Data Class

data_groups = ['time_orbit', 'correction', 'classifier', 'waveform', 'surface_type']

info

waveform

time_orbit

correction

classifier

surface_type

append(l1b_annex: Level1bData, remove_overlap: bool = False, warn_if_temporal_offset_seconds: int = 10, raise_on_error: bool = False) → None

Appends another l1b object to this one. The l1b_annex object is expected to have data after the self instance.

Parameters:

l1b_annex – The Level-1B dataset to be appended
remove_overlap – Trim the appending L1 object in case of temporal overlap
warn_if_temporal_offset_seconds
raise_on_error – Raise an exception if the appending process fails, otherwise an error is logged and the appending is skipped

Returns:

None, current L1 object is changed in-place

trim_to_subset(subset_list: List | numpy.typing.NDArray) → None: Create a subset from an index list

apply_range_correction(correction): Apply range correction

extract_subset(subset_list): Same as trim_to_subset, except returns a new l1bdata instance

extract_region_of_interest(roi): Extracts data for a given region of interest definition

detect_and_fill_gaps(gap_tolerance=0.02): Some radar altimeter input products are not provided with a regular time/sample spacing, e.g. by omitting short sections of the along-track data. This method is supposed to rectify that by 1. Compute the nominal data repitition rate (in seconds) 2. Detect gaps in the timestamp value 3. Fills all arrays in all data groups with empty values

(no interpolation)

update_l1b_metadata()

update_data_limit_attributes(): Set latitude/longitude and timestamp limits in the metadata container

update_waveform_statistics(): Compute waveform metadata attributes

update_surface_type_statistics(): Re-calculate the open ocean percent

update_region_name(): Estimate the region (north/south/global) for metatdata class

reduce_waveform_bin_count(target_count: int, maxloc: float = 0.4) → None

Reduce the bin count of waveform power and range arrays. (e.g. for merging CryoSat-2 SAR [256 bins] and SIN [1024 bins])

Creates a subset and updates the l1b.waveform container

Parameters:

target_count – target number of waveform bins (needs to be smaller than full waveform bin count)
maxloc – preferred location of the maximum of the waveform in the subset

Raises:

None –

Returns:

None

increase_waveform_bin_count(target_count: int) → None

Increase the bin count of waveform power and range arrays. (e.g. for merging CryoSat-2 LRM [128 bins] and SAR [256 bins])

Creates a subset and updates the l1b.waveform container

Parameters:: target_count – target number of waveform bins (needs to be bigger than full waveform bin count)
Raises:: None –
Returns:: None

get_parameter_by_name(data_group: str, parameter_name: str) → None | numpy.ndarray

API method to retrieve any parameter from any data group

Parameters:

data_group
parameter_name

Returns:

set_parameter_by_name(data_group_name: str, parameter_name: str, value: numpy.ndarray) → None: API method to set any parameter in any data group

property n_records: int

property tcs: datetime.datetime

property tce: datetime.datetime

property radar_modes

class pysiral.l1data.L1bdataNCFile(filename)

Bases: Level1bData

Unified L1b Data Class

filename

time_def

ncattrs_ignore_list = ['_NCProperties']

parse(): populated the L1b data container from the l1bdata netcdf file

_import_metadata(nc): transfers l1b metadata attributes (stored as global attributes in l1bdata netCDF files)

_import_timeorbit(nc): transfers l1b timeorbit group (timeorbit datagroup in l1bdata netCDF files)

_import_waveforms(nc): transfers l1b waveform group (waveform datagroup in l1bdata netCDF files)

_import_corrections(nc): transfers l1b corrections group (waveform corrections in l1bdata netCDF files)

_import_surface_type(nc): transfers l1b surface_type group (waveform corrections in l1bdata netCDF files)

_import_classifier(nc): transfers l1b corrections group (waveform corrections in l1bdata netCDF files)

class pysiral.l1data.L1bMetaData

Bases: object

Container for L1B Metadata information (see property attribute_list for a list of attributes)

_attribute_list = ['pysiral_version', 'mission', 'mission_data_version', 'mission_sensor', 'mission_data_source',...

_attrs

__repr__()

__getattr__(item): Modify the attribute getter to provide a shortcut to the data content :param item: Name of the parameter :return:

property attribute_list

property attdict: Return attributes as dictionary (e.g. for netCDF export)

property hemisphere

property year

property month

set_attribute(tag, value)

check_n_records(n_records: int) → None

First time a data set is set: Store number of records as reference

Parameters:: n_records – Number of records
Returns:: None
Raises:: ValueError

class pysiral.l1data.L1bTimeOrbit(info, is_evenly_spaced=True)

Bases: object

Container for Time and Orbit Information of L1b Data

_info

_timestamp = None

_longitude = None

_latitude = None

_altitude = None

_altitude_rate = None

_antenna_pitch = None

_antenna_roll = None

_antenna_yaw = None

_antenna_mispointing = None

_orbit_flag = None

_is_evenly_spaced = True

property longitude

property latitude

property altitude

property altitude_rate

property antenna_pitch

property antenna_roll

property antenna_yaw

property antenna_mispointing

property orbit_flag

property timestamp

property parameter_list

property geolocation_parameter_list

property dimdict: Returns dictionary with dimensions

property is_evenly_spaced

set_position(longitude, latitude, altitude, altitude_rate=None)

set_antenna_attitude(pitch, roll, yaw, mispointing=None)

append(annex)

set_subset(subset_list)

fill_gaps(corrected_n_records, gap_indices, indices_map): API gap filler method. Note: It is assumed that this method is only evoked for filling small gaps. Therefore, we use simple linear interpolation for the parameters of the time orbit group

get_parameter_by_name(name)

static mispointing_from_angles(pitch_deg: numpy.typing.NDArray, roll_deg: numpy.typing.NDArray, heading_deg: numpy.typing.NDArray) → numpy.typing.NDArray

Compute the mispointing (angle between -z direction in spacecraft frame and true nadir) from pitch/roll/heading, assuming rotation of spacecraft is around antenna.

Parameters:

pitch_deg – pitch angles (rotation around y-axis)
roll_deg – roll angles (rotation around x-axis)
heading_deg – true heading (rotation around z-axis)

Returns:

mispointing angle in degrees

__getstate__()

__setstate__(d)

class pysiral.l1data.L1bRangeCorrections(info)

Bases: object

Container for Range Correction Information

_info

_parameter_list = []

set_parameter(tag, value)

property parameter_list

property n_records

property dimdict: Returns dictionary with dimensions

get_parameter_by_index(index)

get_parameter_by_name(name)

append(annex)

set_subset(subset_list)

fill_gaps(corrected_n_records, gap_indices, indices_map): API gap filler method. Note: Gaps will be filled with the nodata=0.0 value

class pysiral.l1data.L1bClassifiers(info)

Bases: object

Containier for parameters that can be used as classifiers

_info

_list

add(value, name, classifier_type='surface_type'): Add a parameter for a given classifier type

property parameter_list

property n_records

property dimdict: Returns dictionary with dimensions

has_parameter(parameter_name)

get_parameter(parameter_name: str, raise_on_error: bool = False) → numpy.ndarray | None

append(annex)

set_subset(subset_list)

fill_gaps(corrected_n_records, gap_indices, indices_map): API gap filler method. Note: Gaps will be filled with the nodata=nan value

__getattr__(item: str) → Any

Direct attribute access to the cfg dictionary

Parameters:: item
Returns:

__getstate__()

__setstate__(d)

class pysiral.l1data.L1bWaveforms(info)

Bases: object

Container for Echo Power Waveforms

_valid_radar_modes = ['lrm', 'sar', 'sin']

_parameter_list = ['power', 'range', 'radar_mode', 'is_valid', 'classification_flag']

_attribute_list = ['echo_power_unit']

_info

echo_power_unit = None

radar_mode_def

_power = None

_range = None

_radar_mode = None

_is_valid = None

_classification_flag = None

property power

property classification_flag

property range

property radar_mode

property is_valid

property parameter_list

property n_range_bins

property n_records

property radar_modes: str | List[str]

property num_radar_modes: int

property dimdict: Returns dictionary with dimensions

set_waveform_data(power, range, radar_mode, classification_flag=None): Set the waveform data :param power: :param range: :param radar_mode: :param classification_flag: :return:

set_valid_flag(valid_flag)

set_classification_flag(classification_flag): Add or update the waveform classification flag :param classification_flag: intarray with shape (n_records, n_range_bins) :return:

append(annex)

set_subset(subset_list)

add_range_delta(range_delta): Add a range delta to all range bins :param range_delta: :return:

fill_gaps(corrected_n_records, gap_indices, indices_map): API gap filler method. Note: Gaps will be filled with custom values for each parameter, see below

_get_wfm_shape(index)