pysiral.sla =========== .. py:module:: pysiral.sla .. autoapi-nested-parse:: @author: Stefan Hendricks pysiral module for estimating sea surface height (ssh) respectively sea level anomaly (sla) from along-track radar altimeter data. The classes are designed to work with the Level-2 Processor, therefore need to be child classes of pysiral.l2proc.procsteps.Level2ProcessorStep. NOTES: 1. The convention of the pysiral Level-2 processor is to compute and sla (with ssh = sla + mss) to the Level-2 data object. Thus, the auxiliary data set mean sea surface (mss) is a mandatory auxiliary data set for the functionality of all classes in this module. Classes ------- .. autoapisummary:: pysiral.sla.SLABaseFunctionality pysiral.sla.SLAGaussianProcess pysiral.sla.SLASmoothedLinear pysiral.sla.SLARaw Functions --------- .. autoapisummary:: pysiral.sla.marine_segment_filter pysiral.sla.get_rolling_standard_deviation_elevation_window Module Contents --------------- .. py:function:: marine_segment_filter(l2, minimum_lead_number, footprint_size, use_ocean_wfm) Check all sections divided by land masses for reliable information content. Specifically, each marine segment between two land masses must have a minimum number of leads :param l2: :param minimum_lead_number: :param footprint_size: :param use_ocean_wfm: :return: mask: True: To be masked, False: Valid SLA .. py:class:: SLABaseFunctionality Bases: :py:obj:`object` A container for methods that are independent of the interpolation algorithm, basically cllection of mostly static method that can be pinned to all other using inheritance. .. py:method:: get_ssh_tiepoints_indices(surface_type: pysiral.core.flags.SurfaceType, elevation: pysiral.l2data.L2DataArray, use_ocean_wfm: bool = None) -> numpy.typing.NDArray :staticmethod: Return the index list of SSH tiepoints. These are as a minimum waveforms identified as lead in the surface type classifcation. Ocean waveforms can be added and an optional filter applies that removes SSH tiepoints based on their distance to the mean sea surface (mss). optional addition :param surface_type: Surface type flag object :param elevation: retracked elevation (will be checked for NaN values) :param use_ocean_wfm: Boolean flag whether to include ocean waveforms :return: A list of indices indicated valid SSH tie points for the Level-2 data object .. py:method:: get_tiepoint_distance_from_l2(l2, smooth_filter_width_footprint_size, use_ocean_wfm=False) Returns the distance in meter to the next ssh tiepoint for each record :param l2: Level-2 data container :param smooth_filter_width_footprint_size: :param use_ocean_wfm: :return: array(float32, shape=l2.n_records) .. py:method:: tiepoint_maxdist_filter(l2, edges_only, distance_threshold, footprint_size) A filter that does not remove sla values which distance to the next ssh tiepoint exceeds a defined threshold :param l2: Level-2 data container :param edges_only: :param distance_threshold: :param footprint_size: :return: None .. py:method:: get_tiepoint_distance(is_tiepoint) Calculates the distance to the next tie point in array entries :param is_tiepoint: boolean array :return: .. py:method:: tiepoint_elevation_sdev_filter(ssh_tiepoint_indices: numpy.typing.NDArray, elevation: numpy.typing.NDArray, footprint_spacing: float, elevation_filter_window_m: float = 50000.0, upper_limit_standard_deviation: float = 2.0, lower_limit_standard_deviation: float = 3.0, minimum_standard_deviation_m: float = 0.1) -> numpy.typing.NDArray :staticmethod: Filter tie points if their elevation is outside a specified multiple of the local elevation standard deviation. Two thresholds for upper and lower elevation bound must be specified. :param ssh_tiepoint_indices: Indices of elevation that are a (potential) sea surface height tiepoint :param elevation: elevation array :param footprint_spacing: Average footprint spacing. Needed to convert filter lenghts in meters into number of array items. :param elevation_filter_window_m: The filter window used for computing the mean elevation and the computation of rolling standard deviation. :param upper_limit_standard_deviation: Sea surface height tie points are removed if their elevation exceeds the mean elevation plus the local standard deviation multiplied by this factor. :param lower_limit_standard_deviation: Sea surface height tie points are removed if their elevation is below the mean elevation minus the local standard deviation multiplied by this factor. :param minimum_standard_deviation_m: The minimum local standard devation. This value prevents the filter becoming to greedy in the case of small local standard devation. :return: The filtered ssh tiepoint index list .. py:method:: get_filter_width(smooth_filter_width_m, smooth_filter_width_footprint_size) :staticmethod: Compute the filter width in points :param smooth_filter_width_m: :param smooth_filter_width_footprint_size: :return: .. py:method:: apply_surface_type_masks(sla, sla_unc, l2, surface_types) :staticmethod: Remove sla and sla uncertainty values for a set surface types (Names must match the surface types name definitions in the l2 data containers) :param sla: :param sla_unc: :param l2: :param surface_types: :return: .. py:method:: get_tiepoints_oneway_distance(a, reverse=False) :staticmethod: loops through array and determines distance to latest flag=true .. py:class:: SLAGaussianProcess(*args, **kwargs) Bases: :py:obj:`pysiral.l2proc.procsteps.Level2ProcessorStep`, :py:obj:`SLABaseFunctionality` Use gaussian processes of the scikit-learn module to predict optimal sla from of ssh tiepoints (with various filter options similar to SLASmoothedLinear). This class will compute the sea level anomaly (sla) .. py:method:: execute_procstep(l1b, l2) Mandatory Level-2 processor method that will execute the processing step and modify the L2 data object in-place. This method will interpolate ssh tiepoints given by lead (+ ocean) elevations and smooth the result. Filter options are available to filter unreasonable sla values. :param l1b: :param l2: :return: .. py:method:: sla_from_gaussian_process(l2, ssh_tiepoint_indices, matern_kernel=None, white_noise_kernel=None) :staticmethod: Compute sea level anomaly be fitting lead tie points with a gaussian process. This method uses an optimization process based on the assumption :param l2: :param ssh_tiepoint_indices: :param matern_kernel: :param white_noise_kernel: :return: .. py:property:: l2_input_vars Mandatory property for Level2ProcessorStep children :return: list (str) .. py:property:: l2_output_vars Mandatory property for Level2ProcessorStep children :return: list (str) .. py:property:: error_bit .. py:class:: SLASmoothedLinear(*args, **kwargs) Bases: :py:obj:`pysiral.l2proc.procsteps.Level2ProcessorStep`, :py:obj:`SLABaseFunctionality` Default implemetation of a smoothed interpolation of ssh tiepoints (with various filter options). This class will compute the sea level anomaly (sla) .. py:method:: execute_procstep(l1b, l2) Mandatory Level-2 processor method that will execute the processing step and modify the L2 data object in-place. This method will interpolate ssh tiepoints given by lead (+ ocean) elevations and smooth the result. Filter options are available to filter unreasonable sla values. :param l1b: :param l2: :return: .. py:method:: smoothed_linear_interpolation_between_tiepoints(l2, ssh_tiepoint_indices, filter_width) :staticmethod: The main SLA computation method in this class :param l2: Level-2 data container :param ssh_tiepoint_indices: :param filter_width: :return: None .. py:method:: calculate_sla_uncertainty(l2, max_distance, sla_unc_min, sla_unc_max, smooth_filter_width_footprint_size) Components that add to sea surface anomaly uncertainty - mss uncertainty (if known) - uncertainty of lead elevations - distance to next lead tiepoint :param l2: :param max_distance: :param sla_unc_min: :param sla_unc_max: :param smooth_filter_width_footprint_size: :return: .. py:property:: l2_input_vars Mandatory property for Level2ProcessorStep children :return: list (str) .. py:property:: l2_output_vars Mandatory property for Level2ProcessorStep children :return: list (str) .. py:property:: error_bit .. py:class:: SLARaw(*args, **kwargs) Bases: :py:obj:`pysiral.l2proc.procsteps.Level2ProcessorStep`, :py:obj:`SLABaseFunctionality` Get the raw SLA. This class will compute the sea level anomaly (sla) :sectionauthor: D. J. Brockley (UCL) .. py:method:: execute_procstep(l1b, l2) Mandatory Level-2 processor method that will execute the processing step and modify the L2 data object in-place. This method will extracts raw SLA measurements by computing elev-mss at lead (+ ocean) locations. :param l1b: :param l2: :return: .. py:method:: sla_from_raw_process(l2, ssh_tiepoint_indices) :staticmethod: Compute sea level anomaly :param l2: :param ssh_tiepoint_indices: :return: .. py:property:: l2_input_vars Mandatory property for Level2ProcessorStep children :return: list (str) .. py:property:: l2_output_vars Mandatory property for Level2ProcessorStep children :return: list (str) .. py:property:: error_bit .. py:function:: get_rolling_standard_deviation_elevation_window(elevation: numpy.typing.NDArray, window_size: int, minimum_standard_deviation_m: float = 0.0, maximum_standard_deviation_m: float = np.inf, upper_limit_standard_deviation: float = 1.0, lower_limit_standard_deviation: float = 1.0) -> Tuple[numpy.typing.NDArray, numpy.typing.NDArray] Compute a rolling window determined by upper_limit = rolling_mean + upper_limit_standard_deviation * rolling_standard_devation lower_limit = rolling_mean - lower_limit_standard_deviation * rolling_standard_devation the window size for the computation of rolling mean and standard devation is specified as number of points. The elevation array is assumed to be equidistant. :param elevation: Elevation array :param window_size: Number of points used to compute rolling mean and standard deviation :param minimum_standard_deviation_m: Minimum permissible rolling standard deviation :param maximum_standard_deviation_m: Maximum permissible rolling standard deviation :param upper_limit_standard_deviation: Multiplier for local standard deviation for upper limit :param lower_limit_standard_deviation: Multiplier for local standard deviation for lower limit :return: lower limit & upper limit with same dimension as input array.