eegproc.model_explainability.model_agnostic.adapter module

Model and dataset contracts for architecture-agnostic counterfactuals.

Adapters isolate model-specific state initialization, classification, decoding, and optional validity metrics from the optimizer. External projects can provide an adapter factory without changing EEGProc; factories are addressed as package.module:function and receive model_path, config, and one sample trial.

class eegproc.model_explainability.model_agnostic.adapter.CounterfactualAdapter

Bases: ABC

Minimal differentiable interface consumed by the generic optimizer.

constraint(name, signal)

Return one scalar validity metric; subclasses opt in by name.

Parameters:

• name (str)

• signal (Tensor)

Return type:

Tensor

default_signal_weight = 0.1

default_state_weight = 0.1

abstractmethod initial_state(inputs)

Return the tensor that should be optimized for one input trial.

Parameters:

inputs (Tensor)

Return type:

Tensor

abstractmethod logits_from_state(state)

Return unnormalized class logits for the optimizable state.

Parameters:

state (Tensor)

Return type:

Tensor

metadata()

Return type:

dict[str, Any]

name = 'custom'

optimization_space = 'latent'

abstractmethod reconstruct(state, reference_input)

Map state to one or more input-shaped differentiable signals.

Parameters:

• state (Tensor)

• reference_input (Tensor)

Return type:

Mapping[str, Tensor]

class eegproc.model_explainability.model_agnostic.adapter.KerasInputAdapter(model, *, output_kind, output_key=None)

Bases: CounterfactualAdapter

Input-space gradients for differentiable Keras models without decoders.

Parameters:

• output_kind (str)

• output_key (str | None, default: None)

default_signal_weight = 0.0

default_state_weight = 0.1

initial_state(inputs)

Return the tensor that should be optimized for one input trial.

logits_from_state(state)

Return unnormalized class logits for the optimizable state.

metadata()

name = 'keras-input'

optimization_space = 'input'

reconstruct(state, reference_input)

Map state to one or more input-shaped differentiable signals.

class eegproc.model_explainability.model_agnostic.adapter.TrialDataset(features, subject_ids, trial_ids, labels=None, normalization_offset=None, normalization_scale=None, channel_names=None, band_names=None, channel_positions=None, feature_order=None, signal_unit=None, metadata=<factory>)

Bases: object

Prepared trials and optional metadata needed to restore source units.

Parameters:

• features (ndarray)

• subject_ids (ndarray)

• trial_ids (ndarray)

• labels (ndarray | None, default: None)

• normalization_offset (ndarray | None, default: None)

• normalization_scale (ndarray | None, default: None)

• channel_names (tuple[str, ...] | None, default: None)

• band_names (tuple[str, ...] | None, default: None)

• channel_positions (ndarray | None, default: None)

• feature_order (str | None, default: None)

• signal_unit (str | None, default: None)

• metadata (dict[str, Any], default: <factory>)

band_names: tuple[str, ...] | None = None

channel_names: tuple[str, ...] | None = None

channel_positions: ndarray | None = None

feature_order: str | None = None

features: ndarray

labels: ndarray | None = None

metadata: dict[str, Any]

normalization_offset: ndarray | None = None

normalization_scale: ndarray | None = None

signal_unit: str | None = None

subject_ids: ndarray

trial_ids: ndarray

eegproc.model_explainability.model_agnostic.adapter.create_adapter(factory_spec, *, model_path, config, sample_input)

Parameters:

• factory_spec (str)

• model_path (Path)

• config (Mapping[str, Any])

• sample_input (ndarray)

Return type:

CounterfactualAdapter

eegproc.model_explainability.model_agnostic.adapter.create_keras_input_adapter(*, model_path, config, sample_input)

Built-in factory for arbitrary differentiable input-space Keras models.

eegproc.model_explainability.model_agnostic.adapter.load_json_mapping(value)

Load a JSON object from inline text or a JSON file path.

Parameters:

value (str | None)

Return type:

dict[str, Any]

eegproc.model_explainability.model_agnostic.adapter.load_trial_dataset(npz_path, *, loader_spec=None, loader_config=None)

Load a standard NPZ or delegate dataset construction to a plug-in.

Parameters:

• npz_path (Path | None)

• loader_spec (str | None, default: None)

• loader_config (Optional[Mapping[str, Any]], default: None)

Return type:

TrialDataset

eegproc.model_explainability.model_agnostic.adapter.validate_trial_dataset(dataset)

Parameters:

dataset (TrialDataset)

Return type:

TrialDataset