The `environment` module¶

This module is used to create and manage spatial environments where the neurons can develop.

Warning

For people using DeNSE from git, this module is remotely tracked from SENeC PyNCulture repository, which means that you have to initialize and pull it separately. The first time, the repository must also be initialized with

git submodule init
git submodule update

To update it later on, just run

git submodule update --remote --merge

The module contains the following functions and classes:

`dense.environment.Area`(shell[, holes, unit, ...])	Specialized `Shape` that stores additional properties regarding the interactions with the neurons.
`dense.environment.Shape`(shell[, holes, ...])	Class containing the shape of the area where neurons will be distributed to form a network.
`dense.environment.culture_from_file`(filename)	Generate a culture from an SVG, a DXF, or a WKT/WKB file.
`dense.environment.plot_shape`(shape[, axis, ...])	Plot a shape (you should set the axis aspect to 1 to respect the proportions).
`dense.environment.pop_largest`(shapes)	Returns the largest shape, removing it from the list.
`dense.environment.shapes_from_file`(filename)	Generate a set of `Shape` objects from an SVG, a DXF, or a WKT/WKB file.

Principle¶

Module dedicated to the description of the spatial boundaries of neuronal cultures. This allows for the generation of neuronal networks that are embedded in space.

The shapely library is used to generate and deal with the spatial environment of the neurons.

Examples

Basic features¶

The module provides a backup Shape object, which can be used with only the numpy and scipy libraries. It allows for the generation of simple rectangle, disk and ellipse shapes.

All these features are of course still available with the more advanced Shape object which inherits from shapely.geometry.Polygon.

Complex shapes from files¶

Content¶

class dense.environment.Area(shell, holes=None, unit='um', height=0.0, name='area', properties=None)[source]¶

Bases: dense.environment.shape.Shape

Specialized Shape that stores additional properties regarding the interactions with the neurons.

Each Area is characteristic of a given substrate and height. These two properties are homogeneous over the whole area, meaning that the neurons interact in the same manner with an Area reagardless of their position inside.

The substrate is described through its modulation of the neuronal properties compared to their default behavior. Thus, a given area will modulate the speed, wall affinity, etc, of the growth cones that are growing above it.

add_subshape(subshape, position, unit='um')[source]¶

property areas¶: Returns the dictionary containing the Shape’s areas.

copy()[source]¶: Create a copy of the current Area.

classmethod from_shape(shape, height=0.0, name='area', properties=None, unit='um', min_x=None, max_x=None)[source]¶

Create an Area from a Shape object.

Parameters: shape (Shape) – Shape that should be converted to an Area.
Returns
Return type: Area object.

property properties¶

class dense.environment.Shape(shell, holes=None, unit='um', parent=None, default_properties=None)[source]¶

Bases: shapely.geometry.polygon.Polygon

Class containing the shape of the area where neurons will be distributed to form a network.

area¶

Area of the shape in the Shape’s Shape.unit() squared (\(\mu m^2\), \(mm^2\), \(cm^2\), \(dm^2\) or \(m^2\)).

Type: double

centroid¶

Position of the center of mass of the current shape in unit.

Type: tuple of doubles

See also

Shape.from_polygon()

property non_default_areas¶: Returns the dictionary containing all Shape’s areas except the default ones.

New in version 0.4.

property parent¶: Return the parent of the Shape.

random_obstacles(n, form, params=None, heights=None, properties=None, etching=0, on_area=None)[source]¶

Place random obstacles inside the shape.

New in version 0.4.

Parameters

n (int or float) –
Number of obstacles if n is an int, otherwise represents the fraction of the shape’s bounding box that should be occupied by

the obstacles’ bounding boxes.
form (str or Shape) – Form of the obstacles, among “disk”, “ellipse”, “rectangle”, or a custom shape.
params (dict, optional (default: None)) – Dictionnary containing the instructions to build a predefined form (“disk”, “ellipse”, “rectangle”). See their creation methods for details. Leave None when using a custom shape.
heights (float or list, optional (default: None)) – Heights of the obstacles. If None, the obstacle will considered as a “hole” in the structure, i.e. an uncrossable obstacle.
properties (dict or list, optional (default: None)) – Properties of the obstacles if they constitue areas (only used if heights is not None). If not provided and heights is not None, will default to the “default_area” properties.
etching (float, optional (default: 0)) – Etching of the obstacles’ corners (rounded corners). Valid only for

static rectangle(height, width, centroid=(0.0, 0.0), unit='um', parent=None, default_properties=None)[source]¶

Generate a rectangle of given height, width and center of mass.

Parameters

height (float) – Height of the rectangle in unit
width (float) – Width of the rectangle in unit
centroid (tuple of floats, optional (default: (0., 0.))) – Position of the rectangle’s center of mass in unit
unit (string (default: 'um')) – Unit in the metric system among ‘um’ (\(\mu m\)), ‘mm’, ‘cm’, ‘dm’, ‘m’
parent (nngt.Graph or subclass, optional (default: None)) – The parent container.
default_properties (dict, optional (default: None)) – Default properties of the environment.

Returns

shape – Rectangle shape.

Return type

Shape

property return_quantity¶: Whether seed_neurons returns positions with units by default.

New in version 0.5.

seed_neurons(neurons=None, container=None, on_area=None, xmin=None, xmax=None, ymin=None, ymax=None, soma_radius=0, unit=None, return_quantity=None)[source]¶

Return the positions of the neurons inside the Shape.

Parameters

neurons (int, optional (default: None)) – Number of neurons to seed. This argument is considered only if the Shape has no parent, otherwise, a position is generated for each neuron in parent.
container (Shape, optional (default: None)) – Subshape acting like a mask, in which the neurons must be contained. The resulting area where the neurons are generated is the intersection() between of the current shape and the container.
on_area (str or list, optional (default: None)) – Area(s) where the seeded neurons should be.
xmin (double, optional (default: lowest abscissa of the Shape)) – Limit the area where neurons will be seeded to the region on the right of xmin.
xmax (double, optional (default: highest abscissa of the Shape)) – Limit the area where neurons will be seeded to the region on the left of xmax.
ymin (double, optional (default: lowest ordinate of the Shape)) – Limit the area where neurons will be seeded to the region on the upper side of ymin.
ymax (double, optional (default: highest ordinate of the Shape)) – Limit the area where neurons will be seeded to the region on the lower side of ymax.
unit (string (default: None)) – Unit in which the positions of the neurons will be returned, among ‘um’, ‘mm’, ‘cm’, ‘dm’, ‘m’.
return_quantity (bool, optional (default: False)) – Whether the positions should be returned as pint.Quantity objects (requires Pint).
versionchanged: (.) – 0.5: Accepts pint units and return_quantity argument.

Note

If both container and on_area are provided, the intersection of the two is used.

Returns: positions – return_quantity is True.
Return type: array of double with shape (N, 2) or pint.Quantity if

set_parent(parent)[source]¶: Set the parent nngt.Graph.

set_return_units(b)[source]¶: Set the default behavior for positions returned by seed_neurons. If True, then the positions returned are quantities with units (from the pint library), otherwise they are simply numpy arrays.

New in version 0.5.

Note

set_return_units(True) requires pint to be installed on the system, otherwise an error will be raised.

property unit¶: Return the unit for the Shape coordinates.

dense.environment.culture_from_file(filename, min_x=None, max_x=None, unit='um', parent=None, interpolate_curve=50, internal_shapes_as='holes', default_properties=None, other_properties=None)[source]¶

Generate a culture from an SVG, a DXF, or a WKT/WKB file.

Valid file needs to contain only closed objects among: rectangles, circles, ellipses, polygons, and closed curves. The objects do not have to be simply connected.

Changed in version 0.6: Added internal_shapes_as and other_properties keyword parameters.

Parameters

filename (str) – Path to the SVG, DXF, or WKT/WKB file.
min_x (float, optional (default: -5000.)) – Position of the leftmost coordinate of the shape’s exterior, in unit.
max_x (float, optional (default: 5000.)) – Position of the rightmost coordinate of the shape’s exterior, in unit.
unit (str, optional (default: 'um')) – Unit of the positions, among micrometers (‘um’), milimeters (‘mm’), centimeters (‘cm’), decimeters (‘dm’), or meters (‘m’).
parent (nngt.Graph or subclass, optional (default: None)) – Assign a parent graph if working with NNGT.
interpolate_curve (int, optional (default: 50)) – Number of points by which a curve should be interpolated into segments.
internal_shapes_as (str, optional (default: "holes")) – Defines how additional shapes contained in the main environment should be processed. If “holes”, then these shapes are substracted from the main environment; if “areas”, they are considered as areas.
default_properties (dict, optional (default: None)) – Properties of the default area of the culture.
other_properties (dict, optional (default: None)) – Properties of the non-default areas of the culture (internal shapes if internal_shapes_as is set to “areas”).

Returns

culture – Shape, vertically centred around zero, such that \(min(y) + max(y) = 0\).

Return type

Shape object

dense.environment.plot_shape(shape, axis=None, m='', mc='#999999', fc='#8888ff', ec='#444444', alpha=0.5, brightness='height', show_contour=True, show=True, **kwargs)[source]¶

Plot a shape (you should set the axis aspect to 1 to respect the proportions).

Parameters

shape (Shape) – Shape to plot.
axis (matplotlib.axes.Axes instance, optional (default: None)) – Axis on which the shape should be plotted. By default, a new figure is created.
m (str, optional (default: invisible)) – Marker to plot the shape’s vertices, matplotlib syntax.
mc (str, optional (default: "#999999")) – Color of the markers.
fc (str, optional (default: "#8888ff")) – Color of the shape’s interior.
ec (str, optional (default: "#444444")) – Color of the shape’s edges.
alpha (float, optional (default: 0.5)) – Opacity of the shape’s interior.
brightness (str, optional (default: height)) – Show how different other areas are from the ‘default_area’ (lower values are darker, higher values are lighter). Difference can concern the ‘height’, or any of the properties of the Area objects.
show_contour (bool, optional (default: True)) – Whether the shapes should be drawn with a contour.
show (bool, optional (default: True)) – Whether the plot should be displayed immediately.
**kwargs (keywords arguments for matplotlib.patches.PathPatch) –

dense.environment.pop_largest(shapes)[source]¶

Returns the largest shape, removing it from the list. If shapes is a shapely.geometry.MultiPolygon, returns the largest shapely.geometry.Polygon without modifying the object.

New in version 0.3.

Parameters: shapes (list of Shape objects or MultiPolygon.) –

dense.environment.shapes_from_file(filename, min_x=None, max_x=None, unit='um', parent=None, interpolate_curve=50, default_properties=None, **kwargs)[source]¶

Generate a set of Shape objects from an SVG, a DXF, or a WKT/WKB file.

Valid file needs to contain only closed objects among: rectangles, circles, ellipses, polygons, and closed curves. The objects do not have to be simply connected.

New in version 0.3.

Parameters

filename (str) – Path to the SVG, DXF, or WKT/WKB file.
min_x (float, optional (default: -5000.)) – Position of the leftmost coordinate of the shape’s exterior, in unit.
max_x (float, optional (default: 5000.)) – Position of the rightmost coordinate of the shape’s exterior, in unit.
unit (str, optional (default: 'um')) – Unit of the positions, among micrometers (‘um’), milimeters (‘mm’), centimeters (‘cm’), decimeters (‘dm’), or meters (‘m’).
parent (nngt.Graph or subclass, optional (default: None)) – Assign a parent graph if working with NNGT.
interpolate_curve (int, optional (default: 50)) – Number of points by which a curve should be interpolated into segments.

Returns

culture – Shape, vertically centred around zero, such that \(min(y) + max(y) = 0\).

Return type

Shape object

The environment module¶

Principle¶

Basic features¶

Complex shapes from files¶

Content¶

The `environment` module¶