neurots.generate.orientations

Module for handling the calculation of neurite orientations.

Functions

check_3d_angles(tmd_parameters)

Check whether the parameters correspond to 3d_angle modes, and return a bool.

compute_interval_n_tree(soma, n_trees[, rng])

Compute the number of trunks to add between each pair of consecutive existing trunks.

fit_3d_angles(tmd_parameters, tmd_distributions)

Fit functions to 3d_angles from tmd_distributions and save in copy of tmd_parameters.

get_probability_function([form, with_density])

Get probability functions to fit 3d trunk angles distributions.

orientations_to_sphere_points(oris, ...)

Compute points on a sphere from the given directions.

points_to_orientations(origin, points)

Returns the unit vector that corresponds to the orientation of a point on the soma surface.

spherical_angles_to_orientations(phis, thetas)

Compute orientation from spherical angles.

spherical_angles_to_pia_orientations(phis, ...)

Compute orientation from spherical angles where thetas are wrt to pia (default=`[0, 1, 0]`).

trunk_absolute_orientation_to_spherical_angles(...)

Generate spherical angles from a unit vector and a list of angles.

trunk_to_spherical_angles(trunk_angles, z_angles)

Generate spherical angles from a list of NeuroM angles.

Classes

OrientationManager(soma, parameters, ...)

Class to generate the tree orientations starting from the soma of the cell.

OrientationManagerBase(soma, parameters, ...)

Base class that automatically registers orientation modes.

class neurots.generate.orientations.OrientationManager(soma, parameters, distributions, context, rng)

Bases: OrientationManagerBase

Class to generate the tree orientations starting from the soma of the cell.

Parameters:
  • soma (Soma) – The soma on which the trees should be attached.

  • parameters (dict) – The parameters used to compute the orientations.

  • distributions (dict) – The distributions used to compute the orientations.

  • context (any) – An object containing contextual information.

  • rng (numpy.random.Generator) – The random number generator to use.

Note

All orientation mode dicts:

{
    "mode": "use_predefined",
    "values": {"orientations": [or1, or2, ...]}
}
{
    "mode": "sample_pairwise_angles",
    "values": {}
}
{
    "mode": "sample_around_primary_orientation",
    "values": {"primary_orientation": [0, 1, 0]}
}
_mode_apical_constraint(_, tree_type)

Create trunks from distribution of angles with apical direction.

See _sample_trunk_from_3d_angle() for more details on the algorithm.

_mode_normal_pia_constraint(values_dict, tree_type)

Returns orientations using normal/exp distribution along a direction.

The direction value should be a dict with two entries: mean and std. The mean is the angle wrt to pia ([0, 1, 0]) direction and the second is the standard deviation of a normal distribution if mean>0 or scaling of exponential distribution if mean=0. As the resulting angle must be in [0, 2 * pi], we clip the obtained angle and uniformly sample the second angle to obtain a 3d direction. For multiple apical trees, mean and std should be two lists with lengths equal to number of trees, otherwise it can be a float.

Pia direction can be overwritten by the parameter ‘pia_direction’ value.

_mode_pia_constraint(_, tree_type)

Create trunks from distribution of angles with pia ([0 , 1, 0]) direction.

See _sample_trunk_from_3d_angle() for more details on the algorithm.

_mode_sample_around_primary_orientation(values_dict, tree_type)

Sample orientations around a primary direction.

_mode_sample_pairwise_angles(_, tree_type)

Returns sampled orientations.

_mode_uniform(_, tree_type)

Uniformly sample angles on the sphere.

_mode_use_predefined(values_dict, tree_type)

Returns predefined orientations.

class neurots.generate.orientations.OrientationManagerBase(soma, parameters, distributions, context, rng)

Bases: object

Base class that automatically registers orientation modes.

Parameters:
  • soma (Soma) – The soma on which the trees should be attached.

  • parameters (dict) – The parameters used to compute the orientations.

  • distributions (dict) – The distributions used to compute the orientations.

  • context (any) – An object containing contextual information.

  • rng (numpy.random.Generator) – The random number generator to use.

Note

To register an orientation mode, derive from this base class and create a method with the following signature:

def _mode_{name}(self, values_dict, tree_type)
_collect_mode_methods()

Collects and stores in self._modes the methods, the name of which starts with ‘_mode_’.

Returns:

A dictionary mapping mode names without the ‘_modes_’ prefix to the methods.

Return type:

dict

_tree_type_method_values(tree_type)

Checks if the orientation entry in parameters has the correct format.

compute_tree_type_orientations(tree_type)

Computes the orientations for all tree types. It updates the _orientations dictionary.

Notes

Updating a data structure that is accessible by all orientation methods, allows to take into account existing orientations for calculating new ones.

get_tree_type_orientations(tree_type)

Returns the orientations for the specific tree type.

property mode_names

Returns the names of the available modes.

neurots.generate.orientations._fit_single_3d_angles(data, neurite_type, morph_class, fit_params=None)

Fit function to distribution of 3d angles for a neurite_type.

Parameters:
  • data (dict) – bins and weights data from input_distribution

  • neurite_type (str) – neurite_type to consider

  • morph_class (str) – morph_class of the neuron (with_apical or without_apical)

  • fit_params (dict) – specific fit parameters such as form and bounds to overwrite the defaults

neurots.generate.orientations._get_fit_params_from_input_parameters(parameters)

Get parameter dict for fits from tmd_parameters.

neurots.generate.orientations._sample_trunk_from_3d_angle(parameters, rng, tree_type, ref_dir, max_tries=100)

Sample trunk directions from fit of distribution of 3d_angles wrt to ref_dir.

We use the accept-reject algorithm so we can sample from any distribution. After a number of unsuccessful tries (default=100), we stop and return a random direction. We also issue a warning so the user is aware that the provided distribution may have issues, mostly related to large region of small probabilities.

neurots.generate.orientations.check_3d_angles(tmd_parameters)

Check whether the parameters correspond to 3d_angle modes, and return a bool.

neurots.generate.orientations.compute_interval_n_tree(soma, n_trees, rng=numpy.random)

Compute the number of trunks to add between each pair of consecutive existing trunks.

If points already exist in the soma, the algorithm is the following:

  • build the intervals between each pair of consecutive points.

  • compute the size of each interval.

  • randomly select the interval in which each new point will be added (the intervals are weighted by their sizes to ensure the new trunks are created isotropically).

  • count the number of new points in each interval.

  • return the intervals in which at least one point must be added.

If no point exists in the soma, the interval [0, 2pi] contains all the new trunks.

Parameters:
  • soma (Soma) – The soma on which the trunks should be added.

  • n_trees (int) – The number of trees that should be added.

  • rng (numpy.random.Generator) – The random number generator to use.

Returns:

The phi intervals and the number of trees in each of them.

Return type:

tuple[numpy.ndarray[float], numpy.ndarray[int]]

neurots.generate.orientations.fit_3d_angles(tmd_parameters, tmd_distributions)

Fit functions to 3d_angles from tmd_distributions and save in copy of tmd_parameters.

If the fit parameters are already in tmd_parameters, the fit is skipped.

Parameters:
  • tmd_parameters (dict) – Input parameters.

  • tmd_distributions (dict) – Input distributions.

Returns:

tmd_parmeters with fit data if 3d_angles mode is found, else None

neurots.generate.orientations.get_probability_function(form='step', with_density=True)

Get probability functions to fit 3d trunk angles distributions.

Parameters:
  • form (str) – Form of the function, can be flat, step or double_step.

  • with_density (bool) – Return the function with spherical density factor or not.

Three forms of functions are available: - flat: uniform flat distribution - step: distribution with a single sigmoid scipy.special.expit() - double_step: distribution with two opposite sigmoids scipy.special.expit()

Each sigmoid is parametrized by a scale and a rate.

In practice, the flat function is used when no asymmetry is present in the data, and the other two are when an asymmetry towards one direction, usually opposite to pia or apical, or two directions, usually along and opposite to pia.

Returns:

function with first arg as angle and next args to parametrize the function

neurots.generate.orientations.orientations_to_sphere_points(oris, sphere_center, sphere_radius)

Compute points on a sphere from the given directions.

Parameters:
Returns:

Points on the surface of the sphere corresponding to the given orientations.

Return type:

numpy.ndarray

neurots.generate.orientations.points_to_orientations(origin, points)

Returns the unit vector that corresponds to the orientation of a point on the soma surface.

Parameters:
Returns:

Normalized orientations from origin to points.

Return type:

numpy.ndarray

neurots.generate.orientations.spherical_angles_to_orientations(phis, thetas)

Compute orientation from spherical angles.

Parameters:
Returns:

The orientation vectors where each row corresponds to a phi-theta pair.

Return type:

numpy.ndarray

neurots.generate.orientations.spherical_angles_to_pia_orientations(phis, thetas, pia_direction=None)

Compute orientation from spherical angles where thetas are wrt to pia (default=`[0, 1, 0]`).

Parameters:
Returns:

The orientation vectors where each row corresponds to a phi-theta pair.

Return type:

numpy.ndarray

neurots.generate.orientations.trunk_absolute_orientation_to_spherical_angles(orientation, trunk_absolute_angles, z_angles)

Generate spherical angles from a unit vector and a list of angles.

Parameters:
  • orientation (list[float]) – The orientation vector.

  • trunk_absolute_angles (list[float]) – The polar angles (phi in spherical coordinates).

  • z_angles (list[float]) – The azimuthal angles (theta in spherical coordinates).

Returns:

The phi and theta angles.

Return type:

tuple[numpy.ndarray[float], numpy.ndarray[float]]

neurots.generate.orientations.trunk_to_spherical_angles(trunk_angles, z_angles, phi_interval=None)

Generate spherical angles from a list of NeuroM angles.

Parameters:
  • trunk_angles (list[float]) – The polar angles (phi in spherical coordinates).

  • z_angles (list[float]) – The azimuthal angles (theta in spherical coordinates).

  • phi_interval (tuple[float, float]) – The interval in which the trunks should be added.

Returns:

The phi and theta angles.

Return type:

tuple[numpy.ndarray[float], numpy.ndarray[float]]