neurots.generate.orientations¶
Module for handling the calculation of neurite orientations.
Functions
|
Check whether the parameters correspond to 3d_angle modes, and return a bool. |
|
Compute the number of trunks to add between each pair of consecutive existing trunks. |
|
Fit functions to 3d_angles from |
|
Get probability functions to fit 3d trunk angles distributions. |
|
Compute points on a sphere from the given directions. |
|
Returns the unit vector that corresponds to the orientation of a point on the soma surface. |
|
Compute orientation from spherical angles. |
|
Compute orientation from spherical angles where thetas are wrt to pia (default=`[0, 1, 0]`). |
Generate spherical angles from a unit vector and a list of angles. |
|
|
Generate spherical angles from a list of NeuroM angles. |
Classes
|
Class to generate the tree orientations starting from the soma of the cell. |
|
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
andstd
. The mean is the angle wrt to pia ([0, 1, 0]
) direction and the second is the standard deviation of a normal distribution ifmean>0
or scaling of exponential distribution ifmean=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
andstd
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:
- _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
.
- 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 toref_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:
- neurots.generate.orientations.fit_3d_angles(tmd_parameters, tmd_distributions)¶
Fit functions to 3d_angles from
tmd_distributions
and save in copy oftmd_parameters
.If the fit parameters are already in
tmd_parameters
, the fit is skipped.
- neurots.generate.orientations.get_probability_function(form='step', with_density=True)¶
Get probability functions to fit 3d trunk angles distributions.
- Parameters:
Three forms of functions are available: -
flat
: uniform flat distribution -step
: distribution with a single sigmoidscipy.special.expit()
-double_step
: distribution with two opposite sigmoidsscipy.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:
oris (numpy.ndarray) – Normalized orientation vectors.
sphere_center (numpy.ndarray) – Center of sphere.
sphere_radius (float) – Radius of sphere.
- Returns:
Points on the surface of the sphere corresponding to the given orientations.
- Return type:
- 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:
origin (numpy.ndarray) – The origin of the vectors.
points (numpy.ndarray) – Points to calculate the vectors to.
- Returns:
Normalized orientations from origin to points.
- Return type:
- neurots.generate.orientations.spherical_angles_to_orientations(phis, thetas)¶
Compute orientation from spherical angles.
- Parameters:
phis (numpy.ndarray) – Polar angles.
thetas (numpy.ndarray) – Azimuthal angles.
- Returns:
The orientation vectors where each row corresponds to a phi-theta pair.
- Return type:
- 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:
phis (numpy.ndarray) – Polar angles.
thetas (numpy.ndarray) – Azimuthal angles.
pia_direction (numpy.ndarray) – Direction of pia if different from
[0, 1, 0]
.
- Returns:
The orientation vectors where each row corresponds to a phi-theta pair.
- Return type:
- 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:
- Returns:
The phi and theta angles.
- Return type:
- neurots.generate.orientations.trunk_to_spherical_angles(trunk_angles, z_angles, phi_interval=None)¶
Generate spherical angles from a list of NeuroM angles.
- Parameters:
- Returns:
The phi and theta angles.
- Return type: