Saturation / desaturation correction#

This page documents SignalCreation.Lidar.Lidar.saturation(), which computes the detector saturation (desaturation) correction coefficient per raw channel, along with its uncertainty. The correction is parameterized by a model (default: Pelon) with two key parameters: \(\tau\) (dead-time) and \(N_{cm}\) (count-to-rate factor).

Overview#

########################
# Saturation correction #
########################
lidar.saturation()

What it does:

  • Selects raw channels (by default, Signal_Type ∈ [100, 119]) from variables whose name starts with the configured raw prefix (see Variable naming and metadata configuration).

  • For each channel, computes a saturation/desaturation coefficient and its uncertainty using the configured method and parameters (\(\tau\), \(N_{cm}\)).

  • Stores results in the dataset under a configurable output prefix (default: saturation), one variable per channel, with per-channel attributes (Signal_Type, possibly tau and N_cm).

  • Channels for which the method is disabled (None) are skipped (no variable is written).

Method signature#

def saturation(
    self,
    list_data_name: None | list = None,
    error_suffix: None | str = None,
    prefix_output_name: None | str = None,
    list_signal_type: list | np.ndarray | None = None,
) -> None:
    """Apply saturation/desaturation model and save per-channel coefficients + uncertainties."""

Parameters#

  • list_data_name (list | None) Optional explicit list of variable names to process. If None, the code discovers raw LIDAR variables using the raw prefix from naming rules and the list_signal_type filter.

  • error_suffix (str | None, default: ``”_Unc”``) Suffix used for the uncertainty variable name. See Variable naming and metadata configuration.

  • prefix_output_name (str | None, default: ``”saturation”``) Base name for the output variables. The actual saved name may be indexed (e.g., saturation_0), following your naming configuration.

  • list_signal_type (list | np.ndarray | None, default: ``np.arange(100, 120)``) Restricts which Signal_Type codes are processed when list_data_name is not provided. See the code families in Signal types (Signal_Type).

XML configuration#

The model and its parameters are configured per channel under <Desaturation>. You can either provide one value per channel (aligned with the order in Read/Lidar_files/Signal_type) or broadcast a single value to all channels with the attribute apply_all="True".

Example:

<Dial>
  <!-- DESATURATION -->
  <Desaturation>
    <!-- Available methods: "pelon" (default). Use apply_all="True" to broadcast. -->
    <Method apply_all="True">pelon</Method>

    <Parameters>
      <!-- Dead-time tau (seconds), per channel or broadcast -->
      <tau type="float" units="s" apply_all="True">3.7e-9</tau>

      <!-- Count-to-rate factor N_cm, per channel or broadcast -->
      <N_cm type="float" apply_all="True">70</N_cm>
    </Parameters>
  </Desaturation>

  <!-- Raw channels declared here; their order aligns parameters per channel -->
  <Read>
    <Lidar_files>
      <Signal_type type="int">
        102, 103, 100, 101, 104, 105
      </Signal_type>
    </Lidar_files>
  </Read>
</Dial>

Channel alignment. The N-th value of tau/N_cm/Method is applied to the N-th Signal_type in Read/Lidar_files/Signal_type. With apply_all="True", a single value is applied to all channels.

Internal workflow#

  1. Inputs & selection

Signal_Type ∈ list_signal_type (default [100,119], see Signal types (Signal_Type)). 2. Read parameters

  • From XML: Desaturation/Method, Desaturation/Parameters/tau, .../N_cm. Broadcasting with apply_all="True" is supported.

  1. Per-channel computation

    • If the method for this channel is None → the channel is skipped.

    • Else call the model kernel (get_desaturation) which returns coefficient and uncertainty.

  2. Save outputs

    • Write one variable per channel under prefix_output_name (default: saturation) and its uncertainty (with error_suffix).

    • Attributes include: long_name="Saturation coefficient", Signal_Type; the kernel may also populate tau/N_cm in the variable attributes.

Outputs in the dataset#

For each processed channel:

  • saturation_* Per-channel desaturation coefficient on the same grid as the input raw signal.

  • saturation_* + uncertainty (e.g., saturation_0_Unc) Uncertainty associated with the coefficient.

Typical attributes - Signal_Type (copied) - long_name = "Saturation coefficient" - possibly tau and N_cm (if set by the kernel)

Examples#

Run with XML defaults:

from SignalCreation.Lidar import Lidar

lidar = Lidar("Configuration_files/Parameters/example_station.xml", "2024-03-28")
lidar.import_lidar_data()
lidar.saturation()  # uses Method=tau/N_cm from XML (broadcast or per-channel)
[v for v in lidar._lidar.data_vars if v.startswith("saturation")]

Process only photon-counting channels (100–105):

lidar.saturation(list_signal_type=[100,101,102,103,104,105])

Custom output name + uncertainty suffix:

lidar.saturation(prefix_output_name="Saturation", error_suffix="_Unc")

Notes & recommendations#

  • Parameter units

    • tau is a time (seconds).

    • N_cm is a detector count-to-rate factor (dimension per your acquisition chain). Ensure the units are consistent with your raw data units (see Importing LIDAR raw data).

  • Per-channel vs broadcast Start with a broadcast (apply_all="True") tuned on a reference channel, then refine per-channel parameters if needed (aging, different electronics).

  • Analog vs photon counting Saturation effects are typically dominant in photon counting. You can restrict list_signal_type to photon-counting families if desired (see Signal types (Signal_Type)).

  • Disabled channels Setting Method to None for a given channel skips the computation and no output variable is saved.

  • Naming & uncertainty Final variable names (and their uncertainty suffix) follow your rules in Variable naming and metadata configuration (delimiter, indexing, suffix).

Tip

Inspect the output attributes to verify effective parameters (tau, N_cm) used by the kernel on each channel.

Caution

If you rely on the attributes tau / N_cm written by the kernel, ensure the values are persisted in your processing logs. This method does not write them back to the XML parameter file automatically.

See also#