brian2modelfitting.inferencer module

class brian2modelfitting.inferencer.Inferencer(dt, model, input, output, features=None, method=None, threshold=None, reset=None, refractory=False, param_init=None)

Bases: object

Class for a simulation-based inference.

It offers an interface similar to that of the Fitter class but instead of fitting, a neural density estimator is trained using a generative model which ultimately provides the posterior distribution over unknown free parameters.

To utilize simulation-based inference, this class uses a sbi library, for details see Tejero-Cantero 2020.

Parameters:

• dt (brian2.units.fundamentalunits.Quantity) – Integration time step.
• model (str or brian2.equations.equations.Equations) – Single cell model equations.
• input (dict) – Input traces in the dictionary format where key corresponds to the name of the input variable as defined in model, and value corresponds to an array of input traces.
• output (dict) – Dictionary of recorded (or simulated) output data traces, where key corresponds to the name of the output variable as defined in model, and value corresponds to an array of recorded traces.
• features (dict, optional) – Dictionary of callables that take a 1-dimensional voltage trace or a spike train and output summary statistics. Keys correspond to output variable names, while values are lists of callables. If features are set to None, automatic feature extraction process will occur instead either by using the default multi-layer perceptron or by using the custom embedding network.
• method (str, optional) – Integration method.
• threshold (str, optional) – The condition which produces spikes. It should be a single line boolean expression.
• reset (str, optional) – The (possibly multi-line) string with the code to execute on reset.
• refractory (bool or str, optional) – Either the length of the refractory period (e.g., 2*ms), a string expression that evaluates to the length of the refractory period after each spike, e.g., '(1 + rand())*ms', or a string expression evaluating to a boolean value, given the condition under which the neuron stays refractory after a spike, e.g., 'v > -20*mV'.
• param_init (dict, optional) – Dictionary of state variables to be initialized with respective values, i.e., initial conditions for the model.

References

• Tejero-Cantero, A., Boelts, J. et al. “sbi: A toolkit for simulation-based inference” Journal of Open Source Software (JOOS), 5(52):2505. 2020.

build_posterior(inference, **posterior_kwargs)

Return the updated inference and the neural posterior objects.

Parameters:

• inference (sbi.inference.NeuralInference) – Instantiated inference object with stored paramaters and simulation outputs.
• posterior_kwargs (dict, optional) – Additional keyword arguments for build_posterior method in all sbi.inference.NeuralInference-type classes. For details, check the official sbi documentation.

Returns:

sbi.inference.NeuralInference object with stored paramaters and simulation outputs prepared for training and the neural posterior object.

Return type:

tuple

conditional_corrcoeff(condition, density=None, limits=None, subset=None, **kwargs)

Return the conditional correlation matrix of a distribution.

All but two parameters are conditioned with the condition as defined in the condition argument and the Pearson correlation coefficient is computed between the remaining two parameters under the distribution. This is performed for all pairs of parameters given whose names are defined in the subset argument. The conditional correlation matrix is stored in the 2-dimenstional array.

Check sbi.analysis.conditional_density.conditional_corrcoeff for more details.

Parameters:

• condition (numpy.ndarray) – Condition that all but the one/two regarded parameters are fixed to.
• density (neural posterior object, optional) – Posterior probability density.
• limits (dict, optional) – Limits for each parameter. Keys correspond to parameter names as defined in the model, while values are lists with limits defined as the Brian 2 quantity objects. If None, min and max of the given samples will be used.
• subset (list, optional) – Parameters that are taken for conditional distribution, if None all parameters are considered.
• kwargs (dict, optional) – Additional keyword arguments for the sbi.analysis.conditional_corrcoeff function.

Returns:

Average conditional correlation matrix.

Return type:

numpy.ndarray

conditional_pairplot(condition, density=None, points=None, limits=None, subset=None, labels=None, ticks=None, **kwargs)

Plot conditional distribution given all other parameters.

The conditionals can be interpreted as slices through the density at a location given by condition.

Check sbi.analysis.conditional_pairplot for more details.

Parameters:

• condition (numpy.ndarray) – Condition that all but the one/two regarded parameters are fixed to.
• density (neural posterior object, optional) – Posterior probability density.
• points (dict, optional) – Additional points to scatter, e.g., true parameter values, if known.
• limits (dict, optional) – Limits for each parameter. Keys correspond to parameter names as defined in the model, while values are lists with limits defined as the Brian 2 quantity objects. If None, min and max of the given samples will be used.
• subset (list, optional) – The names as strings of parameters to plot.
• labels (dict, optional) – Names for each parameter. Keys correspond to parameter names as defined in the model, while values are lists of strings.
• ticks (dict, optional) – Position of the ticks. Keys correspond to parameter names as defined in the model, while values are lists with ticks defined as the Brian 2 quantity objects. If None, default ticks positions will be used.
• kwargs (dict, optional) – Additional keyword arguments for the sbi.analysis.conditional_pairplot function.

Returns:

Figure and axis of conditional pairplot.

Return type:

tuple

extract_summary_statistics(theta, level=0)

Return the summary statistics for the process of training of the neural density estimator.

Parameters:

• theta (numpy.ndarray) – Sampled prior with n_samples rows, and the number of columns corresponds to the number of free parameters.
• level (int, optional) – How far to go back to get the locals/globals.

Returns:

Summary statistics.

Return type:

numpy.ndarray

generate_traces(n_samples=1, posterior=None, output_var=None, param_init=None, level=0)

Generates traces for a single drawn sample from the trained posterior and all inputs.

Parameters:

• n_samples (int, optional) – The number of parameters samples. If n_samples is larger than 1, the mean value of sampled set will be used.
• posterior (neural posterior object, optional) – Posterior distribution.
• output_var (str or list) – Name of the output variable to be monitored, it can also be a list of names to record multiple variables.
• param_init (dict) – Dictionary of initial values for the model.
• level (int, optional) – How far to go back to get the locals/globals.

Returns:

If a single output variable is observed, 2-dimensional array of traces generated by using a set of parameters sampled from the trained posterior distribution of shape (self.n_traces, number of time steps). Otherwise, a dictionary with keys set to names of output variables, and values to generated traces of respective output variables.

Return type:

brian2.units.fundamentalunits.Quantity or dict

generate_training_data(n_samples, prior)

Return sampled prior given the total number of samples.

n_samples : int

The number of samples.

prior : sbi.utils.BoxUniform

Uniformly distributed prior over given parameters.

Returns:Sampled prior with the number of rows that corresponds to the n_samples, while the number of columns depends on the number of free parameters. Return type:numpy.ndarray

infer(n_samples=None, theta=None, x=None, n_rounds=1, inference_method='SNPE', density_estimator_model='maf', inference_kwargs={}, train_kwargs={}, posterior_kwargs={}, restart=False, sbi_device='cpu', **params)

Return the trained posterior.

Note that if theta and x are not provided, n_samples has to be defined. Otherwise, if n_samples is provided, neither theta nor x are needed and will be ignored.

Parameters:

• n_samples (int, optional) – The number of samples.
• theta (numpy.ndarray, optional) – Sampled prior.
• x (numpy.ndarray, optional) – Summary statistics.
• n_rounds (int, optional) – If n_rounds is set to 1, amortized inference will be performed. Otherwise, if n_rounds is integer larger than 1, multi-round inference will be performed. This is only valid if posterior has not been defined manually. Otherwise, if this method is called after posterior has already been built, multi-round inference is performed.
• inference_method (str, optional) – Inference method. Either SNPE, SNLE or SNRE.
• density_estimator_model (str, optional) – The type of density estimator to be created. Either mdn, made, maf, nsf for SNPE and SNLE, or linear, mlp, resnet for SNRE.
• inference_kwargs (dict, optional) – Additional keyword arguments for the init_inference.
• train_kwargs (dict, optional) – Additional keyword arguments for train.
• posterior_kwargs (dict, optional) – Additional keyword arguments for build_posterior.
• restart (bool, optional) – When the method is called for a second time, set to True if amortized inference should be performed. If False, multi-round inference with the existing posterior will be performed.
• sbi_device (str, optional) – Device on which the sbi will operate. By default this is set to cpu and it is advisable to remain so for most cases. In cases where the user provide custom embedding network through inference_kwargs argument, which will be trained more efficiently by using GPU, device should be set accordingly to either gpu or cuda.
• params (dict) – Bounds for each parameter. Keys should correspond to names of parameters as defined in the model equations, while values are lists with the lower and the upper bound with corresponding quantities of the parameter.

Returns:

Approximated posterior distribution over parameters.

Return type:

sbi.inference.posteriors.base_posterior.NeuralPosterior

infer_step(proposal, inference, n_samples=None, theta=None, x=None, train_kwargs={}, posterior_kwargs={}, *args)

Return the trained neural density estimator.

Parameters:

• proposal (sbi.utils.torchutils.BoxUniform) – Prior over parameters for the current round of inference.
• inference (sbi.inference.NeuralInference) – Inference object obtained via init_inference method.
• n_samples (int, optional) – The number of samples.
• theta (numpy.ndarray, optional) – Sampled prior.
• x (numpy.ndarray, optional) – Summary statistics.
• train_kwargs (dict, optional) – Additional keyword arguments for train.
• posterior_kwargs (dict, optional) – Additional keyword arguments for build_posterior.
• args (list, optional) – Additional arguments for train.

Returns:

Trained posterior.

Return type:

sbi.inference.posteriors.base_posterior.NeuralPosterior

init_inference(inference_method, density_estimator_model, prior, sbi_device='cpu', **inference_kwargs)

Return instantiated inference object.

Parameters:

• inference_method (str) – Inference method. Either SNPE, SNLE or SNRE.
• density_estimator_model (str) – The type of density estimator to be created. Either mdn, made, maf, nsf for SNPE and SNLE, or linear, mlp, resnet for SNRE.
• prior (sbi.utils.BoxUniform) – Uniformly distributed prior over free parameters.
• sbi_device (str, optional) – Device on which the sbi will operate. By default this is set to cpu and it is advisable to remain so for most cases. In cases where the user provides custom embedding network through inference_kwargs argument, which will be trained more efficiently by using GPU, device should be set accordingly to either gpu or cuda.
• inference_kwargs (dict, optional) – Additional keyword arguments for different density estimator builder functions: sbi.utils.get_nn_models.posterior_nn for SNPE, sbi.utils.get_nn_models.classifier_nn for SNRE, and sbi.utils.get_nn_models.likelihood_nn for SNLE. For details check the official sbi documentation. A single highlighted keyword argument is a custom embedding network that serves a purpose to learn features from potentially high-dimensional simulation outputs. By default multi-layer perceptron is used if no custom embedding network is provided. For SNPE and SNLE, the user may pass an embedding network for simulation outputs through embedding_net argument, while for SNRE, the user may pass two embedding networks, one for parameters through embedding_net_theta argument, and the other for simulation outputs through embedding_net_x argument.

Returns:

Instantiated inference object.

Return type:

sbi.inference.NeuralInference

init_prior(**params)

Return the prior uniform distribution over the parameters.

Parameters:params (dict) – Dictionary with keys that correspond to parameter names, and the respective values are 2-element lists that hold the upper and the lower bound of a distribution. Returns:sbi-compatible object that contains a uniform prior distribution over a given set of parameters. Return type:sbi.utils.torchutils.BoxUniform

load_posterior(f)

Loads the density estimator state dictionary from a disk file.

Parameters:f (str or os.PathLike) – Path to file either as string or os.PathLike object that contains file name. Returns:Loaded neural posterior with defined method family, density estimator state dictionary, the prior over parameters and the output shape of the simulator. Return type:sbi.inference.posteriors.base_posterior.NeuralPosterior

load_summary_statistics(f)

Load samples from a prior and the extracted summary statistics from a compressed .npz file.

Parameters:f (str or os.PathLike) – Path to file either as string or os.PathLike object that contains file name. Returns:Sampled prior and the summary statistics arrays. Return type:tuple

n_neurons

Return the number of neurons that are used in NeuronGroup class while generating data for training the neural density estimator.

Unlike the Fitter class, Inferencer does not take the total number of samples directly in the constructor. Thus, this property becomes available only after the simulation is performed.

Parameters:None – Returns:Total number of neurons. Return type:int

pairplot(samples=None, points=None, limits=None, subset=None, labels=None, ticks=None, **kwargs)

Plot samples in a 2-dimensional grid with marginals and pairwise marginals.

Check sbi.analysis.plot.pairplot for more details.

Parameters:

• samples (list or numpy.ndarray, optional) – Samples used to build the pairplot.
• points (dict, optional) – Additional points to scatter, e.g., true parameter values, if known.
• limits (dict, optional) – Limits for each parameter. Keys correspond to parameter names as defined in the model, while values are lists with limits defined as the Brian 2 quantity objects. If None, min and max of the given samples will be used.
• subset (list, optional) – The names as strings of parameters to plot.
• labels (dict, optional) – Names for each parameter. Keys correspond to parameter names as defined in the model, while values are lists of strings.
• ticks (dict, optional) – Position of the ticks. Keys correspond to parameter names as defined in the model, while values are lists with ticks defined as the Brian 2 quantity objects. If None, default ticks positions will be used.
• kwargs (dict, optional) – Additional keyword arguments for the sbi.analysis.pairplot function.

Returns:

Figure and axis of the posterior distribution plot.

Return type:

tuple

sample(shape, posterior=None, **kwargs)

Return samples from posterior distribution.

Parameters:

• shape (tuple) – Desired shape of samples that are drawn from posterior.
• posterior (neural posterior object, optional) – Posterior distribution.
• kwargs (dict, optional) – Additional keyword arguments for sample method of the neural posterior object.

Returns:

Samples taken from the posterior of the shape as given in shape.

Return type:

numpy.ndarray

save_posterior(f)

Save the density estimator state dictionary to a disk file.

Parameters:

• posterior (neural posterior object, optional) – Posterior distribution over parameters.
• f (str or os.PathLike) – Path to file either as string or os.PathLike object that contains file name.

Returns:

Return type:

None

save_summary_statistics(f, theta=None, x=None)

Save sampled prior and the extracted summary statistics into a single compressed .npz file.

Parameters:

• f (str or os.PathLike) – Path to a file either as string or os.PathLike object that contains file name.
• theta (numpy.ndarray, optional) – Sampled prior.
• x (numpy.ndarray, optional) – Summary statistics.

Returns:

Return type:

None

setup_simulator(network_name, n_neurons, output_var, param_init, level=1)

Return configured simulator.

Parameters:

• network_name (str) – Network name.
• n_neurons (int) – Number of neurons which equals to the number of samples times the number of input/output traces.
• output_var (str) – Name of the output variable.
• param_init (dict) – Dictionary of state variables to be initialized with respective values.
• level (int, optional) – How far to go back to get the locals/globals.

Returns:

Configured simulator w.r.t. the available device.

Return type:

brian2modelfitting.simulator.Simulator

train(inference, theta, x, *args, **train_kwargs)

Return the trained neural inference object.

Parameters:

• inference (sbi.inference.NeuralInference) – Instantiated inference object with stored paramaters and simulation outputs prepared for the training process.
• theta (torch.tensor) – Sampled prior.
• x (torch.tensor) – Summary statistics.
• args (tuple, optional) – Contains a uniformly distributed proposal. Used only for SNPE, for SNLE and SNRE, proposal should not be passed to inference object, thus args should not be passed. The additional arguments should be passed only if the parameters were not sampled from the prior, e.g., during the multi-round inference. For SNLE and SNRE, this can be the number of round from which the data is stemmed from, e.g., 0 means from the prior. This is used only if the discard_prior_samples is set to True inside the train_kwargs.
• train_kwargs (dict, optional) – Additional keyword arguments for train method in the sbi.inference.NeuralInference class. The user is able to gain the full control over the training process by tuning hyperparameters, e.g., the batch size (by specifiying training_batch_size argument), the learning rate (learning_rate), the validation fraction (validation_fraction), the number of training epochs (max_num_epochs), etc. For details, check the official sbi documentation.

Returns:

Trained inference object.

Return type:

sbi.inference.NeuralInference

brian2modelfitting.inferencer.calc_prior(param_names, **params)

Return the prior distribution over given parameters.

Note that the only currently supported prior distribution is the multi-dimensional uniform distribution defined on a box.

Parameters:

• param_names (list) – List containing parameter names.
• params (dict) – Dictionary with keys that correspond to parameter names, and the respective values are 2-element lists that hold the upper and the lower bound of a distribution.

Returns:

sbi-compatible object that contains a uniform prior distribution over a given set of parameters.

Return type:

sbi.utils.torchutils.BoxUniform

brian2modelfitting.inferencer.configure_simulator()

Return the configured simulator, which can be either RuntimeSimulator, object for the use with RuntimeDevice, or CPPStandaloneSimulator, object for the use with CPPStandaloneDevice.

Parameters:None – Returns:Either RuntimeSimulator or CPPStandaloneSimulator depending on the currently active Device object describing the available computational engine. Return type:brian2modelfitting.simulator.Simulator

brian2modelfitting.inferencer.get_full_namespace(additional_namespace, level=0)

Return the namespace with added additional_namespace, in which references to external parameters or functions are stored.

Parameters:

• additional_namespace (dict) – References to external parameters or functions, where key is the name and value is the value of the external parameter or function.
• level (int, optional) – How far to go back to get the locals/globals.

Returns:

Namespace with additional references to the external parameters or functions.

Return type:

dict

brian2modelfitting.inferencer.get_param_dict(param_values, param_names, n_values)

Return a dictionary compiled of parameter names and values.

Parameters:

• param_values (numpy.ndarray) – Parameter values in a 2-dimensional array with the number of rows corresponding to a number of samples and the number of columns corresponding to a number of parameters.
• param_names (list) – List containing parameter names.
• n_values (int) – Total number of given values for a single parameter.

Returns:

Dictionary containing key-value pairs that correspond to a parameter name and value(s).

Return type:

dict