EegFun

Appearance

BIDS Export ​

Export your EegFun data (raw files and/or preprocessed outputs) to a BIDS-compliant directory structure.

The generated dataset can be validated using the BIDS Validator.

Minimal Example (Raw Data Only) ​

julia
using EegFun

EegFun.export_bids(
    task = "posner",
    raw_dir = ".",
    output_dir = "./bids_dataset",
)

This discovers all .bdf files in raw_dir, auto-extracts subject IDs from the filenames (example1.bdf → sub-01), and creates the BIDS structure with all required sidecar files.

Full Example ​

julia
EegFun.export_bids(
    # Required
    task = "posner",
    raw_dir = ".",
    output_dir = "./bids_dataset",
    layout_file = "biosemi72.csv",

    # Dataset metadata
    dataset_name = "Visual Attention (Posner Cueing)",
    dataset_authors = ["Author A", "Author B"],
    dataset_license = "CC0",

    # Equipment
    manufacturer = "BioSemi",
    manufacturer_model = "ActiveTwo",
    cap_manufacturer = "BioSemi",
    cap_model = "headcap with 72 active electrodes",

    # Task
    task_description = "Posner cueing task with valid and invalid spatial cues",
    instructions = "Fixate on the central cross. Press the button as quickly as possible when the target appears.",

    # Recording context
    institution_name = "Your University",
    institution_address = "123 University Street, City, Country",
    institution_department = "Department of Psychology",
    eeg_ground = "CMS/DRL",
    eeg_placement_scheme = "10-10 subset with 72 electrodes",
    power_line_frequency = 50,

    overwrite = true,
)

Including Preprocessed Data (Derivatives) ​

If you have already run the EegFun preprocessing pipeline, pass the derivatives_dir argument to include the preprocessed JLD2 files:

julia
EegFun.export_bids(
    task = "posner",
    raw_dir = ".",
    derivatives_dir = "./preprocessed_files",
    output_dir = "./bids_dataset",
    layout_file = "biosemi72.csv",
    dataset_name = "Visual Attention (Posner Cueing)",
    overwrite = true,
)

Pipeline output files are automatically renamed to BIDS naming conventions:

Pipeline SuffixBIDS Label
_continuous_originaldesc-continuousOriginal
_continuous_cleaneddesc-continuousCleaned
_epochs_originaldesc-epochsOriginal
_epochs_cleaneddesc-epochsCleaned
_epochs_gooddesc-epochsGood
_erps_originaldesc-erpsOriginal
_erps_cleaneddesc-erpsCleaned
_erps_gooddesc-erpsGood
_icadesc-ica
_artifact_infodesc-artifactInfo

Custom Subject ID Mapping ​

By default, subject IDs are auto-extracted from filenames using the first number found (example12.bdf → sub-12). For custom mappings, use the participant_map argument:

julia
EegFun.export_bids(
    task = "posner",
    raw_dir = ".",
    participant_map = Dict(
        "Pract6" => "sub-01",
        "ExpA2"  => "sub-02",
        "test_file_99" => "sub-03",
    ),
)

Generated Directory Structure ​

text
bids_dataset/
├── dataset_description.json
├── participants.tsv
├── participants.json
├── sub-01/
│   └── eeg/
│       ├── sub-01_task-posner_eeg.bdf
│       ├── sub-01_task-posner_eeg.json
│       ├── sub-01_task-posner_channels.tsv
│       ├── sub-01_task-posner_events.tsv
│       ├── sub-01_task-posner_events.json
│       ├── sub-01_task-posner_electrodes.tsv
│       └── sub-01_task-posner_coordsystem.json
├── sub-02/ ...
└── derivatives/
    └── EegFun/
        ├── dataset_description.json
        └── sub-01/
            └── eeg/
                ├── sub-01_task-posner_desc-epochsGood_eeg.jld2
                ├── sub-01_task-posner_desc-erpsGood_eeg.jld2
                └── ...

Auto-Computed Fields ​

The following fields are extracted automatically from your data — you don't need to provide them:

FieldSource
SamplingFrequencyFrom raw data
EEGReferenceFrom AnalysisInfo
EEGChannelCount / EOGChannelCount / etc.Auto-classified from channel names
RecordingDurationComputed from data length
RecordingTypeAlways "continuous" for raw data
Channel names, types, unitsFrom layout and channel labels
Event onsets and trigger valuesFrom trigger column
Electrode positions (x, y, z)From layout file

Validation ​

After exporting, validate your dataset using the BIDS Validator. Providing more of the optional metadata arguments will reduce the number of validator warnings.

API Reference ​

EegFun.export_bids Function
julia
export_bids(; task, raw_dir, raw_pattern, derivatives_dir, output_dir,
              layout_file, participant_map, dataset_name, dataset_authors,
              power_line_frequency, overwrite, ...)

Export an EegFun project (raw data + preprocessed outputs) to a BIDS-compliant directory structure.

The generated dataset can be validated using the BIDS Validator.

Keyword Arguments

  • task::String: Required. BIDS task label (e.g., "posner").

  • raw_dir::String: Directory containing raw data files (default: ".").

  • raw_pattern::String: Regex pattern for raw files (default: "\\.bdf").

  • derivatives_dir::String: Pipeline output directory containing JLD2 files (default: ""). If empty, only raw data is exported.

  • output_dir::String: Where to create the BIDS dataset (default: "./bids_dataset").

  • layout_file::String: Electrode layout CSV for electrode positions (default: ""). If empty, electrode/coordsystem files are skipped.

  • participant_map::Union{Nothing,Dict{String,String}}: Optional mapping from raw filenames (without extension) to BIDS subject IDs (e.g., "sub-01"). If nothing, IDs are auto-extracted from filenames.

  • dataset_name::String: Name for dataset_description.json (default: "").

  • dataset_authors::Vector{String}: Authors for dataset_description.json (default: String[]).

  • dataset_license::String: License for dataset (default: "CC0").

  • power_line_frequency::Int: Power line frequency in Hz, 50 (EU) or 60 (US) (default: 50).

  • overwrite::Bool: Overwrite existing output directory (default: false).

Recommended metadata (suppresses BIDS validator warnings)

  • task_description::String: Longer description of the task (default: "").

  • instructions::String: Instructions given to participants (default: "").

  • manufacturer::String: EEG equipment manufacturer, e.g., "BioSemi" (default: "").

  • manufacturer_model::String: Equipment model name, e.g., "ActiveTwo" (default: "").

  • cap_manufacturer::String: EEG cap manufacturer, e.g., "BioSemi" (default: "").

  • cap_model::String: Cap model name, e.g., "headcap with 72 active electrodes" (default: "").

  • institution_name::String: Name of the recording institution (default: "").

  • institution_address::String: Address of the institution (default: "").

  • institution_department::String: Department name (default: "").

  • eeg_ground::String: Description of ground electrode location (default: "").

  • eeg_placement_scheme::String: Electrode placement scheme, e.g., "10-20" (default: "").

Example

julia
EegFun.export_bids(
    task = "posner",
    raw_dir = ".",
    derivatives_dir = "./preprocessed_files",
    output_dir = "./bids_dataset",
    layout_file = "biosemi72.csv",
    dataset_name = "Visual Attention (Posner Cueing)",
    dataset_authors = ["Author A", "Author B"],
    manufacturer = "BioSemi",
    manufacturer_model = "ActiveTwo",
    cap_manufacturer = "BioSemi",
    task_description = "Visual attention task using Posner cueing paradigm",
    power_line_frequency = 50,
)
source