BCI IV-2a Conversion

BCI Competition IV data set 2a download and conversion utilities.

Classes:

Name	Description
BCI2AConversionConfig	Parameters for recreating the package processed .npy dataset.

Functions:

Name	Description
download_file	Download a URL unless it already exists.
download_bci2a	Download and extract official BCI Competition IV data set 2a archives.
copy_local_cache_to_processed	Copy an existing local .npy cache into the processed data directory.
convert_bci2a_training_subset	Convert official training GDF files into the six project .npy arrays.

BCI2AConversionConfig dataclass

BCI2AConversionConfig(
    window_samples: int = DEFAULT_WINDOW_SAMPLES,
    window_offset_samples: int = 1,
    test_trial_start: int = DEFAULT_TEST_TRIAL_START,
    test_trial_stop: int = DEFAULT_TEST_TRIAL_STOP,
    eeg_channels: int = N_EEG_CHANNELS,
    scale_to_microvolts: bool = True,
    quantize_microvolts: bool = True,
    reject_artifacts: bool = False,
    split_map: str | Path | None = "builtin",
)

Parameters for recreating the package processed .npy dataset.

Attributes:

Name	Type	Description
window_samples	int	Number of time samples extracted per trial.
window_offset_samples	int	Offset from cue onset before extraction starts.
test_trial_start	int	First trial ordinal for block-split test mode.
test_trial_stop	int	Stop trial ordinal for block-split test mode.
eeg_channels	int	Number of EEG channels to extract.
scale_to_microvolts	bool	Whether to convert MNE's volt values to microvolts.
quantize_microvolts	bool	Whether to round onto the GDF microvolt grid.
reject_artifacts	bool	Whether to remove trials containing GDF artifact marker 1023.
split_map	str | Path | None	Built-in package split, custom split-map JSON path, or None for block split.

download_file

download_file(
    url: str, output_path: Path, force: bool = False
) -> Path

Download a URL unless it already exists.

Parameters:

Name	Type	Description	Default
url	str	Remote file URL.	required
output_path	Path	Local destination path.	required
force	bool	Redownload even if the destination already exists.	False

Returns:

Type	Description
Path	Path to the downloaded file.

download_bci2a

download_bci2a(
    raw_dir: Path | str = Path("data/raw"),
    force: bool = False,
) -> dict[str, Path]

Download and extract official BCI Competition IV data set 2a archives.

Parameters:

Name	Type	Description	Default
raw_dir	Path | str	Destination directory for archives and extracted files.	Path('data/raw')
force	bool	Redownload archives even when they already exist.	False

Returns:

Type	Description
dict[str, Path]	Paths to the downloaded archives and raw directory.

copy_local_cache_to_processed

copy_local_cache_to_processed(
    cache_dir: Path | str,
    processed_dir: Path | str = Path("data/processed"),
    manifest_path: Path | str | None = Path(
        "data/processed/manifest.json"
    ),
) -> None

Copy an existing local .npy cache into the processed data directory.

Parameters:

Name	Type	Description	Default
cache_dir	Path | str	Directory containing the six processed .npy files.	required
processed_dir	Path | str	Destination directory.	Path('data/processed')
manifest_path	Path | str | None	Optional manifest path written after copying.	Path('data/processed/manifest.json')

convert_bci2a_training_subset

convert_bci2a_training_subset(
    raw_dir: Path | str = Path("data/raw"),
    output_dir: Path | str = Path("data/processed"),
    config: BCI2AConversionConfig | None = None,
    manifest_path: Path | str | None = Path(
        "data/processed/manifest.json"
    ),
) -> DatasetBundle

Convert official training GDF files into the six project .npy arrays.

Parameters:

Name	Type	Description	Default
raw_dir	Path | str	Directory containing extracted BCI IV-2a A01T.gdf through A09T.gdf.	Path('data/raw')
output_dir	Path | str	Destination directory for generated .npy files.	Path('data/processed')
config	BCI2AConversionConfig | None	Conversion settings. The default recreates the course project subset.	None
manifest_path	Path | str | None	Optional JSON manifest path.	Path('data/processed/manifest.json')

Returns:

Type	Description
DatasetBundle	Generated data as a DatasetBundle.

Raises:

Type	Description
FileNotFoundError	If a required subject training GDF file is missing.