"""Analyzer registry.
Each analyzer is described by an :class:`AnalyzerSpec`. ``AnalysisManager``
builds the analyzers whose configuration section is enabled and runs them in
its fixed order. Plugins add analyzers with :func:`register_analyzer`; an
analyzer registered with a ``phase`` runs in that phase of the order, and its
configuration section is the plugin section ``analysis.<config_field>``
(registered with :func:`dendritic_modeling.config.extensions.register_config_section`).
"""
from __future__ import annotations
import importlib
from dataclasses import dataclass
from typing import Literal
from dendritic_modeling.plugins import load_plugins
AnalyzerConstructor = Literal["params", "model_params", "none"]
#: Where a plugin analyzer runs in the analysis order: with the test-dataset
#: analyses before or after the weight and reactivation analyses, or with the
#: model-only analyses.
AnalyzerPhase = Literal["pre_weight", "post_reactivation", "model_only"]
ANALYZER_PHASES = ("pre_weight", "post_reactivation", "model_only")
@dataclass(frozen=True)
class AnalyzerSpec:
"""Metadata describing one analysis component."""
name: str
config_field: str
class_path: str
attribute_name: str
save_subdir: str
constructor_style: AnalyzerConstructor = "params"
supports_training: bool = True
# Analyzers that compare snapshots taken during training.
requires_training: bool = False
description: str = ""
# Plugin analyzers: where they run, whether the runner passes ``training``
# and whether a missing analyzer instance is an error.
phase: AnalyzerPhase | None = None
pass_training: bool = False
require_analyzer: bool = False
def load_class(self) -> type:
"""Resolve the analyzer class declared by this spec."""
module_name, _, class_name = self.class_path.rpartition(".")
if not module_name or not class_name:
raise ValueError(f"Invalid analyzer class path: {self.class_path!r}")
module = importlib.import_module(module_name)
analyzer_cls = getattr(module, class_name)
if not isinstance(analyzer_cls, type):
raise TypeError(
f"Analyzer path does not resolve to a class: {self.class_path}"
)
return analyzer_cls
_ANALYZER_REGISTRY: dict[str, AnalyzerSpec] = {}
_BUILTIN_ANALYZERS: tuple[AnalyzerSpec, ...] = (
AnalyzerSpec(
name="performance",
config_field="performance",
class_path="dendritic_modeling.analysis.metrics.performance.PerformanceAnalyzer",
attribute_name="performance_analyzer",
save_subdir="performance",
),
AnalyzerSpec(
name="information",
config_field="information",
class_path="dendritic_modeling.analysis.core.information.InformationAnalyzer",
attribute_name="information_analyzer",
save_subdir="information_analysis",
),
AnalyzerSpec(
name="representation_accessibility",
config_field="representation_accessibility",
class_path=(
"dendritic_modeling.analysis.tools.representation_accessibility."
"RepresentationAccessibilityAnalyzer"
),
attribute_name="representation_accessibility_analyzer",
save_subdir="representation_accessibility",
supports_training=False,
description=(
"Validation-fit linear/nonlinear probes and matched-support class "
"information for stacked soma populations"
),
),
AnalyzerSpec(
name="source_tuning_support",
config_field="source_tuning_support",
class_path=(
"dendritic_modeling.analysis.tools.source_tuning."
"SourceTuningSupportAnalyzer"
),
attribute_name="source_tuning_support_analyzer",
save_subdir="source_tuning_support_analysis",
supports_training=False,
description=(
"Split-safe source-coordinate tuning aligned with exact sparse "
"contacts and effective conductances"
),
),
AnalyzerSpec(
name="input_region_intervention",
config_field="input_region_intervention",
class_path=(
"dendritic_modeling.analysis.tools.input_region_intervention."
"InputRegionInterventionAnalyzer"
),
attribute_name="input_region_intervention_analyzer",
save_subdir="input_region_intervention",
supports_training=False,
description=(
"Paired image-region interventions with layerwise E/I response propagation"
),
),
AnalyzerSpec(
name="synapse_turnover",
config_field="synapse_turnover",
class_path="dendritic_modeling.analysis.tools.synaptic_turnover.SynapticTurnoverAnalyzer",
attribute_name="syn_turnover_analyzer",
save_subdir="synapse_turnover_analysis",
constructor_style="model_params",
requires_training=True,
),
AnalyzerSpec(
name="synapse_pruning",
config_field="synapse_pruning",
class_path="dendritic_modeling.analysis.tools.synaptic_pruning.SynapticPruningAnalyzer",
attribute_name="syn_pruning_analyzer",
save_subdir="synapse_pruning_analysis",
supports_training=False,
description="Realized-contact census and the contacts each pruning step removed",
),
AnalyzerSpec(
name="noise_perturbation",
config_field="noise_perturbation",
class_path="dendritic_modeling.analysis.metrics.noise_perturbation.NoisePerturbationAnalyzer",
attribute_name="noise_perturbation_analyzer",
save_subdir="noise_perturbation_analysis",
),
AnalyzerSpec(
name="single_layer_contribution",
config_field="single_layer_contribution",
class_path="dendritic_modeling.analysis.metrics.layer_contribution.SingleLayerContributionAnalyzer",
attribute_name="single_layer_analyzer",
save_subdir="single_layer_contribution",
),
AnalyzerSpec(
name="ablation",
config_field="ablation",
class_path="dendritic_modeling.analysis.core.ablation.AblationAnalyzer",
attribute_name="ablation_analyzer",
save_subdir="ablation_analysis",
),
AnalyzerSpec(
name="path_matched_intervention",
config_field="path_matched_intervention",
class_path=(
"dendritic_modeling.analysis.tools.path_matched_intervention."
"PathMatchedInterventionAnalyzer"
),
attribute_name="path_matched_intervention_analyzer",
save_subdir="path_matched_intervention",
supports_training=False,
description=(
"Fixed-count, nested soma-to-distal coordinate interventions across "
"dendritic depth"
),
),
AnalyzerSpec(
name="branch_local_sensitivity",
config_field="branch_local_sensitivity",
class_path=(
"dendritic_modeling.analysis.tools.branch_local_sensitivity."
"BranchLocalSensitivityAnalyzer"
),
attribute_name="branch_local_sensitivity_analyzer",
save_subdir="branch_local_sensitivity",
supports_training=False,
description=(
"Observed local E/I/inherited-current branch sensitivities including "
"the fitted reactivation derivative"
),
),
AnalyzerSpec(
name="node_perturbation_credit",
config_field="node_perturbation_credit",
class_path=(
"dendritic_modeling.analysis.tools.node_perturbation_credit."
"NodePerturbationCreditAnalyzer"
),
attribute_name="node_perturbation_credit_analyzer",
save_subdir="node_perturbation_credit",
supports_training=False,
description=(
"Compartment errors estimated from loss changes under antithetic "
"perturbations, compared with the exact errors"
),
),
AnalyzerSpec(
name="local_inhibitory_population_intervention",
config_field="local_inhibitory_population_intervention",
class_path=(
"dendritic_modeling.analysis.tools.layer_population_intervention."
"LocalInhibitoryPopulationInterventionAnalyzer"
),
attribute_name="local_inhibitory_population_intervention_analyzer",
save_subdir="local_inhibitory_population_intervention",
supports_training=False,
description=(
"Whole local inhibitory soma-population interventions across "
"feedforward network layers"
),
),
AnalyzerSpec(
name="path_matched_information",
config_field="path_matched_information",
class_path=(
"dendritic_modeling.analysis.tools.path_matched_information."
"PathMatchedInformationAnalyzer"
),
attribute_name="path_matched_information_analyzer",
save_subdir="path_matched_information",
supports_training=False,
description=(
"Validation-set joint class information on fixed-width, nested "
"soma-to-distal coordinate supports"
),
),
AnalyzerSpec(
name="weight",
config_field="weight",
class_path="dendritic_modeling.analysis.tools.weight.WeightAnalyzer",
attribute_name="weight_analyzer",
save_subdir="weight_analysis",
),
AnalyzerSpec(
name="compartment_statistics",
config_field="compartment_statistics",
class_path="dendritic_modeling.analysis.tools.compartment_statistics.CompartmentStatisticsAnalyzer",
attribute_name="compartment_statistics_analyzer",
save_subdir="compartment_statistics_analysis",
),
AnalyzerSpec(
name="compartment_snr",
config_field="compartment_snr",
class_path="dendritic_modeling.analysis.tools.compartment_snr.CompartmentSNRAnalyzer",
attribute_name="compartment_snr_analyzer",
save_subdir="compartment_snr_analysis",
),
AnalyzerSpec(
name="multiplicative_gain",
config_field="multiplicative_gain",
class_path="dendritic_modeling.analysis.tools.multiplicative_gain.MultiplicativeGainAnalyzer",
attribute_name="multiplicative_gain_analyzer",
save_subdir="multiplicative_gain_analysis",
),
AnalyzerSpec(
name="gain_load_perturbation",
config_field="gain_load_perturbation",
class_path=(
"dendritic_modeling.analysis.tools.gain_load_perturbation."
"GainLoadPerturbationAnalyzer"
),
attribute_name="gain_load_perturbation_analyzer",
save_subdir="gain_load_perturbation",
supports_training=False,
description=(
"Mean-one trial-shared lognormal gain crossed with an explicit "
"independent input-load intervention"
),
),
AnalyzerSpec(
name="receptive_field",
config_field="receptive_field",
class_path="dendritic_modeling.analysis.tools.receptive_fields.ReceptiveFieldAnalyzer",
attribute_name="receptive_field_analyzer",
save_subdir="receptive_field_analysis",
),
AnalyzerSpec(
name="reactivation_dynamics",
config_field="reactivation_dynamics",
class_path="dendritic_modeling.analysis.tools.reactivation_dynamics.ReactivationDynamicsAnalyzer",
attribute_name="reactivation_dynamics_analyzer",
save_subdir="reactivation_dynamics",
),
AnalyzerSpec(
name="synaptic_activation",
config_field="synaptic_activation",
class_path="dendritic_modeling.analysis.tools.synaptic_activation.SynapticActivationAnalyzer",
attribute_name="synaptic_activation_analyzer",
save_subdir="synaptic_activation_analysis",
),
AnalyzerSpec(
name="branch_activation",
config_field="branch_activation",
class_path="dendritic_modeling.analysis.core.branch_activation.BranchActivationAnalyzer",
attribute_name="branch_activation_analyzer",
save_subdir="branch_activation_analysis",
),
AnalyzerSpec(
name="local_rule_components",
config_field="local_rule_components",
class_path="dendritic_modeling.analysis.tools.local_rule_components.LocalRuleComponentAnalyzer",
attribute_name="local_rule_component_analyzer",
save_subdir="local_rule_components",
),
AnalyzerSpec(
name="correlation",
config_field="correlation",
class_path="dendritic_modeling.analysis.tools.correlation_analysis.CorrelationAnalyzer",
attribute_name="correlation_analyzer",
save_subdir="correlation_analysis",
),
AnalyzerSpec(
name="routing",
config_field="routing",
class_path="dendritic_modeling.analysis.tools.routing_analysis.RoutingAnalyzer",
attribute_name="routing_analyzer",
save_subdir="routing_analysis",
constructor_style="none",
),
AnalyzerSpec(
name="inhibitory_specialization",
config_field="inhibitory_specialization",
class_path="dendritic_modeling.analysis.tools.inhibitory_specialization.InhibitorySpecializationAnalyzer",
attribute_name="inhibitory_specialization_analyzer",
save_subdir="inhibitory_specialization",
),
AnalyzerSpec(
name="jacobian_spectrum",
config_field="jacobian_spectrum",
class_path="dendritic_modeling.analysis.tools.jacobian_spectrum.JacobianSpectrumAnalyzer",
attribute_name="jacobian_spectrum_analyzer",
save_subdir="jacobian_spectrum",
),
AnalyzerSpec(
name="dendritic_timetraces",
config_field="dendritic_timetraces",
class_path="dendritic_modeling.analysis.tools.dendritic_timetraces.DendriticTimetracesAnalyzer",
attribute_name="dendritic_timetraces_analyzer",
save_subdir="dendritic_timetraces",
),
AnalyzerSpec(
name="spike_train",
config_field="spike_train",
class_path="dendritic_modeling.analysis.tools.spike_trains.SpikeTrainAnalyzer",
attribute_name="spike_train_analyzer",
save_subdir="spike_train_analysis",
),
AnalyzerSpec(
name="adversarial_robustness",
config_field="adversarial_robustness",
class_path="dendritic_modeling.analysis.metrics.adversarial_robustness.AdversarialRobustnessAnalyzer",
attribute_name="adversarial_robustness_analyzer",
save_subdir="adversarial_robustness_analysis",
),
)
[docs]
def register_analyzer(
name: str,
*,
config_field: str,
class_path: str,
attribute_name: str,
save_subdir: str,
constructor_style: AnalyzerConstructor = "params",
supports_training: bool = True,
requires_training: bool = False,
description: str = "",
phase: AnalyzerPhase | None = None,
pass_training: bool = False,
require_analyzer: bool = False,
allow_override: bool = False,
) -> None:
"""Register an analyzer.
Without ``phase`` the analyzer is metadata only: ``AnalysisManager`` builds
it when its section is enabled but never runs it. With ``phase`` it runs
there, receiving the test dataset (``pre_weight``, ``post_reactivation``)
or only the model (``model_only``).
"""
key = str(name).lower()
if not key:
raise ValueError("analyzer name must be non-empty")
if key in _ANALYZER_REGISTRY and not allow_override:
raise ValueError(f"Analyzer '{key}' is already registered")
if constructor_style not in ("params", "model_params", "none"):
raise ValueError(f"Unsupported analyzer constructor style: {constructor_style}")
if phase is not None and phase not in ANALYZER_PHASES:
raise ValueError(
f"Unsupported analyzer phase {phase!r}; use one of {ANALYZER_PHASES}"
)
_ANALYZER_REGISTRY[key] = AnalyzerSpec(
name=key,
config_field=config_field,
class_path=class_path,
attribute_name=attribute_name,
save_subdir=save_subdir,
constructor_style=constructor_style,
supports_training=supports_training,
requires_training=requires_training,
description=description,
phase=phase,
pass_training=pass_training,
require_analyzer=require_analyzer,
)
def unregister_analyzer(name: str) -> None:
"""Remove analyzer metadata if present."""
_ANALYZER_REGISTRY.pop(str(name).lower(), None)
def get_analyzer_spec(name: str) -> AnalyzerSpec | None:
"""Return metadata for one analyzer."""
key = str(name).lower()
if key not in _ANALYZER_REGISTRY:
load_plugins()
return _ANALYZER_REGISTRY.get(key)
def get_registered_analyzer_names() -> list[str]:
"""Return registered analyzer names, including those of plugins."""
load_plugins()
return sorted(_ANALYZER_REGISTRY)
def get_registered_analyzers() -> dict[str, AnalyzerSpec]:
"""Return a copy of all analyzer specs, including those of plugins."""
load_plugins()
return dict(_ANALYZER_REGISTRY)
def get_builtin_analyzer_names() -> tuple[str, ...]:
"""Return built-in analyzer names in their declared initialization order."""
return tuple(spec.name for spec in _BUILTIN_ANALYZERS)
def get_extension_analyzer_names() -> tuple[str, ...]:
"""Return the names of registered analyzers that are not built in, sorted."""
load_plugins()
builtin = set(get_builtin_analyzer_names())
return tuple(sorted(name for name in _ANALYZER_REGISTRY if name not in builtin))
def load_analyzer_class(name: str) -> type:
"""Resolve the registered analyzer class for one analyzer name."""
spec = get_analyzer_spec(name)
if spec is None:
raise KeyError(f"Analyzer {name!r} is not registered")
return spec.load_class()
def _register_builtin_analyzers() -> None:
for spec in _BUILTIN_ANALYZERS:
register_analyzer(
spec.name,
config_field=spec.config_field,
class_path=spec.class_path,
attribute_name=spec.attribute_name,
save_subdir=spec.save_subdir,
constructor_style=spec.constructor_style,
supports_training=spec.supports_training,
requires_training=spec.requires_training,
description=spec.description,
)
_register_builtin_analyzers()
__all__ = [
"ANALYZER_PHASES",
"AnalyzerConstructor",
"AnalyzerPhase",
"AnalyzerSpec",
"get_analyzer_spec",
"get_builtin_analyzer_names",
"get_extension_analyzer_names",
"get_registered_analyzer_names",
"get_registered_analyzers",
"load_analyzer_class",
"register_analyzer",
"unregister_analyzer",
]