[scfinder] Add clipping handling to PGA processing

[FMassin]

Prevents the use of clipped data in further processing and adds additional logging and select the appropriate envelope for PGA processing based on instrument gain units.

Before, scfinder would process with FinDer the maximum PGA over all the channels (vertical or horizontal) of all the colocated instruments.

Ambiguituous processing of vertical and horizontal PGA remains.

Key Changes:

1. Instrument Gain Unit Check and Prevailing (M/S**2 by default):
   • Integrated logic to check and log whether PGA data is from an accelerometer based on the instrument's gain unit (i.e., "M/S**2").
   • Adjusted the PGA processing to ensure data from different instruments (e.g., accelerometers vs. velocimeters) at the same location is handled correctly, i.e., M/S**2 prevails on others by default.

Updates in the updateMaximum Function (updates the PGA):

• Prevailing of preferred gain units over the others .
• Considering of clipped records while updating the maximum PGA.

2. Discarding of Clipped data:
   • Clipping is now detected, logged, and skipped in the PGA buffer processing.
   • Added logic to skip channels recently clipped within the clipTimeout window.
   • Modified log statements to include clipping status where necessary.

New clipTimeout Parameter:

• Added a new configuration parameter, clipTimeout, in scfinder.xml to specify the delay after which clipped envelope are excluded from processing.
• Default value set to 30 seconds.
• Similar to scvsmag's clipTimeout

Updates in the Amplitude Structure (used for envelopes and PGAs):

• Tracking of whether the data is clipped via a clipped boolean flag, and when that last occured via the lastclipped timestamp.
• Added gainUnit string to keep track of the channel gainUnit.

3. Improved Debug Logging:
   • Logging clipped records and skipping logic.
   • Logging when amplitude is discarted to prefer another data gain units.
   • Logging gain unit information when available.

Unit Test

The two new features can be tested with the unit test data as follows:

scfinder --playback --offline --inventory-db file:///usr/local/src/seiscomp/src/base/sed-addons/test/vs/inventory.xml  --test -I file:///usr/local/src/seiscomp/src/base/sed-addons/test/vs/sorted.mseed --debug

1. Instrument Gain Unit Check and Prevailing (M/S**2 by default):

   • Prevailing logic logging for each collocated instrument when PGA is updated, e.g.: HG [M/S**2] rules over HH [M/S]
   • Setting "" (empty) instead of M/**2 as finder.preferredGainUnits in scfinder.cfg switches the revailing of any unit off as can be seen in temp_data/*/data_* files.
   • Setting M/S instead of M/**2 as finder.preferredGainUnits in scfinder.cfg switches collocated instrument usage from accelerometers to velocimeters as can be seen in temp_data/*/data_* files (e.g., 20 HG less in data_2).

2. Discarding of clipped data:

   • Log message for each clipped PGA that has been skipped: Instrument clipped and skipped
   • Log message after clipped PGA for 30s: Instrument clipped recently and skipped
   • Setting 2 as saturationThreshold in scfinder.cfg allows 4 station contributions less as can be seen in temp_data/*/data_* files.

[FMassin]

@jenrandrews Saturation reference value is already fixed.