pysiral.l1data ============== .. py:module:: pysiral.l1data .. autoapi-nested-parse:: 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 ---------- .. autoapisummary:: pysiral.l1data.DATE2NUM_UNIT Classes ------- .. autoapisummary:: pysiral.l1data.Level1bData pysiral.l1data.L1bdataNCFile pysiral.l1data.L1bMetaData pysiral.l1data.L1bTimeOrbit pysiral.l1data.L1bRangeCorrections pysiral.l1data.L1bClassifiers pysiral.l1data.L1bWaveforms Module Contents --------------- .. py:data:: DATE2NUM_UNIT :value: 'seconds since 1970-01-01 00:00:00.0' .. py:class:: Level1bData Bases: :py:obj:`object` Unified L1b Data Class .. py:attribute:: data_groups :value: ['time_orbit', 'correction', 'classifier', 'waveform', 'surface_type'] .. py:attribute:: info .. py:attribute:: waveform .. py:attribute:: time_orbit .. py:attribute:: correction .. py:attribute:: classifier .. py:attribute:: surface_type .. py:method:: 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. :param l1b_annex: The Level-1B dataset to be appended :param remove_overlap: Trim the appending L1 object in case of temporal overlap :param warn_if_temporal_offset_seconds: :param raise_on_error: Raise an exception if the appending process fails, otherwise an error is logged and the appending is skipped :return: None, current L1 object is changed in-place .. py:method:: trim_to_subset(subset_list: Union[List, numpy.typing.NDArray]) -> None Create a subset from an index list .. py:method:: apply_range_correction(correction) Apply range correction .. py:method:: extract_subset(subset_list) Same as trim_to_subset, except returns a new l1bdata instance .. py:method:: extract_region_of_interest(roi) Extracts data for a given region of interest definition .. py:method:: 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) .. py:method:: update_l1b_metadata() .. py:method:: update_data_limit_attributes() Set latitude/longitude and timestamp limits in the metadata container .. py:method:: update_waveform_statistics() Compute waveform metadata attributes .. py:method:: update_surface_type_statistics() Re-calculate the open ocean percent .. py:method:: update_region_name() Estimate the region (north/south/global) for metatdata class .. py:method:: 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 :param target_count: target number of waveform bins (needs to be smaller than full waveform bin count) :param maxloc: preferred location of the maximum of the waveform in the subset :raises None: :return: None .. py:method:: 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 :param target_count: target number of waveform bins (needs to be bigger than full waveform bin count) :raises None: :return: None .. py:method:: get_parameter_by_name(data_group: str, parameter_name: str) -> Union[None, numpy.ndarray] API method to retrieve any parameter from any data group :param data_group: :param parameter_name: :return: .. py:method:: 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 .. py:property:: n_records :type: int .. py:property:: tcs :type: datetime.datetime .. py:property:: tce :type: datetime.datetime .. py:property:: radar_modes .. py:class:: L1bdataNCFile(filename) Bases: :py:obj:`Level1bData` Unified L1b Data Class .. py:attribute:: filename .. py:attribute:: time_def .. py:attribute:: ncattrs_ignore_list :value: ['_NCProperties'] .. py:method:: parse() populated the L1b data container from the l1bdata netcdf file .. py:method:: _import_metadata(nc) transfers l1b metadata attributes (stored as global attributes in l1bdata netCDF files) .. py:method:: _import_timeorbit(nc) transfers l1b timeorbit group (timeorbit datagroup in l1bdata netCDF files) .. py:method:: _import_waveforms(nc) transfers l1b waveform group (waveform datagroup in l1bdata netCDF files) .. py:method:: _import_corrections(nc) transfers l1b corrections group (waveform corrections in l1bdata netCDF files) .. py:method:: _import_surface_type(nc) transfers l1b surface_type group (waveform corrections in l1bdata netCDF files) .. py:method:: _import_classifier(nc) transfers l1b corrections group (waveform corrections in l1bdata netCDF files) .. py:class:: L1bMetaData Bases: :py:obj:`object` Container for L1B Metadata information (see property attribute_list for a list of attributes) .. py:attribute:: _attribute_list :value: ['pysiral_version', 'mission', 'mission_data_version', 'mission_sensor', 'mission_data_source',... .. py:attribute:: _attrs .. py:method:: __repr__() .. py:method:: __getattr__(item) Modify the attribute getter to provide a shortcut to the data content :param item: Name of the parameter :return: .. py:property:: attribute_list .. py:property:: attdict Return attributes as dictionary (e.g. for netCDF export) .. py:property:: hemisphere .. py:property:: year .. py:property:: month .. py:method:: set_attribute(tag, value) .. py:method:: check_n_records(n_records: int) -> None First time a data set is set: Store number of records as reference :param n_records: Number of records :return: None :raises: ValueError .. py:class:: L1bTimeOrbit(info, is_evenly_spaced=True) Bases: :py:obj:`object` Container for Time and Orbit Information of L1b Data .. py:attribute:: _info .. py:attribute:: _timestamp :value: None .. py:attribute:: _longitude :value: None .. py:attribute:: _latitude :value: None .. py:attribute:: _altitude :value: None .. py:attribute:: _altitude_rate :value: None .. py:attribute:: _antenna_pitch :value: None .. py:attribute:: _antenna_roll :value: None .. py:attribute:: _antenna_yaw :value: None .. py:attribute:: _antenna_mispointing :value: None .. py:attribute:: _orbit_flag :value: None .. py:attribute:: _is_evenly_spaced :value: True .. py:property:: longitude .. py:property:: latitude .. py:property:: altitude .. py:property:: altitude_rate .. py:property:: antenna_pitch .. py:property:: antenna_roll .. py:property:: antenna_yaw .. py:property:: antenna_mispointing .. py:property:: orbit_flag .. py:property:: timestamp .. py:property:: parameter_list .. py:property:: geolocation_parameter_list .. py:property:: dimdict Returns dictionary with dimensions .. py:property:: is_evenly_spaced .. py:method:: set_position(longitude, latitude, altitude, altitude_rate=None) .. py:method:: set_antenna_attitude(pitch, roll, yaw, mispointing=None) .. py:method:: append(annex) .. py:method:: set_subset(subset_list) .. py:method:: 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 .. py:method:: get_parameter_by_name(name) .. py:method:: mispointing_from_angles(pitch_deg: numpy.typing.NDArray, roll_deg: numpy.typing.NDArray, heading_deg: numpy.typing.NDArray) -> numpy.typing.NDArray :staticmethod: Compute the mispointing (angle between -z direction in spacecraft frame and true nadir) from pitch/roll/heading, assuming rotation of spacecraft is around antenna. :param pitch_deg: pitch angles (rotation around y-axis) :param roll_deg: roll angles (rotation around x-axis) :param heading_deg: true heading (rotation around z-axis) :return: mispointing angle in degrees .. py:method:: __getstate__() .. py:method:: __setstate__(d) .. py:class:: L1bRangeCorrections(info) Bases: :py:obj:`object` Container for Range Correction Information .. py:attribute:: _info .. py:attribute:: _parameter_list :value: [] .. py:method:: set_parameter(tag, value) .. py:property:: parameter_list .. py:property:: n_records .. py:property:: dimdict Returns dictionary with dimensions .. py:method:: get_parameter_by_index(index) .. py:method:: get_parameter_by_name(name) .. py:method:: append(annex) .. py:method:: set_subset(subset_list) .. py:method:: fill_gaps(corrected_n_records, gap_indices, indices_map) API gap filler method. Note: Gaps will be filled with the nodata=0.0 value .. py:class:: L1bClassifiers(info) Bases: :py:obj:`object` Containier for parameters that can be used as classifiers .. py:attribute:: _info .. py:attribute:: _list .. py:method:: add(value, name, classifier_type='surface_type') Add a parameter for a given classifier type .. py:property:: parameter_list .. py:property:: n_records .. py:property:: dimdict Returns dictionary with dimensions .. py:method:: has_parameter(parameter_name) .. py:method:: get_parameter(parameter_name: str, raise_on_error: bool = False) -> Union[numpy.ndarray, None] .. py:method:: append(annex) .. py:method:: set_subset(subset_list) .. py:method:: fill_gaps(corrected_n_records, gap_indices, indices_map) API gap filler method. Note: Gaps will be filled with the nodata=nan value .. py:method:: __getattr__(item: str) -> Any Direct attribute access to the cfg dictionary :param item: :return: .. py:method:: __getstate__() .. py:method:: __setstate__(d) .. py:class:: L1bWaveforms(info) Bases: :py:obj:`object` Container for Echo Power Waveforms .. py:attribute:: _valid_radar_modes :value: ['lrm', 'sar', 'sin'] .. py:attribute:: _parameter_list :value: ['power', 'range', 'radar_mode', 'is_valid', 'classification_flag'] .. py:attribute:: _attribute_list :value: ['echo_power_unit'] .. py:attribute:: _info .. py:attribute:: echo_power_unit :value: None .. py:attribute:: radar_mode_def .. py:attribute:: _power :value: None .. py:attribute:: _range :value: None .. py:attribute:: _radar_mode :value: None .. py:attribute:: _is_valid :value: None .. py:attribute:: _classification_flag :value: None .. py:property:: power .. py:property:: classification_flag .. py:property:: range .. py:property:: radar_mode .. py:property:: is_valid .. py:property:: parameter_list .. py:property:: n_range_bins .. py:property:: n_records .. py:property:: radar_modes :type: Union[str, List[str]] .. py:property:: num_radar_modes :type: int .. py:property:: dimdict Returns dictionary with dimensions .. py:method:: 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: .. py:method:: set_valid_flag(valid_flag) .. py:method:: set_classification_flag(classification_flag) Add or update the waveform classification flag :param classification_flag: intarray with shape (n_records, n_range_bins) :return: .. py:method:: append(annex) .. py:method:: set_subset(subset_list) .. py:method:: add_range_delta(range_delta) Add a range delta to all range bins :param range_delta: :return: .. py:method:: 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 .. py:method:: _get_wfm_shape(index)