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#

nngt.geometry.Area([shell, holes])

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

nngt.geometry.Shape([shell, holes])

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

nngt.geometry.culture_from_file(filename[, ...])

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

nngt.geometry.plot_shape(shape[, axis, m, ...])

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

nngt.geometry.pop_largest(shapes)

Returns the largest shape, removing it from the list.

nngt.geometry.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.

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 underlying shapely.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’ (\mu m), ‘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.

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:

Area object.

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’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

Parent

Initialize the Shape object and the underlying shapely.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’ (\mu m), ‘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 main Shape, it will be cut and only the intersection between the area and the container will be kept.

Parameters:
  • area (Area or Shape, or shapely.Polygon.) – Delimitation of the area. Only the intersection between the parent Shape 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 the Shape 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.

add_hole(hole)[source]#

Make a hole in the shape.

New in version 0.4.

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.

copy()[source]#

Create a copy of the current Shape.

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’ (\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 (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’ (\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 (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’ (\mu m), ‘mm’, ‘cm’, ‘dm’, ‘m’.

  • parent (nngt.Graph object) – The parent which will become a nngt.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’ (\mu m), ‘mm’, ‘cm’, ‘dm’, ‘m’

  • parent (nngt.Graph object) – The parent which will become a nngt.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’ (\mu m), ‘mm’, ‘cm’, ‘dm’, ‘m’

  • parent (nngt.Graph object) – The parent which will become a nngt.SpatialGraph.

  • default_properties (dict, optional (default: None)) – Default properties of the environment.

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).

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 (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 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 (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.

property unit#

Return the unit for the Shape coordinates.

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 min(y) + max(y) = 0.

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 largest shapely.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 min(y) + max(y) = 0.