bluepysnap.nodes.node_population¶

Node population access.

Group Concept¶

A Group is a flexible way to address a series of node IDs, it can take the form of:

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.

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' }]})

See more examples in NodePopulation::get

Classes

NodePopulation(circuit, population_name)

Node population access.

class bluepysnap.nodes.node_population.NodePopulation(circuit, population_name)¶

Node population access.

Initializes a NodePopulation object.

Parameters:

circuit (bluepysnap.Circuit) – the circuit object containing the node population
population_name (str) – the name of the node population

Returns:

A NodePopulation object.

Return type:

NodePopulation

property config¶

Access the configuration for the population.

This configuration is extended with:

‘components’ of the circuit config
‘nodes_file’: the path the h5 file containing the population.

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) – see Group Concept
properties (list|str|None) – If specified, return only the properties in the list. Otherwise, return all the 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))

property h5_filepath¶: Get the H5 nodes file associated with population.

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) – See Group Concept
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

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

spatial_segment_index¶: Access to edges spatial index.

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.