Read and Quality Control a Single Field

This auxiliary function reads a field from a binary file using a provided specification and applies a quality control function on the retrieved data. The expectations and functioning of the quality control functions are described in detail in the documentation for seasonder_readSeaSondeCSFileBlock.

Usage

read_and_qc_field(field_spec, connection, endian = "big")

Arguments

field_spec

A list containing the specifications for the field to read. It should contain:

• type: the type of data to read, passed to seasonder_readCSField.

• qc_fun: the name of a quality control function. As detailed in seasonder_readSeaSondeCSFileBlock, this function should be present in the shared environment seasonder_the and must accept field_value as its first argument, followed by any other arguments specified in qc_params.

• qc_params: a list of additional parameters to pass to the quality control function. See seasonder_readSeaSondeCSFileBlock for detailed expectations of the QC function behavior.

connection

A connection to the binary file.

endian

A character string indicating the byte order. Options are "big" and "little" (default is "big").

Value

The value of the field after applying quality control.

Condition Management

This function utilizes the rlang package to manage conditions and provide detailed and structured condition messages:

Condition Classes:

• seasonder_cs_field_skipped: Condition that indicates a CSField was skipped during reading.

• seasonder_cs_field_qc_fun_rerun: Condition that indicates a rerun of the quality control function was triggered.

• seasonder_cs_field_qc_fun_not_defined_error: Error raised when the quality control function specified is not found in the shared environment seasonder_the.

• seasonder_cs_field_qc_fun_error: Error raised when an issue occurs while applying the quality control function.

Condition Cases:

• If a CSField is skipped during reading, the condition seasonder_cs_field_skipped is used to skip QC and then is re-signaled.

• If an alternate QC is rerun using the seasonder_rerun_qc_with_fun restart, the condition seasonder_cs_field_qc_fun_rerun is signaled.

• If the quality control function specified is not found in the shared environment seasonder_the, the error seasonder_cs_field_qc_fun_not_defined_error is raised.

• If there's an issue applying the quality control function, the error seasonder_cs_field_qc_fun_error is raised.

Restart Options: The function provides structured mechanisms to recover from errors/conditions during its execution using withRestarts. The following restart options are available:

• seasonder_rerun_qc_with_fun: Allows for rerunning QC with an alternate function.

  • Usage: In a custom condition handler, you can call seasonder_rerun_qc_with_fun(cond, alternateQCfunction) to trigger this restart and run an alternate QC using alternateQCfunction. alternateQCfunction will be used as follows alternateQCfunction(x) being x the value. No extra parameters are passed.

  • Effect: If invoked, the function logs an info message detailing the reason of the rerun, and then returns the value returned by alternateQCfunction.

See also

seasonder_rerun_qc_with_fun, seasonder_readCSField

It's also important to note that within read_and_qc_field, the function seasonder_readCSField is used. This function has its own error management and restart options, which are detailed in its documentation.