PhotoGEA (version 1.4.0)

identify_tdl_cycles: Identifying cycles in TDL data

Description

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
  )

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.

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).

If no cycles are identified, the most likely explanation is that the values of some of the key input arguments (such as cycle_start_valve, expected_cycle_length_minutes, or expected_cycle_num_valves) may be incorrect for the data in tdl_exdf. In this case, an error message will be sent.

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`