Main module (API)#
For more details regarding the main classes, see:
NNGT#
Package aimed at facilitating the analysis of Neural Networks and Graphs’ Topologies in Python by providing a unified interface for network generation and analysis.
The library mainly provides algorithms for
generating networks
studying their topological properties
doing some basic spatial, topological, and statistical visualizations
interacting with neuronal simulators and analyzing neuronal activity
Available modules#
- analysis
Tools to study graph topology and neuronal activity.
- core
Where the main classes are coded; however, most useful classes and methods for users are loaded at the main level (nngt) when the library is imported, so nngt.core should generally not be used.
- generation
Functions to generate specific networks.
- geometry
Tools to work on metric graphs (see PyNCulture).
- io
Tools for input/output operations.
- lib
Basic functions used by several most other modules.
- simulation
Tools to provide complex network generation with NEST and help analyze the influence of the network structure on neuronal activity.
- plot
Plot data or graphs using matplotlib.
Units#
Functions related to spatial embedding of networks are using micrometers (um) as default unit; other units from the metric system can also be provided:
mm for milimeters
cm centimeters
dm for decimeters
m for meters
Main classes and functions#
|
The basic graph class, which inherits from a library class such as |
|
Class defining groups of nodes. |
|
Class defining the properties needed to create groups of neurons from an existing |
|
Class defining a meta-group of nodes. |
|
Class defining a meta-group of neurons. |
|
The detailed class that inherits from |
|
Class defining groups of neurons. |
|
The basic class that contains groups of neurons and their properties. |
|
The detailed class that inherits from |
|
Class that inherits from |
|
The basic class that contains groups of nodes and their properties. |
|
Generate a |
|
Get the NNGT configuration as a dictionary. |
|
Load a Graph from a file. |
Returns the number of MPI processes (1 if MPI is not used) |
|
Check whether the current code is executing on the master process (rank 0) if MPI is used. |
|
|
Save a graph to file. |
|
Seed the random generator used by NNGT (i.e. |
|
Set NNGT's configuration. |
|
Allows the user to switch to a specific graph library as backend. |
Details#
- class nngt.Graph(*args, **kwargs)[source]#
The basic graph class, which inherits from a library class such as
graph_tool.Graph
,networkx.DiGraph
, origraph.Graph
.The objects provides several functions to easily access some basic properties.
Initialize Graph instance
Changed in version 2.0: Renamed from_graph to copy_graph.
Changed in version 2.2: Added structure argument.
- Parameters:
nodes (int, optional (default: 0)) – Number of nodes in the graph.
name (string, optional (default: “Graph”)) – The name of this
Graph
instance.weighted (bool, optional (default: True)) – Whether the graph edges have weight properties.
directed (bool, optional (default: True)) – Whether the graph is directed or undirected.
copy_graph (
Graph
, optional) – An optionalGraph
that will be copied.structure (
Structure
, optional (default: None)) – A structure dividing the graph into specific groups, which can be used to generate specific connectivities and visualise the connections in a more coarse-grained manner.kwargs (optional keywords arguments) – Optional arguments that can be passed to the graph, e.g. a dict containing information on the synaptic weights (
weights={"distribution": "constant", "value": 2.3}
which is equivalent toweights=2.3
), the synaptic delays, or atype
information.
Note
When using copy_graph, only the topological properties are copied (nodes, edges, and attributes), spatial and biological properties are ignored. To copy a graph exactly, use
copy()
.- Returns:
self (
Graph
)
- class nngt.Group(nodes=None, properties=None, name=None, **kwargs)[source]#
Class defining groups of nodes.
Its main variables are:
- Variables:
Note
A
Group
contains a set of nodes that are unique; the size of the group is the number of unique nodes contained in the group. Passing non-unique nodes will automatically convert them to a unique set.Warning
Equality between
Group`s only compares the size and ``properties`
attributes. This means that groups differing only by theirids
will register as equal.Calling the class creates a group of nodes. The default is an empty group but it is not a valid object for most use cases.
- Parameters:
nodes (int or array-like, optional (default: None)) – Desired size of the group or, a posteriori, NNGT indices of the nodes in an existing graph.
properties (dict, optional (default: {})) – Dictionary containing the properties associated to the nodes.
- Returns:
A new
Group
instance.
- class nngt.GroupProperty(size, constraints={}, neuron_model=None, neuron_param={}, syn_model=None, syn_param={})[source]#
Class defining the properties needed to create groups of neurons from an existing
Graph
or one of its subclasses.- Variables:
~nngt.GroupProperty.size –
int
Size of the group.constraints –
dict
, optional (default: {}) Constraints to respect when building theNeuralGroup
.~nngt.GroupProperty.neuron_model – str, optional (default: None) name of the model to use when simulating the activity of this group.
~nngt.GroupProperty.neuron_param – dict, optional (default: {}) the parameters to use (if they differ from the model’s defaults)
Create a new instance of GroupProperties.
Notes
- The constraints can be chosen among:
“avg_deg”, “min_deg”, “max_deg” (
int
) to constrain the total degree of the nodes“avg/min/max_in_deg”, “avg/min/max_out_deg”, to work with the in/out-degrees
“avg/min/max_betw” (
double
) to constrain the betweenness centrality“in_shape” (
nngt.geometry.Shape
) to chose neurons inside a given spatial region
Examples
>>> di_constrain = { "avg_deg": 10, "min_betw": 0.001 } >>> group_prop = GroupProperties(200, constraints=di_constrain)
- class nngt.MetaGroup(nodes=None, properties=None, name=None, **kwargs)[source]#
Class defining a meta-group of nodes.
Its main variables are:
Calling the class creates a group of nodes. The default is an empty group but it is not a valid object for most use cases.
- Parameters:
nodes (int or array-like, optional (default: None)) – Desired size of the group or, a posteriori, NNGT indices of the nodes in an existing graph.
name (str, optional (default: “Group N”)) – Name of the meta-group.
- Returns:
A new
MetaGroup
object.
- class nngt.MetaNeuralGroup(nodes=None, neuron_type='undefined', neuron_model=None, neuron_param=None, name=None, **kwargs)[source]#
Class defining a meta-group of neurons.
Its main variables are:
- Variables:
Calling the class creates a group of neurons. The default is an empty group but it is not a valid object for most use cases.
- Parameters:
nodes (int or array-like, optional (default: None)) – Desired size of the group or, a posteriori, NNGT indices of the neurons in an existing graph.
name (str, optional (default: “Group N”)) – Name of the meta-group.
- Returns:
A new
MetaNeuralGroup
object.
- class nngt.Network(*args, **kwargs)[source]#
The detailed class that inherits from
Graph
and implements additional properties to describe various biological functions and interact with the NEST simulator.Initializes
Network
instance.- Parameters:
nodes (int, optional (default: 0)) – Number of nodes in the graph.
name (string, optional (default: “Graph”)) – The name of this
Graph
instance.weighted (bool, optional (default: True)) – Whether the graph edges have weight properties.
directed (bool, optional (default: True)) – Whether the graph is directed or undirected.
copy_graph (
GraphObject
, optional (default: None)) – An optionalGraphObject
to serve as base.population (
nngt.NeuralPop
, (default: None)) – An object containing the neural groups and their properties: model(s) to use in NEST to simulate the neurons as well as their parameters.inh_weight_factor (float, optional (default: 1.)) – Factor to apply to inhibitory synapses, to compensate for example the strength difference due to timescales between excitatory and inhibitory synapses.
- Returns:
self (
Network
)
- class nngt.NeuralGroup(nodes=None, neuron_type='undefined', neuron_model=None, neuron_param=None, name=None, **kwargs)[source]#
Class defining groups of neurons.
Its main variables are:
- Variables:
~nngt.NeuralGroup.ids –
list
ofint
the ids of the neurons in this group.~nngt.NeuralGroup.neuron_type –
int
the default is1
for excitatory neurons;-1
is for inhibitory neurons; meta-groups must have neuron_type set toNone
~nngt.NeuralGroup.neuron_model – str, optional (default: None) the name of the model to use when simulating the activity of this group
~nngt.NeuralGroup.neuron_param – dict, optional (default: {}) the parameters to use (if they differ from the model’s defaults)
~nngt.NeuralGroup.is_metagroup –
bool
whether the group is a meta-group or not (neuron_type isNone
for meta-groups)
Warning
Equality between
NeuralGroup`s only compares the size and neuronal type, ``model`
andparam
attributes. This means that groups differing only by theirids
will register as equal.Calling the class creates a group of neurons. The default is an empty group but it is not a valid object for most use cases.
- Parameters:
nodes (int or array-like, optional (default: None)) – Desired size of the group or, a posteriori, NNGT indices of the neurons in an existing graph.
neuron_type (int, optional (default: 1)) – Type of the neurons (1 for excitatory, -1 for inhibitory) or None if not relevant (only allowed for metag roups).
neuron_model (str, optional (default: None)) – NEST model for the neuron.
neuron_param (dict, optional (default: model defaults)) – Dictionary containing the parameters associated to the NEST model.
- Returns:
A new
NeuralGroup
instance.
- class nngt.NeuralPop(size=None, parent=None, meta_groups=None, with_models=True, **kwargs)[source]#
The basic class that contains groups of neurons and their properties.
- Variables:
has_models –
bool
,True
if every group has amodel
attribute.~nngt.NeuralPop.size –
int
, Returns the number of neurons in the population.syn_spec –
dict
, Dictionary containing informations about the synapses between the different groups in the population.~nngt.NeuralPop.is_valid –
bool
, Whether this population can be used to create a network in NEST.
Initialize NeuralPop instance.
- Parameters:
size (int, optional (default: 0)) – Number of neurons that the population will contain.
parent (
Network
, optional (default: None)) – Network associated to this population.meta_groups (dict of str/
NeuralGroup
items) – Optional set of groups. Contrary to the primary groups which define the population and must be disjoint, meta groups can overlap: a neuron can belong to several different meta groups.with_models (
bool
) – whether the population’s groups contain models to use in NEST*args (items for OrderedDict parent)
**kwargs (
dict
)
- Returns:
pop (
NeuralPop
object.)
- class nngt.SpatialGraph(*args, **kwargs)[source]#
The detailed class that inherits from
Graph
and implements additional properties to describe spatial graphs (i.e. graph where the structure is embedded in space.Initialize SpatialClass instance.
- Parameters:
nodes (int, optional (default: 0)) – Number of nodes in the graph.
name (string, optional (default: “Graph”)) – The name of this
Graph
instance.weighted (bool, optional (default: True)) – Whether the graph edges have weight properties.
directed (bool, optional (default: True)) – Whether the graph is directed or undirected.
shape (
Shape
, optional (default: None)) – Shape of the neurons’ environment (None leads to a square of side 1 cm)positions (
numpy.array
(N, 2), optional (default: None)) – Positions of the neurons; if not specified and nodes is not 0, then neurons will be reparted at random inside theShape
object of the instance.**kwargs (keyword arguments for
Graph
or) –Shape
if no shape was given.
- Returns:
self (
SpatialGraph
)
- class nngt.SpatialNetwork(*args, **kwargs)[source]#
Class that inherits from
Network
andSpatialGraph
to provide a detailed description of a real neural network in space, i.e. with positions and biological properties to interact with NEST.Initialize SpatialNetwork instance.
- Parameters:
name (string, optional (default: “Graph”)) – The name of this
Graph
instance.weighted (bool, optional (default: True)) – Whether the graph edges have weight properties.
directed (bool, optional (default: True)) – Whether the graph is directed or undirected.
shape (
Shape
, optional (default: None)) – Shape of the neurons’ environment (None leads to a square of side 1 cm)positions (
numpy.array
, optional (default: None)) – Positions of the neurons; if not specified and nodes != 0, then neurons will be reparted at random inside theShape
object of the instance.population (class:~nngt.NeuralPop, optional (default: None)) – Population from which the network will be built.
- Returns:
self (
SpatialNetwork
)
- class nngt.Structure(size=None, parent=None, meta_groups=None, **kwargs)[source]#
The basic class that contains groups of nodes and their properties.
- Variables:
Initialize Structure instance.
- Parameters:
size (int, optional (default: 0)) – Number of nodes that the structure will contain.
parent (
Network
, optional (default: None)) – Network associated to this structure.meta_groups (dict of str/
Group
items) – Optional set of groups. Contrary to the primary groups which define the structure and must be disjoint, meta groups can overlap: a neuron can belong to several different meta groups.**kwargs (
dict
)
- Returns:
struct (
Structure
object.)
- nngt.generate(di_instructions, **kwargs)[source]#
Generate a
Graph
or one of its subclasses from adict
containing all the relevant informations.- Parameters:
di_instructions (
dict
) – Dictionary containing the instructions to generate the graph. It must have at least"graph_type"
in its keys, with a value among"distance_rule", "erdos_renyi", "fixed_degree", "newman_watts", "price_scale_free", "random_scale_free"
. Depending on the type, di_instructions should also contain at least all non-optional arguments of the generator function.
See also
- nngt.get_config(key=None, detailed=False)[source]#
Get the NNGT configuration as a dictionary.
Note
This function has no MPI barrier on it.
- nngt.load_from_file(filename, fmt='auto', separator=' ', secondary=';', attributes=None, attributes_types=None, notifier='@', ignore='#', name='LoadedGraph', directed=True, cleanup=False)[source]#
Load a Graph from a file.
Changed in version 2.0: Added optional attributes_types and cleanup arguments.
Warning
Support for GraphML and DOT formats are currently limited and require one of the non-default backends (DOT requires graph-tool).
- Parameters:
filename (str) – The path to the file.
fmt (str, optional (default: “neighbour”)) – The format used to save the graph. Supported formats are: “neighbour” (neighbour list, default if format cannot be deduced automatically), “ssp” (scipy.sparse), “edge_list” (list of all the edges in the graph, one edge per line, represented by a
source target
-pair), “gml” (gml format, default if filename ends with ‘.gml’), “graphml” (graphml format, default if filename ends with ‘.graphml’ or ‘.xml’), “dot” (dot format, default if filename ends with ‘.dot’), “gt” (only when using graph_tool`<http://graph-tool.skewed.de/>_ as library, detected if `filename ends with ‘.gt’).separator (str, optional (default “ “)) – separator used to separate inputs in the case of custom formats (namely “neighbour” and “edge_list”)
secondary (str, optional (default: “;”)) – Secondary separator used to separate attributes in the case of custom formats.
attributes (list, optional (default: [])) – List of names for the attributes present in the file. If a notifier is present in the file, names will be deduced from it; otherwise the attributes will be numbered. For “edge_list”, attributes may also be present as additional columns after the source and the target.
attributes_types (dict, optional (default: str)) – Backup information if the type of the attributes is not specified in the file. Values must be callables (types or functions) that will take the argument value as a string input and convert it to the proper type.
notifier (str, optional (default: “@”)) – Symbol specifying the following as meaningfull information. Relevant information are formatted
@info_name=info_value
, whereinfo_name
is in (“attributes”, “directed”, “name”, “size”) and associatedinfo_value
are of type (list
,bool
,str
,int
). Additional notifiers are@type=SpatialGraph/Network/SpatialNetwork
, which must be followed by the relevant notifiers among@shape
,@structure
, and@graph
.ignore (str, optional (default: “#”)) – Ignore lines starting with the ignore string.
name (str, optional (default: from file information or ‘LoadedGraph’)) – The name of the graph.
directed (bool, optional (default: from file information or True)) – Whether the graph is directed or not.
cleanup (bool, optional (default: False)) – If true, removes nodes before the first one that appears in the edges and after the last one and renumber the nodes from 0.
- Returns:
graph (
Graph
or subclass) – Loaded graph.
- nngt.on_master_process()[source]#
Check whether the current code is executing on the master process (rank 0) if MPI is used.
- Returns:
True if rank is 0, if mpi4py is not present or if MPI is not used,
otherwise False.
- nngt.save_to_file(graph, filename, fmt='auto', separator=' ', secondary=';', attributes=None, notifier='@')[source]#
Save a graph to file.
@todo: implement dot, xml/graphml, and gt formats
- Parameters:
graph (
Graph
or subclass) – Graph to save.filename (str) – The path to the file.
fmt (str, optional (default: “auto”)) – The format used to save the graph. Supported formats are: “neighbour” (neighbour list, default if format cannot be deduced automatically), “ssp” (scipy.sparse), “edge_list” (list of all the edges in the graph, one edge per line, represented by a
source target
-pair), “gml” (gml format, default if filename ends with ‘.gml’), “graphml” (graphml format, default if filename ends with ‘.graphml’ or ‘.xml’), “dot” (dot format, default if filename ends with ‘.dot’), “gt” (only when using graph_tool as library, detected if filename ends with ‘.gt’).separator (str, optional (default “ “)) – separator used to separate inputs in the case of custom formats (namely “neighbour” and “edge_list”)
secondary (str, optional (default: “;”)) – Secondary separator used to separate attributes in the case of custom formats.
attributes (list, optional (default:
None
)) – List of names for the edge attributes present in the graph that will be saved to disk; by default (None
), all attributes will be saved.notifier (str, optional (default: “@”)) – Symbol specifying the following as meaningfull information. Relevant information are formatted
@info_name=info_value
, withinfo_name
in (“attributes”, “attr_types”, “directed”, “name”, “size”). Additional notifiers are@type=SpatialGraph/Network/SpatialNetwork
, which are followed by the relevant notifiers among@shape
,@structure
, and@graph
to separate the sections.
Note
Positions are saved as bytes by
numpy.nparray.tostring()
- nngt.seed(msd=None, seeds=None)[source]#
Seed the random generator used by NNGT (i.e. the numpy RandomState: for details, see
numpy.random.RandomState
).- Parameters:
msd (int, optional) – Master seed for numpy RandomState. Must be convertible to 32-bit unsigned integers.
seeds (list of ints, optional) – Seeds for RandomState (when using MPI). Must be convertible to 32-bit unsigned integers, one entry per MPI process.
- nngt.set_config(config, value=None, silent=False)[source]#
Set NNGT’s configuration.
- Parameters:
config (dict or str) – Either a full configuration dictionary or one key to be set together with its associated value.
value (object, optional (default: None)) – Value associated to config if config is a key.
Examples
>>> nngt.set_config({'multithreading': True, 'omp': 4}) >>> nngt.set_config('multithreading', False)
Notes
See the config file nngt/nngt.conf.default or ~/.nngt/nngt.conf for details about your configuration.
This function has an MPI barrier on it, so it must always be called on all processes.
See also
- nngt.use_backend(backend, reloading=True, silent=False)[source]#
Allows the user to switch to a specific graph library as backend.
Warning
If
Graph
objects have already been created, they will no longer be compatible with NNGT methods.- Parameters:
backend (string) – Name of a graph library among ‘graph_tool’, ‘igraph’, ‘networkx’, or ‘nngt’.
reloading (bool, optional (default: True)) – Whether the graph objects should be reloaded through reload (this should always be set to True except when NNGT is first initiated!)
silent (bool, optional (default: False)) – Whether the changes made to the configuration should be logged at the DEBUG (True) or INFO (False) level.