Skip to main content

alignment.EphysOnlyLocalizer

alignment.EphysOnlyLocalizer(
    channel_model,
    brain_atlas,
    *,
    fit_dir=None,
    n_restarts=10,
    seed=0,
    progress=None,
    **overrides,
)

Localize probes without histology (see the module doc for the method).

Args: channel_model: :class:~ephysatlas.alignment.models.ChannelModel. brain_atlas: iblatlas.atlas.AllenAtlas. fit_dir: Where the fitted parameters and the lattice predictions are cached; default ~/ephys-atlas/results/alignment/ephys_only_fit/<model_commit>. Fitted with :meth:fit when absent (needs the feature release, i.e. ONE credentials). n_restarts: Annealing restarts from the planned trajectory. seed: Base seed of the restarts’ random streams (restart r uses seed + 1000003 r). progress: progress(fraction, message) callback for the first use, when the lattice predictions are computed and the fit runs. **overrides: Any field of :class:ScoreConfig or :class:AnnealConfig, e.g. temperature_T=20.

Attributes

Name Description
T The likelihood temperature in use (the override, else the tuned value).

Methods

Name Description
bin_likelihood_maps Each depth bin’s Student-t likelihood term over the lattice (no prior, before the 1/T).
fit Fit the residual model and plan prior on the TRAIN probes, kappa and the temperature
lattice_for [V, F] whitened lattice predictions for pid: the cached lattice, with the voxels
localize Localize one probe from its recording and planned trajectory.
loo_voxels Lattice voxels whose model neighbourhood can include pid’s bank channels.
set_params Use fitted parameters: mu_r, W, nu, kappa, prior and T.

bin_likelihood_maps

alignment.EphysOnlyLocalizer.bin_likelihood_maps(features, *, pid='')

Each depth bin’s Student-t likelihood term over the lattice (no prior, before the 1/T).

Args: features: [C, F] recorded channel features, as for :meth:localize. pid: Insertion id (a training probe gets its leave-probe-out lattice).

Returns: tuple: (grid_xyz_m [V, 3], nll [B, V]): the lattice voxels (m, left hemisphere) and t_b(v) = (nu + F)/2 log(1 + |W (x_b - mu_r) - W G_v|^2 / (nu - 2)) for every bin b (top first, see diagnostics["bin_centre_um"] of a result) and voxel v.

fit

alignment.EphysOnlyLocalizer.fit(dataset=None, progress=None)

Fit the residual model and plan prior on the TRAIN probes, kappa and the temperature on the VALIDATION probes; write them to fit_dir (see :mod:.ephys_only_fit).

Args: dataset: :class:~ephysatlas.alignment.data.ChannelDataset (loaded when None). progress: progress(fraction, message) callback.

Returns: dict: The fit summary (also fit_dir/fit_summary.json).

lattice_for

alignment.EphysOnlyLocalizer.lattice_for(pid)

[V, F] whitened lattice predictions for pid: the cached lattice, with the voxels near a training probe’s own bank channels re-predicted without that probe.

localize

alignment.EphysOnlyLocalizer.localize(
    features,
    planned_xyz,
    *,
    pid='',
    progress=None,
    record_history=False,
)

Localize one probe from its recording and planned trajectory.

Args: features: [C, F] recorded channel features, feature units, the channel model’s feature order, row order (top first). planned_xyz: [C, 3] planned channel positions (m), row order. pid: Insertion id. A training probe of the model’s neighbour bank is localized on a leave-probe-out lattice (voxels near its own bank channels re-predicted without it). progress: progress(fraction, message) callback. record_history: Also keep snapshots of every annealing restart (every HISTORY_EVERY iterations and the last one).

Returns: AlignmentResult: method="ephys_only"; trace_xyz the inferred bin trajectory [B, 3] (39 points for a full probe), channel_xyz every channel along it (those beyond the first / last bin centre extrapolated along the trajectory), both in the planned trajectory’s hemisphere. diagnostics arrays:

- ``candidate_score`` / ``candidate_distance_um`` / ``candidate_stage`` ``[n]``: every
  trajectory the search scored (score ``c_p S``; mean pointwise distance to the result,
  µm; restart index, -1 for the planned seed), at most 5000;
- ``restart_score`` / ``restart_iterations`` ``[n_restarts]``;
- ``init_xyz`` ``[B, 3]``: the planned seed trajectory (m, left hemisphere);
- ``bin_centre_um`` ``[B]`` (µm below the top channel) and ``bin_channel_index`` ``[C]``
  (bin of each channel row, -1 when in none);
- with ``record_history``: ``history_restart``, ``history_iteration``,
  ``history_temperature``, ``history_score`` (current), ``history_best_score`` ``[H]``
  and ``history_best_xyz`` ``[H, B, 3]`` (best-so-far trajectory, m, left hemisphere);

and scalars ``score``, ``temperature_T``, ``c_p``, ``scale_K``, ``mad_S``,
``n_restarts``, ``best_restart``, ``likelihood_over_T``, ``likelihood_sum``,
``outside_penalty``, ``prior``, ``planned_score``, ``n_bins``, ``nu``,
``plan_degenerate``, ``plan_span_um``, ``plan_hemisphere``, ``theta_deg``,
``phi_deg``, ``length_um``.

Raises: PlannedTrajectoryUnavailable: If the plan is a placeholder or spans < 100 µm.

loo_voxels

alignment.EphysOnlyLocalizer.loo_voxels(pid)

Lattice voxels whose model neighbourhood can include pid’s bank channels.

set_params

alignment.EphysOnlyLocalizer.set_params(params)

Use fitted parameters: mu_r, W, nu, kappa, prior and T.