Analyzer reference
One section per analyzer, grouped by what it measures. Every section is
written under analysis.<analyzer> with enabled, training and
params; Analysis explains when analyzers run, how
analysis.runtime controls their data iteration, and where they write. The
Analyzer catalogue summarizes all of them. Each section below gives the
model the analyzer needs, the split it reads, its main options with their
defaults, an example, and its output files (<name> is final,
epoch<N> or a stage name). The example configurations under
configs/examples/ named in a section are complete analysis profiles for
Analyzing saved checkpoints.
Performance and robustness
performance
Scores the model on whole splits: accuracy, auc and
categorical_loglikelihood (on by default) and mse and
cosine_similarity (off by default). For a regression model the
classification scores are replaced by mse and cosine_similarity.
training_splits (per-epoch runs) and final_splits (after training)
choose the splits, from train, validation and test (default: all
three); the older spelling valid loads with a warning. performance
ignores analysis.runtime.<phase>.max_samples.
analysis:
performance:
enabled: true
training: true
training_splits: ["validation"]
final_splits: ["train", "validation", "test"]
params:
accuracy: true
auc: false
categorical_loglikelihood: true
Output: performance/<name>.json after training ({metric: {train, valid,
test}}) and performance/epochs/epoch<N>.json per epoch. When per-epoch
results exist, training also draws performance_evolution_<metric>.png.
noise_perturbation
Scores the model on test inputs with added noise. For every magnitude m in
uniform_magnitudes (noise uniform in [-m, m]) and every standard
deviation in gaussian_sdevs, n_samples noisy copies of the test inputs
are drawn (seeded by seed), clipped to clamp_range and scored together.
Options (defaults): uniform_noise: true, uniform_magnitudes: [0.1,
0.2], gaussian_noise: true, gaussian_sdevs: [0.1, 0.2],
n_samples: 10, clamp_range: [0.0, 1.0] (null disables the clip, for
inputs outside [0, 1]), and the score switches accuracy, auc,
categorical_loglikelihood, mse and cosine_similarity, all
true. The regression scores are NaN for classifiers; switch them off.
analysis:
noise_perturbation:
enabled: true
params:
uniform_magnitudes: [0.1, 0.2, 0.4]
gaussian_sdevs: [0.1, 0.2, 0.4]
n_samples: 10
mse: false
cosine_similarity: false
Output: noise_perturbation_analysis/<name> (JSON: uniform and
gaussian, then the level, then the score; the log-likelihood key is
categorical_ll). dendritic-collect-perturbation-response combines it
with performance and multiplicative_gain (see
Analyzing saved checkpoints).
multiplicative_gain
Scores the model on test inputs multiplied by a sweep of gains: n_steps
values from gain_min to gain_max, spaced linearly or, with
logspace: true, logarithmically (a log sweep with gain_min: 0 runs from
1/gain_max to gain_max). With uniform_gain: true every input is
multiplied by the gain; with false every input element gets its own gain,
uniform in [1, gain]. input_preprocess (none, relu,
softplus, shift_min, global_shift_min) is applied before the gain,
and noise_model: poisson replaces each scaled input by a Poisson count with
that mean (floored at poisson_eps). All gain levels draw their random gains
and noise from noise_seed, so levels differ only in the gain. Poisson
generator datasets apply the gain to their rates and keep their own noise; the
preprocessing and noise options must then keep their defaults.
At least one score must be selected (all are false by default):
accuracy, auc and categorical_loglikelihood for classifiers,
mse and cosine_similarity for regression models. Scores that do not
fit the model are dropped with a warning.
analysis:
multiplicative_gain:
enabled: true
params:
gain_min: 0.0
gain_max: 10.0
n_steps: 11
accuracy: true
categorical_loglikelihood: true
Output: multiplicative_gain_analysis/<name>.json with gain_factors,
raw_scores per gain and the mean scores inside (ID), below
(OOD_lower) and above (OOD_upper) in_distribution_gain_range, the
gain range of the evaluated dataset ([1, 1] unless it is a Poisson
generator with a gain). Per-epoch runs write epochs/epoch<N>.json; after
training the analyzer draws <score>_vs_gain_final.png and, with per-epoch
results, an animation over epochs.
gain_load_perturbation
Final-only. Scores a classifier on test inputs under a factorial of two
perturbations: a mean-one log-normal gain shared by all input coordinates of a
trial (log standard deviations gain_log_sds) and an input load
(load_levels). load_mode: gaussian_input adds independent zero-mean
Gaussian noise with standard deviation load_level to every coordinate;
load_mode: positive_inhibitory adds a positive log-normal background with
mean load_level (log standard deviation load_log_sd) to the
coordinates from inhibitory_start on, for inputs ordered [E | I]. Every
cell has draws_per_condition technical draws seeded by base_draw_seed;
write it explicitly so that checkpoints from runs with different seeds share
the same random numbers (an unset seed is derived from each run’s
experiment.probe_seed). clamp_min (default
0) and clamp_max clip every cell, the unperturbed one included;
clipping rectifies Gaussian load into a positive-mean perturbation, so each
record reports the fractions of values the clamp moved, and a warning is
logged when clean inputs already fall outside the clamp. Set
clamp_min: null for zero-mean Gaussian load.
Further options: max_samples, the scores accuracy and
categorical_loglikelihood (both true), record_input_statistics
(mean, standard deviation, zero fraction, coefficient of variation and range
of every cell) and record_branch_local_sensitivity with its
branch_sensitivity_* options, which evaluates the
branch_local_sensitivity estimator
on the draws listed in branch_sensitivity_draws.
analysis:
gain_load_perturbation:
enabled: true
params:
gain_log_sds: [0.0, 0.2, 0.5, 0.8]
load_levels: [0.0, 0.1, 0.3, 0.5]
load_mode: gaussian_input
draws_per_condition: 5
clamp_min: null
Output: gain_load_perturbation/<name>.json. Collect checkpoint runs with
dendritic-collect-gain-load-response.
adversarial_robustness
Accuracy on test inputs perturbed by the fast gradient sign method (FGSM) for
every epsilon in epsilons (default [0.0, 0.05, 0.1, 0.15, 0.2,
0.3]); perturbed inputs are clipped to [0, 1]. The batch size is the
phase’s analysis.runtime batch size; params.batch_size has no effect
in training or checkpoint runs.
analysis:
adversarial_robustness:
enabled: true
params:
epsilons: [0.0, 0.05, 0.1]
Output: adversarial_robustness_analysis/adversarial_robustness_<name>.json
(eps_<epsilon> to scores).
single_layer_contribution
Requires a structured E/I core (an ExcitationInhibitionNetwork; other
cores are skipped with a warning). For each dendritic layer, scores the test
split with the excitatory and inhibitory synapses of all other layers
lesioned: with both of the layer’s banks (both_contribution), only its
excitatory bank (excitation_contribution) or only its inhibitory bank
(inhibition_contribution). The model is restored afterwards. The score
switches are those of noise_perturbation, all true; switch off mse
and cosine_similarity for classifiers.
analysis:
single_layer_contribution:
enabled: true
params:
mse: false
cosine_similarity: false
Output: single_layer_contribution/<name> (JSON) and one figure per score.
Information
information
Information-theoretic measures of the signals of every dendritic branch: the
excitatory current E, the inhibitory current I, the input from child
branches Vb, the branch output Vout and, with
compute.include_vinf (default true), the soma activation Vinf,
about the class C and about each other. It requires E/I dendritic branch
layers (a structured E/I core or a population_network); other models are
skipped with a warning. It reads the test split, or the validation split with
compute.analysis_split: validation, and processes the selected examples
in one forward pass.
params.selection.components chooses the families of terms. When it is
empty, basic, pairwise, conditional, ablation_aligned and
layer_proxies are computed.
Component |
Terms |
|---|---|
|
|
|
|
|
|
|
Conditional terms that mirror ablations: |
|
|
|
Layer-level summaries of the single-branch terms ( |
|
A Gaussian proxy from class-conditional means and variances
( |
|
Partial information decomposition of |
|
Information of branch currents and outputs about the output of the branch’s soma. |
Other selectors under params.selection:
scopesExtra breakdowns:
layer(per dendritic layer),einet(excitatory and inhibitory pathways separately) andneuron(per captured branch coordinate; expensive).neurondoes not mean the soma population of a layer; use representation_accessibility for soma populations.signal_variantsnetwork(the model’s signals, always included),lda(signals projected on LDA weights,*_lin), andrandom(a random-weight baseline forlda,*_sh; needsbaselines.random_weights.n_shufflesabove 0).
params.compute sets how branches are combined:
computation_level(defaultsingle_branch)single_branch(each branch),layer_branch(the branches of a layer together) orall_branch(all branches together).branch_aggregation(defaultmean)For
layer_branchandall_branch:mean(average the branches),multivariate(joint vectors) orsample(branches as separate observations).branch_sample_count_per_layer,branch_sample_strategy,branch_sample_seedAnalyze a label-independent sample of branches per layer at
single_branch;branch_sample_strategyisuniformorparent_soma_balanced(cycle through the parent somas).max_samples,output_units,normalize_mi,network_population_informationA cap on the examples;
bits(default) ornats; division byH(C); and the raw information of the whole soma population (off by default).
params.estimator.method chooses the estimator:
kraskov(default; alsoauto)The k-nearest-neighbour estimator, with
estimator.kraskov.n_neighbors(default 10).decoderA cross-validated classifier bound for terms with
C, configured byestimator.decoder(cv_folds,C,standardize,seed, andcontinuousfor terms between continuous signals).binnedA plug-in estimator on binned signals:
estimator.binned.n_bins(20),binning_strategy(quantileoruniform),bias_correction(noneormiller_madow).sklearnThe scikit-learn estimators. It has no options of its own: the
estimator.sklearnkeys are not read.copulaWith
estimator.copula.type: gaussian(default), the Gaussian-copula estimator of Ince et al. (2017): every column becomes the standard normal score of its rank, and the information is that of a Gaussian with the scores’ covariance, with the analytic bias correction. It is exact for Gaussian dependence and a lower bound otherwise, needs more samples than dimensions (per class for class-conditional terms), and handles class labels through class-conditional entropies, so label order does not matter.type: kernelestimates the copula density of two continuous scalars with Gaussian kernels.
params.baselines adds surrogate estimates with the same estimator:
random_weights (n_shuffles, seed) for the random variant, and
label_shuffle_null (n_shuffles, seed, and components: the
families that get a *_null counterpart, from basic (default),
pairwise, conditional, ablation_aligned, upstream_unique_cmi,
soma_coupling or all), which recomputes the terms with permuted labels
as a finite-sample bias estimate.
analysis:
information:
enabled: true
params:
selection:
components: ["basic", "pairwise", "conditional", "gaussian_fisher"]
scopes: ["layer"]
signal_variants: ["network"]
compute:
max_samples: 1000
computation_level: "single_branch"
analysis_split: "validation"
estimator:
method: "kraskov"
kraskov:
n_neighbors: 10
baselines:
label_shuffle_null:
n_shuffles: 20
Flat spellings such as params.method, params.components or
params.lda_n_shuffles load with a deprecation warning and are moved to the
grouped keys.
Output: information_analysis/<name> (JSON) and <name>_summary.txt;
with the layer and einet scopes, per-layer summaries in
per_layer_results/; and figures with fixed names, replaced at every pass.
dendritic_modeling.utils.information provides the estimators as functions.
correlation
Requires a structured E/I core (an ExcitationInhibitionNetwork; other
cores are skipped with a warning). Pearson correlations between excitatory,
inhibitory and output signals on the test split (at most
compute.max_samples examples, default 5000). Selectors under
params.selection, all of them by default:
componentstotal(all examples),noise(within class),signal(between class means; computed only for two-class tasks) andtuning(class selectivity).pairsEE,II,EI,E_output,I_output,output_output.scopeslayerandeinet(by default),neuron.
compute.computation_level is synaptic (individual synapses, sampled
with params.sampling: sampling_strategy stratified (default) or
random, n_synapse_pairs, max_pairs_per_category and
stratified_categories, default ["within_branch", "within_layer"]),
single_branch, layer_branch (default) or all_branch. The category
across_layer, listed by earlier versions but never implemented, loads
with a warning and is dropped (dendritic-upgrade-config removes it); any
other unknown category raises. Selector entries are compared in lower case with - and
spaces read as _, and also accept all (total), tuning_curves
(tuning), e_vout/exc_output/exc_vout (E_output), the
matching I_output spellings, vout_vout/out_out
(output_output) and per_layer/per_einet/per_neuron. An unknown
selector entry, computation level or sampling strategy raises when the
configuration loads, with the valid names. Flat spellings such as
params.components or params.computation_level load with a
deprecation warning and are moved to the grouped keys.
analysis:
correlation:
enabled: true
params:
selection:
components: ["total", "noise", "signal"]
pairs: ["EE", "II", "EI"]
scopes: ["layer"]
compute:
computation_level: "layer_branch"
Output: correlation_analysis/<name> (JSON), <name>_summary.csv and
figures with fixed names.
compartment_snr
Requires dendritic branch layers and a classifier; other models are skipped
with a warning. Discriminability-style signal-to-noise ratios on the test
split. This is not a simple signal/noise power ratio: branch-level scalar
signals report d'^2 as between-class variance divided by total variance,
while multivariate input and layer signals report d_max, d_total,
n_sig_dirs and ratio_sig_dirs from between-class versus total
covariance (the squared canonical correlations with the class labels,
computed in float64). They are in-sample, so even label-free activity gives
d_total of about (C - 1) D / (n - 1); compare layers of different
widths through d_total_null_mean (the mean over label shuffles) and
dim_over_n. A leading direction counts in n_sig_dirs when its
eigenvalue exceeds the null_quantile (0.95) of the same-rank eigenvalue
over null_permutations (100) label shuffles, seeded by null_seed.
input_capture_mode chooses the input view: branch (default) measures
the tensors entering the dendritic branch layers; network measures the
model-level excitatory input and inhibitory output of an
ExcitationInhibitionNetwork. Further switches: input_analysis,
layer_analysis, branch_analysis and the *_aggregation options,
all true. Per-epoch runs skip the input analysis.
analysis:
compartment_snr:
enabled: true
training: true
params:
input_capture_mode: branch
null_permutations: 100
Output: compartment_snr_analysis/<name>.json (per epoch
epochs/epoch<N>.json), and after training figures in layer_analysis/
and branch_analysis/, with animations over epochs when per-epoch results
exist.
representation_accessibility
Final-only. Requires a feedforward population_network whose populations are
excitatory or inhibitory; it analyzes the post-gate soma outputs of every
layer. It reports five separate estimands:
class accessibility: Ridge or MLP probes fit on the validation split and evaluated on the test split, with label-shuffle nulls;
joint
I(X; C)of a label-independent population projection, on the validation split;scalar
I(x_i; C)of individual somas, on the validation split;held-out decoding from label-independent nested subsets of population coordinates (individual somas of E-only or I-only representations);
covariance and correlation effective dimension, on the validation split.
The MLP result is nonlinear class accessibility, not mutual information. The mean of per-soma scalar information is redundancy-sensitive and is not the joint information of the layer. Every probe is fit on the validation split, and the test split is used only for the final probe evaluation.
Representations may be excitatory, inhibitory, joint,
readout or an exact name such as population:e0. A network without an
inhibitory soma population records that representation as missing.
balanced_countsketch projections give a label-independent matched width:
use the native width to compare mechanisms with identical architectures, and a
common projected width to compare E, I and joint populations of different
sizes. Projection draws, MLP initializations and random-subset draws are
technical repeats; average them within a trained checkpoint before inference
across training seeds. Within each draw, subset sizes are nested prefixes of
one random coordinate permutation, so the capacity curve is paired. Subset
decoding uses one deterministic ridge probe per coordinate set. Population
geometry reports participation-ratio and entropy effective ranks of the
covariance spectrum (native soma scales) and the correlation spectrum
(standardized somas); these describe dimensional concentration, not class
information.
The defaults are one identity projection native and one ridge probe
linear with 20 label shuffles; information, subset_decoding and
geometry are off. information.projection_names (default
[matched16]) must name declared projections.
analysis:
runtime:
final:
mode: "stream"
batch_size: 256
representation_accessibility:
enabled: true
params:
representations: ["excitatory", "inhibitory", "joint"]
projections:
- name: "matched16"
type: "balanced_countsketch"
output_dim: 16
draws: 5
probes:
- name: "linear"
type: "ridge"
ridge_alpha: 1.0
n_label_shuffles: 20
- name: "nonlinear"
type: "mlp"
max_projection_draws: 1
hidden_dims: [32, 16]
activation: "relu"
alpha: 0.0001
learning_rate_init: 0.001
batch_size: 256
max_iter: 300
early_stopping: true
validation_fraction: 0.1
n_iter_no_change: 20
draws: 3
n_label_shuffles: 5
information:
enabled: true
compute_joint: true
compute_per_soma: true
projection_names: ["matched16"]
per_soma_representations: ["excitatory", "inhibitory"]
n_neighbors: 5
n_label_shuffles: 20
standardize: true
subset_decoding:
enabled: true
representations: ["excitatory"]
subset_sizes: [1, 2, 4, 8, 16, 32, 64]
draws: 10
probe:
name: "subset_linear"
type: "ridge"
ridge_alpha: 1.0
n_label_shuffles: 5
geometry:
enabled: true
representations: ["excitatory"]
variance_epsilon: 1.0e-12
seed: 42
Output: representation_accessibility/<name>.json. Example profile:
configs/examples/representation_accessibility_analysis.yaml. Collect
checkpoint runs with dendritic-collect-representations.
path_matched_information
Final-only. Joint-vector class information on the same nested anatomical
supports as path_matched_intervention: complete soma-to-distal paths are
selected without data, and their prefixes give the same number of compartment
coordinates at every depth. The signals are the pre-gate excitatory and
inhibitory currents, their joint vector, the child current, the pre-gate
voltage and the post-gate output (signals, all six by default). Every
coordinate is standardized on the validation examples without labels, and
the Ross continuous-discrete k-nearest-neighbour estimator gives the
information in bits, with a label-permutation distribution
(n_label_shuffles).
The analyzer reads only the validation split. Depth 0 (the soma) uses the
whole soma population once; every other depth uses support_draws path
draws, which are technical repeats: average them within a checkpoint before
treating independently trained checkpoints as units. depths defaults to
every depth, soma included. Set module_name_prefix to select one dendritic
tree when the model has more than one; expected_n_somas and
expected_branch_factors make the analysis fail on a checkpoint with a
different architecture. An unset information_seed or support_seed is
derived from experiment.probe_seed (see Seeds).
analysis:
path_matched_information:
enabled: true
params:
signals: [excitation_current, inhibition_current, joint_EI_currents,
upstream_child_current, pre_gate_voltage, post_gate_output]
depths: [0, 1, 2, 3, 4]
support_draws: 5
support_seed: 271828
information_seed: 314159
n_neighbors: 10
n_label_shuffles: 20
expected_n_somas: 20
expected_branch_factors: [3, 3, 3, 3]
Output: path_matched_information/<name>.json. Example profile:
configs/examples/path_matched_information_analysis.yaml. Collect checkpoint
runs with dendritic-collect-path-information.
Interventions
ablation
Requires E/I dendritic branch layers (a structured E/I core or a
population_network); other models are skipped without a message. Scores
the test split after disrupting one part of the network at a time. Methods
(params.methods.ablation_methods, default [lesion]):
lesionSet the effective weights (after the weight transform) of the selected synapses to zero.
shufflePermute the selected signal across the examples of a batch (
methods.shuffle_seed). Keeps its distribution but breaks its alignment with the labels.mean_clampReplace the selected signal by its mean over the training split, computed once before the evaluation and recorded under
mean_clamp_reference. Keeps the operating point but removes trial-to-trial variability.methods.clamp_statisticaccepts onlymean.
Another method name or clamp statistic raises when the configuration loads.
Selectors under params.selection must be set: with the default empty
lists nothing is ablated and only an empty baseline is written. Their entries
are compared in lower case with - and spaces read as _; an entry that
names no level, target or score raises when the configuration loads, with the
valid names, instead of selecting nothing.
levelslayer(whole dendritic layers) andcompartment(each branch row in turn; lesion only, other methods are skipped).targetsall_synapses(orall),excitation(exc),inhibition(inh) andupstream(vb,branch_input; the coupling from child branches).metricsaccuracy,auc,categorical_loglikelihood(categorical_ll,loglikelihood,log_likelihood),mse,cosine_similarity(cosine) andpred_label_mi_bits(pred_label_mi,pred_mi; the information between predicted and true labels, in bits). Scores that do not fit the model are dropped.
analysis:
ablation:
enabled: true
params:
selection:
levels: ["layer"]
targets: ["excitation", "inhibition", "upstream", "all_synapses"]
metrics: ["accuracy", "pred_label_mi_bits"]
methods:
ablation_methods: ["lesion", "shuffle", "mean_clamp"]
Output: ablation_analysis/<name>.json (per epoch epochs/epoch<N>.json)
and figures per method and score, with an animation over epochs when per-epoch
results exist.
path_matched_intervention
Final-only. A fixed-count control for comparing causal sensitivity across dendritic depth. One complete soma-to-distal path is selected per soma and technical draw without inspecting data, labels, activations or the checkpoint, and its prefixes give the same number of compartment coordinates at every depth. Only those coordinates are changed; every other coordinate of the targeted signal stays as the model produces it.
targets (default: the first three) are excitation_current,
inhibition_current and joint_EI_currents, which act on currents before
the compartment’s transfer and gate, and post_gate_output, which acts on
the branch-layer output before the next, more proximal layer consumes it.
methods (default: all three) are zero, fixed_train_mean (the mean
over the training split, computed once) and global_test_shuffle (one
test-donor permutation over the whole split, shared across depths and, for
joint targets, across E and I, so a joint shuffle keeps the donor’s
sample-wise E/I covariance). depths are soma-relative and dendritic:
1 is proximal, larger values are more distal, 0 is rejected; the
default is every dendritic depth. paths_per_soma (for example
[1, 2, 3]) gives a nested dose-response in which each dose contains the
smaller ones; it may not exceed the proximal branch factor, and empty means
one path per soma. Each record reports the accuracy drop, the increase of the
mean cross entropy, and the accuracy drop normalized by the baseline accuracy
above chance_accuracy (default 1 / n_classes); the analysis raises
when the model is not above chance. max_samples caps the test examples.
Supports depend on support_namespace, support_seed and
support_draws. Set module_name_prefix when the model has more than one
dendritic tree (any multi-layer stack, or an E/I network whose E and I cells
both have trees), and expected_n_somas and expected_branch_factors to
make the analysis fail on a checkpoint with a different architecture.
analysis:
path_matched_intervention:
enabled: true
params:
targets: ["excitation_current", "inhibition_current", "joint_EI_currents",
"post_gate_output"]
methods: ["zero", "fixed_train_mean", "global_test_shuffle"]
paths_per_soma: [1, 2, 3]
support_draws: 5
support_seed: 271828
shuffle_seed: 314159
expected_n_somas: 20
expected_branch_factors: [3, 3, 3, 3]
The two path-matched analyzers select identical supports only when they use
the same support_namespace, support_seed and support_draws. An
unset support_seed is derived from experiment.probe_seed and the
analyzer’s own configuration path, so the two analyzers then draw different
supports: write the same support_seed in both sections, and check the
support hash when collecting.
Output: path_matched_intervention/<name>.json with accuracy, cross
entropy, exact available and replaced coordinate counts and hashed supports.
Example profile: configs/examples/path_matched_intervention_analysis.yaml.
Collect checkpoint runs with dendritic-collect-path-interventions.
local_inhibitory_population_intervention
Final-only. Replaces the complete post-gate output of the inhibitory
population of one network layer of a feedforward population_network and
re-evaluates the test split. Every layer must have exactly one inhibitory
population, other than the readout, with exactly one outgoing same-step
ff_inhibitory route to a local excitatory population; other graphs raise.
The analysis therefore measures the complete local I-to-E signal of that
layer, not a compartment current or recurrent inhibition.
methods (default: all three) are global_test_shuffle (donors from the
whole test split), within_class_test_shuffle (donors of the same class)
and zero; the results report the accuracy drop and the increase of the
mean cross entropy. The global-minus-within-class contrast measures
class-aligned dependence. permutation_draws (default 3) donor permutations
are technical repeats within a checkpoint (shuffle_seed).
expected_network_layers and expected_inhibitory_width make the
analysis fail on a different architecture; max_samples caps the test
examples.
analysis:
local_inhibitory_population_intervention:
enabled: true
params:
methods: [global_test_shuffle, within_class_test_shuffle, zero]
permutation_draws: 5
shuffle_seed: 1234
expected_network_layers: 5
expected_inhibitory_width: 16
Output: local_inhibitory_population_intervention/<name>.json. Example
profile:
configs/examples/local_inhibitory_population_intervention_analysis.yaml.
Collect checkpoint runs with dendritic-collect-local-i-interventions.
input_region_intervention
Final-only. Paired interventions on image regions of a feedforward image
classifier (recurrent cores and models with typed synapses, spiking somas,
dendritic spikes or soma feedback raise). image_shape and at least one
region are required. Each region has a name and a kind:
central_square (the central center_fraction of the height and width,
default 0.5) or surround (the rest of the image), the same for every
example; or foreground (locations whose channel-mean intensity exceeds
foreground_threshold, default 0.5) or background (the other
locations), computed from each unmodified input. operations
(remove_only, retain_only) replace the region or everything except
it with zero or with the featurewise mean of the reference split
(replacement_methods: zero, reference_mean). The interventions
are evaluated on
evaluation_split (default test) with the reference mean from
reference_split (default train).
Outputs include accuracy and NLL changes, changes of the E and I soma
population responses, and, within matched target trees
(target_population_polarities, default [excitatory]), changes of the
excitatory and inhibitory pre-gate drive, pre-gate voltage, post-gate branch
output and soma output. identity_soma_class_mapping with
identity_soma_population_name and identity_soma_network_layer_index
adds summaries for somas assigned to classes. Results are aggregate
statistics; no per-example values are saved.
Masking the raw image of directly copied E/I image banks perturbs both routes, so the result is differential E/I response propagation, not a pathway-specific intervention, and later-layer records are propagated responses, not pixel receptive fields. Records from excitatory- and inhibitory-target trees are separate estimands and must not be pooled. The positive inhibitory drive is not a signed downstream effect: additive units subtract it, whereas shunting units place it in the divisor.
analysis:
input_region_intervention:
enabled: true
params:
image_shape: [1, 28, 28]
regions:
- name: center
kind: central_square
center_fraction: 0.5
- name: foreground
kind: foreground
foreground_threshold: 0.5
operations: [remove_only, retain_only]
replacement_methods: [zero, reference_mean]
Output: input_region_intervention/<name>.json. Example profile:
configs/examples/input_region_intervention_analysis.yaml. Collect
checkpoint runs with dendritic-collect-input-region-interventions.
branch_local_sensitivity
Final-only. Local diagonal derivatives of each branch’s post-gate output with
respect to its excitatory current E, inhibitory current I, inherited
child current C and inherited conductance G, at the operating points of
the test split. The analyzer differentiates the fitted gate at the observed
voltage, so learned gate gain is included. It supports shunting, raw
additive, tangent-matched additive and conductance-normalized additive
branches; across-feature additive normalization is rejected because it is
not a local diagonal operation.
The output reports mean signed and absolute derivatives, RMS derivatives, and
mean absolute first-order contributions by soma-relative depth. These are
descriptive operating-point sensitivities, not class information or evidence
that a signal is necessary; use path_matched_intervention for the latter. depths defaults to
every dendritic depth; include_soma: true adds depth 0. The tree
selection and architecture checks are those of path_matched_intervention.
analysis:
branch_local_sensitivity:
enabled: true
params:
depths: [1, 2, 3, 4]
module_name_prefix: core_network.layers.0.populations.e0.branch_layers
expected_n_somas: 64
expected_branch_factors: [3, 3, 3, 3]
Output: branch_local_sensitivity/<name>.json. Example profile:
configs/examples/branch_local_sensitivity_analysis.yaml. Collect checkpoint
runs with dendritic-collect-branch-sensitivities.
node_perturbation_credit
Final-only. Estimates the error of every compartment of the selected
soma-relative depths from loss changes under antithetic perturbations of
that level (Node-perturbation estimates, applied with
compartment perturbations) and compares it
with the exact error, the gradient of the loss with respect to a zero
perturbation. coordinate is output, voltage or, for shunting
levels, current. dictionaries sets the perturbation directions:
independent (every compartment), siblings (one direction per group of
children of a parent) or neuron (one per neuron). relative_scales
multiply the RMS of the perturbed quantity over the level on the analysed
examples (for current, the shunting numerator).
match_perturbation_energy adds runs of the structured dictionaries scaled
by sqrt(D / m), so their expected perturbation energy equals that of
independent draws. loss is cross_entropy (class labels) or mse
(any output shape, also one value per example). The first max_samples
examples of the evaluation split are analysed (default 256; null for
all), and every forward pass takes at most analysis.runtime.batch_size
rows, a row being one example under one draw. seed fixes the draws; left
unset, a run fills it from its probe seed (seed 0 without one), and every row
records the seed of its draws.
The tree selection and checks are those of path_matched_intervention.
Each perturbed level must run DendriticBranchLayer.forward once per model
forward (feedforward population networks qualify). Recurrent cores, stateful
current paths, cores with autograd_credit_mode: soma_broadcast and models
with signal_rounding are refused: their gradients are not the derivatives
of the forward the perturbations probe (rounding makes it piecewise constant,
while autograd passes gradients through the casts).
The estimator assumes that examples are independent. Overrides
sample_rolled_denominator, sample_rolled_tangent and
permuted_current_denominator are refused anywhere in the model, including
outside the selected tree: they can couple examples and change their pairings
when perturbation draws are batched.
A level that executes but does not influence the loss has zero exact credit, including when all model parameters are frozen and the loss has no gradient graph. Alignment to a zero reference is undefined. When both exact and estimated credit are zero, the cosines and relative metrics are reported as NaN.
The scale is relative to the RMS over the level, while the effect of a
perturbation depends on each compartment. For current the voltage
response is the injected current divided by the compartment’s total
conductance, so weakly driven, high-resistance compartments receive much
larger relative perturbations, and a nonlinear tree can distort current
estimates at scales where output and voltage estimates show no scale
dependence. List several relative_scales: an estimate that changes with
the scale is distorted by it.
Each row reports a depth, dictionary, energy, relative scale and draw count:
cosine with the exact error over all compartments, the mean cosine within each
neuron, sign agreement, relative error, norm ratio, for structured
dictionaries the share of the exact error’s energy in their span and the
cosine with that projection, the forward evaluations per example (two per
draw) and the wall time per draw (CUDA work included). The file also records
the seed, device, dtype, chunk and rows per forward. These are
measurements at a fixed state; they say nothing by themselves about learning
with the estimates.
analysis:
node_perturbation_credit:
enabled: true
params:
depths: [1, 2]
module_name_prefix: core_network.layers.0.excitatory_cells.branch_layers
coordinate: output
dictionaries: [independent, siblings, neuron]
relative_scales: [0.01, 0.1]
draws: [1, 4, 16, 64, 256]
match_perturbation_energy: true
max_samples: 256
Output: node_perturbation_credit/<name>.json. Example profile:
configs/examples/node_perturbation_credit_analysis.yaml.
Connectivity and weights
weight
Requires E/I dendritic branch layers; other models are skipped without a
message. Statistics of the synaptic weights (synapse_weights) and of the
branch coupling weights (branch_weights): means, variances, percentiles,
minimum and maximum (compute_* switches), total dendritic strength, and
counts of active synapses above weight_threshold (1e-6), globally, per
layer and per branch. computation_level, branch_aggregation,
per_einet_analysis and per_neuron_analysis are accepted but do not
change the result.
- Source support
compute_source_support: trueadds exact source-contact frequency and mean effective-conductance profiles by network layer, target population, soma, dendritic depth and pathway (source_support_target_polarities, default[excitatory];source_support_pathways, default[ff_excitatory, ff_inhibitory]), saved as<name>_source_support_profiles.npzand<name>_source_support_records.csv. It reads the populations of apopulation_networkor a recurrent structured E/I core; a feedforwardeinetcore yields no profiles. Withsource_support_image_shapethe profiles of image inputs are also drawn (source_support_plot_soma_indices,source_support_fig_save_format, defaultpdf).- Source-region alignment
compute_source_region_alignment: truealigns the image-space profile with class-conditional source occupancy estimated onsource_region_reference_split(defaultvalidation). It requirescompute_source_support,source_support_image_shapeand an explicit class for every target soma (source_region_soma_to_class). For a source profile \(w_p\) normalized to sum to one, it reports\[A_{\mathrm{pref}}=\sum_p w_p P(x_p>\tau\mid Y=c_s),\qquad T=A_{\mathrm{pref}}-A_{\mathrm{rest}}.\]Contact and conductance weighting are separate quantities, as are center/surround support mass and within-region preferred/rest alignment. These are structural and activity-alignment statistics, not information or causal attribution. Only the network layers in
source_region_image_network_layers(default[0]) count as image pixels;source_region_foreground_thresholds(default[0.0, 0.5]),source_region_center_boundsandsource_region_max_reference_samplescomplete the options.
analysis:
weight:
enabled: true
params:
compute_source_support: true
source_support_image_shape: [28, 28]
compute_source_region_alignment: true
source_region_soma_to_class: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
source_region_reference_split: validation
Output: weight_analysis/<name> (JSON), figures with fixed names after
training, and the source-support and alignment files above. Example profiles:
configs/examples/synaptic_source_support_analysis.yaml and
configs/examples/synaptic_source_region_alignment_analysis.yaml. Collect
checkpoint runs with dendritic-collect-synaptic-support.
source_tuning_support
Final-only. Requires a feedforward population_network. Asks whether the
exact source coordinates a synaptic pathway selects are tuned to the
preferred class of their target soma. The preferred class is chosen on
reference_split (default train) and the source moments are estimated
on evaluation_split (default validation); with
require_independent_splits (default true) the two must differ. It
reports uniform-, contact- and conductance-weighted preferred/rest means,
threshold exceedance probabilities, standardized mean differences and the
excess over the uniform eligible-source baseline, and, for every target soma,
the centered class-profile correlation between that soma on the reference
split and every source coordinate on the evaluation split.
Only declared first-layer sources (image_source_layers,
image_source_names) with a matching image_shape are treated as pixels;
deeper sources use native neuron coordinates. The analysis keeps per-class
sufficient statistics and never stores example-by-source matrices. It works
with fixed indexed, indexed-release, standard Top-K and variance Top-K
contacts; release models use the mean transmission w * p(w) while keeping
the structural contact counts, and variance Top-K uses its saved training
statistics. See Conductance options for a contextual-input example.
analysis:
source_tuning_support:
enabled: true
params:
reference_split: train
evaluation_split: validation
pathways: [ff_excitatory, ff_inhibitory]
target_polarities: [excitatory, inhibitory]
image_shape: [28, 28]
image_source_layers: [0]
Output: source_tuning_support_analysis/<name>.json. Example profiles:
configs/examples/source_tuning_support_analysis.yaml and
configs/examples/conductance_source_tuning_analysis.yaml. Collect
checkpoint runs with dendritic-collect-source-tuning; its checkpoint
summaries average target somas with equal weight and never pool trained
seeds.
synapse_turnover
Requires training: true (the default). Counts the contacts of every
synapse bank (exc, inh, rec_exc, rec_inh) of every dendritic
branch layer that stay active, form and disappear. The first snapshot is the
model before training, and later ones are taken every snapshot_interval
epochs (default 1). incremental compares each snapshot with the previous
one and cumulative with the first, per module and summed per pathway. It
raises when the model has no masked synapse banks.
analysis:
synapse_turnover:
enabled: true
params:
snapshot_interval: 5
Output, after training only: synapse_turnover_analysis/<name> (JSON),
<name>_turnover.png and <name>_turnover_by_layer.png.
synapse_pruning
Final-only. A census of the realized contacts of every synapse bank of every
dendritic branch layer: a contact is realized when the bank’s mask selects it
and its effective weight is nonzero, so contacts that pruning set to zero do
not count even when a Top-K mask still selects them. When the run prunes
(training.main.pruning), the census before and after every pruning step is
recorded with the pruning statistics, the losses before and after it, and the
contacts removed per layer and pathway.
analysis:
synapse_pruning:
enabled: true
params:
save_figures: true
Output: synapse_pruning_analysis/<name> (JSON), <name>_summary.txt and,
with save_figures, the realized contacts per branch and their mean and
standard deviation against depth.
receptive_field
Requires dendritic branch layers. Gathers the input-level receptive-field
maps of all branch layers from the weights and plots sampled maps
(n_rows by n_cols). Set rf_shape when excitatory and inhibitory
maps share one image shape, or exc_rf_shape and inh_rf_shape.
save_raw_data (default true) saves the raw maps, and
load_raw_data: true reuses a saved file (raw_filename) instead of
reading the weights. Optional extensions, which read the test split:
compute_activation_tuning: class-preferred branch excitation, inhibition, E/I ratio and output summaries, and withactivation_samples_per_classa class-balanced sample of scalar branch signals (activation_sample_signals:exc,inh,upstream,depolarizing_drive,vout,ei_ratio), restricted by depth and branch with theactivation_sample_*options;compute_component_rfs: E/I mean and conditioned component maps per soma;compute_rf_tuning: aggregate tuning, confusion and entropy summaries, discriminability heatmaps, preferred and non-preferred compartment summaries for the E/I layerrf_tuning_layer_index, drawn whenplot_rf_tuningis true.
analysis:
receptive_field:
enabled: true
params:
rf_shape: [28, 28]
compute_activation_tuning: true
Output: receptive_field_analysis/<name>_raw_receptive_fields.pt,
<name>_summary.json (in epochs/ during training), optional tuning
files, and after training exc_receptive_fields and
inh_receptive_fields figures in fig_save_format (default png).
configs/templates/analysis_full_template.yaml lists every receptive-field
option.
inhibitory_specialization
Requires recurrent inhibition onto excitatory dendrites (a recurrent core with
branch_rec_inhibition weights); other models are skipped with a warning.
For each local recurrent I-to-E route it computes the gate index
G = f_soma - f_distal for every (I, E) pair, where f_level is the
fraction of the realized inhibitory weight mass that the I cell delivers to
the E cell’s compartments at that level; pairs without a realized synapse are
excluded. Each I cell is classified from the mean and standard deviation of
its G values as gate-specialist (mean above gate_threshold, default
0.1, and standard deviation below std_threshold, default 0.15),
context-specialist (mean below -gate_threshold), mixed-conditional
(standard deviation above std_threshold) or diffuse. The level fractions
divided by the compartment count are reported as
per_compartment_control. For named population_network cores the
results are keyed by the excitatory target population (for example
population_network/microcircuit.pyr) and list the inhibitory source
populations.
summarize_inhibitory_specialization_from_compartment_weights and
ei_connectivity_motifs use the same computation.
analysis:
inhibitory_specialization:
enabled: true
params:
gate_threshold: 0.1
std_threshold: 0.15
Output: inhibitory_specialization/<name>.json and, with save_figures
(default true), <name>.pdf.
Activity
compartment_statistics
Requires dendritic branch layers; other models are skipped (recorded as
skipped in analysis_status.json, see Completion status).
Statistics (mean, variance, percentiles, minimum and maximum, entropy) of the
weights, inputs and activations of the compartments, globally, per layer and
per branch, on the test split. It also runs on named recurrent population
graphs whose branch layers use TopKLinear synapses. Options: the content
switches synapse_weights, branch_weights, inputs,
activations; the level switches global_analysis, layer_analysis,
branch_analysis; the statistic switches compute_*;
per_class_analysis (default false); and n_samples (a cap on the
examples) with seed, which only orders the capped examples.
analysis:
compartment_statistics:
enabled: true
params:
n_samples: 2000
per_class_analysis: true
Output: compartment_statistics_analysis/<name> (JSON) and figures with
fixed names. The E/I ratio figure ratio_pairwise_comparison.png uses only
the branches that have both excitatory and inhibitory statistics: branches
without inhibitory synapses are left out, and an excitatory-only tree gets no
ratio figure. What was left out is logged and listed under
missing_outputs in analysis_status.json.
synaptic_activation
Requires dendritic branch layers; other models are skipped without a message.
Records the activation of every synapse (input times effective weight) of the
excitatory, inhibitory and recurrent Top-K synapse banks on the test split,
and summarizes it for the whole network (network_summary), per layer
(layer_summary) and per branch (branch_summary), and as raw values
(raw_summary); all four are on. With downsample (default true)
only samples examples (default 5) are used; logspace reports
logarithms. It also runs on named recurrent population graphs whose branch
layers use TopKLinear synapses.
analysis:
synaptic_activation:
enabled: true
params:
downsample: true
samples: 32
Output: synaptic_activation_analysis/<name> (JSON).
branch_activation
Requires dendritic branch layers; other models are skipped without a message.
Records, per branch layer, the excitatory current, the inhibitory current
(when the layer has inhibitory input) and the branch output on the test split,
with the summary, logspace, downsample and samples options of
synaptic_activation. synapse_activations and branch_activations
(both true) choose the recorded signals.
analysis:
branch_activation:
enabled: true
params:
raw_summary: false
samples: 32
Output: branch_activation_analysis/<name> (JSON).
Dynamics and learning
reactivation_dynamics
Runs after every epoch by default (training: true). Tracks every gate
(reactivation) module built from a param_* or linear_* activation
type, residual_silu or endpoint_tanh; a model without such gates
writes nothing. For each it records the gate
parameters, the distribution of the pre-gate voltage (mean, standard
deviation, median, MAD, quantiles) and output statistics; for the unit-range
gates ParametricTanh and ParametricTanhOnlyM also the saturation
fractions sat_lo = P(output < 0.05) and sat_hi = P(output > 0.95). It
uses one batch of at most max_samples examples (default 1024) from the
training split during training and from the test split after training,
independently of analysis.runtime. Useful for diagnosing gate-slope drift,
the quality of the gate calibration and the stationarity of the voltage
distribution.
analysis:
reactivation_dynamics:
enabled: true
training: true
params:
max_samples: 1024
Output: reactivation_dynamics/epochs/<name>.json for every pass,
final included. Collect checkpoint runs with
dendritic-collect-reactivation, which adds the network layer, population
and soma-relative depth of each gate as columns.
routing
Recurrent dendritic cores only (a recurrent structured E/I core or a recurrent
population_network); others are skipped. For each population it reports
the share of activity in each dendritic level, as raw L2 norms and as
width-normalized RMS values, and the fraction of each level’s signal that
comes from feedforward rather than recurrent input, as means and standard
deviations over all time steps and examples of the test split (processed in
batches of 128). routing has no params.
analysis:
routing:
enabled: true
Output: routing_analysis/<name> (JSON).
jacobian_spectrum
Requires recurrent excitation or inhibition onto dendrites; other models are
skipped. The top_k (default 16) singular values and the spectral radii of
the effective recurrent excitatory and inhibitory weights at each dendritic
level, with the level’s time constant when available. This summarizes weight
matrices; StateTransitionJacobianAnalyzer (see Analysis)
differentiates the complete state update instead.
analysis:
jacobian_spectrum:
enabled: true
params:
top_k: 5
save_figures: true
Output: jacobian_spectrum/<name>.json and, with save_figures,
<name>.pdf.
dendritic_timetraces
Simulates how the learned dendritic cascade responds to a synthetic two-pulse
input, using the trained per-level time constants and ParametricTanh gate
parameters; populations without per-level time constants or with other gates
are skipped. The protocol has n_timesteps steps (default 90), stimulus
windows stim1_window and stim2_window with amplitudes stim1_amp and
stim2_amp, a response_window, and noise noise_std (seeded by
seed). Structured recurrent E/I layers report layer_N keys; named
population networks report keys such as
population_network/microcircuit.pyr.
analysis:
dendritic_timetraces:
enabled: true
params:
n_timesteps: 80
save_figures: true
Output: dendritic_timetraces/<name>.json and one PDF per layer.
spike_train
For models with spiking somas (LIFSoma modules; see
Spiking soma); others are skipped. The analyzer hooks the soma
directly, so it works with spike_readout set to spikes, rate or
membrane. On at most max_samples test examples (default 512) it
reports compact raster events, mean firing rate, silent-unit and silent-trial
fractions, spike-count Fano factors and ISI mean and coefficient of variation.
Options: dt (1.0), threshold (0.5), include_raster,
max_raster_samples (8), include_per_timestep_rate.
analysis:
spike_train:
enabled: true
params:
max_samples: 512
include_raster: true
max_raster_samples: 8
include_per_timestep_rate: true
Output: spike_train_analysis/<name>.json.
local_rule_components
The factors of the local learning rule of local_ca (see
Local credit assignment) by dendritic depth and synapse type: branch
voltage, input resistance, excitatory and inhibitory driving forces,
presynaptic drive, eligibilities and, with include_broadcast, the
broadcast error (broadcast_mode: scalar or per_soma;
error_mode: auto, ce, bce, mse or none).
include_dendritic adds the dendritic factors. It reads at most
max_samples examples (default 1024) of the training split during training
and of the test split after it. e_rev_exc and e_rev_inh must keep
their values 1.0 and 0.0. Models with indexed-release banks, learnable or
non-unit leak, endpoint_tanh gates, or additive layers other than raw
additive raise.
analysis:
local_rule_components:
enabled: true
training: true
params:
max_samples: 1024
broadcast_mode: per_soma
error_mode: auto
Output: local_rule_components/epochs/epoch<N>.json and .csv per epoch,
rows appended to trajectory.csv (append_training_csv), and
final/<name>.json and .csv after training (save_json,
save_csv).