Skip to content

Fitting

btorch.fitting

Model-driven fitting and tuning utilities.

Unlike :mod:btorch.analysis (post-hoc statistics of recorded activity), the tools here simulate :mod:btorch.models networks and optimise their parameters.

  • :mod:.tuning: constant-current f-I / V-I sweeps of a neuron class.
  • :mod:.two_compartment: Allen-data fitting of the two-compartment GLIF neuron.

Attributes

__all__ = ['tuning', 'two_compartment'] module-attribute

btorch.fitting.tuning

Functions:

compute_fi_vi_curve(neuron_cls, neuron_params, current_start=0.0, current_end=20.0, steps=20, duration=1000, dt=1.0, device='cpu')

Simulate a constant-current sweep and return the f-I and V-I curves.

Builds the neuron, wraps it in an RNN and runs it once with all currents as a batch (this is a simulation, not a lookup).

Parameters:

Name Type Description Default
neuron_cls type[Module]

The neuron class to instantiate.

required
neuron_params Mapping[str, Any]

Dictionary of parameters for the neuron.

required
current_start float

Starting current value for sweep.

0.0
current_end float

Ending current value for sweep.

20.0
steps int

Number of currents to sweep.

20
duration float

Duration of simulation in ms.

1000
dt float

Time step in ms.

1.0
device str | device

Device to run on.

'cpu'

Returns:

Type Description
dict[str, Tensor]

A dictionary containing: - currents: Tensor of shape (steps,) - frequencies: Firing rate in Hz, shape (steps, n_neuron) - voltages: Tensor of shape (time_steps, steps, n_neuron) - time: Time axis in ms, shape (time_steps,)

Source code in btorch/fitting/tuning.py
def compute_fi_vi_curve(
    neuron_cls: type[torch.nn.Module],
    neuron_params: Mapping[str, Any],
    current_start: float = 0.0,
    current_end: float = 20.0,
    steps: int = 20,
    duration: float = 1000,
    dt: float = 1.0,
    device: str | torch.device = "cpu",
) -> dict[str, torch.Tensor]:
    """Simulate a constant-current sweep and return the f-I and V-I curves.

    Builds the neuron, wraps it in an RNN and runs it once with all currents
    as a batch (this is a simulation, not a lookup).

    Args:
        neuron_cls: The neuron class to instantiate.
        neuron_params: Dictionary of parameters for the neuron.
        current_start: Starting current value for sweep.
        current_end: Ending current value for sweep.
        steps: Number of currents to sweep.
        duration: Duration of simulation in ms.
        dt: Time step in ms.
        device: Device to run on.

    Returns:
        A dictionary containing:
            - currents: Tensor of shape (steps,)
            - frequencies: Firing rate in Hz, shape (steps, n_neuron)
            - voltages: Tensor of shape (time_steps, steps, n_neuron)
            - time: Time axis in ms, shape (time_steps,)
    """
    currents = torch.linspace(current_start, current_end, steps, device=device)

    params = dict(neuron_params)
    n_neuron = params.pop("n_neuron", 1)
    params["device"] = device

    neuron = neuron_cls(n_neuron=n_neuron, **params)
    init_net_state(neuron, batch_size=steps, device=device)

    rnn_model = make_rnn(neuron, update_state_names=["v"])

    time_steps = int(duration / dt)
    input_current = currents[None, :, None].expand(time_steps, steps, n_neuron)

    with torch.no_grad():
        with environ.context(dt=dt):
            spikes, states = rnn_model(input_current)

    voltages = states["v"]

    spike_counts = spikes.sum(dim=0)  # (steps, n_neuron)
    frequencies = spike_counts / (duration / 1000.0)

    return {
        "currents": currents,
        "frequencies": frequencies,
        "voltages": voltages,
        "time": torch.arange(0, duration, dt, device=device),
    }

init_net_state(net, batch_size=None, **kwargs)

Initialize state for all MemoryModule instances in a network.

Walks through every Module in net and calls init_state() if it is a base.MemoryModule or has an init_state method. Also moves the network to the device/dtype specified in kwargs.

Parameters:

Name Type Description Default
net Module

Network to initialize.

required
batch_size int | Sequence[int] | None

Batch size(s) for state initialization.

None
**kwargs Any

Passed to init_state() (e.g., device, dtype).

{}
Example

functional.init_net_state(model, batch_size=4, device="cuda")

Source code in btorch/models/functional.py
def init_net_state(
    net: nn.Module,
    batch_size: int | Sequence[int] | None = None,
    **kwargs: Any,
) -> None:
    """Initialize state for all MemoryModule instances in a network.

    Walks through every ``Module`` in ``net`` and calls ``init_state()``
    if it is a ``base.MemoryModule`` or has an ``init_state`` method.
    Also moves the network to the device/dtype specified in ``kwargs``.

    Args:
        net: Network to initialize.
        batch_size: Batch size(s) for state initialization.
        **kwargs: Passed to ``init_state()`` (e.g., ``device``, ``dtype``).

    Example:
        >>> functional.init_net_state(model, batch_size=4, device="cuda")
    """

    _call_on_modules(net, "init_state", batch_size, **kwargs)

make_rnn(obj=None, allow_buffer=False, **rnn_kwargs)

make_rnn(
    obj: type[base.MemoryModule],
    allow_buffer: bool = False,
    **rnn_kwargs,
) -> type[RecurrentNNAbstract]
make_rnn(
    obj: base.MemoryModule,
    allow_buffer: bool = False,
    **rnn_kwargs,
) -> RecurrentNNAbstract
make_rnn(
    obj: None = None,
    allow_buffer: bool = False,
    **rnn_kwargs,
) -> Callable[
    [type[base.MemoryModule]], type[RecurrentNNAbstract]
]

RNN wrapper.

Source code in btorch/models/rnn.py
def make_rnn(
    obj: type[base.MemoryModule] | base.MemoryModule | None = None,
    allow_buffer: bool = False,
    **rnn_kwargs: Any,
) -> (
    type[RecurrentNNAbstract]
    | RecurrentNNAbstract
    | Callable[[type[base.MemoryModule]], type[RecurrentNNAbstract]]
):
    """RNN wrapper."""

    def _build_rnn_class(
        neuron_cls: type[base.MemoryModule] | base.MemoryModule,
    ) -> type[RecurrentNNAbstract]:
        class RNNWrapped(RecurrentNNAbstract):
            def __init__(self, *args: Any, **kwargs: Any) -> None:
                super().__init__(**rnn_kwargs)
                if isinstance(neuron_cls, type):
                    self.rnn_cell = neuron_cls(*args, **kwargs)
                else:
                    self.rnn_cell = neuron_cls

            def single_step_forward(
                self, *args: Any, **kwargs: Any
            ) -> tuple[Any, dict[str, Tensor]]:
                out = self.rnn_cell(*args, **kwargs)
                states = filter_hidden_states(
                    self.rnn_cell, self.update_state_names, allow_buffer=allow_buffer
                )
                return out, states

        RNNWrapped.__name__ = (
            f"RNN_{getattr(neuron_cls, '__name__', type(neuron_cls).__name__)}"
        )
        return RNNWrapped

    if isinstance(obj, type):
        return _build_rnn_class(obj)
    elif isinstance(obj, base.MemoryModule):
        Wrapped = _build_rnn_class(obj)
        return Wrapped()
    elif obj is None:

        def decorator(cls: type[base.MemoryModule]) -> type[RecurrentNNAbstract]:
            return _build_rnn_class(cls)

        return decorator

    raise TypeError(
        "`make_rnn` expects a MemoryModule class, a MemoryModule instance, "
        "or `None` when used as a decorator."
    )

btorch.fitting.two_compartment

Allen-data fitting utilities for the two-compartment GLIF neuron.

Layout:

  • :mod:.data: Allen sweep loading, resampling and cell selection.
  • :mod:.loss: :class:FitLossConfig and the voltage/spike loss terms.
  • :mod:.evaluation: rollout and per-sweep evaluation.
  • :mod:.report: fit report writer (JSON + figures).
  • :mod:.fit: the staged / global / TBPTT fitting strategies.

Attributes

DEFAULT_TWO_COMPARTMENT_FIT_STAGES = (TwoCompartmentFitStage(name='passive', trainable_params=(frozenset({'E_L', 'tau_s'})), sweep_kind='silent', voltage_weight=1.0, spike_weight=0.0, spike_count_weight=10.0, spike_timing_weight=0.0, spike_count_over_weight=8.0, spike_count_under_weight=1.0, sparsity_weight=0.0, param_bounds={'E_L': (-82.0, -65.0), 'tau_s': (8.0, 60.0)}), TwoCompartmentFitStage(name='threshold_reset', trainable_params=(frozenset({'tau_s', 'E_L', 'R_s', 'v_threshold', 'v_reset', 'delta_T'})), sweep_kind='countcal', voltage_weight=0.02, spike_weight=1.0, spike_count_weight=50.0, spike_timing_weight=12.0, spike_count_over_weight=2.0, spike_count_under_weight=5.0, sparsity_weight=0.0, param_bounds={'tau_s': (6.0, 40.0), 'E_L': (-78.0, -66.0), 'R_s': (0.04, 0.35), 'v_threshold': (-50.0, -42.0), 'v_reset': (-78.0, -58.0), 'delta_T': (0.0, 12.0)}), TwoCompartmentFitStage(name='spike_init', trainable_params=(frozenset({'tau_s', 'E_L', 'R_s', 'v_threshold', 'delta_T'})), sweep_kind='spiking', voltage_weight=0.01, spike_weight=1.0, spike_count_weight=60.0, spike_timing_weight=15.0, spike_count_over_weight=2.0, spike_count_under_weight=6.0, sparsity_weight=0.0, param_bounds={'tau_s': (5.0, 35.0), 'E_L': (-78.0, -64.0), 'R_s': (0.05, 0.4), 'v_threshold': (-52.0, -40.0), 'delta_T': (0.5, 15.0)}), TwoCompartmentFitStage(name='adaptation', trainable_params=(frozenset({'tau_a', 'tau_th', 'delta_th'})), sweep_kind='spiking', voltage_weight=0.05, spike_weight=1.0, spike_count_weight=35.0, spike_timing_weight=10.0, spike_count_over_weight=2.0, spike_count_under_weight=4.0, sparsity_weight=0.0, param_bounds={'tau_a': (20.0, 250.0), 'tau_th': (5.0, 250.0), 'delta_th': (0.0, 15.0)}), TwoCompartmentFitStage(name='coupling', trainable_params=(frozenset({'w_Ca', 'theta_Ca', 'w_sa', 'w_as'})), sweep_kind='all', voltage_weight=0.02, spike_weight=1.0, spike_count_weight=25.0, spike_timing_weight=10.0, spike_count_over_weight=3.0, spike_count_under_weight=2.0, sparsity_weight=0.002, param_bounds={'w_Ca': (0.0, 1.0), 'theta_Ca': (0.0, 8.0), 'w_sa': (0.0, 1.2), 'w_as': (0.0, 1.2)})) module-attribute

DEFAULT_TWO_COMPARTMENT_PARAM_BOUNDS = {'tau_s': (5.0, 80.0), 'R_s': (0.01, 0.5), 'E_L': (-85.0, -55.0), 'tau_a': (20.0, 400.0), 'tau_th': (5.0, 400.0), 'delta_th': (0.0, 20.0), 'delta_T': (0.0, 10.0), 'w_Ca': (0.0, 3.0), 'theta_Ca': (-5.0, 15.0), 'w_sa': (0.0, 3.0), 'w_as': (0.0, 3.0), 'v_threshold': (-55.0, -35.0), 'v_reset': (-80.0, -50.0)} module-attribute

SweepKind = Literal['all', 'silent', 'lowrate', 'spiking', 'countcal'] module-attribute

__all__ = ['AllenSweepBatch', 'DEFAULT_TWO_COMPARTMENT_PARAM_BOUNDS', 'DEFAULT_TWO_COMPARTMENT_FIT_STAGES', 'FitEvaluation', 'FitLossConfig', 'GlobalSearchConfig', 'StagedConfig', 'TbpttConfig', 'TwoCompartmentFitStage', 'TwoCompartmentModel', 'choose_current_clamp_sweeps', 'detect_spikes_from_voltage', 'evaluate_fit_across_sweeps', 'evaluate_two_compartment_fit', 'exponential_filter_spike_train', 'filter_mouse_visp_l5_pyramidal_cells', 'fit_two_compartment_model', 'get_cell_types_cache', 'load_allen_sweep', 'mask_post_spike_voltage_samples', 'plot_two_compartment_fit', 'query_mouse_visp_l5_pyramidal_cells', 'resample_trace', 'rollout_two_compartment', 'save_fit_report', 'spike_timing_loss', 'spike_timing_stats', 'two_compartment_loss'] module-attribute

Classes

AllenSweepBatch dataclass

Preprocessed Allen sweep tensors for fitting.

Parameters:

Name Type Description Default
specimen_id int

Allen specimen identifier.

required
sweep_number int

Sweep number within the NWB file.

required
dt float

Simulation timestep in milliseconds.

required
i_soma Tensor

Somatic current tensor shaped (T, B, N).

required
v_true Tensor

Recorded voltage tensor shaped (T, B, N).

required
spike_true Tensor

Binary spike tensor shaped (T, B, N).

required
i_apical Tensor | None

Optional apical input tensor shaped (T, B, N).

None
metadata dict[str, Any] | None

Auxiliary Allen metadata retained for bookkeeping.

None
Source code in btorch/fitting/two_compartment/data.py
@dataclass
class AllenSweepBatch:
    """Preprocessed Allen sweep tensors for fitting.

    Args:
        specimen_id: Allen specimen identifier.
        sweep_number: Sweep number within the NWB file.
        dt: Simulation timestep in milliseconds.
        i_soma: Somatic current tensor shaped ``(T, B, N)``.
        v_true: Recorded voltage tensor shaped ``(T, B, N)``.
        spike_true: Binary spike tensor shaped ``(T, B, N)``.
        i_apical: Optional apical input tensor shaped ``(T, B, N)``.
        metadata: Auxiliary Allen metadata retained for bookkeeping.
    """

    specimen_id: int
    sweep_number: int
    dt: float
    i_soma: Tensor
    v_true: Tensor
    spike_true: Tensor
    i_apical: Tensor | None = None
    metadata: dict[str, Any] | None = None

FitEvaluation dataclass

Evaluation artifacts for a fitted model on one sweep.

Source code in btorch/fitting/two_compartment/evaluation.py
@dataclass
class FitEvaluation:
    """Evaluation artifacts for a fitted model on one sweep."""

    specimen_id: int
    sweep_number: int
    dt: float
    metrics: dict[str, float]
    traces: dict[str, np.ndarray]

FitLossConfig dataclass

Loss weights and spike-matching settings for the two-compartment fit.

This is the single public way to configure the loss: pass one instance as loss= to :func:two_compartment_loss, :func:evaluate_two_compartment_fit, :func:evaluate_fit_across_sweeps and :func:fit_two_compartment_model.

Parameters:

Name Type Description Default
voltage_weight float

Weight of the masked voltage reconstruction loss.

1.0
spike_weight float

Weight of the smoothed spike-train loss.

1.0
spike_count_weight float

Weight of the spike-count matching penalty.

0.0
spike_timing_weight float

Weight of the hard spike-timing event loss.

0.0
spike_count_over_weight float

Weight of over-prediction in the count loss (must be positive).

1.0
spike_count_under_weight float

Weight of under-prediction in the count loss (must be positive).

1.0
sparsity_weight float

Weight of the w_Ca sparsity penalty.

0.0001
spike_tau_ms float

Smoothing constant (ms) of the spike-train loss.

10.0
post_spike_mask_ms float

Duration (ms) of the post-spike voltage mask.

3.0
spike_match_window_ms float

Tolerance window (ms) for matching predicted and true spikes.

10.0
spike_miss_penalty_ms float | None

Per-event penalty (ms) assigned to unmatched spikes in the hard timing loss. Defaults to the match window.

None
Source code in btorch/fitting/two_compartment/loss.py
@dataclass(frozen=True)
class FitLossConfig:
    """Loss weights and spike-matching settings for the two-compartment fit.

    This is the single public way to configure the loss: pass one instance as
    ``loss=`` to :func:`two_compartment_loss`,
    :func:`evaluate_two_compartment_fit`, :func:`evaluate_fit_across_sweeps`
    and :func:`fit_two_compartment_model`.

    Args:
        voltage_weight: Weight of the masked voltage reconstruction loss.
        spike_weight: Weight of the smoothed spike-train loss.
        spike_count_weight: Weight of the spike-count matching penalty.
        spike_timing_weight: Weight of the hard spike-timing event loss.
        spike_count_over_weight: Weight of over-prediction in the count loss
            (must be positive).
        spike_count_under_weight: Weight of under-prediction in the count loss
            (must be positive).
        sparsity_weight: Weight of the ``w_Ca`` sparsity penalty.
        spike_tau_ms: Smoothing constant (ms) of the spike-train loss.
        post_spike_mask_ms: Duration (ms) of the post-spike voltage mask.
        spike_match_window_ms: Tolerance window (ms) for matching predicted
            and true spikes.
        spike_miss_penalty_ms: Per-event penalty (ms) assigned to unmatched
            spikes in the hard timing loss. Defaults to the match window.
    """

    voltage_weight: float = 1.0
    spike_weight: float = 1.0
    spike_count_weight: float = 0.0
    spike_timing_weight: float = 0.0
    spike_count_over_weight: float = 1.0
    spike_count_under_weight: float = 1.0
    sparsity_weight: float = 1e-4
    spike_tau_ms: float = 10.0
    post_spike_mask_ms: float = 3.0
    spike_match_window_ms: float = 10.0
    spike_miss_penalty_ms: float | None = None

GlobalSearchConfig dataclass

Options of the bounded global search ("global", "hybrid" and every stage of "staged").

Parameters:

Name Type Description Default
param_bounds dict[str, tuple[float, float]] | None

Per-parameter (low, high) overrides; unspecified parameters use DEFAULT_TWO_COMPARTMENT_PARAM_BOUNDS.

None
maxiter int

Differential-evolution outer iterations.

20
popsize int

Differential-evolution population size multiplier.

8
local_maxiter int

Maximum L-BFGS-B iterations of the polish step.

50
seed int | None

Random seed (None for non-deterministic); staged fits add the stage index to it.

0
polish bool

Run L-BFGS-B after the global search.

True
Source code in btorch/fitting/two_compartment/fit.py
@dataclass(frozen=True)
class GlobalSearchConfig:
    """Options of the bounded global search (``"global"``, ``"hybrid"`` and
    every stage of ``"staged"``).

    Args:
        param_bounds: Per-parameter ``(low, high)`` overrides; unspecified
            parameters use ``DEFAULT_TWO_COMPARTMENT_PARAM_BOUNDS``.
        maxiter: Differential-evolution outer iterations.
        popsize: Differential-evolution population size multiplier.
        local_maxiter: Maximum L-BFGS-B iterations of the polish step.
        seed: Random seed (``None`` for non-deterministic); staged fits add
            the stage index to it.
        polish: Run L-BFGS-B after the global search.
    """

    param_bounds: dict[str, tuple[float, float]] | None = None
    maxiter: int = 20
    popsize: int = 8
    local_maxiter: int = 50
    seed: int | None = 0
    polish: bool = True

StagedConfig dataclass

Options of the staged back-end (method="staged").

Parameters:

Name Type Description Default
stages Sequence[TwoCompartmentFitStage] | None

Stage definitions; None uses DEFAULT_TWO_COMPARTMENT_FIT_STAGES. Each stage is searched with the :class:GlobalSearchConfig passed alongside.

None
Source code in btorch/fitting/two_compartment/fit.py
@dataclass(frozen=True)
class StagedConfig:
    """Options of the staged back-end (``method="staged"``).

    Args:
        stages: Stage definitions; ``None`` uses
            ``DEFAULT_TWO_COMPARTMENT_FIT_STAGES``. Each stage is searched
            with the :class:`GlobalSearchConfig` passed alongside.
    """

    stages: Sequence[TwoCompartmentFitStage] | None = None

TbpttConfig dataclass

Options of the truncated-BPTT back-end (method="tbptt"/"hybrid").

Parameters:

Name Type Description Default
lr float

Adam learning rate.

0.001
epochs int

Passes over the sweeps.

10
chunk_size int

Truncated-BPTT chunk length in time steps; the hidden state carries over between chunks while the graph is detached.

500
Source code in btorch/fitting/two_compartment/fit.py
@dataclass(frozen=True)
class TbpttConfig:
    """Options of the truncated-BPTT back-end
    (``method="tbptt"``/``"hybrid"``).

    Args:
        lr: Adam learning rate.
        epochs: Passes over the sweeps.
        chunk_size: Truncated-BPTT chunk length in time steps; the hidden
            state carries over between chunks while the graph is detached.
    """

    lr: float = 1e-3
    epochs: int = 10
    chunk_size: int = 500

TwoCompartmentFitStage dataclass

Configuration for one stage of staged parameter fitting.

Source code in btorch/fitting/two_compartment/fit.py
@dataclass(frozen=True)
class TwoCompartmentFitStage:
    """Configuration for one stage of staged parameter fitting."""

    name: str
    trainable_params: frozenset[str]
    sweep_kind: SweepKind
    voltage_weight: float
    spike_weight: float
    spike_count_weight: float
    spike_timing_weight: float
    sparsity_weight: float
    spike_count_over_weight: float = 1.0
    spike_count_under_weight: float = 1.0
    param_bounds: dict[str, tuple[float, float]] | None = None

TwoCompartmentModel

Bases: Protocol

What the fitting and evaluation code needs from a neuron model.

:class:~btorch.models.neurons.two_compartment.TwoCompartmentGLIF satisfies it. Besides the members below, the model must be a :class:torch.nn.Module that works with :func:btorch.models.functional.init_net_state and reset_net (hidden state buffers), and its fitted parameters are those with requires_grad=True (names must have bounds, see DEFAULT_TWO_COMPARTMENT_PARAM_BOUNDS).

Attributes:

Name Type Description
w_Ca Tensor

Calcium-coupling weights; their mean absolute value is the sparsity penalty of the loss.

Source code in btorch/fitting/two_compartment/evaluation.py
class TwoCompartmentModel(Protocol):
    """What the fitting and evaluation code needs from a neuron model.

    :class:`~btorch.models.neurons.two_compartment.TwoCompartmentGLIF`
    satisfies it. Besides the members below, the model must be a
    :class:`torch.nn.Module` that works with
    :func:`btorch.models.functional.init_net_state` and ``reset_net`` (hidden
    state buffers), and its fitted parameters are those with
    ``requires_grad=True`` (names must have bounds, see
    ``DEFAULT_TWO_COMPARTMENT_PARAM_BOUNDS``).

    Attributes:
        w_Ca: Calcium-coupling weights; their mean absolute value is the
            sparsity penalty of the loss.
    """

    w_Ca: Tensor

    def multi_step_forward(
        self,
        i_soma_seq: Tensor,
        i_apical_seq: Tensor | None = None,
        *,
        return_state: bool = False,
    ) -> tuple[Tensor, Tensor, dict[str, Tensor]]:
        """Run ``(T, *batch, n_neuron)`` inputs and return ``(spike, v,
        state)`` where ``state`` holds ``v_pre_spike``, ``i_a`` and ``i_bap``
        (called with ``return_state=True``)."""
        ...

    def parameters(self) -> Iterable[torch.nn.Parameter]: ...

    def named_parameters(self) -> Iterable[tuple[str, torch.nn.Parameter]]: ...
Methods:
multi_step_forward(i_soma_seq, i_apical_seq=None, *, return_state=False)

Run (T, *batch, n_neuron) inputs and return (spike, v, state) where state holds v_pre_spike, i_a and i_bap (called with return_state=True).

Source code in btorch/fitting/two_compartment/evaluation.py
def multi_step_forward(
    self,
    i_soma_seq: Tensor,
    i_apical_seq: Tensor | None = None,
    *,
    return_state: bool = False,
) -> tuple[Tensor, Tensor, dict[str, Tensor]]:
    """Run ``(T, *batch, n_neuron)`` inputs and return ``(spike, v,
    state)`` where ``state`` holds ``v_pre_spike``, ``i_a`` and ``i_bap``
    (called with ``return_state=True``)."""
    ...

Functions:

_fit_sweeps_once(model, sweeps, *, device=None, dtype=torch.float32, loss)

Evaluate the current model parameters on one or more sweeps.

Returns the per-sweep loss terms (see :func:_loss_floats) averaged over sweeps.

Source code in btorch/fitting/two_compartment/fit.py
def _fit_sweeps_once(
    model: TwoCompartmentModel,
    sweeps: Iterable[AllenSweepBatch],
    *,
    device: str | torch.device | None = None,
    dtype: torch.dtype = torch.float32,
    loss: FitLossConfig,
) -> dict[str, float]:
    """Evaluate the current model parameters on one or more sweeps.

    Returns the per-sweep loss terms (see :func:`_loss_floats`) averaged over
    sweeps.
    """
    rows: list[dict[str, float]] = []
    with torch.no_grad():
        for sweep in sweeps:
            i_soma, v_true, spike_true, i_apical = _prepare_sweep(
                model, sweep, device=device, dtype=dtype
            )

            with environ.context(dt=float(sweep.dt)):
                rollout = rollout_two_compartment(model, i_soma, i_apical)
                losses = two_compartment_loss(
                    v_pred=rollout["v"],
                    spike_pred=rollout["spike"],
                    v_true=v_true,
                    spike_true=spike_true,
                    dt=sweep.dt,
                    w_Ca=model.w_Ca,
                    loss=loss,
                )
            rows.append(_loss_floats(losses))

    if not rows:
        raise ValueError("At least one sweep is required for fitting.")

    return {key: sum(row[key] for row in rows) / len(rows) for key in rows[0]}

_fit_two_compartment_model_global(model, sweeps, *, config, device=None, dtype=torch.float32, loss)

Fit with bounded global search and optional local L-BFGS-B polish.

Source code in btorch/fitting/two_compartment/fit.py
def _fit_two_compartment_model_global(
    model: TwoCompartmentModel,
    sweeps: Iterable[AllenSweepBatch],
    *,
    config: GlobalSearchConfig,
    device: str | torch.device | None = None,
    dtype: torch.dtype = torch.float32,
    loss: FitLossConfig,
) -> list[dict[str, float | str]]:
    """Fit with bounded global search and optional local L-BFGS-B polish."""
    # Resolve through the package namespace at call time so that
    # ``btorch.fitting.two_compartment._fit_sweeps_once`` can be
    # monkeypatched (the characterization tests spy on it).
    from . import _fit_sweeps_once  # noqa: PLC0415

    sweep_list = list(sweeps)
    x0, slices = _pack_trainable_parameters(model)
    bounds = _build_parameter_bounds(model, slices, param_bounds=config.param_bounds)
    history: list[dict[str, float | str]] = []

    def objective(x: np.ndarray) -> float:
        _set_trainable_parameters(model, x, slices)
        metrics = _fit_sweeps_once(
            model,
            sweep_list,
            device=device,
            dtype=dtype,
            loss=loss,
        )
        return metrics["total_loss"]

    global_result = optimize.differential_evolution(
        objective,
        bounds=bounds,
        maxiter=config.maxiter,
        popsize=config.popsize,
        seed=config.seed,
        polish=False,
        updating="deferred",
    )
    _set_trainable_parameters(model, global_result.x, slices)
    metrics = _fit_sweeps_once(
        model,
        sweep_list,
        device=device,
        dtype=dtype,
        loss=loss,
    )
    history.append(
        {
            "phase": "global",
            "epoch": 0.0,
            "specimen_id": -1.0,
            "sweep_number": -1.0,
            "chunk_start": -1.0,
            "total_loss": metrics["total_loss"],
            "voltage_loss": metrics["voltage_loss"],
            "spike_loss": metrics["spike_loss"],
            "spike_count_loss": metrics["spike_count_loss"],
            "spike_timing_loss": metrics["spike_timing_loss"],
            "sparsity_loss": metrics["sparsity_loss"],
        }
    )

    if not config.polish:
        return history

    local_result = optimize.minimize(
        objective,
        global_result.x,
        method="L-BFGS-B",
        bounds=bounds,
        options={"maxiter": int(config.local_maxiter)},
    )
    _set_trainable_parameters(model, local_result.x, slices)
    metrics = _fit_sweeps_once(
        model,
        sweep_list,
        device=device,
        dtype=dtype,
        loss=loss,
    )
    history.append(
        {
            "phase": "local",
            "epoch": 1.0,
            "specimen_id": -1.0,
            "sweep_number": -1.0,
            "chunk_start": -1.0,
            "total_loss": metrics["total_loss"],
            "voltage_loss": metrics["voltage_loss"],
            "spike_loss": metrics["spike_loss"],
            "spike_count_loss": metrics["spike_count_loss"],
            "spike_timing_loss": metrics["spike_timing_loss"],
            "sparsity_loss": metrics["sparsity_loss"],
        }
    )
    return history

_loss_floats(losses)

Convert a :func:two_compartment_loss result to float history entries.

Keys are "<component>_loss" for every loss term, e.g. "total_loss" and "spike_count_loss".

Source code in btorch/fitting/two_compartment/loss.py
def _loss_floats(losses: dict[str, Tensor]) -> dict[str, float]:
    """Convert a :func:`two_compartment_loss` result to float history entries.

    Keys are ``"<component>_loss"`` for every loss term, e.g. ``"total_loss"``
    and ``"spike_count_loss"``.
    """
    return {
        f"{name}_loss": float(value.detach().cpu()) for name, value in losses.items()
    }

_prepare_sweep(model, sweep, *, device, dtype, init_state=True)

Move a sweep to device/dtype and reset the model for it.

Parameters:

Name Type Description Default
model TwoCompartmentModel

Model whose state is (re)initialised for the sweep batch size.

required
sweep AllenSweepBatch

Sweep to convert.

required
device str | device | None

Target device.

required
dtype dtype

Target dtype.

required
init_state bool

Also call init_net_state (skip after the first sweep when the state buffers already exist).

True

Returns:

Type Description
tuple[Tensor, Tensor, Tensor, Tensor | None]

(i_soma, v_true, spike_true, i_apical) on the target device.

Source code in btorch/fitting/two_compartment/evaluation.py
def _prepare_sweep(
    model: TwoCompartmentModel,
    sweep: AllenSweepBatch,
    *,
    device: str | torch.device | None,
    dtype: torch.dtype,
    init_state: bool = True,
) -> tuple[Tensor, Tensor, Tensor, Tensor | None]:
    """Move a sweep to ``device``/``dtype`` and reset the model for it.

    Args:
        model: Model whose state is (re)initialised for the sweep batch size.
        sweep: Sweep to convert.
        device: Target device.
        dtype: Target dtype.
        init_state: Also call ``init_net_state`` (skip after the first sweep
            when the state buffers already exist).

    Returns:
        ``(i_soma, v_true, spike_true, i_apical)`` on the target device.
    """
    i_soma = sweep.i_soma.to(device=device, dtype=dtype)
    v_true = sweep.v_true.to(device=device, dtype=dtype)
    spike_true = sweep.spike_true.to(device=device, dtype=dtype)
    i_apical = None
    if sweep.i_apical is not None:
        i_apical = sweep.i_apical.to(device=device, dtype=dtype)

    batch_size = i_soma.shape[1]
    if init_state:
        functional.init_net_state(
            model, batch_size=batch_size, device=device, dtype=dtype
        )
    functional.reset_net(model, batch_size=batch_size, device=device, dtype=dtype)
    return i_soma, v_true, spike_true, i_apical

choose_current_clamp_sweeps(sweep_records, *, preferred_stimuli=('long square',))

Select current-clamp sweeps appropriate for somatic fitting.

Source code in btorch/fitting/two_compartment/data.py
def choose_current_clamp_sweeps(
    sweep_records: Sequence[dict[str, Any]],
    *,
    preferred_stimuli: Sequence[str] = ("long square",),
) -> list[dict[str, Any]]:
    """Select current-clamp sweeps appropriate for somatic fitting."""
    matched = []
    for sweep in sweep_records:
        stimulus_name = (
            sweep.get("stimulus_name")
            or sweep.get("ephys_stimulus", {}).get("description")
            or ""
        )
        stimulus_units = sweep.get("stimulus_units") or ""
        clamp_mode = sweep.get("clamp_mode") or sweep.get("stimulus_type_name") or ""

        is_current_clamp = _matches_any(stimulus_units, ["pa", "amp"]) or (
            clamp_mode and not _matches_any(clamp_mode, ["voltage clamp"])
        )
        if not is_current_clamp:
            continue
        if preferred_stimuli and not _matches_any(stimulus_name, preferred_stimuli):
            continue
        matched.append(sweep)
    return matched

detect_spikes_from_voltage(voltage, *, threshold=0.0)

Detect upward threshold crossings in a voltage trace.

Source code in btorch/fitting/two_compartment/data.py
def detect_spikes_from_voltage(
    voltage: Tensor,
    *,
    threshold: float = 0.0,
) -> Tensor:
    """Detect upward threshold crossings in a voltage trace."""
    above = voltage >= threshold
    shifted = torch.zeros_like(above)
    shifted[1:] = above[:-1]
    return (above & ~shifted).to(voltage.dtype)

evaluate_fit_across_sweeps(model, sweeps, *, device=None, dtype=torch.float32, loss=None)

Evaluate a fitted model on multiple sweeps and aggregate metrics.

Parameters:

Name Type Description Default
model TwoCompartmentModel

Fitted two-compartment neuron.

required
sweeps Iterable[AllenSweepBatch]

Sweeps to evaluate; at least one is required.

required
device str | device | None

Torch device; defaults to the model's device.

None
dtype dtype

Torch dtype used for the rollouts.

float32
loss FitLossConfig | None

Loss weights and spike-matching settings (defaults to :class:FitLossConfig).

None

Returns:

Type Description
list[FitEvaluation]

Per-sweep evaluations and the aggregate (mean_* plus per regime

dict[str, float]

silent_/lowrate_/spiking_ means) metric dictionary.

Raises:

Type Description
ValueError

If sweeps is empty.

Source code in btorch/fitting/two_compartment/evaluation.py
def evaluate_fit_across_sweeps(
    model: TwoCompartmentModel,
    sweeps: Iterable[AllenSweepBatch],
    *,
    device: str | torch.device | None = None,
    dtype: torch.dtype = torch.float32,
    loss: FitLossConfig | None = None,
) -> tuple[list[FitEvaluation], dict[str, float]]:
    """Evaluate a fitted model on multiple sweeps and aggregate metrics.

    Args:
        model: Fitted two-compartment neuron.
        sweeps: Sweeps to evaluate; at least one is required.
        device: Torch device; defaults to the model's device.
        dtype: Torch dtype used for the rollouts.
        loss: Loss weights and spike-matching settings (defaults to
            :class:`FitLossConfig`).

    Returns:
        Per-sweep evaluations and the aggregate (``mean_*`` plus per regime
        ``silent_/lowrate_/spiking_`` means) metric dictionary.

    Raises:
        ValueError: If ``sweeps`` is empty.
    """
    evaluations = [
        evaluate_two_compartment_fit(
            model, sweep, device=device, dtype=dtype, loss=loss
        )
        for sweep in sweeps
    ]
    if not evaluations:
        raise ValueError("At least one sweep is required for evaluation.")

    metric_names = evaluations[0].metrics.keys()
    aggregate = {
        f"mean_{name}": float(np.mean([ev.metrics[name] for ev in evaluations]))
        for name in metric_names
    }
    group_filters = {
        "silent": [
            ev for ev in evaluations if float(ev.metrics["spike_count_true"]) == 0.0
        ],
        "spiking": [
            ev for ev in evaluations if float(ev.metrics["spike_count_true"]) > 0.0
        ],
        "lowrate": [
            ev
            for ev in evaluations
            if 0.0 < float(ev.metrics["spike_count_true"]) <= 5.0
        ],
    }
    aggregate["n_sweeps"] = float(len(evaluations))
    for group_name, group in group_filters.items():
        aggregate[f"n_{group_name}_sweeps"] = float(len(group))
        if not group:
            continue
        for name in metric_names:
            aggregate[f"{group_name}_mean_{name}"] = float(
                np.mean([ev.metrics[name] for ev in group])
            )
    return evaluations, aggregate

evaluate_two_compartment_fit(model, sweep, *, device=None, dtype=torch.float32, loss=None)

Evaluate a fitted model on a single sweep and collect metrics.

Parameters:

Name Type Description Default
model TwoCompartmentModel

Fitted two-compartment neuron.

required
sweep AllenSweepBatch

Sweep to roll the model out on.

required
device str | device | None

Torch device; defaults to the model's device.

None
dtype dtype

Torch dtype used for the rollout.

float32
loss FitLossConfig | None

Loss weights and spike-matching settings (defaults to :class:FitLossConfig).

None
Source code in btorch/fitting/two_compartment/evaluation.py
def evaluate_two_compartment_fit(
    model: TwoCompartmentModel,
    sweep: AllenSweepBatch,
    *,
    device: str | torch.device | None = None,
    dtype: torch.dtype = torch.float32,
    loss: FitLossConfig | None = None,
) -> FitEvaluation:
    """Evaluate a fitted model on a single sweep and collect metrics.

    Args:
        model: Fitted two-compartment neuron.
        sweep: Sweep to roll the model out on.
        device: Torch device; defaults to the model's device.
        dtype: Torch dtype used for the rollout.
        loss: Loss weights and spike-matching settings (defaults to
            :class:`FitLossConfig`).
    """
    config = FitLossConfig() if loss is None else loss
    i_soma, v_true, spike_true, i_apical = _prepare_sweep(
        model, sweep, device=device, dtype=dtype
    )

    with torch.no_grad():
        with environ.context(dt=float(sweep.dt)):
            rollout = rollout_two_compartment(model, i_soma, i_apical)

    losses = two_compartment_loss(
        v_pred=rollout["v"],
        spike_pred=rollout["spike"],
        v_true=v_true,
        spike_true=spike_true,
        dt=sweep.dt,
        w_Ca=model.w_Ca,
        loss=config,
    )
    timing_stats = spike_timing_stats(
        spike_true,
        rollout["spike"],
        dt=sweep.dt,
        match_window_ms=config.spike_match_window_ms,
    )
    refractory_bins = int(round(config.post_spike_mask_ms / sweep.dt))
    voltage_mask = mask_post_spike_voltage_samples(
        spike_true,
        refractory_bins=refractory_bins,
    )
    v_true_np = _to_1d_numpy(v_true)
    v_pred_np = _to_1d_numpy(rollout["v"])
    spike_true_np = _to_1d_numpy(spike_true)
    spike_pred_np = _to_1d_numpy(rollout["spike"])
    i_soma_np = _to_1d_numpy(i_soma)
    time_ms = np.arange(v_true_np.shape[0], dtype=np.float64) * float(sweep.dt)

    mask_np = _to_1d_numpy(voltage_mask.to(dtype=torch.float32)) > 0.5
    if mask_np.any():
        masked_error = v_pred_np[mask_np] - v_true_np[mask_np]
        voltage_rmse = float(np.sqrt(np.mean(masked_error**2)))
        target_masked = v_true_np[mask_np]
        ss_res = float(np.sum(masked_error**2))
        ss_tot = float(np.sum((target_masked - target_masked.mean()) ** 2))
        voltage_r2 = 1.0 - ss_res / max(ss_tot, 1e-12)
    else:
        voltage_rmse = float("nan")
        voltage_r2 = float("nan")

    spike_mae = float(np.mean(np.abs(spike_pred_np - spike_true_np)))
    spike_count_true = int((spike_true_np > 0.5).sum())
    spike_count_pred = int((spike_pred_np > 0.5).sum())
    spike_count_error = abs(spike_count_pred - spike_count_true)
    f1_score = _f1_score_from_binary_traces(spike_true_np, spike_pred_np)

    metrics = {
        **_loss_floats(losses),
        "voltage_rmse": voltage_rmse,
        "voltage_r2": voltage_r2,
        "spike_mae": spike_mae,
        "spike_f1": f1_score,
        "spike_count_true": float(spike_count_true),
        "spike_count_pred": float(spike_count_pred),
        "spike_count_error": float(spike_count_error),
        "spike_timing_f1": timing_stats["timing_f1"],
        "spike_precision": timing_stats["precision"],
        "spike_recall": timing_stats["recall"],
        "matched_spikes": timing_stats["matched_spikes"],
        "false_positive_spikes": timing_stats["false_positive_spikes"],
        "false_negative_spikes": timing_stats["false_negative_spikes"],
        "mean_timing_error_ms": timing_stats["mean_timing_error_ms"],
    }
    return FitEvaluation(
        specimen_id=sweep.specimen_id,
        sweep_number=sweep.sweep_number,
        dt=sweep.dt,
        metrics=metrics,
        traces={
            "time_ms": time_ms,
            "i_soma": i_soma_np,
            "v_true": v_true_np,
            "v_pred": v_pred_np,
            "spike_true": spike_true_np,
            "spike_pred": spike_pred_np,
        },
    )

exponential_filter_spike_train(spike_train, *, tau_ms, dt)

Apply a causal exponential filter to a spike train.

Source code in btorch/fitting/two_compartment/loss.py
def exponential_filter_spike_train(
    spike_train: Tensor,
    *,
    tau_ms: float,
    dt: float,
) -> Tensor:
    """Apply a causal exponential filter to a spike train."""
    if tau_ms <= 0.0:
        raise ValueError(f"tau_ms must be positive, got {tau_ms}.")
    alpha = float(np.exp(-dt / tau_ms))
    filtered = torch.zeros_like(spike_train)
    filtered[0] = spike_train[0]
    for t in range(1, spike_train.shape[0]):
        filtered[t] = alpha * filtered[t - 1] + (1.0 - alpha) * spike_train[t]
    return filtered

filter_mouse_visp_l5_pyramidal_cells(cells)

Filter Allen cell metadata to mouse VISp layer-5 pyramidal candidates.

Notes

Allen metadata can vary across cache versions, so this filter accepts a few equivalent key names and uses spiny as a practical proxy for pyramidal morphology when an explicit class label is unavailable.

Source code in btorch/fitting/two_compartment/data.py
def filter_mouse_visp_l5_pyramidal_cells(
    cells: Sequence[dict[str, Any]],
) -> list[dict[str, Any]]:
    """Filter Allen cell metadata to mouse VISp layer-5 pyramidal candidates.

    Notes:
        Allen metadata can vary across cache versions, so this filter accepts a
        few equivalent key names and uses ``spiny`` as a practical proxy for
        pyramidal morphology when an explicit class label is unavailable.
    """
    matched = []
    for cell in cells:
        species = cell.get("species") or cell.get("donor__species")
        area = (
            cell.get("structure_area_abbrev")
            or cell.get("structure_acronym")
            or cell.get("structure_parent__acronym")
        )
        layer = cell.get("structure_layer_name") or cell.get("cortical_layer")
        dendrite = cell.get("dendrite_type") or cell.get("cell_type")

        if not _matches_any(species, ["mouse", "mus musculus"]):
            continue
        if not _matches_any(area, ["visp", "primary visual cortex"]):
            continue
        if not _matches_any(layer, ["layer 5", "5"]):
            continue
        if not _matches_any(dendrite, ["spiny", "pyramidal"]):
            continue
        matched.append(cell)
    return matched

fit_two_compartment_model(model, sweeps, *, method='hybrid', device=None, dtype=torch.float32, loss=None, tbptt=None, search=None, staged=None)

Fit the model with a robust strategy for poor initialization.

Each back-end receives exactly its own option object; None selects its defaults.

Parameters:

Name Type Description Default
model TwoCompartmentModel

Two-compartment neuron to fit (see :class:~btorch.fitting.two_compartment.TwoCompartmentModel).

required
sweeps Iterable[AllenSweepBatch]

Allen or synthetic sweeps to fit against.

required
method Literal['hybrid', 'global', 'tbptt', 'staged']

"hybrid" first performs bounded global search, then runs a short TBPTT refinement. "global" stops after the search/polish stage. "tbptt" keeps the original truncated-BPTT workflow. "staged" fits parameter groups sequentially with stage-specific sweep subsets and spike-count-first weighting.

'hybrid'
device str | device | None

Torch device for evaluation and refinement.

None
dtype dtype

Torch dtype used during fitting.

float32
loss FitLossConfig | None

Loss weights and spike-matching settings; None uses the :class:FitLossConfig defaults. In method="staged" the per-stage weights override the weight fields of this config while its spike-matching settings are kept.

None
tbptt TbpttConfig | None

:class:TbpttConfig for "tbptt" and "hybrid".

None
search GlobalSearchConfig | None

:class:GlobalSearchConfig for "global", "hybrid" and "staged".

None
staged StagedConfig | None

:class:StagedConfig for "staged".

None

Returns:

Type Description
list[dict[str, float | str]]

A history list with one row per fitting stage or TBPTT chunk.

Raises:

Type Description
ValueError

If an option object is passed that method does not use (it would be silently ignored), or no sweep/stage can be fit.

Notes

The default "hybrid" method is intended for real fitting runs where the starting parameters may be far from the biological regime. Global search handles the large basin-finding problem more robustly than pure BPTT, while the optional TBPTT stage can still fine-tune the result.

Source code in btorch/fitting/two_compartment/fit.py
def fit_two_compartment_model(
    model: TwoCompartmentModel,
    sweeps: Iterable[AllenSweepBatch],
    *,
    method: Literal["hybrid", "global", "tbptt", "staged"] = "hybrid",
    device: str | torch.device | None = None,
    dtype: torch.dtype = torch.float32,
    loss: FitLossConfig | None = None,
    tbptt: TbpttConfig | None = None,
    search: GlobalSearchConfig | None = None,
    staged: StagedConfig | None = None,
) -> list[dict[str, float | str]]:
    """Fit the model with a robust strategy for poor initialization.

    Each back-end receives exactly its own option object; ``None`` selects its
    defaults.

    Args:
        model: Two-compartment neuron to fit (see
            :class:`~btorch.fitting.two_compartment.TwoCompartmentModel`).
        sweeps: Allen or synthetic sweeps to fit against.
        method: ``"hybrid"`` first performs bounded global search, then runs a
            short TBPTT refinement. ``"global"`` stops after the search/polish
            stage. ``"tbptt"`` keeps the original truncated-BPTT workflow.
            ``"staged"`` fits parameter groups sequentially with stage-specific
            sweep subsets and spike-count-first weighting.
        device: Torch device for evaluation and refinement.
        dtype: Torch dtype used during fitting.
        loss: Loss weights and spike-matching settings; ``None`` uses the
            :class:`FitLossConfig` defaults. In ``method="staged"`` the
            per-stage weights override the weight fields of this config while
            its spike-matching settings are kept.
        tbptt: :class:`TbpttConfig` for ``"tbptt"`` and ``"hybrid"``.
        search: :class:`GlobalSearchConfig` for ``"global"``, ``"hybrid"`` and
            ``"staged"``.
        staged: :class:`StagedConfig` for ``"staged"``.

    Returns:
        A history list with one row per fitting stage or TBPTT chunk.

    Raises:
        ValueError: If an option object is passed that ``method`` does not
            use (it would be silently ignored), or no sweep/stage can be fit.

    Notes:
        The default ``"hybrid"`` method is intended for real fitting runs where
        the starting parameters may be far from the biological regime. Global
        search handles the large basin-finding problem more robustly than pure
        BPTT, while the optional TBPTT stage can still fine-tune the result.
    """
    used = {
        "tbptt": {"tbptt", "hybrid"},
        "search": {"global", "hybrid", "staged"},
        "staged": {"staged"},
    }
    for name, value in (("tbptt", tbptt), ("search", search), ("staged", staged)):
        if value is not None and method not in used[name]:
            raise ValueError(
                f"`{name}` is not used by method={method!r} "
                f"(used by: {sorted(used[name])})."
            )

    loss = FitLossConfig() if loss is None else loss
    tbptt = TbpttConfig() if tbptt is None else tbptt
    search = GlobalSearchConfig() if search is None else search
    staged = StagedConfig() if staged is None else staged
    sweep_list = list(sweeps)
    common = {"device": device, "dtype": dtype, "loss": loss}

    if method == "tbptt":
        return _fit_two_compartment_model_tbptt(
            model, sweep_list, config=tbptt, **common
        )
    if method == "staged":
        return _fit_two_compartment_model_staged(
            model, sweep_list, config=staged, search=search, **common
        )

    history = _fit_two_compartment_model_global(
        model, sweep_list, config=search, **common
    )
    if method == "global":
        return history
    history.extend(
        _fit_two_compartment_model_tbptt(model, sweep_list, config=tbptt, **common)
    )
    return history

get_cell_types_cache(manifest_file=None, *, cache=None)

Create or reuse an AllenSDK CellTypesCache instance.

Parameters:

Name Type Description Default
manifest_file str | Path | None

Path of the cache manifest; None uses AllenSDK's default location. Ignored when cache is given.

None
cache CellTypesCache | None

An existing cache, returned unchanged.

None

Returns:

Type Description
CellTypesCache

cache if provided, else a new CellTypesCache.

Raises:

Type Description
ImportError

If AllenSDK is not installed and no cache is given.

Source code in btorch/fitting/two_compartment/data.py
def get_cell_types_cache(
    manifest_file: str | Path | None = None,
    *,
    cache: CellTypesCache | None = None,
) -> CellTypesCache:
    """Create or reuse an AllenSDK ``CellTypesCache`` instance.

    Args:
        manifest_file: Path of the cache manifest; ``None`` uses AllenSDK's
            default location. Ignored when ``cache`` is given.
        cache: An existing cache, returned unchanged.

    Returns:
        ``cache`` if provided, else a new ``CellTypesCache``.

    Raises:
        ImportError: If AllenSDK is not installed and no ``cache`` is given.
    """
    if cache is not None:
        return cache
    CellTypesCache = _require_allensdk()
    if manifest_file is None:
        return CellTypesCache()
    return CellTypesCache(manifest_file=str(manifest_file))

load_allen_sweep(specimen_id, sweep_number, *, dt=0.5, manifest_file=None, cache=None, voltage_spike_threshold=0.0, voltage_scale=1000.0, current_scale=1000000000000.0)

Load one Allen ephys sweep and convert it to time-first torch tensors.

Notes

AllenSDK current-clamp sweeps are typically returned in SI units (volts and amps). The two-compartment neuron parameters in this module use biologically familiar millivolt-scale voltages and pA-scale input magnitudes, so the default conversion is volts -> mV and amps -> pA.

Source code in btorch/fitting/two_compartment/data.py
def load_allen_sweep(
    specimen_id: int,
    sweep_number: int,
    *,
    dt: float = 0.5,
    manifest_file: str | Path | None = None,
    cache: Any | None = None,
    voltage_spike_threshold: float = 0.0,
    voltage_scale: float = 1e3,
    current_scale: float = 1e12,
) -> AllenSweepBatch:
    """Load one Allen ephys sweep and convert it to time-first torch tensors.

    Notes:
        AllenSDK current-clamp sweeps are typically returned in SI units
        (volts and amps). The two-compartment neuron parameters in this module
        use biologically familiar millivolt-scale voltages and pA-scale input
        magnitudes, so the default conversion is volts -> mV and amps -> pA.
    """
    ctc = get_cell_types_cache(manifest_file, cache=cache)
    dataset = ctc.get_ephys_data(specimen_id)
    sweep = dataset.get_sweep(sweep_number)

    response = np.asarray(sweep["response"], dtype=np.float32)
    stimulus = np.asarray(sweep["stimulus"], dtype=np.float32)
    sampling_rate = float(sweep["sampling_rate"])
    index_start, index_stop = sweep["index_range"]
    sl = slice(int(index_start), int(index_stop) + 1)

    source_dt = 1000.0 / sampling_rate
    voltage = resample_trace(
        response[sl],
        source_dt=source_dt,
        target_dt=dt,
    )
    current = resample_trace(
        stimulus[sl],
        source_dt=source_dt,
        target_dt=dt,
    )
    voltage = voltage * float(voltage_scale)
    current = current * float(current_scale)
    spike_true = detect_spikes_from_voltage(
        voltage,
        threshold=voltage_spike_threshold,
    )

    return AllenSweepBatch(
        specimen_id=specimen_id,
        sweep_number=sweep_number,
        dt=dt,
        i_soma=current[:, None, None],
        v_true=voltage[:, None, None],
        spike_true=spike_true[:, None, None],
        i_apical=torch.zeros_like(current)[:, None, None],
        metadata={
            "sampling_rate_hz": sampling_rate,
            "voltage_scale": voltage_scale,
            "current_scale": current_scale,
        },
    )

mask_post_spike_voltage_samples(spike_true, *, refractory_bins=3)

Mask out voltage samples immediately after true spikes.

Source code in btorch/fitting/two_compartment/loss.py
def mask_post_spike_voltage_samples(
    spike_true: Tensor,
    *,
    refractory_bins: int = 3,
) -> Tensor:
    """Mask out voltage samples immediately after true spikes."""
    if refractory_bins < 0:
        raise ValueError(
            f"refractory_bins must be non-negative, got {refractory_bins}."
        )
    mask = torch.ones_like(spike_true, dtype=torch.bool)
    spike_idx = spike_true > 0
    for offset in range(refractory_bins + 1):
        if offset == 0:
            mask = mask & ~spike_idx
            continue
        shifted = torch.zeros_like(spike_idx)
        shifted[offset:] = spike_idx[:-offset]
        mask = mask & ~shifted
    return mask

plot_two_compartment_fit(evaluation, history=None, *, output_path)

Create a compact fit-quality figure with traces and loss history.

Source code in btorch/fitting/two_compartment/_plots.py
def plot_two_compartment_fit(
    evaluation: "FitEvaluation",
    history: Sequence[dict[str, float | str]] | None = None,
    *,
    output_path: str | Path,
) -> Path:
    """Create a compact fit-quality figure with traces and loss history."""
    output = Path(output_path)
    output.parent.mkdir(parents=True, exist_ok=True)

    fig, axes = plt.subplots(4, 1, figsize=(12, 10), sharex=False)
    time_ms = evaluation.traces["time_ms"]

    axes[0].plot(time_ms, evaluation.traces["i_soma"], color="tab:blue", lw=1.2)
    axes[0].set_ylabel("I soma")
    axes[0].set_title(
        f"Specimen {evaluation.specimen_id}, sweep {evaluation.sweep_number}"
    )

    axes[1].plot(time_ms, evaluation.traces["v_true"], label="Recorded", lw=1.5)
    axes[1].plot(time_ms, evaluation.traces["v_pred"], label="Predicted", lw=1.2)
    axes[1].set_ylabel("Voltage")
    axes[1].legend(loc="best")

    spike_true_t = evaluation.traces["spike_true"]
    spike_pred_t = evaluation.traces["spike_pred"]
    axes[2].eventplot(
        [time_ms[spike_true_t > 0.5], time_ms[spike_pred_t > 0.5]],
        lineoffsets=[1, 0],
        linelengths=0.8,
        colors=["tab:green", "tab:red"],
    )
    axes[2].set_yticks([0, 1], ["Pred", "True"])
    axes[2].set_ylabel("Spikes")

    if history:
        x = np.arange(len(history))
        axes[3].plot(x, [float(row["total_loss"]) for row in history], label="Total")
        axes[3].plot(
            x,
            [float(row["voltage_loss"]) for row in history],
            label="Voltage",
        )
        axes[3].plot(
            x,
            [float(row["spike_loss"]) for row in history],
            label="Spike",
        )
        axes[3].legend(loc="best")
        axes[3].set_xlabel("Optimization step")
    else:
        axes[3].axis("off")

    axes[3].set_ylabel("Loss")
    metrics_text = "\n".join(
        f"{name}: {value:.4f}" for name, value in evaluation.metrics.items()
    )
    fig.text(
        0.99,
        0.5,
        metrics_text,
        va="center",
        ha="right",
        fontsize=9,
        family="monospace",
    )
    fig.tight_layout(rect=(0.0, 0.0, 0.9, 1.0))
    fig.savefig(output, dpi=160)
    plt.close(fig)
    return output

query_mouse_visp_l5_pyramidal_cells(*, manifest_file=None, cache=None)

Query candidate mouse VISp layer-5 pyramidal cells from AllenSDK.

Source code in btorch/fitting/two_compartment/data.py
def query_mouse_visp_l5_pyramidal_cells(
    *,
    manifest_file: str | Path | None = None,
    cache: Any | None = None,
) -> list[dict[str, Any]]:
    """Query candidate mouse VISp layer-5 pyramidal cells from AllenSDK."""
    ctc = get_cell_types_cache(manifest_file, cache=cache)
    return filter_mouse_visp_l5_pyramidal_cells(ctc.get_cells())

resample_trace(trace, *, source_dt, target_dt)

Resample a 1D trace to a new timestep using linear interpolation.

Source code in btorch/fitting/two_compartment/data.py
def resample_trace(
    trace: np.ndarray | Tensor,
    *,
    source_dt: float,
    target_dt: float,
) -> Tensor:
    """Resample a 1D trace to a new timestep using linear interpolation."""
    if target_dt <= 0.0:
        raise ValueError(f"target_dt must be positive, got {target_dt}.")
    trace_t = torch.as_tensor(trace, dtype=torch.float32)
    if trace_t.ndim != 1:
        raise ValueError(f"Expected a 1D trace, got shape {tuple(trace_t.shape)}.")
    if abs(source_dt - target_dt) < 1e-12:
        return trace_t

    duration_ms = max((trace_t.shape[0] - 1) * source_dt, 0.0)
    target_steps = max(int(round(duration_ms / target_dt)) + 1, 1)
    source_time = torch.linspace(0.0, duration_ms, trace_t.shape[0])
    target_time = torch.linspace(0.0, duration_ms, target_steps)

    np_resampled = np.interp(
        target_time.cpu().numpy(),
        source_time.cpu().numpy(),
        trace_t.cpu().numpy(),
    )
    return torch.from_numpy(np_resampled).to(dtype=torch.float32)

rollout_two_compartment(model, i_soma, i_apical=None)

Run a time-first rollout and collect fitting-relevant traces.

Source code in btorch/fitting/two_compartment/evaluation.py
def rollout_two_compartment(
    model: TwoCompartmentModel,
    i_soma: Tensor,
    i_apical: Tensor | None = None,
) -> dict[str, Tensor]:
    """Run a time-first rollout and collect fitting-relevant traces."""
    spike, voltage, state = model.multi_step_forward(
        i_soma,
        i_apical,
        return_state=True,
    )
    return {
        "spike": spike,
        "v": voltage,
        "v_pre_spike": state["v_pre_spike"],
        "i_a": state["i_a"],
        "i_bap": state["i_bap"],
    }

save_fit_report(model, evaluations, aggregate_metrics, history, *, output_dir)

Save fitted parameters, metrics, history, and plots to disk.

Writes fitted_parameters.json (every named parameter, flattened), fit_metrics.json (aggregate plus per_sweep entries), fit_history.json and one PNG per evaluation.

Parameters:

Name Type Description Default
model Module

Fitted model; its named_parameters are serialised.

required
evaluations Sequence[FitEvaluation]

Per-sweep evaluations to plot and record.

required
aggregate_metrics dict[str, float]

Metrics averaged over sweeps.

required
history Sequence[dict[str, float | str]]

Rows returned by fit_two_compartment_model.

required
output_dir str | Path

Directory (created if missing).

required

Returns:

Type Description
dict[str, Path]

Dict with output_dir, parameters, metrics, history

dict[str, Path]

(JSON paths), plot (the last evaluation's figure) and

dict[str, Path]

primary_plot (the first evaluation with recorded spikes, else the

dict[str, Path]

last figure). Both plot entries fall back to output_dir when

dict[str, Path]

evaluations is empty.

Source code in btorch/fitting/two_compartment/report.py
def save_fit_report(
    model: torch.nn.Module,
    evaluations: Sequence[FitEvaluation],
    aggregate_metrics: dict[str, float],
    history: Sequence[dict[str, float | str]],
    *,
    output_dir: str | Path,
) -> dict[str, Path]:
    """Save fitted parameters, metrics, history, and plots to disk.

    Writes ``fitted_parameters.json`` (every named parameter, flattened),
    ``fit_metrics.json`` (``aggregate`` plus ``per_sweep`` entries),
    ``fit_history.json`` and one PNG per evaluation.

    Args:
        model: Fitted model; its ``named_parameters`` are serialised.
        evaluations: Per-sweep evaluations to plot and record.
        aggregate_metrics: Metrics averaged over sweeps.
        history: Rows returned by ``fit_two_compartment_model``.
        output_dir: Directory (created if missing).

    Returns:
        Dict with ``output_dir``, ``parameters``, ``metrics``, ``history``
        (JSON paths), ``plot`` (the last evaluation's figure) and
        ``primary_plot`` (the first evaluation with recorded spikes, else the
        last figure). Both plot entries fall back to ``output_dir`` when
        ``evaluations`` is empty.
    """
    out_dir = Path(output_dir)
    out_dir.mkdir(parents=True, exist_ok=True)

    parameter_payload = {
        name: param.detach().cpu().reshape(-1).tolist()
        for name, param in model.named_parameters()
    }
    metrics_payload = {
        "aggregate": aggregate_metrics,
        "per_sweep": [
            {
                "specimen_id": ev.specimen_id,
                "sweep_number": ev.sweep_number,
                "dt_ms": ev.dt,
                "metrics": ev.metrics,
            }
            for ev in evaluations
        ],
    }

    parameters_path = out_dir / "fitted_parameters.json"
    metrics_path = out_dir / "fit_metrics.json"
    history_path = out_dir / "fit_history.json"
    with parameters_path.open("w", encoding="utf-8") as f:
        json.dump(parameter_payload, f, indent=2)
    with metrics_path.open("w", encoding="utf-8") as f:
        json.dump(metrics_payload, f, indent=2)
    with history_path.open("w", encoding="utf-8") as f:
        json.dump(list(history), f, indent=2)

    last_plot = None
    primary_plot = None
    for index, evaluation in enumerate(evaluations):
        plot_path = out_dir / (
            f"fit_specimen_{evaluation.specimen_id}_"
            f"sweep_{evaluation.sweep_number}_{index}.png"
        )
        last_plot = plot_two_compartment_fit(
            evaluation,
            history=history,
            output_path=plot_path,
        )
        if (
            primary_plot is None
            and evaluation.metrics.get("spike_count_true", 0.0) > 0.0
        ):
            primary_plot = last_plot

    if primary_plot is None:
        primary_plot = last_plot

    return {
        "output_dir": out_dir,
        "parameters": parameters_path,
        "metrics": metrics_path,
        "history": history_path,
        "primary_plot": primary_plot if primary_plot is not None else out_dir,
        "plot": last_plot if last_plot is not None else out_dir,
    }

spike_timing_loss(spike_true, spike_pred, *, dt, match_window_ms=10.0, miss_penalty_ms=None)

Compute a hard event-based spike-timing loss for global optimization.

Source code in btorch/fitting/two_compartment/loss.py
def spike_timing_loss(
    spike_true: Tensor,
    spike_pred: Tensor,
    *,
    dt: float,
    match_window_ms: float = 10.0,
    miss_penalty_ms: float | None = None,
) -> Tensor:
    """Compute a hard event-based spike-timing loss for global optimization."""
    penalty_ms = float(match_window_ms if miss_penalty_ms is None else miss_penalty_ms)
    stats = spike_timing_stats(
        spike_true,
        spike_pred,
        dt=dt,
        match_window_ms=match_window_ms,
    )
    matched = stats["matched_spikes"]
    false_positive = stats["false_positive_spikes"]
    false_negative = stats["false_negative_spikes"]
    total_events = max(matched + false_positive + false_negative, 1.0)
    total_error_ms = matched * stats["mean_timing_error_ms"] + penalty_ms * (
        false_positive + false_negative
    )
    return torch.as_tensor(
        total_error_ms / total_events,
        dtype=spike_pred.dtype,
        device=spike_pred.device,
    )

spike_timing_stats(spike_true, spike_pred, *, dt, match_window_ms=10.0)

Match predicted and true spikes using a tolerance-window cost.

Source code in btorch/fitting/two_compartment/loss.py
def spike_timing_stats(
    spike_true: Tensor,
    spike_pred: Tensor,
    *,
    dt: float,
    match_window_ms: float = 10.0,
) -> dict[str, float]:
    """Match predicted and true spikes using a tolerance-window cost."""
    if match_window_ms <= 0.0:
        raise ValueError(f"match_window_ms must be positive, got {match_window_ms}.")

    true_idx = _extract_spike_indices(spike_true)
    pred_idx = _extract_spike_indices(spike_pred)
    true_count = int(true_idx.size)
    pred_count = int(pred_idx.size)

    if true_count == 0 and pred_count == 0:
        return {
            "matched_spikes": 0.0,
            "false_positive_spikes": 0.0,
            "false_negative_spikes": 0.0,
            "precision": 1.0,
            "recall": 1.0,
            "timing_f1": 1.0,
            "mean_timing_error_ms": 0.0,
            "matched_fraction": 1.0,
        }

    if true_count == 0:
        return {
            "matched_spikes": 0.0,
            "false_positive_spikes": float(pred_count),
            "false_negative_spikes": 0.0,
            "precision": 0.0,
            "recall": 1.0,
            "timing_f1": 0.0,
            "mean_timing_error_ms": float(match_window_ms),
            "matched_fraction": 0.0,
        }

    if pred_count == 0:
        return {
            "matched_spikes": 0.0,
            "false_positive_spikes": 0.0,
            "false_negative_spikes": float(true_count),
            "precision": 1.0,
            "recall": 0.0,
            "timing_f1": 0.0,
            "mean_timing_error_ms": float(match_window_ms),
            "matched_fraction": 0.0,
        }

    distance_ms = np.abs(true_idx[:, None] - pred_idx[None, :]).astype(np.float64) * dt
    row_ind, col_ind = linear_sum_assignment(distance_ms)
    matched_distance = distance_ms[row_ind, col_ind]
    within_window = matched_distance <= match_window_ms
    matched_distance = matched_distance[within_window]
    matched_spikes = int(matched_distance.size)
    false_positive = pred_count - matched_spikes
    false_negative = true_count - matched_spikes
    precision = matched_spikes / max(pred_count, 1)
    recall = matched_spikes / max(true_count, 1)
    if precision + recall == 0.0:
        timing_f1 = 0.0
    else:
        timing_f1 = 2.0 * precision * recall / (precision + recall)

    mean_timing_error_ms = (
        float(matched_distance.mean()) if matched_spikes > 0 else float(match_window_ms)
    )
    return {
        "matched_spikes": float(matched_spikes),
        "false_positive_spikes": float(false_positive),
        "false_negative_spikes": float(false_negative),
        "precision": float(precision),
        "recall": float(recall),
        "timing_f1": float(timing_f1),
        "mean_timing_error_ms": mean_timing_error_ms,
        "matched_fraction": matched_spikes / max(true_count, 1),
    }

two_compartment_loss(*, v_pred, spike_pred, v_true, spike_true, dt, w_Ca=None, loss=None)

Compute a composite fitting loss for the two-compartment model.

Parameters:

Name Type Description Default
v_pred Tensor

Predicted voltage, shape [T, B, N].

required
spike_pred Tensor

Predicted spikes, shape [T, B, N].

required
v_true Tensor

Recorded voltage, same shape as v_pred.

required
spike_true Tensor

Recorded spikes, same shape as spike_pred.

required
dt float

Simulation step in ms.

required
w_Ca Tensor | None

Optional calcium-coupling weights for the sparsity penalty.

None
loss FitLossConfig | None

Loss weights and spike-matching settings. None uses the :class:FitLossConfig defaults.

None

Returns:

Type Description
dict[str, Tensor]

Dict with the weighted "total" and the unweighted components

dict[str, Tensor]

"voltage", "spike", "spike_count", "spike_timing" and

dict[str, Tensor]

"sparsity".

Raises:

Type Description
ValueError

If the spike-count over/under weights are not positive.

Source code in btorch/fitting/two_compartment/loss.py
def two_compartment_loss(
    *,
    v_pred: Tensor,
    spike_pred: Tensor,
    v_true: Tensor,
    spike_true: Tensor,
    dt: float,
    w_Ca: Tensor | None = None,
    loss: FitLossConfig | None = None,
) -> dict[str, Tensor]:
    """Compute a composite fitting loss for the two-compartment model.

    Args:
        v_pred: Predicted voltage, shape ``[T, B, N]``.
        spike_pred: Predicted spikes, shape ``[T, B, N]``.
        v_true: Recorded voltage, same shape as ``v_pred``.
        spike_true: Recorded spikes, same shape as ``spike_pred``.
        dt: Simulation step in ms.
        w_Ca: Optional calcium-coupling weights for the sparsity penalty.
        loss: Loss weights and spike-matching settings. ``None`` uses the
            :class:`FitLossConfig` defaults.

    Returns:
        Dict with the weighted ``"total"`` and the unweighted components
        ``"voltage"``, ``"spike"``, ``"spike_count"``, ``"spike_timing"`` and
        ``"sparsity"``.

    Raises:
        ValueError: If the spike-count over/under weights are not positive.
    """
    c = FitLossConfig() if loss is None else loss
    refractory_bins = int(round(c.post_spike_mask_ms / dt))
    mask = mask_post_spike_voltage_samples(
        spike_true,
        refractory_bins=refractory_bins,
    )

    if mask.any():
        voltage_loss = F.mse_loss(v_pred[mask], v_true[mask])
    else:
        voltage_loss = torch.zeros((), device=v_pred.device, dtype=v_pred.dtype)

    spike_pred_smooth = exponential_filter_spike_train(
        spike_pred,
        tau_ms=c.spike_tau_ms,
        dt=dt,
    )
    spike_true_smooth = exponential_filter_spike_train(
        spike_true,
        tau_ms=c.spike_tau_ms,
        dt=dt,
    )
    spike_loss = F.smooth_l1_loss(spike_pred_smooth, spike_true_smooth)
    spike_count_pred = (spike_pred > 0.5).to(spike_pred.dtype).sum(dim=0)
    spike_count_true = spike_true.sum(dim=0)
    if c.spike_count_over_weight <= 0.0 or c.spike_count_under_weight <= 0.0:
        raise ValueError("Spike-count over/under weights must be positive.")
    spike_count_over = torch.relu(spike_count_pred - spike_count_true)
    spike_count_under = torch.relu(spike_count_true - spike_count_pred)
    spike_count_loss = (
        c.spike_count_over_weight * spike_count_over.square()
        + c.spike_count_under_weight * spike_count_under.square()
    ).mean()
    spike_timing_event_loss = spike_timing_loss(
        spike_true,
        spike_pred,
        dt=dt,
        match_window_ms=c.spike_match_window_ms,
        miss_penalty_ms=c.spike_miss_penalty_ms,
    )

    if w_Ca is None:
        sparsity_loss = torch.zeros((), device=v_pred.device, dtype=v_pred.dtype)
    else:
        sparsity_loss = w_Ca.abs().mean()

    total = (
        c.voltage_weight * voltage_loss
        + c.spike_weight * spike_loss
        + c.spike_count_weight * spike_count_loss
        + c.spike_timing_weight * spike_timing_event_loss
        + c.sparsity_weight * sparsity_loss
    )
    return {
        "total": total,
        "voltage": voltage_loss,
        "spike": spike_loss,
        "spike_count": spike_count_loss,
        "spike_timing": spike_timing_event_loss,
        "sparsity": sparsity_loss,
    }