Identifying cycles in TDL data — identify_tdl

Tool for identifying complete measurement cycles in a set of tunable diode laser (TDL) data.

Usage

identify_tdl_cycles(
    tdl_exdf,
    valve_column_name,
    cycle_start_valve,
    expected_cycle_length_minutes,
    expected_cycle_num_valves,
    expected_cycle_num_time_pts = expected_cycle_num_valves,
    timestamp_colname
  )

Arguments

tdl_exdf: An exdf object representing data from a TDL data logger.
valve_column_name: The name of the column in tdl_exdf that contains the valve number; typically, this is 'valve_number'.
cycle_start_valve: The value of the valve column that indicates the start of a new cycle.
expected_cycle_length_minutes: The expected length of a full cycle (in minutes); here the length is determined by the difference in timestamp between the first and last measurements that compose the cycle. For example, if a cycle consists of 9 valves that each require 20 seconds to measure, the expected length of the cycle in minutes would be 8 * 20 / 60 = 2.7 minutes (approximately).
expected_cycle_num_valves: The total number of unique valves that are measured in each cycle. For example, if a cycle consists of measuements from valves 1, 3, 13, 6, and 13, then expected_cycle_num_valves should be 4.
expected_cycle_num_time_pts: The total number of time points that are recorded in each cycle. For example, if 10 measuements are logged per second and a cycle is 12 minutes long, expected_cycle_num_time_pts should be 12 * 60 * 10 = 7200.
timestamp_colname: The name of the column in tdl_exdf that contains the timestamp of each measurement; typically, this is 'TIMESTAMP'.

Details

Typically a TDL system periodically cycles between multiple gas lines during measurements. Some of the gas lines represent gas mixtures with known composition that can be used for calibration, while others are the "unknown" mixtures whose composition is being measured. A collection of valves are used to control which gas line is being measured at any given time, and the "active" valve for each recorded data point is included in a measurement file.

When using the calibration lines to apply corrections to the measured data, it is necessary to first identify complete measurements cycles within the data set. Here, complete cycles are identified using the following criteria:

A cycle is said to begin when the value of valve_column_name is cycle_start_valve.
A cycle ends after expected_cycle_num_valves valves have been measured.
The time difference between the first and last points of a cycle cannot deviate from expected_cycle_length_minutes by more than +/- 30 seconds.

In addition to identifying valid measurement cycles within the data, identify_tdl_cycles also calculates the elapsed time at the beginning of each cycle (in minutes).

Value

An exdf object based on tdl_exdf that includes two new columns: the cycle_num column indicates the measurement cycle corresponding to each measurement, and the elapsed_time column indicates the elapsed time (in minutes) at the start of each cycle. Any rows in tdl_exdf that were not found to be part of a complete cycle will not be included in the return value.

Examples

# Example: reading a TDL file that is included with the PhotoGEA package and
# identifying its measurement cycles.
tdl_file <- read_gasex_file(
  PhotoGEA_example_file_path('tdl_sampling_1.dat'),
  'TIMESTAMP'
)

tdl_file <- identify_tdl_cycles(
  tdl_file,
  valve_column_name = 'valve_number',
  cycle_start_valve = 20,
  expected_cycle_length_minutes = 2.7,
  expected_cycle_num_valves = 9,
  timestamp_colname = 'TIMESTAMP'
)

str(tdl_file) # Notice the two new columns: `cycle_num` and `elapsed_time`
#> 'data.frame':	918 obs. of  100 variables:
#>  $ TIMESTAMP [read_cr3000] (TS)            : POSIXlt, format: "2022-07-12 06:12:43" "2022-07-12 06:13:03" ...
#>  $ RECORD [read_cr3000] (RN)               : num  0 1 2 3 4 5 6 7 8 9 ...
#>  $ valve_number [read_cr3000] ()           : num  20 21 23 26 2 10 11 12 13 20 ...
#>  $ diag_system_Avg [read_cr3000] ()        : num  128 128 128 132 128 128 128 128 128 128 ...
#>  $ NumSamples [read_cr3000] ()             : num  100 100 100 100 100 100 100 100 100 100 ...
#>  $ Conc12C_Avg [read_cr3000] (ppm)         : num  2.9 68.8 311.9 1022.5 294.3 ...
#>  $ Conc13C_Avg [read_cr3000] (ppm)         : num  0.132 0.847 3.481 11.114 3.299 ...
#>  $ TGAStatus_Avg [read_cr3000] ()          : num  96 96 96 96 96 96 96 96 96 96 ...
#>  $ TGAPressure_Avg [read_cr3000] (mb)      : num  30 30 30 30 30 ...
#>  $ LaserTemp_Avg [read_cr3000] (degC)      : num  -4 -4 -4 -4 -4 ...
#>  $ DCCurrentA_Avg [read_cr3000] (mA)       : num  50.4 50.4 50.4 50.4 50.4 ...
#>  $ DCCurrentB_Avg [read_cr3000] (mA)       : num  38.9 38.9 38.9 38.9 38.9 ...
#>  $ TGAAnalog1_Avg [read_cr3000] (V)        : num  0.0244 0.0244 0.0244 0.0244 0.0244 ...
#>  $ TGATemp1_Avg [read_cr3000] (degC)       : num  30 30 30 30 30 ...
#>  $ TGATemp2_Avg [read_cr3000] (degC)       : num  30 30 30 30 30 ...
#>  $ LaserCooler_Avg [read_cr3000] (V)       : num  2.02 2.02 2.02 2.02 2.02 ...
#>  $ RefDetSigA_Avg [read_cr3000] (mV)       : num  2.48 2.48 2.48 2.48 2.48 ...
#>  $ RefDetSigB_Avg [read_cr3000] (mV)       : num  0.503 0.503 0.502 0.502 0.502 ...
#>  $ RefDetTransA_Avg [read_cr3000] (%)      : num  41.2 41.2 41.1 41.1 41.1 ...
#>  $ RefDetTransB_Avg [read_cr3000] (%)      : num  54.8 54.8 54.7 54.7 54.7 ...
#>  $ RefDetTemp_Avg [read_cr3000] (degC)     : num  -35 -35 -35 -35 -35 ...
#>  $ RefDetCooler_Avg [read_cr3000] ()       : num  1461 1461 1461 1461 1461 ...
#>  $ RefDetGainOffset_Avg [read_cr3000] ()   : num  8217 8217 8217 8217 8217 ...
#>  $ SmpDetSigA_Avg [read_cr3000] (mV)       : num  57.8 56.5 51.6 39.8 52 ...
#>  $ SmpDetSigB_Avg [read_cr3000] (mV)       : num  10.08 9.88 9.17 7.38 9.22 ...
#>  $ SmpDetTransA_Avg [read_cr3000] (%)      : num  99.8 97.4 89.2 68.8 89.8 ...
#>  $ SmpDetTransB_Avg [read_cr3000] (%)      : num  114.4 112.2 104.2 84.2 104.8 ...
#>  $ SmpDetTemp_Avg [read_cr3000] (degC)     : num  -39 -39 -39 -39 -39 ...
#>  $ SmpDetCooler_Avg [read_cr3000] ()       : num  1449 1449 1449 1449 1449 ...
#>  $ SmpDetGainOffset_Avg [read_cr3000] ()   : num  8456 8456 8456 8456 8456 ...
#>  $ TGATemp1DutyCycle_Avg [read_cr3000] ()  : num  0.13 0.121 0.132 0.129 0.138 ...
#>  $ TGATemp2DutyCycle_Avg [read_cr3000] ()  : num  0.0601 0.077 0.0677 0.0676 0.0649 ...
#>  $ SampleFlow_Avg [read_cr3000] (ml_min)   : num  167 167 167 164 162 ...
#>  $ ExcessFlow_Avg [read_cr3000] (ml_min)   : num  95.77 105.457 140.852 0.123 53.341 ...
#>  $ SamplePress_Avg [read_cr3000] (mb)      : num  400 400 400 396 400 ...
#>  $ BypassPress_Avg [read_cr3000] (mb)      : num  400 400 400 400 400 ...
#>  $ SampleP_control_Avg [read_cr3000] ()    : num  0.4 0.404 0.414 0.2 0.385 ...
#>  $ BypassP_control_Avg [read_cr3000] ()    : num  0.477 0.475 0.471 0.484 0.496 ...
#>  $ TGAPress_control_Avg [read_cr3000] ()   : num  0.528 0.529 0.53 0.53 0.53 ...
#>  $ panel_tmpr_Avg [read_cr3000] (degC)     : num  24.7 24.7 24.7 24.7 24.7 ...
#>  $ batt_volt_Avg [read_cr3000] (V)         : num  11.8 11.8 11.8 11.8 11.8 ...
#>  $ buff_depth_Max [read_cr3000] ()         : num  0 0 0 0 0 0 0 0 0 0 ...
#>  $ Conc12C_Std [read_cr3000] (ppm)         : num  0.5244 0.0946 0.2025 1.1064 1.5535 ...
#>  $ Conc13C_Std [read_cr3000] (ppm)         : num  0.00797 0.00637 0.00849 0.02317 0.018 ...
#>  $ TGAStatus_Std [read_cr3000] ()          : num  0 0 0 0 0 0 0 0 0 0 ...
#>  $ TGAPressure_Std [read_cr3000] (mb)      : num  0.0101 0.0105 0.0115 0.0102 0.0112 ...
#>  $ LaserTemp_Std [read_cr3000] (degC)      : num  0.000244 0.000289 0.000272 0.000287 0.00025 ...
#>  $ DCCurrentA_Std [read_cr3000] (mA)       : num  0.000454 0.0006 0.000338 0.000492 0.000503 ...
#>  $ DCCurrentB_Std [read_cr3000] (mA)       : num  0.000677 0.000844 0.00061 0.000753 0.000625 ...
#>  $ TGAAnalog1_Std [read_cr3000] (V)        : num  1.56e-05 1.39e-05 1.31e-05 1.30e-05 1.31e-05 ...
#>  $ TGATemp1_Std [read_cr3000] (degC)       : num  0.000994 0.00121 0.003558 0.001737 0.001128 ...
#>  $ TGATemp2_Std [read_cr3000] (degC)       : num  0.00215 0.00137 0.00141 0.00126 0.00227 ...
#>  $ LaserCooler_Std [read_cr3000] (V)       : num  0.000293 0.000347 0.000326 0.000345 0.000301 ...
#>  $ RefDetSigA_Std [read_cr3000] (mV)       : num  0.00155 0.00185 0.00155 0.00199 0.00154 ...
#>  $ RefDetSigB_Std [read_cr3000] (mV)       : num  0.00169 0.00148 0.00145 0.0015 0.00188 ...
#>  $ RefDetTransA_Std [read_cr3000] (%)      : num  0.0298 0.0354 0.0268 0.0366 0.0293 ...
#>  $ RefDetTransB_Std [read_cr3000] (%)      : num  0.255 0.233 0.223 0.226 0.258 ...
#>  $ RefDetTemp_Std [read_cr3000] (degC)     : num  0.00364 0.0032 0.00361 0.00365 0.00315 ...
#>  $ RefDetCooler_Std [read_cr3000] ()       : num  0.354 0.316 0.356 0.357 0.299 ...
#>  $ RefDetGainOffset_Std [read_cr3000] ()   : num  0 0 0 0 0 0 0 0 0 0 ...
#>  $ SmpDetSigA_Std [read_cr3000] (mV)       : num  0.01137 0.00519 0.00502 0.01354 0.02786 ...
#>  $ SmpDetSigB_Std [read_cr3000] (mV)       : num  0.00497 0.00576 0.00366 0.00388 0.00501 ...
#>  $ SmpDetTransA_Std [read_cr3000] (%)      : num  0.0214 0.00781 0.00875 0.02549 0.05127 ...
#>  $ SmpDetTransB_Std [read_cr3000] (%)      : num  0.0631 0.0441 0.0564 0.0485 0.0763 ...
#>  $ SmpDetTemp_Std [read_cr3000] (degC)     : num  0.00136 0.00128 0.00116 0.00148 0.00128 ...
#>  $ SmpDetCooler_Std [read_cr3000] ()       : num  0.1147 0.1077 0.1009 0.1203 0.0931 ...
#>  $ SmpDetGainOffset_Std [read_cr3000] ()   : num  0 0 0 0 0 0 0 0 0 0 ...
#>  $ TGATemp1DutyCycle_Std [read_cr3000] ()  : num  0.00923 0.00826 0.0119 0.00883 0.00886 ...
#>  $ TGATemp2DutyCycle_Std [read_cr3000] ()  : num  0.00837 0.00978 0.00828 0.00849 0.00862 ...
#>  $ SampleFlow_Std [read_cr3000] (ml_min)   : num  0.1467 0.2004 0.1747 0.0871 0.1594 ...
#>  $ ExcessFlow_Std [read_cr3000] (ml_min)   : num  0.10026 0.11171 0.1207 0.00958 0.08248 ...
#>  $ SamplePress_Std [read_cr3000] (mb)      : num  0.0214 0.0234 0.0199 0.0935 0.0242 ...
#>  $ BypassPress_Std [read_cr3000] (mb)      : num  0.1431 0.0428 0.1358 0.4229 0.3114 ...
#>  $ SampleP_control_Std [read_cr3000] ()    : num  9.05e-05 8.99e-05 7.08e-05 0.00 2.21e-04 ...
#>  $ BypassP_control_Std [read_cr3000] ()    : num  1.85e-04 5.47e-05 1.52e-04 4.63e-04 3.60e-04 ...
#>  $ TGAPress_control_Std [read_cr3000] ()   : num  0.000536 0.000541 0.000592 0.000525 0.000577 ...
#>  $ panel_tmpr_Std [read_cr3000] (degC)     : num  0.00641 0.00222 0.00214 0.0023 0.00224 ...
#>  $ batt_volt_Std [read_cr3000] (V)         : num  0.00241 0.00235 0.00224 0.00218 0.00232 ...
#>  $ Li64Match_Avg(1) [read_cr3000] ()       : num  1 1 1 1 1 1 1 1 1 1 ...
#>  $ Li64Match_Avg(2) [read_cr3000] ()       : num  0 0 0 0 0 0 0 0 0 0 ...
#>  $ Li64Tmpr_Avg(1) [read_cr3000] (degC)    : num  -79.2 -77.6 -81.6 -79.4 -79.7 ...
#>  $ Li64Tmpr_Avg(2) [read_cr3000] (degC)    : num  NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN ...
#>  $ Li64Heat_Avg(1) [read_cr3000] ()        : num  1 1 1 1 1 1 1 1 1 1 ...
#>  $ Li64Heat_Avg(2) [read_cr3000] ()        : num  0 0 0 0 0 0 0 0 0 0 ...
#>  $ _Mix_diag_system_Avg [read_cr3000] ()   : num  NaN 960 960 960 960 960 960 960 960 960 ...
#>  $ _Mix_ExcessZeroFlow_Avg [read_cr3000] (): num  NaN 0.42 0.379 0.441 0.411 ...
#>  $ _Mix_ExcessMixFlow_Avg [read_cr3000] () : num  NaN 159 158 158 158 ...
#>  $ _Mix_CO2Press_Avg [read_cr3000] ()      : num  NaN 11.4 11.4 11.4 11.4 ...
#>  $ _Mix_ZeroPress_Avg [read_cr3000] ()     : num  NaN 16.5 16.5 16.5 16.5 ...
#>  $ _Mix_CO2P_control_Avg [read_cr3000] ()  : num  NaN 0 0 0 0 0 0 0 0 0 ...
#>  $ _Mix_ZeroP_control_Avg [read_cr3000] () : num  NaN 0 0 0 0 0 0 0 0 0 ...
#>  $ _Mix_MixTmpr1_Avg [read_cr3000] ()      : num  NaN 32 32 32 32 ...
#>  $ _Mix_MixTmpr2_Avg [read_cr3000] ()      : num  NaN 31.7 31.7 31.7 31.7 ...
#>  $ _Mix_MixHeat1_Avg [read_cr3000] ()      : num  NaN 1 1 1 1 1 1 1 1 1 ...
#>  $ _Mix_MixHeat2_Avg [read_cr3000] ()      : num  NaN 1 1 1 1 1 1 1 1 1 ...
#>  $ _Mix_panel_tmpr_Avg [read_cr3000] ()    : num  NaN 24.1 24.1 24.1 24.1 ...
#>  $ _Mix_batt_volt_Avg [read_cr3000] ()     : num  NaN 9.62 9.62 9.62 9.62 ...
#>  $ file_name [read_gasex_file] (NA)        : chr  "/home/runner/work/_temp/Library/PhotoGEA/extdata/tdl_sampling_1.dat" "/home/runner/work/_temp/Library/PhotoGEA/extdata/tdl_sampling_1.dat" "/home/runner/work/_temp/Library/PhotoGEA/extdata/tdl_sampling_1.dat" "/home/runner/work/_temp/Library/PhotoGEA/extdata/tdl_sampling_1.dat" ...
#>  $ cycle_num [calculated] (NA)             : num  1 1 1 1 1 1 1 1 1 2 ...
#>   [list output truncated]