API Reference

BrainVisionDataFormat

Julia package for reading BrainVision EEG data files (.vhdr, .vmrk, .eeg format).

This package provides functionality to:

• Read BrainVision files (.vhdr, .vmrk, .eeg) into Julia data structures

File Format

BrainVision files consist of three components:

• .vhdr: Header file with metadata and channel information
• .vmrk: Marker file with event/trigger information
• .eeg: Binary data file with EEG samples

Quick Start

using BrainVisionDataFormat

# Read complete BrainVision dataset
data = read_brainvision("experiment")

# Read only markers
markers = read_brainvision_markers("experiment.vmrk")

# Read only header
header = read_brainvision_header("experiment.vhdr")

BrainVisionHeader

Represents header information from a BrainVision .vhdr file.

Fields

• DataFile::String: Name of the EEG data file
• MarkerFile::String: Name of the marker file
• DataFormat::String: Data format (e.g., "BINARY")
• DataOrientation::String: Data orientation (e.g., "MULTIPLEXED")
• BinaryFormat::String: Binary format specification
• NumberOfChannels::Int: Number of channels
• SamplingInterval::Float64: Sampling interval in microseconds
• Fs::Float64: Sampling rate in Hz
• label::Vector{String}: Channel labels
• reference::Vector{String}: Reference information
• resolution::Vector{Float64}: Resolution values
• unit::Vector{String}: Unit information
• nSamples::Int: Number of samples
• nTrials::Int: Number of trials
• nSamplesPre::Int: Number of pre-stimulus samples
• impedances::Union{NamedTuple, Nothing}: Impedance information if available

Example

header = read_brainvision_header("experiment.vhdr")
println("Sampling rate: $(header.Fs) Hz")
println("Number of channels: $(header.NumberOfChannels)")

BrainVisionMarker

Represents a single marker event from a BrainVision .vmrk file.

Fields

• type::String: Event type (e.g., "Stimulus", "Response", "New Segment")
• value::String: Event value/description
• sample::Int: Sample number (position in data points)
• duration::Int: Duration in data points
• timestamp::Union{String, Nothing}: Timestamp if available (raw string format)

Example

marker = BrainVisionMarker("Stimulus", "S 11", 209263, 1, nothing)
println("Type: $(marker.type), Sample: $(marker.sample)")

BrainVisionData

Container for complete BrainVision data including EEG data, markers, and header metadata.

Fields

• data::Union{Matrix{Float64}, Nothing}: EEG data matrix (samples × channels)
• markers::Vector{BrainVisionMarker}: Array of marker events
• header::Union{BrainVisionHeader, Nothing}: Header information
• filename::String: Source filename

Example

data = read_brainvision_complete("experiment.vhdr")
println("EEG data shape: $(size(data.data))")
println("Found $(length(data.markers)) events")

BrainVisionMarkerData

Legacy container for BrainVision data with only markers and metadata.

Fields

• markers::Vector{BrainVisionMarker}: Array of marker events
• filename::String: Source filename
• n_events::Int: Number of events
• sampling_rate::Union{Float64, Nothing}: Sampling rate if available

Example

data = read_brainvision("experiment.vmrk")
println("Found $(length(data.markers)) events")

read_brainvision(base_filename; begsample=1, endsample=nothing, chanindx=nothing)

Read complete BrainVision dataset from base filename (without extension).

This is the main entry point for reading BrainVision data. It loads the header, markers, and EEG data from the three-file BrainVision format (.vhdr, .vmrk, .eeg) and returns a complete dataset object.

Arguments

• base_filename::String: Base filename without extension (e.g., "experiment" for "experiment.vhdr")
• begsample::Int: First sample to read (1-indexed, default: 1)
• endsample::Union{Int, Nothing}: Last sample to read (default: all samples)
• chanindx::Union{AbstractVector{Int}, Nothing}: Channel indices to read (default: all channels)

Returns

• BrainVisionData: Complete dataset with EEG data, markers, and header

Examples

# Load complete dataset
data = read_brainvision("experiment")

# Access components
data = data.data  # Matrix{Float64} (samples × channels)
markers = data.markers    # Vector{BrainVisionMarker}
header = data.header      # BrainVisionHeader

# Load specific time range
data = read_brainvision("experiment", begsample=1000, endsample=5000)

# Load specific channels
data = read_brainvision("experiment", chanindx=1:10)

Notes

• The function automatically finds the corresponding .vhdr, .vmrk, and .eeg files
• All three files must exist for successful loading
• EEG data is returned as a matrix with dimensions (samples × channels)
• Data is automatically scaled to microvolts using resolution values from the header

See Also

• read_brainvision_header - Read only header
• read_brainvision_markers - Read only markers

read_brainvision_header(filename)

Read BrainVision header file (.vhdr) and return a BrainVisionHeader object.

This function parses the header file to extract all metadata including channel information, recording parameters, sampling rate, and file format specifications.

Arguments

• filename::String: Path to the .vhdr file

Returns

• BrainVisionHeader: Complete header information with all metadata

Examples

# Read header from file
header = read_brainvision_header("experiment.vhdr")

# Access header information
println("Channels: ", header.NumberOfChannels)
println("Sampling rate: ", header.Fs, " Hz")
println("Data format: ", header.DataFormat)

See Also

• read_brainvision - Read complete dataset
• read_brainvision_markers - Read marker file

read_brainvision_markers(filename)

Read BrainVision marker file (.vmrk) and return a BrainVisionMarkerData object.

This function parses the marker file to extract all event/trigger information including timestamps, durations, and marker types. Markers are commonly used to mark experimental events, artifacts, or other significant time points in the EEG recording.

Arguments

• filename::String: Path to the .vmrk file

Returns

• BrainVisionMarkerData: Container with all markers and metadata

Examples

# Read markers from file
markers = read_brainvision_markers("experiment.vmrk")

# Access marker information
println("Found ", markers.n_events, " events")
for marker in markers.markers
    println("Event: ", marker.type, " at sample ", marker.sample)
end

See Also

• read_brainvision - Read complete dataset
• read_brainvision_header - Read header file
• get_markers_by_type - Filter markers by type

get_markers_by_type(data, type)

Get all markers of a specific type.

Arguments

• data::Union{BrainVisionData, BrainVisionMarkerData}: BrainVision data container
• type::String: Marker type to filter by (e.g., "Stimulus", "Response")

Returns

• Vector{BrainVisionMarker}: Filtered markers of the specified type

Example

stimuli = get_markers_by_type(data, "Stimulus")
println("Found $(length(stimuli)) stimulus events")

get_markers_in_range(data, start_sample, end_sample)

Get all markers within a sample range.

Arguments

• data::Union{BrainVisionData, BrainVisionMarkerData}: BrainVision data container
• start_sample::Int: First sample number (inclusive)
• end_sample::Int: Last sample number (inclusive)

Returns

• Vector{BrainVisionMarker}: Markers within the specified sample range

Example

early_events = get_markers_in_range(data, 1, 100000)
println("Found $(length(early_events)) events in first 100k samples")

get_unique_types(data)

Get all unique marker types in the data.

Arguments

• data::Union{BrainVisionData, BrainVisionMarkerData}: BrainVision data container

Returns

• Vector{String}: Unique marker types found in the data

Example

types = get_unique_types(data)
println("Found types: $types")

samples_to_time(samples, sampling_rate)

Convert sample numbers to time in seconds.

Arguments

• samples::Union{Int, Vector{Int}}: Sample number(s) to convert
• sampling_rate::Float64: Sampling rate in Hz

Returns

• Union{Float64, Vector{Float64}}: Time in seconds

Example

time_sec = samples_to_time(1000, 500.0)  # 2.0 seconds
times = samples_to_time([1000, 2000, 3000], 500.0)  # [2.0, 4.0, 6.0] seconds