bluepysnap.nodes¶

Node population access.

Classes

`NodePopulation`(node_storage, population_name)	Node population access.
`NodeStorage`(config, circuit)	Node storage access.
`Nodes`(circuit)	The top level Nodes accessor.

class bluepysnap.nodes.NodePopulation(node_storage, population_name, population_config=None)¶

Node population access.

Initializes a NodePopulation object from a NodeStorage and population name.

Parameters

node_storage (NodeStorage) – the node storage containing the node population
population_name (str) – the name of the node population
population_config (dict) – the config for the population

Returns

A NodePopulation object.

Return type

NodePopulation

config¶: Population config dictionary combined with the components dictionary.

container_property_names(container)¶

Lists the ConstContainer properties shared with the NodePopulation.

Parameters

container (ConstContainer) – a container class for node properties.

Returns

A list of strings corresponding to the properties that you can use from the: container class

Return type

list

Examples

>>> from bluepysnap.sonata_constants import Node
>>> print(my_node_population.container_property_names(Node))
>>> ["X", "Y", "Z"] # values from Node that you can use with my_node_population
>>> my_node_population.property_values(Node.X)
>>> my_node_population.property_values(Node.get("X"))

count(group=None)¶

Total number of nodes for a given node group.

Parameters

group (int/CircuitNodeId/CircuitNodeIds/sequence/str/mapping/None) –

Which nodes will have their positions returned depends on the type of the group argument:

int, CircuitNodeId: return the count of a single node.
CircuitNodeIds return the count of nodes from a NodeCircuitNodeIds.
sequence: return the count of nodes from a list of node IDs.
str: return the count of nodes in a node set.
mapping: return count of nodes matching a properties filter.
None: return the count of all nodes.

Returns

The total number of nodes in a given group.

Return type

int

get(group=None, properties=None)¶

Node properties as a pandas Series or DataFrame.

Parameters

group (int/CircuitNodeId/CircuitNodeIds/sequence/str/mapping/None) –
Which nodes will have their properties returned depends on the type of the group argument:
- int, CircuitNodeId: return the properties of a single node.
- CircuitNodeIds return the properties from a NodeCircuitNodeIds.
- sequence: return the properties from a list of node.
- str: return the properties of nodes in a node set.
- mapping: return the properties of nodes matching a properties filter.
- None: return the properties of all nodes.
properties (list|str|None) – If specified, return only the properties in the list. Otherwise return all properties.

Returns

The type of the returned object depends on the type of the input parameters, see the Examples for an explanation of the different cases.

Return type

value/pandas.Series/pandas.DataFrame

Notes

The NodePopulation.property_names function will give you all the usable properties for the properties argument.

Examples

Considering a node population composed by 3 nodes (0, 1, 2) and 12 properties, the following examples show the types of the returned objects.

If group is a single node ID and properties a single property, returns a single scalar value.

>>> result = my_node_population.get(group=0, properties=Cell.MTYPE)
>>> type(result)
str

If group is a single node ID and properties a list or None, returns a pandas Series indexed by the properties.

>>> result = my_node_population.get(group=0)
>>> type(result), result.shape
(pandas.core.series.Series, (12,))

>>> result = my_node_population.get(group=0, properties=[Cell.MTYPE])
>>> type(result), result.shape
(pandas.core.series.Series, (1,))

If group is anything other than a single node ID, and properties is a single property, returns a pandas Series indexed by node IDs.

>>> result = my_node_population.get(properties=Cell.MTYPE)
>>> type(result), result.shape
(pandas.core.series.Series, (3,))

>>> result = my_node_population.get(group=[0], properties=Cell.MTYPE)
>>> type(result), result.shape
(pandas.core.series.Series, (1,))

In all the other cases, returns a pandas DataFrame indexed by node IDs.

>>> result = my_node_population.get()
>>> type(result), result.shape
(pandas.core.frame.DataFrame, (3, 12))

>>> result = my_node_population.get(group=[0])
>>> type(result), result.shape
(pandas.core.frame.DataFrame, (1, 12))

>>> result = my_node_population.get(properties=[Cell.MTYPE])
>>> type(result), result.shape
(pandas.core.frame.DataFrame, (3, 1))

>>> result = my_node_population.get(group=[0], properties=[Cell.MTYPE])
>>> type(result), result.shape
(pandas.core.frame.DataFrame, (1, 1))

ids(group=None, limit=None, sample=None, raise_missing_property=True)¶

Node IDs corresponding to node group.

Parameters

group (int/CircuitNodeId/CircuitNodeIds/sequence/str/mapping/None) –
Which IDs will be returned depends on the type of the group argument:
- int, CircuitNodeId: return a single node ID if it belongs to the circuit.
- CircuitNodeIds return IDs of nodes from the node population in an array.
- sequence: return IDs of nodes in an array.
- str: return IDs of nodes in a node set.
- mapping: return IDs of nodes matching a properties filter.
- None: return all node IDs.
If group is a sequence, the order of results is preserved. Otherwise the result is sorted and contains no duplicates.
sample (int) – If specified, randomly choose sample number of IDs from the match result. If the size of the sample is greater than the size of the NodePopulation then all ids are taken and shuffled.
limit (int) – If specified, return the first limit number of IDs from the match result. If limit is greater than the size of the population all node IDs are returned.
raise_missing_property (bool) – if True, raises if a property is not listed in this population. Otherwise the ids are just not selected if a property is missing.

Returns

A numpy array of IDs.

Return type

numpy.array

Examples

The available group parameter values:

>>> nodes.ids(group=None)  #  returns all IDs
>>> nodes.ids(group={})  #  returns all IDs
>>> nodes.ids(group=1)  #  returns the single ID if present in population
>>> #  returns the single ID if present in population and the circuit id population
>>> #  corresponds to nodes.name
>>> nodes.ids(group=CircuitNodeId('pop', 1))
>>> nodes.ids(group=[1,2,3])  # returns list of IDs if all present in population
>>> #  returns list of IDs if all present in population
>>> nodes.ids(group=CircuitNodeIds.from_dict({"pop": [0, 1,2]}))
>>> nodes.ids(group="node_set_name")  # returns list of IDs matching node set
>>> nodes.ids(group={ Node.LAYER: 2})  # returns list of IDs matching layer==2
>>> nodes.ids(group={ Node.LAYER: [2, 3]})  # returns list of IDs with layer in [2,3]
>>> nodes.ids(group={ Node.X: (0, 1)})  # returns list of IDs with 0 < x < 1
>>> # returns list of IDs matching one of the queries inside the 'or' list
>>> nodes.ids(group={'$or': [{ Node.LAYER: [2, 3]},
>>>                          { Node.X: (0, 1), Node.MTYPE: 'L1_SLAC' }]})
>>> # returns list of IDs matching all the queries inside the 'and' list
>>> nodes.ids(group={'$and': [{ Node.LAYER: [2, 3]},
>>>                           { Node.X: (0, 1), Node.MTYPE: 'L1_SLAC' }]})

models¶: Access to node neuron models.

morph¶: Access to node morphologies.

orientations(group=None)¶

Node orientation(s) as a pandas numpy array or pandas Series.

Parameters

group (int/CircuitNodeId/CircuitNodeIds/sequence/str/mapping/None) –

Which nodes will have their positions returned depends on the type of the group argument:

int, CircuitNodeId: return the orientation of a single node.
CircuitNodeIds return the orientation from a NodeCircuitNodeIds.
sequence: return the orientations from a list of node IDs.
str: return the orientations of nodes in a node set.
mapping: return the orientations of nodes matching a properties filter.
None: return the orientations of all nodes.

Returns

A 3x3 rotation matrix if a single node ID is passed as group. Otherwise a pandas Series with rotation matrices indexed by node IDs.

Return type

numpy.ndarray/pandas.Series

positions(group=None)¶

Node position(s) as pandas Series or DataFrame.

Parameters

group (int/CircuitNodeId/CircuitNodeIds/sequence/str/mapping/None) –

Which nodes will have their positions returned depends on the type of the group argument:

int, CircuitNodeId: return the position of a single node.
CircuitNodeIds return the position from a NodeCircuitNodeIds.
sequence: return the positions from a list of node IDs.
str: return the positions of nodes in a node set.
mapping: return the positions of nodes matching a properties filter.
None: return the positions of all nodes.

Returns

Series of (‘x’, ‘y’, ‘z’) if single node ID is

passed as group. Otherwise, a pandas.DataFrame of (‘x’, ‘y’, ‘z’) indexed by node IDs.

Return type

pandas.Series/pandas.DataFrame

property_dtypes¶

Returns the dtypes of all the properties.

Returns: series indexed by field name with the corresponding dtype as value.
Return type: pandas.Series

property property_names¶

Set of available node properties.

Notes

Properties are a combination of the group attributes and the dynamics_params.

property_values(prop, is_present=False)¶

Set of values for a given property.

Parameters

prop (str) – Name of the property to retrieve.
is_present (bool) – if the field is categorical it forces the values to be actually
(see (present inside the dataset.) – Notes for more information).

Returns

A set of the unique values of the property in the node population.

Return type

set

Notes

For categorical fields returning ‘unique’ values can be confusing, see: https://pandas.pydata.org/pandas-docs/stable/user_guide/categorical.html in #working-with-categories. The is_present argument forces the unique() even on the categorical fields.

size¶: Node population size.

source_in_edges()¶

Set of edge population names that use this node population as source.

Returns: a set containing the names of edge populations using this NodePopulation as source.
Return type: set

target_in_edges()¶

Set of edge population names that use this node population as target.

Returns: a set containing the names of edge populations using this NodePopulation as target.
Return type: set

property type¶: Population type.

class bluepysnap.nodes.NodeStorage(config, circuit)¶

Node storage access.

Initializes a NodeStorage object from a node config and a Circuit.

Parameters

config (dict) – a node config from the global circuit config
circuit (bluepysnap.Circuit) – the circuit object that contains the NodePopulation
storage. (from this) –

Returns

A NodeStorage object.

Return type

NodeStorage

property circuit¶: Returns the circuit object containing this storage.

property csv_filepath¶: Returns the csv filepath of the Storage.

property h5_filepath¶: Returns the filepath of the Storage.

load_population_data(population)¶

Load node properties from SONATA Nodes.

Parameters: population (str) – a population name .
Returns: pandas.DataFrame with node properties (zero-based index).

population(population_name)¶: Access the different populations from the storage.

population_names¶: Returns all population names inside this file.

property storage¶: Access to the libsonata node storage.

class bluepysnap.nodes.Nodes(circuit)¶

The top level Nodes accessor.

Initialize the top level Nodes accessor.

get(group=None, properties=None)¶

Node properties as a pandas DataFrame.

Parameters

group (CircuitNodeIds/int/sequence/str/mapping/None) – Which nodes will have their properties returned depends on the type of the group argument: See ids.
properties (str/list) – If specified, return only the properties in the list. Otherwise return all properties.

Returns

Return a pandas DataFrame indexed by NodeCircuitIds containing the: properties from properties.

Return type

pandas.DataFrame

Notes

The NodePopulation.property_names function will give you all the usable properties for the properties argument.

ids(group=None, sample=None, limit=None)¶

Returns the CircuitNodeIds corresponding to the nodes from group.

Parameters

group (CircuitNodeId/CircuitNodeIds/int/sequence/str/mapping/None) – Which IDs will be
argument (returned depends on the type of the group) –
- CircuitNodeId: return the ID in a CircuitNodeIds object if it belongs to
  the circuit.
- CircuitNodeIds: return the IDs in a CircuitNodeIds object if they belong to
  the circuit.
- int: if the node ID is present in all populations, returns a CircuitNodeIds
  object containing the corresponding node ID for all populations.
- sequence: if all the values contained in the sequence are present in all
  populations, returns a CircuitNodeIds object containing the corresponding node IDs for all populations.
- str: use a node set name as input. Returns a CircuitNodeIds object containing
  nodes selected by the node set.
- mapping: Returns a CircuitNodeIds object containing nodes matching a
  properties filter.
- None: return all node IDs of the circuit in a CircuitNodeIds object.
sample (int) – If specified, randomly choose sample number of IDs from the match result. If the size of the sample is greater than the size of all the NodePopulations then all ids are taken and shuffled.
limit (int) – If specified, return the first limit number of IDs from the match result. If limit is greater than the size of all the populations, all node IDs are returned.

Returns

returns a CircuitNodeIds containing all the node IDs and the: corresponding populations. All the explicitly requested IDs must be present inside the circuit.

Return type

CircuitNodeIds

Raises

BluepySnapError – when a population from a CircuitNodeIds is not present in the circuit.
BluepySnapError – when an id query via a int, sequence, or CircuitNodeIds is not present in the circuit.

Examples

The available group parameter values (example with 2 node populations pop1 and pop2):

>>> nodes = circuit.nodes
>>> nodes.ids(group=None)  #  returns all CircuitNodeIds from the circuit
>>> node_ids = CircuitNodeIds.from_arrays(["pop1", "pop2"], [1, 3])
>>> nodes.ids(group=node_ids)  #  returns ID 1 from pop1 and ID 3 from pop2
>>> nodes.ids(group=0)  #  returns CircuitNodeIds 0 from pop1 and pop2
>>> nodes.ids(group=[0, 1])  #  returns CircuitNodeIds 0 and 1 from pop1 and pop2
>>> nodes.ids(group="node_set_name")  # returns CircuitNodeIds matching node set
>>> nodes.ids(group={Node.LAYER: 2})  # returns CircuitNodeIds matching layer==2
>>> nodes.ids(group={Node.LAYER: [2, 3]})  # returns CircuitNodeIds with layer in [2,3]
>>> nodes.ids(group={Node.X: (0, 1)})  # returns CircuitNodeIds with 0 < x < 1
>>> # returns CircuitNodeIds matching one of the queries inside the 'or' list
>>> nodes.ids(group={'$or': [{ Node.LAYER: [2, 3]},
>>>                          { Node.X: (0, 1), Node.MTYPE: 'L1_SLAC' }]})
>>> # returns CircuitNodeIds matching all the queries inside the 'and' list
>>> nodes.ids(group={'$and': [{ Node.LAYER: [2, 3]},
>>>                           { Node.X: (0, 1), Node.MTYPE: 'L1_SLAC' }]})

items()¶

Returns iterator on the tuples (population name, NodePopulations).

Made to simulate the behavior of a dict.items().

keys()¶

Returns iterator on the NodePopulation names.

Made to simulate the behavior of a dict.keys().

property_values(prop)¶: Returns all the values for a given Nodes property.

values()¶

Returns iterator on the NodePopulations.

Made to simulate the behavior of a dict.values().