Geometry module#
This module is a direct copy of the SENeC package
PyNCulture.
Therefore, in the examples below, you will have to import nngt
instead of
PyNCulture
and replace pnc
by nngt.geometry
.
Overview#
|
Specialized |
|
Class containing the shape of the area where neurons will be distributed to form a network. |
|
Generate a culture from an SVG, a DXF, or a WKT/WKB file. |
|
Plot a shape (you should set the axis aspect to 1 to respect the proportions). |
|
Returns the largest shape, removing it from the list. |
|
Generate a set of |
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.
import matplotlib.pyplot as plt
import PyNCulture as nc
fig, ax = plt.subplots()
''' Choose a shape (uncomment the desired line) '''
# culture = nc.Shape.rectangle(15, 20, (5, 0))
culture = nc.Shape.disk(20, (5, 0))
# culture = nc.Shape.ellipse((20, 5), (5, 0))
''' Generate the neurons inside '''
pos = culture.seed_neurons(neurons=1000, xmax=0., ymax=0.)
''' Plot '''
nc.plot_shape(culture, ax, show=False)
ax.scatter(pos[:, 0], pos[:, 1], s=2, zorder=2)
plt.show()
All these features are of course still available with the more advanced
Shape
object which inherits from shapely.geometry.Polygon
.
Complex shapes from files#
import matplotlib.pyplot as plt
import PyNCulture as nc
''' Choose a file '''
culture_file = "culture_from_filled_polygons.svg"
# culture_file = "culture_with_holes.svg"
# culture_file = "culture.dxf"
shapes = nc.shapes_from_file(culture_file, min_x=-5000., max_x=5000.)
''' Plot the shapes '''
fig, ax = plt.subplots()
fig.suptitle("shapes")
for p in shapes:
nc.plot_shape(p, ax, show=False)
plt.show()
''' Make a culture '''
fig2, ax2 = plt.subplots()
plt.title("culture")
culture = nc.culture_from_file(culture_file, min_x=-5000., max_x=5000.)
nc.plot_shape(culture, ax2)
''' Add neurons '''
fig3, ax3 = plt.subplots()
plt.title("culture with neurons")
culture_bis = nc.culture_from_file(culture_file, min_x=-5000., max_x=5000.)
pos = culture_bis.seed_neurons(neurons=1000, xmax=0)
nc.plot_shape(culture_bis, ax3, show=False)
ax3.scatter(pos[:, 0], pos[:, 1], s=2, zorder=3)
plt.show()
Content#
- class nngt.geometry.Area(shell=None, holes=None, **kwargs)[source]#
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.
Initialize the
Shape
object and the underlyingshapely.geometry.Polygon
.- Parameters
shell (array-like object of shape (N, 2)) – List of points defining the external border of the shape.
holes (array-like, optional (default: None)) – List of array-like objects of shape (M, 2), defining empty regions inside the shape.
unit (string (default: ‘um’)) – Unit in the metric system among ‘um’ (
), ‘mm’, ‘cm’, ‘dm’, ‘m’.
height (float, optional (default: 0.)) – Height of the area.
name (str, optional (default: “area”)) – The name of the area.
properties (dict, optional (default: default neuronal properties)) – Dictionary containing the list of the neuronal properties that are modified by the substrate. Since this describes how the default property is modulated, all values must be positive reals or NaN.
- property areas#
Returns the dictionary containing the Shape’s areas.
- class nngt.geometry.Shape(shell=None, holes=None, **kwargs)[source]#
Class containing the shape of the area where neurons will be distributed to form a network.
- area#
Area of the shape in the
Shape
’sShape.unit()
squared (,
,
,
or
).
- Type
double
See also
Parent
Initialize the
Shape
object and the underlyingshapely.geometry.Polygon
.- Parameters
exterior (array-like object of shape (N, 2)) – List of points defining the external border of the shape.
interiors (array-like, optional (default: None)) – List of array-like objects of shape (M, 2), defining empty regions inside the shape.
unit (string (default: ‘um’)) – Unit in the metric system among ‘um’ (
), ‘mm’, ‘cm’, ‘dm’, ‘m’.
parent (
nngt.Graph
or subclass) – The graph which is associated to this Shape.default_properties (dict, optional (default: None)) – Default properties of the environment.
- add_area(area, height=None, name=None, properties=None, override=False)[source]#
Add a new area to the
Shape
. If the new area has a part that is outside the mainShape
, it will be cut and only the intersection between the area and the container will be kept.- Parameters
area (
Area
orShape
, orshapely.Polygon
.) – Delimitation of the area. Only the intersection between the parentShape
and this new area will be kept.name (str, optional, default (“areaX” where X is the number of areas)) – Name of the area, under which it can be retrieved using the
Shape.area()
property of theShape
object.properties (dict, optional (default: None)) – Properties of the area. If area is a
Area
, then this is not necessary.override (bool, optional (default: False)) – If True, the new area will be made over existing areas that will be reduced in consequence.
- property areas#
Returns the dictionary containing the Shape’s areas.
- contains_neurons(positions)[source]#
Check whether the neurons are contained in the shape.
New in version 0.4.
- Parameters
positions (point or 2D-array of shape (N, 2))
- Returns
contained (bool or 1D boolean array of length N) – True if the neuron is contained, False otherwise.
- property default_areas#
Returns the dictionary containing only the default areas.
New in version 0.4.
- static disk(radius, centroid=(0.0, 0.0), unit='um', parent=None, default_properties=None)[source]#
Generate a disk of given radius and center (centroid).
- Parameters
radius (float) – Radius of the disk 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’ (
), ‘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 (
Shape
) – Rectangle shape.
- static ellipse(radii, centroid=(0.0, 0.0), unit='um', parent=None, default_properties=None)[source]#
Generate a disk of given radius and center (centroid).
- Parameters
radii (tuple of floats) – Couple (rx, ry) containing the radii of the two axes 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’ (
), ‘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 (
Shape
) – Rectangle shape.
- static from_file(filename, min_x=None, max_x=None, unit='um', parent=None, interpolate_curve=50, default_properties=None)[source]#
Create a shape from a DXF, an SVG, or a WTK/WKB file.
New in version 0.3.
- Parameters
filename (str) – Path to the file that should be loaded.
min_x (float, optional (default: -5000.)) – Absolute horizontal position of the leftmost point in the environment in unit (default: ‘um’). If None, no rescaling occurs.
max_x (float, optional (default: 5000.)) – Absolute horizontal position of the rightmost point in the environment in unit. If None, no rescaling occurs.
unit (string (default: ‘um’)) – Unit in the metric system among ‘um’ (
), ‘mm’, ‘cm’, ‘dm’, ‘m’.
parent (
nngt.Graph
object) – The parent which will become anngt.SpatialGraph
.interpolate_curve (int, optional (default: 50)) – Number of points that should be used to interpolate a curve.
default_properties (dict, optional (default: None)) – Default properties of the environment.
- static from_polygon(polygon, min_x=None, max_x=None, unit='um', parent=None, default_properties=None)[source]#
Create a shape from a
shapely.geometry.Polygon
.- Parameters
polygon (
shapely.geometry.Polygon
) – The initial polygon.min_x (float, optional (default: -5000.)) – Absolute horizontal position of the leftmost point in the environment in unit If None, no rescaling occurs.
max_x (float, optional (default: 5000.)) – Absolute horizontal position of the rightmost point in the environment in unit If None, no rescaling occurs.
unit (string (default: ‘um’)) – Unit in the metric system among ‘um’ (
), ‘mm’, ‘cm’, ‘dm’, ‘m’
parent (
nngt.Graph
object) – The parent which will become anngt.SpatialGraph
.default_properties (dict, optional (default: None)) – Default properties of the environment.
- static from_wkt(wtk, min_x=None, max_x=None, unit='um', parent=None, default_properties=None)[source]#
Create a shape from a WKT string.
New in version 0.2.
- Parameters
wtk (str) – The WKT string.
min_x (float, optional (default: -5000.)) – Absolute horizontal position of the leftmost point in the environment in unit If None, no rescaling occurs.
max_x (float, optional (default: 5000.)) – Absolute horizontal position of the rightmost point in the environment in unit If None, no rescaling occurs.
unit (string (default: ‘um’)) – Unit in the metric system among ‘um’ (
), ‘mm’, ‘cm’, ‘dm’, ‘m’
parent (
nngt.Graph
object) – The parent which will become anngt.SpatialGraph
.default_properties (dict, optional (default: None)) – Default properties of the environment.
See also
- property non_default_areas#
Returns the dictionary containing all Shape’s areas except the default ones.
New in version 0.4.
- 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 bythe 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).
- 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’ (
), ‘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 (
Shape
) – Rectangle 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 theintersection()
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 (array of double with shape (N, 2) or pint.Quantity if) – return_quantity is True.
- 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.
- nngt.geometry.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
object) – Shape, vertically centred around zero, such that.
- nngt.geometry.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
)
- nngt.geometry.pop_largest(shapes)[source]#
Returns the largest shape, removing it from the list. If shapes is a
shapely.geometry.MultiPolygon
, returns the largestshapely.geometry.Polygon
without modifying the object.New in version 0.3.
- Parameters
shapes (list of
Shape
objects or MultiPolygon.)
- nngt.geometry.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
object) – Shape, vertically centred around zero, such that.