| Title: | I/O Functions for PhysioExperiment Objects |
|---|---|
| Description: | Provides comprehensive I/O capabilities for PhysioExperiment objects. Supports EDF/EDF+, HDF5, BIDS, CSV, MATLAB formats, and DuckDB database integration. Includes out-of-memory processing for large datasets via HDF5Array. |
| Authors: | Yusuke Matsui |
| Maintainer: | Yusuke Matsui <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.2.0 |
| Built: | 2026-05-16 08:46:20 UTC |
| Source: | https://github.com/x-biosignal/PhysioIO |
Package on-load hook
.onLoad(libname, pkg).onLoad(libname, pkg)
libname |
Library path. |
pkg |
Package name. |
These functions establish a connection to a DuckDB database using the
DBI interface. They form a minimal skeleton to be expanded with concrete
schema management functions in future iterations.
connectDatabase(path = ":memory:") disconnectDatabase(con)connectDatabase(path = ":memory:") disconnectDatabase(con)
path |
Path to a DuckDB database file. |
con |
A database connection produced by |
A database connection object.
Raasveldt M, Muehleisen H (2019). "DuckDB: an embeddable analytical database." Proceedings of the 2019 International Conference on Management of Data (SIGMOD). doi:10.1145/3299869.3320212
initPhysioSchema, registerExperiment,
queryExperiments
## Not run: # Connect to an in-memory database con <- connectDatabase() # Connect to a file-based database con <- connectDatabase("experiments.duckdb") # Always disconnect when done disconnectDatabase(con) ## End(Not run)## Not run: # Connect to an in-memory database con <- connectDatabase() # Connect to a file-based database con <- connectDatabase("experiments.duckdb") # Always disconnect when done disconnectDatabase(con) ## End(Not run)
Get database statistics
dbStats(con)dbStats(con)
con |
A DuckDB connection. |
A list with database statistics.
Raasveldt M, Muehleisen H (2019). "DuckDB: an embeddable analytical database." Proceedings of the 2019 International Conference on Management of Data (SIGMOD). doi:10.1145/3299869.3320212
connectDatabase, initPhysioSchema,
queryExperiments
## Not run: con <- connectDatabase("experiments.duckdb") initPhysioSchema(con) # Get database statistics stats <- dbStats(con) cat("Experiments:", stats$n_experiments, "\n") cat("Channels:", stats$n_channels, "\n") cat("Subjects:", paste(stats$subjects, collapse = ", "), "\n") disconnectDatabase(con) ## End(Not run)## Not run: con <- connectDatabase("experiments.duckdb") initPhysioSchema(con) # Get database statistics stats <- dbStats(con) cat("Experiments:", stats$n_experiments, "\n") cat("Channels:", stats$n_channels, "\n") cat("Subjects:", paste(stats$subjects, collapse = ", "), "\n") disconnectDatabase(con) ## End(Not run)
Delete experiment from database
deleteExperiment(con, experiment_id, confirm = TRUE)deleteExperiment(con, experiment_id, confirm = TRUE)
con |
A DuckDB connection. |
experiment_id |
The experiment identifier. |
confirm |
If TRUE, requires confirmation. |
Invisible NULL.
Raasveldt M, Muehleisen H (2019). "DuckDB: an embeddable analytical database." Proceedings of the 2019 International Conference on Management of Data (SIGMOD). doi:10.1145/3299869.3320212
registerExperiment, loadExperiment,
queryExperiments
## Not run: con <- connectDatabase("experiments.duckdb") # Delete an experiment deleteExperiment(con, "exp_20240101120000_1234") # Skip existence check (for batch deletion) deleteExperiment(con, "exp_id", confirm = FALSE) disconnectDatabase(con) ## End(Not run)## Not run: con <- connectDatabase("experiments.duckdb") # Delete an experiment deleteExperiment(con, "exp_20240101120000_1234") # Skip existence check (for batch deletion) deleteExperiment(con, "exp_id", confirm = FALSE) disconnectDatabase(con) ## End(Not run)
Functions for managing experiment data in DuckDB database. Provides a relational schema for storing metadata, signals, and events. Initialize PhysioExperiment database schema
initPhysioSchema(con)initPhysioSchema(con)
con |
A DuckDB connection from connectDatabase(). |
Creates the database tables for storing experiment metadata, signals, and events.
Invisible NULL.
Raasveldt M, Muehleisen H (2019). "DuckDB: an embeddable analytical database." Proceedings of the 2019 International Conference on Management of Data (SIGMOD). doi:10.1145/3299869.3320212
connectDatabase, registerExperiment,
dbStats
## Not run: # Set up a new database con <- connectDatabase("experiments.duckdb") initPhysioSchema(con) # Check statistics dbStats(con) disconnectDatabase(con) ## End(Not run)## Not run: # Set up a new database con <- connectDatabase("experiments.duckdb") initPhysioSchema(con) # Check statistics dbStats(con) disconnectDatabase(con) ## End(Not run)
Tests whether the default assay of a PhysioExperiment is stored as an HDF5-backed DelayedArray.
isHDF5Backed(x)isHDF5Backed(x)
x |
A PhysioExperiment object. |
Logical scalar; TRUE if the default assay inherits from
HDF5Array or DelayedArray, FALSE otherwise.
The HDF Group (1997-2024). "Hierarchical Data Format, version 5." https://www.hdfgroup.org/HDF5/
readPhysioHDF5, writePhysioHDF5,
realizeHDF5
# Regular in-memory PhysioExperiment pe <- PhysioExperiment( assays = list(raw = matrix(1:100, nrow = 10)), samplingRate = 100 ) isHDF5Backed(pe) # FALSE# Regular in-memory PhysioExperiment pe <- PhysioExperiment( assays = list(raw = matrix(1:100, nrow = 10)), samplingRate = 100 ) isHDF5Backed(pe) # FALSE
List sessions for a subject in BIDS dataset
listBIDSSessions(bids_root, subject)listBIDSSessions(bids_root, subject)
bids_root |
Path to the BIDS dataset root. |
subject |
Subject identifier (without 'sub-' prefix). |
Character vector of session IDs (without 'ses-' prefix).
Gorgolewski KJ, et al. (2016). "The brain imaging data structure, a format for organizing and describing outputs of neuroimaging experiments." Scientific Data, 3, 160044. doi:10.1038/sdata.2016.44
listBIDSSubjects, readBIDS,
validateBIDS
## Not run: # List sessions for a specific subject sessions <- listBIDSSessions("path/to/bids", subject = "01") print(sessions) # e.g., c("baseline", "followup") ## End(Not run)## Not run: # List sessions for a specific subject sessions <- listBIDSSessions("path/to/bids", subject = "01") print(sessions) # e.g., c("baseline", "followup") ## End(Not run)
List subjects in a BIDS dataset
listBIDSSubjects(bids_root)listBIDSSubjects(bids_root)
bids_root |
Path to the BIDS dataset root. |
Character vector of subject IDs (without 'sub-' prefix).
Gorgolewski KJ, et al. (2016). "The brain imaging data structure, a format for organizing and describing outputs of neuroimaging experiments." Scientific Data, 3, 160044. doi:10.1038/sdata.2016.44
listBIDSSessions, readBIDS,
validateBIDS
## Not run: # List all subjects in a BIDS dataset subjects <- listBIDSSubjects("path/to/bids") print(subjects) # e.g., c("01", "02", "03") ## End(Not run)## Not run: # List all subjects in a BIDS dataset subjects <- listBIDSSubjects("path/to/bids") print(subjects) # e.g., c("01", "02", "03") ## End(Not run)
Reconstructs a PhysioExperiment object from database records.
loadExperiment(con, experiment_id, load_signals = FALSE)loadExperiment(con, experiment_id, load_signals = FALSE)
con |
A DuckDB connection. |
experiment_id |
The experiment identifier. |
load_signals |
If TRUE, loads signal data from chunks. |
A PhysioExperiment object.
Raasveldt M, Muehleisen H (2019). "DuckDB: an embeddable analytical database." Proceedings of the 2019 International Conference on Management of Data (SIGMOD). doi:10.1145/3299869.3320212
registerExperiment, queryExperiments,
deleteExperiment
## Not run: con <- connectDatabase("experiments.duckdb") # Load experiment metadata only pe <- loadExperiment(con, "exp_20240101120000_1234") # Load with signal data pe_full <- loadExperiment(con, "exp_20240101120000_1234", load_signals = TRUE ) disconnectDatabase(con) ## End(Not run)## Not run: con <- connectDatabase("experiments.duckdb") # Load experiment metadata only pe <- loadExperiment(con, "exp_20240101120000_1234") # Load with signal data pe_full <- loadExperiment(con, "exp_20240101120000_1234", load_signals = TRUE ) disconnectDatabase(con) ## End(Not run)
Harmonize clinical codes across sites
mapClinicalCodes( x, mapping, code_col = "scale_name", mapped_col = "scale_name_std", from_col = "from", to_col = "to", unmatched = c("keep", "na", "drop") )mapClinicalCodes( x, mapping, code_col = "scale_name", mapped_col = "scale_name_std", from_col = "from", to_col = "to", unmatched = c("keep", "na", "drop") )
x |
Clinical metadata data frame. |
mapping |
Code mapping, either:
|
code_col |
Source code column in |
mapped_col |
Output mapped code column. |
from_col |
Source column in mapping data.frame. |
to_col |
Target column in mapping data.frame. |
unmatched |
Behavior for unmatched codes: |
Data frame with mapped_col appended.
Goldberger AL, et al. (2000). "PhysioBank, PhysioToolkit, and PhysioNet: components of a new research resource for complex physiologic signals." Circulation, 101(23), e215-e220. doi:10.1161/01.CIR.101.23.e215
readClinicalMetadataCSV,
validateClinicalMetadata
df <- data.frame(scale_name = c("fim_total", "Berg"), stringsAsFactors = FALSE) map <- c(fim_total = "FIM", Berg = "BBS") mapClinicalCodes(df, map, code_col = "scale_name")df <- data.frame(scale_name = c("fim_total", "Berg"), stringsAsFactors = FALSE) map <- c(fim_total = "FIM", Berg = "BBS") mapClinicalCodes(df, map, code_col = "scale_name")
Query experiments from database
queryExperiments(con, subject_id = NULL, task = NULL, date_range = NULL)queryExperiments(con, subject_id = NULL, task = NULL, date_range = NULL)
con |
A DuckDB connection. |
subject_id |
Optional filter by subject. |
task |
Optional filter by task. |
date_range |
Optional date range (vector of 2 dates). |
A data.frame of matching experiments.
Raasveldt M, Muehleisen H (2019). "DuckDB: an embeddable analytical database." Proceedings of the 2019 International Conference on Management of Data (SIGMOD). doi:10.1145/3299869.3320212
registerExperiment, loadExperiment,
dbStats
## Not run: con <- connectDatabase("experiments.duckdb") # Query all experiments all_exps <- queryExperiments(con) # Filter by subject sub01_exps <- queryExperiments(con, subject_id = "sub01") # Filter by task rest_exps <- queryExperiments(con, task = "rest") # Filter by date range recent <- queryExperiments(con, date_range = c("2024-01-01", "2024-12-31") ) disconnectDatabase(con) ## End(Not run)## Not run: con <- connectDatabase("experiments.duckdb") # Query all experiments all_exps <- queryExperiments(con) # Filter by subject sub01_exps <- queryExperiments(con, subject_id = "sub01") # Filter by task rest_exps <- queryExperiments(con, task = "rest") # Filter by date range recent <- queryExperiments(con, date_range = c("2024-01-01", "2024-12-31") ) disconnectDatabase(con) ## End(Not run)
Functions for reading and writing data in BIDS (Brain Imaging Data Structure) format. Supports BIDS-EEG and BIDS-iEEG specifications. Read PhysioExperiment from BIDS dataset
readBIDS( bids_root, subject, session = NULL, task, run = NULL, modality = c("eeg", "ieeg"), load_events = TRUE )readBIDS( bids_root, subject, session = NULL, task, run = NULL, modality = c("eeg", "ieeg"), load_events = TRUE )
bids_root |
Path to the BIDS dataset root directory. |
subject |
Subject identifier (without 'sub-' prefix). |
session |
Session identifier (without 'ses-' prefix). Optional. |
task |
Task name. |
run |
Run number. Optional. |
modality |
Data modality: "eeg" or "ieeg". |
load_events |
If TRUE, loads events from the events.tsv file. |
Reads EEG/iEEG data from a BIDS-compliant directory structure.
A PhysioExperiment object.
Gorgolewski KJ, et al. (2016). "The brain imaging data structure, a format for organizing and describing outputs of neuroimaging experiments." Scientific Data, 3, 160044. doi:10.1038/sdata.2016.44
writeBIDS, validateBIDS,
readEDF, listBIDSSubjects
## Not run: # Read EEG data from BIDS dataset pe <- readBIDS("path/to/bids", subject = "01", task = "rest") # Read with session and run specified pe <- readBIDS("path/to/bids", subject = "01", session = "01", task = "oddball", run = 1, modality = "eeg") # Read without loading events pe <- readBIDS("path/to/bids", subject = "02", task = "rest", load_events = FALSE) ## End(Not run)## Not run: # Read EEG data from BIDS dataset pe <- readBIDS("path/to/bids", subject = "01", task = "rest") # Read with session and run specified pe <- readBIDS("path/to/bids", subject = "01", session = "01", task = "oddball", run = 1, modality = "eeg") # Read without loading events pe <- readBIDS("path/to/bids", subject = "02", task = "rest", load_events = FALSE) ## End(Not run)
Utilities for loading and validating clinical assessment metadata so
physiological sessions can be linked with EDC/EHR variables using
subject_id and visit_id.
Read clinical metadata from CSV
readClinicalMetadataCSV( path, col_map = NULL, required_cols = c("subject_id", "visit_id", "scale_name", "scale_score"), date_cols = c("assessment_date", "visit_date"), validate = TRUE, sep = ",", header = TRUE, ... )readClinicalMetadataCSV( path, col_map = NULL, required_cols = c("subject_id", "visit_id", "scale_name", "scale_score"), date_cols = c("assessment_date", "visit_date"), validate = TRUE, sep = ",", header = TRUE, ... )
path |
Path to the CSV/TSV file. |
col_map |
Optional named character vector for renaming columns. Names are source columns and values are target column names. |
required_cols |
Required columns for validation. |
date_cols |
Columns to parse as Date ( |
validate |
Logical; run |
sep |
Field separator, default |
header |
Logical, default |
... |
Additional arguments passed to |
Data frame containing standardized clinical metadata.
Goldberger AL, et al. (2000). "PhysioBank, PhysioToolkit, and PhysioNet: components of a new research resource for complex physiologic signals." Circulation, 101(23), e215-e220. doi:10.1161/01.CIR.101.23.e215
validateClinicalMetadata,
mapClinicalCodes, readCSV
tmp <- tempfile(fileext = ".csv") write.csv(data.frame( sid = "S01", vid = "V01", scale_name = "FIM", scale_score = 90, assessment_date = "2026-01-10" ), tmp, row.names = FALSE) df <- readClinicalMetadataCSV( tmp, col_map = c(sid = "subject_id", vid = "visit_id") ) unlink(tmp)tmp <- tempfile(fileext = ".csv") write.csv(data.frame( sid = "S01", vid = "V01", scale_name = "FIM", scale_score = 90, assessment_date = "2026-01-10" ), tmp, row.names = FALSE) df <- readClinicalMetadataCSV( tmp, col_map = c(sid = "subject_id", vid = "visit_id") ) unlink(tmp)
Functions for reading and writing signal data in CSV/TSV format. Supports both wide format (time x channels) and long format. Read PhysioExperiment from CSV file
readCSV( path, format = c("wide", "long"), time_col = NULL, channel_cols = NULL, sampling_rate = NULL, sep = ",", header = TRUE, ... )readCSV( path, format = c("wide", "long"), time_col = NULL, channel_cols = NULL, sampling_rate = NULL, sep = ",", header = TRUE, ... )
path |
Path to the CSV file. |
format |
Data format: "wide" (time x channels) or "long" (stacked). |
time_col |
Name of the time column. If NULL, assumes first column or generates time from sampling rate. |
channel_cols |
For wide format, column names/indices to use as channels. If NULL, uses all non-time columns. |
sampling_rate |
Sampling rate in Hz. Required if time column is not present. |
sep |
Column separator. Default is ",". |
header |
Logical. If TRUE, first row contains column names. |
... |
Additional arguments passed to read.csv/read.table. |
Reads physiological signal data from a CSV file.
A PhysioExperiment object.
Wickham H (2014). "Tidy Data." Journal of Statistical Software, 59(10), 1-23. doi:10.18637/jss.v059.i10
writeCSV, readEventsCSV,
readEDF, readMAT
## Not run: # Read wide-format CSV with time column pe <- readCSV("signals.csv", time_col = "time", sampling_rate = 256) # Read without time column (generate from sampling rate) pe <- readCSV("signals.csv", sampling_rate = 256) # Read TSV file pe <- readCSV("signals.tsv", sep = "\t", sampling_rate = 256) ## End(Not run)## Not run: # Read wide-format CSV with time column pe <- readCSV("signals.csv", time_col = "time", sampling_rate = 256) # Read without time column (generate from sampling rate) pe <- readCSV("signals.csv", sampling_rate = 256) # Read TSV file pe <- readCSV("signals.tsv", sep = "\t", sampling_rate = 256) ## End(Not run)
Functions for reading European Data Format (EDF/EDF+) files commonly used for EEG, PSG, and other physiological recordings. Read EDF/EDF+ file
readEDF(path, channels = NULL, start_time = NULL, end_time = NULL)readEDF(path, channels = NULL, start_time = NULL, end_time = NULL)
path |
Path to the EDF file. |
channels |
Optional character vector of channel names to load. If NULL, all channels are loaded. |
start_time |
Optional start time in seconds for reading a subset. |
end_time |
Optional end time in seconds for reading a subset. |
Reads an EDF or EDF+ file and returns a PhysioExperiment object.
EDF (European Data Format) is a standard file format for storing multichannel physiological signals. EDF+ extends this with annotations and discontinuous recordings.
The function parses the EDF header to extract:
Channel labels and types
Sampling rates (may differ per channel)
Physical dimensions (units)
Recording start date/time
If channels have different sampling rates, data is resampled to the highest rate.
A PhysioExperiment object with the EDF signal
data stored in the "raw" assay. Channel metadata (label, transducer,
physical dimensions, digital/physical min/max) are stored in colData,
and recording metadata (patient ID, start date/time) in metadata.
Kemp, B., et al. (1992). "A simple format for exchange of digitized polygraphic recordings." Electroencephalography and Clinical Neurophysiology, 82(5), 391-393. doi:10.1016/0013-4694(92)90009-7
writeEDF, readBIDS,
readPhysioHDF5, readCSV
## Not run: # Read an EDF file pe <- readEDF("recording.edf") # Read only specific channels pe <- readEDF("recording.edf", channels = c("Fp1", "Fp2", "C3", "C4")) # Read a time window (10 to 60 seconds) pe <- readEDF("recording.edf", start_time = 10, end_time = 60) ## End(Not run)## Not run: # Read an EDF file pe <- readEDF("recording.edf") # Read only specific channels pe <- readEDF("recording.edf", channels = c("Fp1", "Fp2", "C3", "C4")) # Read a time window (10 to 60 seconds) pe <- readEDF("recording.edf", start_time = 10, end_time = 60) ## End(Not run)
Reads electrode positions from a CSV file with x, y, z coordinates.
readElectrodePositionsCSV( path, name_col = "name", x_col = "x", y_col = "y", z_col = "z", sep = ",", ... )readElectrodePositionsCSV( path, name_col = "name", x_col = "x", y_col = "y", z_col = "z", sep = ",", ... )
path |
Path to the CSV file. |
name_col |
Name of the electrode name column. |
x_col |
Name of the x coordinate column. |
y_col |
Name of the y coordinate column. |
z_col |
Name of the z coordinate column. |
sep |
Column separator. |
... |
Additional arguments passed to read.csv. |
A data.frame with electrode positions.
Wickham H (2014). "Tidy Data." Journal of Statistical Software, 59(10), 1-23. doi:10.18637/jss.v059.i10
writeElectrodePositionsCSV, readCSV,
readBIDS
## Not run: # Read electrode positions positions <- readElectrodePositionsCSV("electrodes.csv") # Apply to PhysioExperiment pe <- setElectrodePositions(pe, positions) ## End(Not run)## Not run: # Read electrode positions positions <- readElectrodePositionsCSV("electrodes.csv") # Apply to PhysioExperiment pe <- setElectrodePositions(pe, positions) ## End(Not run)
Reads event markers from a CSV file with onset, duration, and type columns.
readEventsCSV( path, onset_col = "onset", duration_col = "duration", type_col = "type", value_col = "value", sep = ",", ... )readEventsCSV( path, onset_col = "onset", duration_col = "duration", type_col = "type", value_col = "value", sep = ",", ... )
path |
Path to the CSV file. |
onset_col |
Name of the onset column (in seconds). |
duration_col |
Name of the duration column. |
type_col |
Name of the event type column. |
value_col |
Name of the event value column. |
sep |
Column separator. |
... |
Additional arguments passed to read.csv. |
A PhysioEvents object.
Wickham H (2014). "Tidy Data." Journal of Statistical Software, 59(10), 1-23. doi:10.18637/jss.v059.i10
writeEventsCSV, readCSV,
readBIDS
## Not run: # Read events from CSV events <- readEventsCSV("events.csv") # Add to PhysioExperiment pe <- setEvents(pe, events) ## End(Not run)## Not run: # Read events from CSV events <- readEventsCSV("events.csv") # Add to PhysioExperiment pe <- setEvents(pe, events) ## End(Not run)
Reads physiological signal data from a MATLAB .mat file. Supports both standard .mat files and EEGLAB .set structures.
readMAT( path, data_var = NULL, sr_var = NULL, channel_var = NULL, event_var = NULL, transpose = FALSE )readMAT( path, data_var = NULL, sr_var = NULL, channel_var = NULL, event_var = NULL, transpose = FALSE )
path |
Path to the .mat file. |
data_var |
Name of the variable containing signal data. If NULL, attempts to auto-detect. |
sr_var |
Name of the variable containing sampling rate. |
channel_var |
Name of the variable containing channel labels. |
event_var |
Name of the variable containing events. |
transpose |
Logical. If TRUE, transposes the data matrix. |
The function attempts to auto-detect the data structure if variable names are not specified. It looks for common variable names used in EEG toolboxes:
data, EEG.data, signal, X for signal data
srate, fs, Fs, samplingRate for sampling rate
chanlocs, channels, labels for channel information
event, events, EEG.event for events
A PhysioExperiment object.
MathWorks (2024). "MAT-File Format." Technical documentation. https://www.mathworks.com/help/matlab/import_export/mat-file-versions.html
writeMAT, readEDF,
readCSV, readPhysioHDF5
## Not run: # Read MATLAB file with auto-detection pe <- readMAT("eeg_data.mat") # Specify variable names pe <- readMAT("data.mat", data_var = "signal", sr_var = "fs") # Read EEGLAB format pe <- readMAT("EEG.set", data_var = "EEG") ## End(Not run)## Not run: # Read MATLAB file with auto-detection pe <- readMAT("eeg_data.mat") # Specify variable names pe <- readMAT("data.mat", data_var = "signal", sr_var = "fs") # Read EEGLAB format pe <- readMAT("EEG.set", data_var = "EEG") ## End(Not run)
Reads a PhysioExperiment object from HDF5 format. By default, returns DelayedArray-backed assays for out-of-memory processing.
readPhysioHDF5(path, as_delayed = TRUE)readPhysioHDF5(path, as_delayed = TRUE)
path |
Path to the HDF5 file. |
as_delayed |
Logical. If TRUE (default), returns DelayedArray-backed assays. If FALSE, loads data into memory. |
A PhysioExperiment object. When
as_delayed = TRUE, assays are HDF5Array objects enabling
out-of-memory access; when FALSE, assays are standard in-memory
arrays.
The HDF Group (1997-2024). "Hierarchical Data Format, version 5." https://www.hdfgroup.org/HDF5/
writePhysioHDF5, isHDF5Backed,
realizeHDF5, writeAssayHDF5
## Not run: # Read HDF5 file with DelayedArray backend (out-of-memory) pe <- readPhysioHDF5("data.h5") isHDF5Backed(pe) # TRUE # Read HDF5 file into memory pe_mem <- readPhysioHDF5("data.h5", as_delayed = FALSE) isHDF5Backed(pe_mem) # FALSE ## End(Not run)## Not run: # Read HDF5 file with DelayedArray backend (out-of-memory) pe <- readPhysioHDF5("data.h5") isHDF5Backed(pe) # TRUE # Read HDF5 file into memory pe_mem <- readPhysioHDF5("data.h5", as_delayed = FALSE) isHDF5Backed(pe_mem) # FALSE ## End(Not run)
Loads HDF5-backed assays into memory as regular arrays.
realizeHDF5(x, assays = NULL)realizeHDF5(x, assays = NULL)
x |
A PhysioExperiment object. |
assays |
Optional character vector of assay names to realize. If NULL, realizes all assays. |
A PhysioExperiment object with the specified
assays realized as in-memory arrays.
The HDF Group (1997-2024). "Hierarchical Data Format, version 5." https://www.hdfgroup.org/HDF5/
readPhysioHDF5, writePhysioHDF5,
isHDF5Backed
## Not run: # Load HDF5-backed data pe <- readPhysioHDF5("data.h5") # Realize all assays to memory pe_mem <- realizeHDF5(pe) # Realize only specific assays pe_partial <- realizeHDF5(pe, assays = c("raw", "filtered")) ## End(Not run)## Not run: # Load HDF5-backed data pe <- readPhysioHDF5("data.h5") # Realize all assays to memory pe_mem <- realizeHDF5(pe) # Realize only specific assays pe_partial <- realizeHDF5(pe, assays = c("raw", "filtered")) ## End(Not run)
Stores experiment metadata and optionally signal data in the database.
registerExperiment( con, x, experiment_id = NULL, subject_id = NULL, session_id = NULL, task = NULL, store_signals = FALSE, chunk_size = 10000L )registerExperiment( con, x, experiment_id = NULL, subject_id = NULL, session_id = NULL, task = NULL, store_signals = FALSE, chunk_size = 10000L )
con |
A DuckDB connection. |
x |
A PhysioExperiment object. |
experiment_id |
Unique identifier for the experiment. |
subject_id |
Subject identifier. |
session_id |
Session identifier. |
task |
Task name. |
store_signals |
If TRUE, stores signal data in chunks. |
chunk_size |
Number of samples per chunk for signal storage. |
The experiment_id.
Raasveldt M, Muehleisen H (2019). "DuckDB: an embeddable analytical database." Proceedings of the 2019 International Conference on Management of Data (SIGMOD). doi:10.1145/3299869.3320212
loadExperiment, queryExperiments,
deleteExperiment, initPhysioSchema
## Not run: con <- connectDatabase() initPhysioSchema(con) # Create sample data pe <- PhysioExperiment( assays = list(raw = matrix(rnorm(10000), nrow = 1000, ncol = 10)), samplingRate = 256 ) # Register experiment (metadata only) exp_id <- registerExperiment(con, pe, subject_id = "sub01", task = "rest" ) # Register with signal data exp_id <- registerExperiment(con, pe, subject_id = "sub02", task = "oddball", store_signals = TRUE ) disconnectDatabase(con) ## End(Not run)## Not run: con <- connectDatabase() initPhysioSchema(con) # Create sample data pe <- PhysioExperiment( assays = list(raw = matrix(rnorm(10000), nrow = 1000, ncol = 10)), samplingRate = 256 ) # Register experiment (metadata only) exp_id <- registerExperiment(con, pe, subject_id = "sub01", task = "rest" ) # Register with signal data exp_id <- registerExperiment(con, pe, subject_id = "sub02", task = "oddball", store_signals = TRUE ) disconnectDatabase(con) ## End(Not run)
Performs basic validation of BIDS compliance.
validateBIDS(bids_root)validateBIDS(bids_root)
bids_root |
Path to the BIDS dataset root. |
A list with validation results.
Gorgolewski KJ, et al. (2016). "The brain imaging data structure, a format for organizing and describing outputs of neuroimaging experiments." Scientific Data, 3, 160044. doi:10.1038/sdata.2016.44
readBIDS, writeBIDS,
listBIDSSubjects
## Not run: # Validate a BIDS dataset result <- validateBIDS("path/to/bids") if (result$valid) { message("Dataset is BIDS-compliant") } else { message("Validation errors: ", paste(result$errors, collapse = ", ")) } ## End(Not run)## Not run: # Validate a BIDS dataset result <- validateBIDS("path/to/bids") if (result$valid) { message("Dataset is BIDS-compliant") } else { message("Validation errors: ", paste(result$errors, collapse = ", ")) } ## End(Not run)
Validate clinical metadata
validateClinicalMetadata( x, required_cols = c("subject_id", "visit_id", "scale_name", "scale_score"), allowed_source_system = c("EDC", "EHR", "paper_crf"), allowed_assessor_role = c("PT", "OT", "MD", "RN", "researcher"), strict = FALSE )validateClinicalMetadata( x, required_cols = c("subject_id", "visit_id", "scale_name", "scale_score"), allowed_source_system = c("EDC", "EHR", "paper_crf"), allowed_assessor_role = c("PT", "OT", "MD", "RN", "researcher"), strict = FALSE )
x |
Data frame created from EDC/EHR exports. |
required_cols |
Required columns that must exist and be non-missing. |
allowed_source_system |
Allowed values for |
allowed_assessor_role |
Allowed values for |
strict |
Logical; stop when validation fails. |
A list with validation details and an overall valid flag.
Goldberger AL, et al. (2000). "PhysioBank, PhysioToolkit, and PhysioNet: components of a new research resource for complex physiologic signals." Circulation, 101(23), e215-e220. doi:10.1161/01.CIR.101.23.e215
readClinicalMetadataCSV,
mapClinicalCodes, validateBIDS
df <- data.frame( subject_id = "S01", visit_id = "V01", scale_name = "FIM", scale_score = 88, assessment_date = "2026-01-01", stringsAsFactors = FALSE ) validateClinicalMetadata(df)df <- data.frame( subject_id = "S01", visit_id = "V01", scale_name = "FIM", scale_score = 88, assessment_date = "2026-01-01", stringsAsFactors = FALSE ) validateClinicalMetadata(df)
Writes a single assay to an existing HDF5 file.
writeAssayHDF5(x, path, assay_name, compression_level = 6L)writeAssayHDF5(x, path, assay_name, compression_level = 6L)
x |
A PhysioExperiment object. |
path |
Path to the HDF5 file. |
assay_name |
Character string naming the assay to write. |
compression_level |
Integer compression level (0-9). |
Invisible NULL. The assay is written to the HDF5 file as a
side effect.
The HDF Group (1997-2024). "Hierarchical Data Format, version 5." https://www.hdfgroup.org/HDF5/
writePhysioHDF5, readPhysioHDF5,
realizeHDF5
## Not run: # Add a new processed assay to an existing HDF5 file pe <- readPhysioHDF5("data.h5") pe <- butterworthFilter(pe, low = 1, high = 30, type = "pass") # Write the filtered assay back to the HDF5 file writeAssayHDF5(pe, "data.h5", "filtered") ## End(Not run)## Not run: # Add a new processed assay to an existing HDF5 file pe <- readPhysioHDF5("data.h5") pe <- butterworthFilter(pe, low = 1, high = 30, type = "pass") # Write the filtered assay back to the HDF5 file writeAssayHDF5(pe, "data.h5", "filtered") ## End(Not run)
Writes data in BIDS-compliant directory structure.
writeBIDS( x, bids_root, subject, session = NULL, task, run = NULL, modality = c("eeg", "ieeg"), overwrite = FALSE )writeBIDS( x, bids_root, subject, session = NULL, task, run = NULL, modality = c("eeg", "ieeg"), overwrite = FALSE )
x |
A PhysioExperiment object. |
bids_root |
Path to the BIDS dataset root directory. |
subject |
Subject identifier (without 'sub-' prefix). |
session |
Session identifier (without 'ses-' prefix). Optional. |
task |
Task name. |
run |
Run number. Optional. |
modality |
Data modality: "eeg" or "ieeg". |
overwrite |
If TRUE, overwrites existing files. |
Invisible path to the created files.
Gorgolewski KJ, et al. (2016). "The brain imaging data structure, a format for organizing and describing outputs of neuroimaging experiments." Scientific Data, 3, 160044. doi:10.1038/sdata.2016.44
readBIDS, writeEDF,
listBIDSSubjects, validateBIDS
## Not run: # Create a PhysioExperiment pe <- PhysioExperiment( assays = list(raw = matrix(rnorm(25600), nrow = 2560, ncol = 10)), colData = S4Vectors::DataFrame(label = paste0("Ch", 1:10)), samplingRate = 256 ) # Export to BIDS format writeBIDS(pe, "path/to/bids", subject = "01", task = "rest") # With session and run writeBIDS(pe, "path/to/bids", subject = "01", session = "01", task = "oddball", run = 1) ## End(Not run)## Not run: # Create a PhysioExperiment pe <- PhysioExperiment( assays = list(raw = matrix(rnorm(25600), nrow = 2560, ncol = 10)), colData = S4Vectors::DataFrame(label = paste0("Ch", 1:10)), samplingRate = 256 ) # Export to BIDS format writeBIDS(pe, "path/to/bids", subject = "01", task = "rest") # With session and run writeBIDS(pe, "path/to/bids", subject = "01", session = "01", task = "oddball", run = 1) ## End(Not run)
Writes physiological signal data to a CSV file.
writeCSV( x, path, format = c("wide", "long"), include_time = TRUE, assay_name = NULL, sep = ",", ... )writeCSV( x, path, format = c("wide", "long"), include_time = TRUE, assay_name = NULL, sep = ",", ... )
x |
A PhysioExperiment object. |
path |
Output file path. |
format |
Output format: "wide" (time x channels) or "long". |
include_time |
Logical. If TRUE, includes a time column. |
assay_name |
Assay to export. If NULL, uses default assay. |
sep |
Column separator. Default is ",". |
... |
Additional arguments passed to write.csv/write.table. |
Invisible path to the created file.
Wickham H (2014). "Tidy Data." Journal of Statistical Software, 59(10), 1-23. doi:10.18637/jss.v059.i10
readCSV, writeEventsCSV,
writeEDF, writePhysioHDF5
# Create example data pe <- PhysioExperiment( assays = list(raw = matrix(rnorm(400), nrow = 100, ncol = 4)), colData = S4Vectors::DataFrame(label = c("Fz", "Cz", "Pz", "Oz")), samplingRate = 100 ) # Write to temporary CSV file tmp <- tempfile(fileext = ".csv") writeCSV(pe, tmp) # Write in long format writeCSV(pe, tmp, format = "long") # Clean up unlink(tmp)# Create example data pe <- PhysioExperiment( assays = list(raw = matrix(rnorm(400), nrow = 100, ncol = 4)), colData = S4Vectors::DataFrame(label = c("Fz", "Cz", "Pz", "Oz")), samplingRate = 100 ) # Write to temporary CSV file tmp <- tempfile(fileext = ".csv") writeCSV(pe, tmp) # Write in long format writeCSV(pe, tmp, format = "long") # Clean up unlink(tmp)
Writes a PhysioExperiment object to EDF format.
writeEDF(x, path, patient_id = "X", recording_id = "X")writeEDF(x, path, patient_id = "X", recording_id = "X")
x |
A PhysioExperiment object. |
path |
Output file path. |
patient_id |
Patient identification string. |
recording_id |
Recording identification string. |
Invisible NULL. The EDF file is written to path as a
side effect.
Kemp, B., et al. (1992). "A simple format for exchange of digitized polygraphic recordings." Electroencephalography and Clinical Neurophysiology, 82(5), 391-393. doi:10.1016/0013-4694(92)90009-7
readEDF, writeBIDS,
writePhysioHDF5, writeCSV
## Not run: # Create a PhysioExperiment with EEG-like data pe <- PhysioExperiment( assays = list(raw = matrix(rnorm(25600), nrow = 2560, ncol = 10)), colData = S4Vectors::DataFrame(label = paste0("Ch", 1:10)), samplingRate = 256 ) # Export to EDF format writeEDF(pe, "output.edf", patient_id = "Subject01", recording_id = "Session1") ## End(Not run)## Not run: # Create a PhysioExperiment with EEG-like data pe <- PhysioExperiment( assays = list(raw = matrix(rnorm(25600), nrow = 2560, ncol = 10)), colData = S4Vectors::DataFrame(label = paste0("Ch", 1:10)), samplingRate = 256 ) # Export to EDF format writeEDF(pe, "output.edf", patient_id = "Subject01", recording_id = "Session1") ## End(Not run)
Writes electrode positions from a PhysioExperiment to CSV.
writeElectrodePositionsCSV(x, path, sep = ",", ...)writeElectrodePositionsCSV(x, path, sep = ",", ...)
x |
A PhysioExperiment object with electrode positions. |
path |
Output file path. |
sep |
Column separator. |
... |
Additional arguments passed to write.csv. |
Invisible path to the created file.
Wickham H (2014). "Tidy Data." Journal of Statistical Software, 59(10), 1-23. doi:10.18637/jss.v059.i10
readElectrodePositionsCSV, writeCSV,
writeBIDS
pe <- PhysioExperiment( assays = list(raw = matrix(rnorm(400), nrow = 100, ncol = 4)), colData = S4Vectors::DataFrame(label = c("Fz", "Cz", "Pz", "Oz")), samplingRate = 100 ) pe <- applyMontage(pe, "10-20") # Write electrode positions tmp <- tempfile(fileext = ".csv") writeElectrodePositionsCSV(pe, tmp) # Clean up unlink(tmp)pe <- PhysioExperiment( assays = list(raw = matrix(rnorm(400), nrow = 100, ncol = 4)), colData = S4Vectors::DataFrame(label = c("Fz", "Cz", "Pz", "Oz")), samplingRate = 100 ) pe <- applyMontage(pe, "10-20") # Write electrode positions tmp <- tempfile(fileext = ".csv") writeElectrodePositionsCSV(pe, tmp) # Clean up unlink(tmp)
Writes PhysioEvents to a CSV file.
writeEventsCSV(events, path, sep = ",", ...)writeEventsCSV(events, path, sep = ",", ...)
events |
A PhysioEvents object. |
path |
Output file path. |
sep |
Column separator. |
... |
Additional arguments passed to write.csv. |
Invisible path to the created file.
Wickham H (2014). "Tidy Data." Journal of Statistical Software, 59(10), 1-23. doi:10.18637/jss.v059.i10
readEventsCSV, writeCSV,
writeBIDS
# Create events events <- PhysioEvents( onset = c(1.0, 2.5, 4.0), duration = c(0.5, 0.5, 0.5), type = c("stimulus", "stimulus", "response"), value = c("A", "B", "correct") ) # Write to temporary file tmp <- tempfile(fileext = ".csv") writeEventsCSV(events, tmp) # Clean up unlink(tmp)# Create events events <- PhysioEvents( onset = c(1.0, 2.5, 4.0), duration = c(0.5, 0.5, 0.5), type = c("stimulus", "stimulus", "response"), value = c("A", "B", "correct") ) # Write to temporary file tmp <- tempfile(fileext = ".csv") writeEventsCSV(events, tmp) # Clean up unlink(tmp)
Saves a PhysioExperiment object to MATLAB .mat format.
writeMAT( x, path, data_var = "data", include_metadata = TRUE, assay_name = NULL )writeMAT( x, path, data_var = "data", include_metadata = TRUE, assay_name = NULL )
x |
A PhysioExperiment object. |
path |
Output file path. |
data_var |
Name for the data variable in the .mat file. |
include_metadata |
Logical. If TRUE, includes metadata variables. |
assay_name |
Assay to export. If NULL, uses default assay. |
Invisible NULL.
MathWorks (2024). "MAT-File Format." Technical documentation. https://www.mathworks.com/help/matlab/import_export/mat-file-versions.html
readMAT, writeCSV,
writeEDF, writePhysioHDF5
## Not run: pe <- PhysioExperiment( assays = list(raw = matrix(rnorm(1000), nrow = 100, ncol = 10)), colData = S4Vectors::DataFrame(label = paste0("Ch", 1:10)), samplingRate = 256 ) # Write to .mat file writeMAT(pe, "output.mat") # Custom variable name writeMAT(pe, "output.mat", data_var = "EEG_data") ## End(Not run)## Not run: pe <- PhysioExperiment( assays = list(raw = matrix(rnorm(1000), nrow = 100, ncol = 10)), colData = S4Vectors::DataFrame(label = paste0("Ch", 1:10)), samplingRate = 256 ) # Write to .mat file writeMAT(pe, "output.mat") # Custom variable name writeMAT(pe, "output.mat", data_var = "EEG_data") ## End(Not run)
These helper functions provide a lightweight interface to serialise and
deserialise PhysioExperiment objects to RDS files. They act as placeholders
for richer IO backends that can be developed later.
writePhysio(x, path) readPhysio(path)writePhysio(x, path) readPhysio(path)
x |
A |
path |
Path to an |
readPhysio() returns a PhysioExperiment object.
writePhysio() returns the input object invisibly.
Wickham, H. (2014). "Tidy Data." Journal of Statistical Software, 59(10), 1-23. doi:10.18637/jss.v059.i10
readEDF, readPhysioHDF5,
readCSV, readMAT
# Create a PhysioExperiment object pe <- PhysioExperiment( assays = list(raw = matrix(rnorm(1000), nrow = 100, ncol = 10)), samplingRate = 256 ) # Write to a temporary file tmp <- tempfile(fileext = ".rds") writePhysio(pe, tmp) # Read it back pe_loaded <- readPhysio(tmp) samplingRate(pe_loaded) # Clean up unlink(tmp)# Create a PhysioExperiment object pe <- PhysioExperiment( assays = list(raw = matrix(rnorm(1000), nrow = 100, ncol = 10)), samplingRate = 256 ) # Write to a temporary file tmp <- tempfile(fileext = ".rds") writePhysio(pe, tmp) # Read it back pe_loaded <- readPhysio(tmp) samplingRate(pe_loaded) # Clean up unlink(tmp)
Functions for reading and writing PhysioExperiment objects to HDF5 format, supporting out-of-memory operations for large datasets. Write PhysioExperiment to HDF5
writePhysioHDF5( x, path, overwrite = FALSE, chunk_dims = NULL, compression_level = 6L )writePhysioHDF5( x, path, overwrite = FALSE, chunk_dims = NULL, compression_level = 6L )
x |
A PhysioExperiment object. |
path |
Path to the output HDF5 file. |
overwrite |
Logical. If TRUE, overwrites existing file. |
chunk_dims |
Optional integer vector specifying chunk dimensions for
HDF5 storage. If |
compression_level |
Integer compression level (0-9). Default is 6. |
Saves a PhysioExperiment object to HDF5 format, enabling out-of-memory access for large datasets.
Invisible NULL. The HDF5 file is written to path as
a side effect.
The HDF Group (1997-2024). "Hierarchical Data Format, version 5." https://www.hdfgroup.org/HDF5/
readPhysioHDF5, isHDF5Backed,
realizeHDF5, writeAssayHDF5
## Not run: # Create a large PhysioExperiment pe <- PhysioExperiment( assays = list(raw = matrix(rnorm(1e6), nrow = 1e5, ncol = 10)), samplingRate = 1000 ) # Save to HDF5 with compression writePhysioHDF5(pe, "data.h5", compression_level = 6) # Overwrite existing file writePhysioHDF5(pe, "data.h5", overwrite = TRUE) ## End(Not run)## Not run: # Create a large PhysioExperiment pe <- PhysioExperiment( assays = list(raw = matrix(rnorm(1e6), nrow = 1e5, ncol = 10)), samplingRate = 1000 ) # Save to HDF5 with compression writePhysioHDF5(pe, "data.h5", compression_level = 6) # Overwrite existing file writePhysioHDF5(pe, "data.h5", overwrite = TRUE) ## End(Not run)