wrictools

Overview

This package provides functions, tutorials, and examples to preprocess, analyze, and visualize data from whole room indirect calorimeters (WRIC) by Maastricht Instruments, using the ‘OmniCal’ software (both version 1 and 2). Some functions may also work with WRICs from other manufacturers, though full functionality has only been validated for Maastricht Instruments devices.

If you instead want to use the functions in Python, please click below. Please note, that the Python code will not be further maintained as of March 2025.

Installation

# Install from CRAN
install.packages("wrictools")

If instead you want to install wrictools from GitHub use:

library(remotes)
install_github("NinaZiegenbein/wrictools")

Example Usage

Preprocess Local WRIC file(s)

If you have a WRIC text file locally and want to preprocess it, the workflow involves reading the metadata at the top of the file, extracting the raw measurements into a structured CSV format, and trimming the dataset to only include rows between the specified study start and end times. Additional steps include extracting protocol information from the note file, combining the two measurement streams, optionally splitting the data by room (only for data collected with software version 1) before saving the final output as a CSV file. Many of these steps are parameter-controlled, allowing you to choose which actions to apply during preprocessing.

Note: The data.txt in the /data folder is synthetic data intended to highlight the data pipeline, but should not be used for actual analysis as it is unphysiological and does not correlate to the note.txt file either!

library(wrictools)

data_txt <- system.file("extdata", "data.txt", package = "wrictools") # loading example data
result <- preprocess_wric_file(data_txt) 

The above code specifies only the necessary parameter filepath and assumes the default values for all other parameters. But you can specify these parameters for yourself, as can be seen below. As these are the default options the two function calls return exactly the same results.

result <- preprocess_wric_file(
  filepath = data_txt, 
  code = "id", 
  manual = NULL, 
  save_csv = FALSE, 
  path_to_save = NULL, 
  combine = TRUE, 
  method = "mean", 
  start = NULL, 
  end = NULL, 
  notefilepath = NULL, 
  keywords_dict = NULL, 
  entry_exit_dict = NULL
)

Here are explanations and options to all parameters you can specify:

• filepath: [String, filepath] Directory path to the WRIC .txt file.
• code [String] Method for generating subject IDs. Default is “id”, also possible to specify “id+comment”, where both ID and comment values are combined or “manual”, where you can specify your own.
• manual [String] Custom codes for subjects in Room 1 and Room 2 if code is “manual”.
• save_csv [Logical], whether to save extracted metadata and data to CSV files or not. Default is False
• path_to_save [String] Directory path for saving CSV files, NULL uses the current directory, NULL is Default.
• combine [Logical], whether to combine S1 and S2 measurements. Default is True
• method [String] Method for combining measurements (“mean”, “median”, “s1”, “s2”, “min”, “max”).
• start [character or POSIXct or NULL], rows before this will be removed, if NULL takes first row e.g “2023-11-13 11:43:00”
• end [character or POSIXct or NULL], rows after this will be removed, if NULL takes last rows e.g “2023-11-13 11:43:00”
• notefilepath: [String] Directory path of the corresponding note file (.txt) If you specify a path to the corresponding notefile, the code will try to automatically extract the datetime and current protocol specification (sleeping, exercising, eating etc). If possible please read the How To Note File, before you start your study for consistent note taking. If there is a TimeStamp in the note e.g “Participants starts eating at 16:10”, the time of the creation of the note will be overwritten with the time specified in the free-text of the note. The “protocol” is extracted by keyword search. You can check currently included keywords and extend them by checking the keywords_dict in the extract_note_info() function of the preprocessing.R file.
• keywords_dict: [Nested List] A dictionary of keywords used to extract protocol events from a note file. Each entry should be a named list with keywords, value and type. Find out more in the function documentation or in vignette("wrictools").

The function returns a named list with the elements metadata and df. For software version 1, metadata contains r1 and r2, and df contains room1 and room2.
For version 2, metadata and df each contain a single data frame metadataand data. If save_csv is True, then the DataFrames will be saved as csv files with “id_visit_WRIC_data.csv” or “id_visit_WRIC_metadata.csv”.

As this is probably the most important function I have explained this here in length. But you can always run

?preprocess_wric_file

to get the description, parameters, return values and examples of how to use the function or any other function within the package.

For a more detailed tutorial on how to use the package, please look at vignette wrictools.

Preprocess multiple files on RedCap

If you want to preprocess multiple WRIC files stored on a REDCap server, you can supply a CSV file containing the record IDs of interest. The function will automatically fetch the corresponding raw WRIC data, preprocess it, and return the results.

To connect to your REDCap project, you need your API token and the API URL for your instance. These can be assigned in the global environment manually, or be stored in a local file (for example ~/.config.R) and sourced when you run the function. A minimal config file looks like this:

api_token <- 'YOUR_API_TOKEN' # Replace with your personal API token
api_url <- 'https://redcap.au.dk/api/' #change this url to your RedCAP url (e.g. 'https://redcap.wustl.edu/')

⚠️ Important: Keep your token private and never share or commit it to version control. If working with sensitive data, consider removing the token from your config file after use.

You also need to specify the field name of the REDCap instrument where the raw WRIC data is stored (e.g. “wric_data”) and provide the CSV with record IDs (one per row, no headers or extra text). The record IDs must exactly match those used in REDCap.

# Load your REDCap credentials
source(path.expand("~/.config.R"))

# This creates a temporary csv file with record ID's
tmp_csv <- tempfile(fileext = ".csv")
write.csv(data.frame(X1 = c(1, 2, 3)), tmp_csv, row.names = FALSE)

# Preprocess WRIC files
result <- preprocess_wric_files(
  csv_file   = tmp_csv,
  fieldname  = "wric_data",
  api_url    = api_url,
  api_token  = api_token
)

The function returns a list, where each element corresponds to one record ID. Each record ID contains its own returned named list (see description of preprocess_wric_file() above)

Other good-to-know functions

Remember that you can learn more about each function and it’s usage by ?function_name.

• upload_file_to_redcap to upload data to RedCAP
• visualize_with_protocolto visualize your data including highlights of the protocol
• cut_rows to cut your dataframe to certain timepoints
• check-discrepanciesto check the difference between the two sensors within a chamber

For analysis of zero tests or methanol burns find out more in xxx.#TODO

Support, Maintenance and Future Work

For any issues, questions, or suggestions feel free to open an issue on GitHub or reach out to Nina Ziegenbein at ninzie@ph.au.dk.