Migrating to braintools 1.0

Migrating to braintools 1.0#

Since 0.4, every function that moved has a new home in braintools, and the old names still work as deprecated aliases. Braintools 1.0.0 removes all of them, together with the deprecated arguments listed below. This page lists every deprecation and its replacement, so code can be updated before the upgrade.

Finding deprecated calls in your code#

A deprecated name warns when it is called (or a deprecated class is instantiated), never when it is imported. The warning category is braintools._deprecation.BraintoolsDeprecationWarning, and every message has the same form:

`braintools.metric.firing_rate` is deprecated since 0.4.0 and will be removed in 1.0.0. Use `braintools.analysis.spike.firing_rate` instead.

Since 0.4, BraintoolsDeprecationWarning is a subclass of FutureWarning (it used to subclass DeprecationWarning). Python shows FutureWarning by default, so the warnings now appear even when the deprecated call is made from library code rather than from your script. Filters written for DeprecationWarning no longer match them.

To turn every braintools deprecation into an error, so that each remaining call site fails loudly:

python -W error::FutureWarning my_script.py

or, from Python (for example in a test suite’s conftest.py):

import warnings
from braintools._deprecation import BraintoolsDeprecationWarning

warnings.simplefilter('error', BraintoolsDeprecationWarning)

With pytest, add a filter to pyproject.toml:

[tool.pytest.ini_options]
filterwarnings = [
    'error:`braintools\.[^`]*` is deprecated since:FutureWarning',
]

To silence them instead (for example in a downstream package that has not migrated yet), use warnings.filterwarnings('ignore', category=BraintoolsDeprecationWarning).

Every deprecation#

The table lists every deprecation registered in braintools. A function or class entry is an alias of the replacement. An argument entry is a deprecated argument or argument value of a function that stays. A feature entry is an object that is deprecated without a direct replacement.

Deprecated

Replacement

Kind

Since

Removed in

braintools.BernoulliEncoder

braintools.spike.BernoulliEncoder

class

0.4.0

1.0.0

braintools.cogtask.utils.firing_rate

braintools.cogtask.utils.rate_to_prob

function

0.4.0

1.0.0

braintools.conn.MorphologyDistance(decay_function=str)

pass a braintools.init.*Profile instance

argument

0.4.0

1.0.0

braintools.DeltaEncoder

braintools.spike.DeltaEncoder

class

0.4.0

1.0.0

braintools.file.load_matfile(header_info=...)

braintools.file.load_matfile(include_header=not header_info)

argument

0.2.0

1.0.0

braintools.init.Beta(unit=...)

braintools.init.Beta(...) with the unit attached to the value arguments

argument

0.1.0

1.0.0

braintools.init.Constant(unit=...)

braintools.init.Constant(...) with the unit attached to the value arguments

argument

0.1.0

1.0.0

braintools.init.DeltaOrthogonal(unit=...)

braintools.init.DeltaOrthogonal(...)(size) * unit

argument

0.1.0

1.0.0

braintools.init.Exponential(unit=...)

braintools.init.Exponential(...) with the unit attached to the value arguments

argument

0.1.0

1.0.0

braintools.init.Gamma(unit=...)

braintools.init.Gamma(...) with the unit attached to the value arguments

argument

0.1.0

1.0.0

braintools.init.LogNormal(unit=...)

braintools.init.LogNormal(...) with the unit attached to the value arguments

argument

0.1.0

1.0.0

braintools.init.Normal(unit=...)

braintools.init.Normal(...) with the unit attached to the value arguments

argument

0.1.0

1.0.0

braintools.init.Orthogonal(unit=...)

braintools.init.Orthogonal(...)(size) * unit

argument

0.1.0

1.0.0

braintools.init.TruncatedNormal(unit=...)

braintools.init.TruncatedNormal(...) with the unit attached to the value arguments

argument

0.1.0

1.0.0

braintools.init.Uniform(unit=...)

braintools.init.Uniform(...) with the unit attached to the value arguments

argument

0.1.0

1.0.0

braintools.init.Weibull(unit=...)

braintools.init.Weibull(...) with the unit attached to the value arguments

argument

0.1.0

1.0.0

braintools.LatencyEncoder

braintools.spike.LatencyEncoder

class

0.4.0

1.0.0

braintools.metric.burst_synchrony_index

braintools.analysis.spike.burst_synchrony_index

function

0.4.0

1.0.0

braintools.metric.coherence_analysis

braintools.analysis.spectral.coherence_analysis

function

0.4.0

1.0.0

braintools.metric.correlation_index

braintools.analysis.spike.correlation_index

function

0.4.0

1.0.0

braintools.metric.cross_correlation

braintools.analysis.spike.cross_correlation

function

0.4.0

1.0.0

braintools.metric.current_source_density

braintools.analysis.field.current_source_density

function

0.4.0

1.0.0

braintools.metric.firing_rate

braintools.analysis.spike.firing_rate

function

0.4.0

1.0.0

braintools.metric.functional_connectivity

braintools.analysis.population.functional_connectivity

function

0.4.0

1.0.0

braintools.metric.functional_connectivity_dynamics

braintools.analysis.population.functional_connectivity_dynamics

function

0.4.0

1.0.0

braintools.metric.lfp_phase_coherence

braintools.analysis.spectral.lfp_phase_coherence

function

0.4.0

1.0.0

braintools.metric.matrix_correlation

braintools.analysis.stats.matrix_correlation

function

0.4.0

1.0.0

braintools.metric.phase_amplitude_coupling

braintools.analysis.spectral.phase_amplitude_coupling

function

0.4.0

1.0.0

braintools.metric.phase_locking_value

braintools.analysis.spike.phase_locking_value

function

0.4.0

1.0.0

braintools.metric.power_spectral_density

braintools.analysis.spectral.power_spectral_density

function

0.4.0

1.0.0

braintools.metric.raster_plot

braintools.spike.SpikeTrains.from_dense

function

0.4.0

1.0.0

braintools.metric.spectral_entropy

braintools.analysis.spectral.spectral_entropy

function

0.4.0

1.0.0

braintools.metric.spike_time_tiling_coefficient

braintools.analysis.spike.spike_time_tiling_coefficient

function

0.4.0

1.0.0

braintools.metric.spike_train_synchrony

braintools.analysis.spike.spike_train_synchrony

function

0.4.0

1.0.0

braintools.metric.theta_gamma_coupling

braintools.analysis.spectral.theta_gamma_coupling

function

0.4.0

1.0.0

braintools.metric.unitary_LFP

braintools.analysis.field.unitary_LFP

function

0.4.0

1.0.0

braintools.metric.van_rossum_distance

braintools.analysis.spike.van_rossum_distance

function

0.4.0

1.0.0

braintools.metric.victor_purpura_distance

braintools.analysis.spike.victor_purpura_distance

function

0.4.0

1.0.0

braintools.metric.voltage_fluctuation

braintools.analysis.population.voltage_fluctuation

function

0.4.0

1.0.0

braintools.metric.weighted_correlation

braintools.analysis.stats.weighted_correlation

function

0.4.0

1.0.0

braintools.optim.Adam(beta1=...)

braintools.optim.Adam(betas=(beta1, beta2))

argument

0.1.0

1.0.0

braintools.optim.Adam(beta2=...)

braintools.optim.Adam(betas=(beta1, beta2))

argument

0.1.0

1.0.0

braintools.PoissonEncoder

braintools.spike.PoissonEncoder

class

0.4.0

1.0.0

braintools.PopulationEncoder

braintools.spike.PopulationEncoder

class

0.4.0

1.0.0

braintools.RankOrderEncoder

braintools.spike.RankOrderEncoder

class

0.4.0

1.0.0

braintools.RateEncoder

braintools.spike.RateEncoder

class

0.4.0

1.0.0

braintools.spike.PoissonEncoder(time_window=...)

braintools.spike.PoissonEncoder() without time_window (it has no effect)

argument

0.4.0

1.0.0

braintools.SpikeCountEncoder

braintools.spike.SpikeCountEncoder

class

0.4.0

1.0.0

braintools.StepCurrentEncoder

braintools.spike.StepCurrentEncoder

class

0.4.0

1.0.0

braintools.TemporalEncoder

braintools.spike.TemporalEncoder

class

0.4.0

1.0.0

braintools.trainer.GradientClipCallback

Trainer(gradient_clip_val=...)

feature

0.4.0

1.0.0

braintools.trainer.Trainer(benchmark=...)

the default (XLA autotunes automatically)

argument

0.4.0

1.0.0

braintools.trainer.Trainer(deterministic=...)

Trainer(seed=...)

argument

0.4.0

1.0.0

braintools.trainer.Trainer(precision=...)

explicit dtype casts of the model and data

argument

0.4.0

1.0.0

braintools.trainer.Trainer(strategy=...)

the default strategy='auto'

argument

0.4.0

1.0.0

The top-level braintools.spike_bitwise* names are also kept as aliases of braintools.spike.bitwise*. They do not warn yet, because other packages in the ecosystem bind them at import time, but new code should use braintools.spike.bitwise_or and the other braintools.spike.bitwise* names.

braintools.metric → braintools.analysis#

The measures for analysing neural activity moved out of braintools.metric into the subpackages of braintools.analysis. The functions themselves are unchanged: same arguments, same results. Only the import path changes.

Old (braintools.metric.*)

New

firing_rate, victor_purpura_distance, van_rossum_distance, spike_train_synchrony, burst_synchrony_index, phase_locking_value, spike_time_tiling_coefficient, correlation_index, cross_correlation

braintools.analysis.spike

power_spectral_density, coherence_analysis, phase_amplitude_coupling, theta_gamma_coupling, spectral_entropy, lfp_phase_coherence

braintools.analysis.spectral

unitary_LFP, current_source_density

braintools.analysis.field

voltage_fluctuation, functional_connectivity, functional_connectivity_dynamics

braintools.analysis.population

matrix_correlation, weighted_correlation

braintools.analysis.stats

 
# Before
rate = braintools.metric.firing_rate(spikes, width=5.0)

# After
rate = braintools.analysis.spike.firing_rate(spikes, width=5.0)

braintools.metric.raster_plot(sp_matrix, times) has no one-to-one replacement. Use braintools.spike.SpikeTrains.from_dense to hold the spikes, or compute the same arrays directly:

t, i = numpy.nonzero(sp_matrix > 0)
neuron_indices, spike_times = i, times[t]  # == metric.raster_plot(sp_matrix, times)

Plotting a raster is braintools.visualize.raster_plot, which is not deprecated.

The training losses and metrics (cross-entropy, regression losses, ranking losses, cosine_similarity and the rest) stay in braintools.metric.

Top-level encoders → braintools.spike#

The ten spike encoders moved from the top level to braintools.spike: LatencyEncoder, RateEncoder, PoissonEncoder, PopulationEncoder, BernoulliEncoder, DeltaEncoder, StepCurrentEncoder, SpikeCountEncoder, TemporalEncoder and RankOrderEncoder.

# Before
encoder = braintools.PoissonEncoder()

# After
encoder = braintools.spike.PoissonEncoder()

Instances built either way pass isinstance checks against both names. The time_window argument of PoissonEncoder never had an effect and is deprecated; drop it.

braintools.trainer is frozen#

Since 0.4, braintools.trainer gets maintenance fixes only, with no new features. Features that never did anything are deprecated:

  • GradientClipCallback never clipped gradients. Use Trainer(gradient_clip_val=...).

  • Trainer(precision=...) other than 32: cast the model and data to the dtype you want instead.

  • Trainer(deterministic=...): pass Trainer(seed=...).

  • Trainer(benchmark=...): drop it; XLA autotunes automatically.

  • Trainer(strategy=...) other than 'auto': drop it.

conn.MorphologyDistance(decay_function=str) → distance profiles#

MorphologyDistance took the decay function as a string. Pass a braintools.init distance profile instead; it carries its own length scale, so sigma is omitted.

Old

New

decay_function='gaussian', sigma=s

decay_function=braintools.init.GaussianProfile(s) (or the default, decay_function=None, sigma=s)

decay_function='exponential', sigma=s

decay_function=braintools.init.ExponentialProfile(s)

decay_function='linear', sigma=s

decay_function=braintools.init.LinearProfile(s)

cogtask.utils.firing_rate → rate_to_prob#

braintools.cogtask.utils.firing_rate(base, dt) converts a rate in Hz to a spike probability per time step (base * dt / 1000), not a firing rate. It is renamed braintools.cogtask.utils.rate_to_prob, with the same arguments and result, so it is no longer confused with braintools.analysis.spike.firing_rate.

Deprecated unit= arguments and load_matfile(header_info=...)#

  • The unit= argument of Constant, Uniform, Normal, LogNormal, Gamma, Exponential, TruncatedNormal, Beta and Weibull in braintools.init is deprecated: attach the unit to the values instead, for example Normal(0.0 * u.mV, 1.0 * u.mV) rather than Normal(0.0, 1.0, unit=u.mV). ZeroInit(unit=...) is not deprecated.

  • Orthogonal(unit=...) and DeltaOrthogonal(unit=...) are deprecated: multiply the generated weights by the unit.

  • braintools.file.load_matfile(header_info=...) meant the inverse of its name. Use include_header=not header_info.

Before 0.4 these warned with a plain DeprecationWarning. They now use BraintoolsDeprecationWarning like every other deprecation.