Configuration (pyavs.config)

The unified configuration system for analysis/processing parameters, with save/load and parameter-signature generation for reproducible derivatives paths. See Configuration System for a worked example.

PyAVSConfig

Unified configuration for pyAVS workflows.

This module provides a single, comprehensive configuration class that combines all analysis, processing, source reconstruction, path, and data parameters.

class pyavs.config.config.PyAVSConfig(subject_id: int = 2, sessions: ~typing.List[int] = <factory>, event_type: str = 'saccade', tmin: float = -0.5, tmax: float = 0.8, blocks: ~typing.List[int] | None = None, min_block: int = 1, max_block: int | None = None, n_jobs: int = -1, random_seed: int = 42, rois: ~typing.List[str] = <factory>, hemi: str = 'both', method: str = 'beamformer', atlas: str = 'glasser', pick_ori: str = 'normal', resample_freq: int = 500, filter_params: ~typing.Dict[str, ~typing.Any] = <factory>, use_precomputed_ica: bool = True, apply_ica: bool = False, ica_solutions_dir: str | None = None, ica_exclusion_dir: str | None = None, ica_params: ~typing.Dict[str, ~typing.Any] | None = None, interpolate_bad_channels: bool = True, partition_random_epochs: float = 1.0, n_epochs_per_session: int = 350, reg: float = 0.05, weight_norm: str | None = None, rank: str | int = 'info', reduce_rank: bool = False, noise_cov_method: str = 'empirical', data_cov_method: str = 'auto', empty_room_type: str = 'per_sess', use_cov: bool = True, recompute_cov: bool = False, forward_spacing: str = 'oct6', mindist: float = 5.0, depth: float = 0.8, snr: float = 3.0, loose: float = 0.2, bem_conductivity: ~typing.Tuple[float, float, float] = (0.3, 0.006, 0.3), coord_frame: str = 'head', tfr_params: ~typing.Dict[str, ~typing.Any] = <factory>, data_path: str | None = None, derivatives_path: str | None = None, output_prefix: str = 'as', cache_dir: str | None = None, stimuli_dir: str | None = None, subjects_dir: str | None = None, data_type: str = 'population_codes', exclude_bad_channels: bool = True, exclude_bad_epochs: bool = True, preload: bool = True, verbose: bool = False, save_metadata: bool = True, save_times: bool = True, save_random_epochs: bool = False, output_format: str = 'h5', compression: str = 'gzip', screen_size_pixels: ~typing.Tuple[int, int] = (1024, 768), screen_size_degrees: float = 33.1, screen_usage: float = 0.925, input_image_size: ~typing.Tuple[int, int] = (947, 710), save_stcs: bool = False, save_filters: bool = True, write_output: bool = True, only_metadata: bool = False, get_object_labels: bool = False, recompute_meg_prepro: bool = False, recompute_filters: bool = False)

Bases: object

Unified configuration for all pyAVS workflows.

This class consolidates all configuration parameters, providing a single source of truth for all processing parameters.

subject_id: int = 2

sessions: List[int]

event_type: str = 'saccade'

tmin: float = -0.5

tmax: float = 0.8

blocks: List[int] | None = None

min_block: int = 1

max_block: int | None = None

n_jobs: int = -1

random_seed: int = 42

rois: List[str]

hemi: str = 'both'

method: str = 'beamformer'

atlas: str = 'glasser'

pick_ori: str = 'normal'

resample_freq: int = 500

filter_params: Dict[str, Any]

use_precomputed_ica: bool = True

apply_ica: bool = False

ica_solutions_dir: str | None = None

ica_exclusion_dir: str | None = None

ica_params: Dict[str, Any] | None = None

interpolate_bad_channels: bool = True

partition_random_epochs: float = 1.0

n_epochs_per_session: int = 350

reg: float = 0.05

weight_norm: str | None = None

rank: str | int = 'info'

reduce_rank: bool = False

noise_cov_method: str = 'empirical'

data_cov_method: str = 'auto'

empty_room_type: str = 'per_sess'

use_cov: bool = True

recompute_cov: bool = False

forward_spacing: str = 'oct6'

mindist: float = 5.0

depth: float = 0.8

snr: float = 3.0

loose: float = 0.2

bem_conductivity: Tuple[float, float, float] = (0.3, 0.006, 0.3)

coord_frame: str = 'head'

tfr_params: Dict[str, Any]

data_path: str | None = None

derivatives_path: str | None = None

output_prefix: str = 'as'

cache_dir: str | None = None

stimuli_dir: str | None = None

subjects_dir: str | None = None

data_type: str = 'population_codes'

exclude_bad_channels: bool = True

exclude_bad_epochs: bool = True

preload: bool = True

verbose: bool = False

save_metadata: bool = True

save_times: bool = True

save_random_epochs: bool = False

output_format: str = 'h5'

compression: str = 'gzip'

screen_size_pixels: Tuple[int, int] = (1024, 768)

screen_size_degrees: float = 33.1

screen_usage: float = 0.925

input_image_size: Tuple[int, int] = (947, 710)

save_stcs: bool = False

save_filters: bool = True

write_output: bool = True

only_metadata: bool = False

get_object_labels: bool = False

recompute_meg_prepro: bool = False

recompute_filters: bool = False

setup_paths() → None

Set up and validate all paths.

The derived directories below are always recomputed from the current data_path (rather than only filled in when None) so that calling this again after data_path changes — e.g. via a second pyavs.configure()/ set_data_path() call — doesn’t leave them stale, pointing at the old root. Nothing in the codebase pins these individually as overrides independent of data_path, so this is safe.

derivatives_path is the exception: it is a genuine override (a read-only dataset copy still needs a writable output root), so an explicitly set value, or PYAVS_DERIVATIVES_PATH, wins over the default of <data_path>/derivatives/pyavs.

get_layout()

Build the Layout for the configured root.

Returns:

None if no data path is configured.

Return type:

pyavs.layout.Layout or None

get_parameter_signature_dict() → Dict[str, Any]

Get dictionary of all parameters for generating parameter signatures.

Returns parameters that affect analysis results for consistent naming.

get_filter_kwargs() → Dict[str, Any]

Get kwargs for beamformer filter computation functions.

get_population_codes_kwargs() → Dict[str, Any]

Get kwargs for population codes computation.

get_composer_kwargs() → Dict[str, Any]

Get kwargs for AVSComposer initialization.

get_source_reconstruction_kwargs() → Dict[str, Any]

Get kwargs for source reconstruction setup.

get_tfr_kwargs() → Dict[str, Any]

Get kwargs for time-frequency analysis.

get_derivatives_path() → str | None

Get the pyAVS derivatives write root.

get_subjects_dir() → str | None

Get the FreeSurfer subjects directory (derivatives/freesurfer).

SUBJECTS_DIR takes precedence if it is set and exists.

get_filter_string() → str

Get string representation of filter parameters.

get_source_rois() → List[str]

Get ROIs that are source-level (not sensor).

get_sensor_rois() → List[str]

Get ROIs that are sensor-level.

get_pixels_per_degree() → float

Calculate pixels per degree of visual angle.

get_scene_scaling_factor(scene_height: int | None = None) → float

Calculate scaling factor for scene images.

get_rescaled_scene_size(scene_size: Tuple[int, int] | None = None) → Tuple[int, int]

Get rescaled scene size based on screen parameters.

get_visual_system_params() → Dict[str, Any]

Get all visual system parameters as a dictionary.

to_dict() → Dict[str, Any]

Convert entire configuration to dictionary.

from_dict(config_dict: Dict[str, Any]) → None

Load configuration from dictionary.

validate() → None

Validate configuration parameters.

__init__(subject_id: int = 2, sessions: ~typing.List[int] = <factory>, event_type: str = 'saccade', tmin: float = -0.5, tmax: float = 0.8, blocks: ~typing.List[int] | None = None, min_block: int = 1, max_block: int | None = None, n_jobs: int = -1, random_seed: int = 42, rois: ~typing.List[str] = <factory>, hemi: str = 'both', method: str = 'beamformer', atlas: str = 'glasser', pick_ori: str = 'normal', resample_freq: int = 500, filter_params: ~typing.Dict[str, ~typing.Any] = <factory>, use_precomputed_ica: bool = True, apply_ica: bool = False, ica_solutions_dir: str | None = None, ica_exclusion_dir: str | None = None, ica_params: ~typing.Dict[str, ~typing.Any] | None = None, interpolate_bad_channels: bool = True, partition_random_epochs: float = 1.0, n_epochs_per_session: int = 350, reg: float = 0.05, weight_norm: str | None = None, rank: str | int = 'info', reduce_rank: bool = False, noise_cov_method: str = 'empirical', data_cov_method: str = 'auto', empty_room_type: str = 'per_sess', use_cov: bool = True, recompute_cov: bool = False, forward_spacing: str = 'oct6', mindist: float = 5.0, depth: float = 0.8, snr: float = 3.0, loose: float = 0.2, bem_conductivity: ~typing.Tuple[float, float, float] = (0.3, 0.006, 0.3), coord_frame: str = 'head', tfr_params: ~typing.Dict[str, ~typing.Any] = <factory>, data_path: str | None = None, derivatives_path: str | None = None, output_prefix: str = 'as', cache_dir: str | None = None, stimuli_dir: str | None = None, subjects_dir: str | None = None, data_type: str = 'population_codes', exclude_bad_channels: bool = True, exclude_bad_epochs: bool = True, preload: bool = True, verbose: bool = False, save_metadata: bool = True, save_times: bool = True, save_random_epochs: bool = False, output_format: str = 'h5', compression: str = 'gzip', screen_size_pixels: ~typing.Tuple[int, int] = (1024, 768), screen_size_degrees: float = 33.1, screen_usage: float = 0.925, input_image_size: ~typing.Tuple[int, int] = (947, 710), save_stcs: bool = False, save_filters: bool = True, write_output: bool = True, only_metadata: bool = False, get_object_labels: bool = False, recompute_meg_prepro: bool = False, recompute_filters: bool = False) → None

ConfigManager

Configuration manager for pyAVS workflows using unified configuration.

class pyavs.config.manager.ConfigManager(config: PyAVSConfig | None = None)

Bases: object

Configuration manager wrapper for unified PyAVSConfig.

This class provides backward compatibility while using the unified configuration structure.

__init__(config: PyAVSConfig | None = None)

Initialize configuration manager.

property analysis

Backward compatibility for analysis config access.

property processing

Backward compatibility for processing config access.

property source

Backward compatibility for source config access.

property paths

Backward compatibility for paths config access.

property data

Backward compatibility for data config access.

get_parameter_signature_dict() → Dict[str, Any]

Get dictionary of all parameters for generating parameter signatures.

Returns:

Dictionary containing all parameters that affect analysis results

Return type:

dict

get_filter_kwargs() → Dict[str, Any]

Get kwargs for filter computation functions.

get_population_codes_kwargs() → Dict[str, Any]

Get kwargs for population codes computation.

get_composer_kwargs() → Dict[str, Any]

Get kwargs for AVSComposer initialization.

get_source_reconstruction_kwargs() → Dict[str, Any]

Get kwargs for source reconstruction setup.

get_tfr_kwargs() → Dict[str, Any]

Get kwargs for time-frequency analysis.

validate() → None

Validate all configuration sections.

to_dict() → Dict[str, Any]

Convert entire configuration to dictionary.

from_dict(config_dict: Dict[str, Any]) → None

Load configuration from dictionary.

save(filepath: str | Path, format: str = 'auto') → None

Save configuration to file.

Parameters:

• filepath (str or Path) – Path to save configuration

• format (str) – File format (‘json’, ‘yaml’, ‘auto’)

load(filepath: str | Path, format: str = 'auto') → None

Load configuration from file.

Parameters:

• filepath (str or Path) – Path to configuration file

• format (str) – File format (‘json’, ‘yaml’, ‘auto’)

pyavs.config.manager.get_config() → ConfigManager

Get the global configuration instance.

Returns:

Global configuration manager with unified config

Return type:

ConfigManager

pyavs.config.manager.set_config(config: ConfigManager | PyAVSConfig) → None

Set the global configuration instance.

Parameters:

config (ConfigManager or PyAVSConfig) – Configuration to set as global

pyavs.config.manager.load_config(filepath: str | Path, format: str = 'auto') → ConfigManager

Load configuration from file and set as global.

Parameters:

• filepath (str or Path) – Path to configuration file

• format (str) – File format (‘json’, ‘yaml’, ‘auto’)

Returns:

Loaded configuration manager

Return type:

ConfigManager

pyavs.config.manager.save_config(filepath: str | Path, format: str = 'auto', config: ConfigManager | None = None) → None

Save configuration to file.

Parameters:

• filepath (str or Path) – Path to save configuration

• format (str) – File format (‘json’, ‘yaml’, ‘auto’)

• config (ConfigManager, optional) – Configuration to save. If None, uses global config

Directory Helpers

Convenience namespace for resolved AVS directory paths.

pyavs.config.dirs.get_dirs() → SimpleNamespace

Return a namespace of resolved AVS data directories.

All paths are derived from the configured avs-public root (set via pyavs.configure() or the PYAVS_DATA_PATH env var).

Returns:

Attributes: root, stimuli, derivatives, subjects_dir. All are None if no data path is configured.

Return type:

SimpleNamespace

Examples

>>> import pyavs
>>> pyavs.configure('/path/to/avs-public')
>>> d = pyavs.dirs()
>>> d.stimuli
'/path/to/avs-public/stimuli'
>>> d.subjects_dir
'/path/to/avs-public/derivatives/freesurfer'