Geometrical factor loading#

This page documents SignalCreation.Lidar.Lidar.geometrical_factor(), which loads and stores the geometrical factor profile for each selected raw LIDAR channel. For every channel, it chooses the appropriate file from XML config (conditioned on Signal_Type), reads the profile with GeometricFactor, creates a unit uncertainty array, and writes both into self._lidar.

Overview#

  • Discovers raw channels from the dataset (prefix from naming rules), restricted to Signal_Type in [100, 119] and excluding uncertainty variables.

  • For each channel: 1. Selects the geometrical-factor file using the XML mapping conditioned on the channel’s Signal_Type. 2. Builds the station altitude as a Pint quantity from self._lidar['altitude']. 3. Instantiates GeometricFactor and retrieves the factor profile aligned to the channel. 4. Creates a unit-uncertainty array (xr.ones_like). 5. Saves value + uncertainty into self._lidar with a configurable output prefix.

If no filenames are configured under GeometricFactor/filenames, the method exits without changes.

Function signature#

def geometrical_factor(
    self,
    list_data_name: None | list = None,
    error_suffix: None | str = None,
    prefix_output_name: str | None = None,
) -> None:
    """Load per-channel geometrical factor and store it into the LIDAR dataset."""

Parameters#

  • list_data_name (list | None) Optional explicit list of variable names to process. Note: in the current implementation, it is recomputed internally from the dataset by filtering on valid Signal_Type values and excluding uncertainties.

  • error_suffix (str | None, default: ``”_Unc”``) Suffix used to name the uncertainty variable. Currently validated but not used inside the function body (the uncertainty is set to ones).

  • prefix_output_name (str | None, default from naming rules) Output variable prefix used when saving results. Defaults to nv.get_var_name("geometric_factor").

Inputs and assumptions#

  • self._lidar provides:

    • a coordinate/variable "altitude" with unit metadata in attrs['units'];

    • raw channel variables prefixed by nv.get_var_name('raw_lidar_data') and each with an integer "Signal_Type" attribute.

  • unit_registry (global Pint registry) and self._ureg (instance registry) are available.

  • XML configuration accessible via self._param.

XML configuration#

The method reads the following keys:

  • Read/Lidar_files/Signal_type Global list of channel signal types (used for alignment/validation).

  • GeometricFactor/filenames (required to proceed) Per-channel file(s) defining the geometrical factor. The method selects the filename for a given channel using self._param.get_param_xml_with_condition() with the condition key "Read/Lidar_files/Signal_type" and the channel’s Signal_Type value.

  • GeometricFactor/format Format/hints used by GeometricFactor to read the profile.

Outputs (side effects)#

  • Initializes self._geometrical_factor as a list (if None), then appends one GeometricFactor instance per processed channel.

  • Adds two xarray.DataArray objects to self._lidar via nv.add_lidar_da(): - the geometrical factor profile, - the associated unit-uncertainty array, both carrying {"Signal_Type": <channel value>} in their attributes.

Return value: None — everything is stored in-place.

Errors, validation, and logs#

  • Input parameters are validated with tf.check_input_param() (type + allow None).

  • If GeometricFactor/filenames is missing or None, the function returns early without raising an exception.

  • Debug messages are issued via logging.

Example#

Minimal usage (default discovery of channels and default output name):

lidar.geometrical_factor()

Custom output prefix:

lidar.geometrical_factor(prefix_output_name="GF")

Notes#

  • error_suffix is kept for forward compatibility and may be used in a future implementation that propagates real uncertainties.

  • The station altitude is passed to GeometricFactor as a Pint quantity built from self._lidar['altitude'] and its units.

See also#