### Install libsonata from GitHub

Source: https://github.com/bluebrain/libsonata/blob/master/README.rst

Install the libsonata library directly from its GitHub repository using pip.

```shell
pip install git+https://github.com/BlueBrain/libsonata
```

--------------------------------

### Install libsonata from PyPI

Source: https://github.com/bluebrain/libsonata/blob/master/README.rst

Install the libsonata library using pip from the Python Package Index.

```shell
pip install libsonata
```

--------------------------------

### Install Targets

Source: https://github.com/bluebrain/libsonata/blob/master/CMakeLists.txt

Installs the sonata_shared and sonata_static targets, along with header files and CMake configuration files.

```cmake
install(TARGETS sonata_shared sonata_static
    EXPORT sonata-targets
    LIBRARY
        DESTINATION lib
    ARCHIVE
        DESTINATION lib
)

install(DIRECTORY ${SONATA_INCLUDE_DIR}/bbp
    DESTINATION include
)

install(FILES CMake/sonata-config.cmake
    DESTINATION share/sonata/CMake
)

install(EXPORT sonata-targets
    DESTINATION share/sonata/CMake
    NAMESPACE sonata::
)
```

--------------------------------

### Querying Connectivity in Libsonata

Source: https://github.com/bluebrain/libsonata/blob/master/README.rst

Examples of querying source/target nodes and connectivity using Selection objects. These methods help in understanding network connections.

```pycon
# get source / target node ID for the 42nd edge:
>>> population.source_node(42)
>>> population.target_node(42)

# query connectivity (result is Selection object)
>>> selection_to_1 = population.afferent_edges(1)  # all edges with target node_id 1
>>> population.target_nodes(selection_to_1)  # since selection only contains edges
                                                # targeting node_id 1 the result will be a
                                                # numpy array of all 1's
>>> selection_from_2 = population.efferent_edges(2)  # all edges sourced from node_id 2
>>> selection = population.connecting_edges(2, 1)  # this selection is all edges from
                                                      # node_id 2 to node_id 1

# ...or their vectorized analogues
>>> selection = population.afferent_edges([1, 2, 3])
>>> selection = population.efferent_edges([1, 2, 3])
>>> selection = population.connecting_edges([1, 2, 3], [4, 5, 6])
```

--------------------------------

### Retrieving Soma Report Data with get()

Source: https://github.com/bluebrain/libsonata/blob/master/README.rst

Demonstrates how to fetch specific node IDs and time ranges from a SomaReportPopulation, and access the resulting data, times, and IDs.

```pycon
# get a list of all node ids in the selected population
>>> population_somas.get_node_ids()
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20]

# get the DataFrame of the node_id values for the timesteps between tstart and tstop
>>> data_frame = population_somas.get(node_ids=[13, 14], tstart=0.8, tstop=1.0)

# get the data values
>>> data_frame.data
[[13.8, 14.8], [13.9, 14.9]]

# get the list of timesteps
>>> data_frame.times
[0.8, 0.9]

# get the list of node ids
>>> data_frame.ids
[13, 14]
```

--------------------------------

### Manage pybind11 Dependency

Source: https://github.com/bluebrain/libsonata/blob/master/python/CMakeLists.txt

Includes pybind11 either from a submodule or by finding an installed package. This is necessary for building Python extensions with pybind11.

```cmake
if (EXTLIB_FROM_SUBMODULES)
    add_subdirectory(pybind11 EXCLUDE_FROM_ALL)
else()
    find_package(pybind11)
endif()
```

--------------------------------

### Create Selection from Ranges

Source: https://github.com/bluebrain/libsonata/blob/master/README.rst

Instantiate a libsonata.Selection object from a sequence of ranges (pairs of start and end values). This represents contiguous blocks of element IDs.

```python
>>> selection = libsonata.Selection([(1, 4), (5, 6)])
>>> selection.flatten()
[1, 2, 3, 5]
>>> selection.flat_size
4
>>> bool(selection)
True
```

--------------------------------

### Get Node Attribute for a Selection of Nodes

Source: https://github.com/bluebrain/libsonata/blob/master/README.rst

Retrieve attribute values for a specified selection of nodes. The selection can be created using libsonata.Selection.

```python
# ...or Selection of nodes (see below) => returns NumPy array with corresponding values
>>> selection = libsonata.Selection(values=[1, 5, 9, 42])  # nodes 1, 5, 9, 42
>>> mtypes = population.get_attribute('mtype', selection)
>>> list(zip(selection.flatten(), mtypes))
[(1, u'mtype_of_1'), (5, u'mtype_of_5'), (9, u'mtype_of_9'), (42, u'mtype_of_42')]
```

--------------------------------

### Materialize Node Set Selection

Source: https://github.com/bluebrain/libsonata/blob/master/README.rst

Get a libsonata.Selection object representing the nodes that match a specific node set name within a given population.

```python
# get the selection of nodes that match in population
>>> selection = node_sets.materialize('Layer1', population)
```

--------------------------------

### Get Edge Attribute for a Selection of Edges

Source: https://github.com/bluebrain/libsonata/blob/master/README.rst

Retrieve attribute values for a specified selection of edges. The selection can be created using libsonata.Selection.

```python
# ...or Selection of edges => returns NumPy array with corresponding values
>>> selection = libsonata.Selection([1, 5, 9])
>>> population.get_attribute('delay', selection) # returns delays for edges 1, 5, 9
```

--------------------------------

### Get Edge Attribute for Single Edge

Source: https://github.com/bluebrain/libsonata/blob/master/README.rst

Retrieve the attribute value for a specific edge within an EdgePopulation. Requires the attribute name and the edge ID.

```python
# total number of edges in the population
>>> population.size

# attribute names
>>> population.attribute_names

# get attribute value for single edge, say 123
>>> population.get_attribute('delay', 123)
```

--------------------------------

### Get Node Attribute for Single Node

Source: https://github.com/bluebrain/libsonata/blob/master/README.rst

Retrieve the attribute value for a specific node within a NodePopulation. Requires the attribute name and the node ID.

```python
# total number of nodes in the population
>>> population.size

# attribute names
>>> population.attribute_names

# get attribute value for single node, say 42
>>> population.get_attribute('mtype', 42)
```

--------------------------------

### Initialize NodeStorage in Python

Source: https://github.com/bluebrain/libsonata/blob/master/README.rst

Open a SONATA HDF5 file for reading node data. This is the first step to access node populations.

```python
import libsonata

nodes = libsonata.NodeStorage('path/to/H5/file')
```

--------------------------------

### Build libsonata C++ Library

Source: https://github.com/bluebrain/libsonata/blob/master/README.rst

Clone the libsonata repository and build the C++ library using CMake and Make. Ensure to set the C++ standard if necessary.

```shell
git clone git@github.com:BlueBrain/libsonata.git --recursive
cd libsonata
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release -DEXTLIB_FROM_SUBMODULES=ON ..
make -j
```

--------------------------------

### Discover and Configure Tests with Catch2

Source: https://github.com/bluebrain/libsonata/blob/master/tests/CMakeLists.txt

Configures Catch2 to discover and run tests for the 'unittests' executable, setting the working directory for test execution.

```cmake
catch_discover_tests(unittests
    WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
    )
```

--------------------------------

### Reading Soma Report Data with SomaReportReader

Source: https://github.com/bluebrain/libsonata/blob/master/README.rst

Demonstrates how to initialize SomaReportReader and access population names and specific populations from an H5 file.

```pycon
>>> somas = libsonata.SomaReportReader('path/to/H5/file')

# list populations
>>> somas.get_population_names()

# open population
>>> population_somas = somas['<name>']
```

--------------------------------

### Reading Spike Data with SpikeReader

Source: https://github.com/bluebrain/libsonata/blob/master/README.rst

Demonstrates how to initialize SpikeReader and access population names and specific populations from an H5 file.

```pycon
>>> import libsonata

>>> spikes = libsonata.SpikeReader('path/to/H5/file')

# list populations
>>> spikes.get_population_names()

# open population
>>> population = spikes['<name>']
```

--------------------------------

### Accessing Spike Data with SpikePopulation

Source: https://github.com/bluebrain/libsonata/blob/master/README.rst

Shows how to retrieve all spikes, spikes within a time range, and check the sorting order of spike data.

```pycon
# get all spikes [(node_id, timestep)]
>>> population.get()
[(5, 0.1), (2, 0.2), (3, 0.3), (2, 0.7), (3, 1.3)]

# get all spikes betwen tstart and tstop
>>> population.get(tstart=0.2, tstop=1.0)
[(2, 0.2), (3, 0.3), (2, 0.7)]

# get spikes attribute sorting (by_time, by_id, none)
>>> population.sorting
'by_time'
```

--------------------------------

### Initialize EdgeStorage in Python

Source: https://github.com/bluebrain/libsonata/blob/master/README.rst

Open a SONATA HDF5 file for reading edge data. This is analogous to NodeStorage and is the first step to access edge populations.

```python
>>> edges = libsonata.EdgeStorage('path/to/H5/file')

# list populations
>>> edges.population_names

# open population
>>> population = edges.open_population(<name>)
```

--------------------------------

### Configure Version Header

Source: https://github.com/bluebrain/libsonata/blob/master/CMakeLists.txt

Generates a version.cpp file from a template (version.cpp.in) to embed version information into the build.

```cmake
configure_file (
  ${CMAKE_CURRENT_SOURCE_DIR}/src/version.cpp.in
  ${CMAKE_CURRENT_BINARY_DIR}/src/version.cpp
  )
```

--------------------------------

### Include fmt Library

Source: https://github.com/bluebrain/libsonata/blob/master/extlib/CMakeLists.txt

Adds the 'fmt' library as a subdirectory to the project. This is typically used for string formatting utilities.

```cmake
add_subdirectory(fmt)
```

--------------------------------

### Reading Element Report Data with ElementReportReader

Source: https://github.com/bluebrain/libsonata/blob/master/README.rst

Demonstrates how to initialize ElementReportReader and access population names and specific populations from an H5 file.

```pycon
>>> elements = libsonata.ElementReportReader('path/to/H5/file')

# list populations
>>> elements.get_population_names()

# open population
>>> population_elements = elements['<name>']
```

--------------------------------

### Find Required Packages

Source: https://github.com/bluebrain/libsonata/blob/master/CMakeLists.txt

Locates and loads necessary external libraries like Catch2 (for tests), HighFive, fmt, and nlohmann_json. Uses subdirectories if EXT LIB_FROM_SUBMODULES is enabled.

```cmake
if (EXTLIB_FROM_SUBMODULES)
    add_subdirectory(extlib EXCLUDE_FROM_ALL)
else()
    if (SONATA_TESTS)
        find_package(Catch2 REQUIRED)
    endif()
    find_package(HighFive REQUIRED)
    find_package(fmt REQUIRED)
    find_package(nlohmann_json REQUIRED)
endif()
```

--------------------------------

### Project Definition

Source: https://github.com/bluebrain/libsonata/blob/master/CMakeLists.txt

Defines the project name and version. The version is dynamically determined from the Git tag.

```cmake
project(sonata VERSION ${SONATA_VERSION})
```

--------------------------------

### Define Test Source Files

Source: https://github.com/bluebrain/libsonata/blob/master/tests/CMakeLists.txt

Lists the C++ source files that will be compiled as part of the unit tests.

```cmake
set(TESTS_SRC
  main.cpp
  test_config.cpp
  test_edges.cpp
  test_node_sets.cpp
  test_nodes.cpp
  test_report_reader.cpp
  test_selection.cpp
)
```

--------------------------------

### Creating Pandas DataFrame from Spike Data

Source: https://github.com/bluebrain/libsonata/blob/master/README.rst

Illustrates how to convert spike data obtained from Libsonata into a pandas DataFrame for better analysis and visualization.

```pycon
>>> import pandas

data = population.get()
df = pandas.DataFrame(data=data, columns=['ids', 'times']).set_index('times')
print(df)
       ids
times
0.1      5
0.2      2
0.3      3
0.7      2
1.3      3
```

--------------------------------

### Create Unittests Executable

Source: https://github.com/bluebrain/libsonata/blob/master/tests/CMakeLists.txt

Defines the 'unittests' executable target using the previously defined source files.

```cmake
add_executable(unittests ${TESTS_SRC})
```

--------------------------------

### Enable Python Bindings

Source: https://github.com/bluebrain/libsonata/blob/master/CMakeLists.txt

Adds the Python subdirectory for building Python bindings if SONATA_PYTHON is defined.

```cmake
if (SONATA_PYTHON)
    add_subdirectory(python)
endif()
```

--------------------------------

### Include Catch2 Framework

Source: https://github.com/bluebrain/libsonata/blob/master/tests/CMakeLists.txt

Includes the Catch2 testing framework, conditionally based on the EXTLIB_FROM_SUBMODULES variable. This is typically done in extlib/CMakeLists.txt when using submodules.

```cmake
if(NOT EXTLIB_FROM_SUBMODULES)
  # When using submodules `include(.../Catch)` is performed
  # in `extlib/CMakeLists.txt`.
  include(Catch)
endif()
```

--------------------------------

### Tests Build Option

Source: https://github.com/bluebrain/libsonata/blob/master/CMakeLists.txt

Configures whether to build tests for the project. Defaults to ON.

```cmake
option(SONATA_TESTS "Build tests" ON)
```

--------------------------------

### Find and Configure HDF5

Source: https://github.com/bluebrain/libsonata/blob/master/extlib/CMakeLists.txt

Locates the HDF5 library and its include directories, making them available for the project. This is required for HDF5-dependent features.

```cmake
find_package(HDF5 REQUIRED)
add_library(HighFive INTERFACE)
target_include_directories(HighFive INTERFACE
    HighFive/include/
    ${HDF5_INCLUDE_DIRS})
target_link_libraries(HighFive INTERFACE
    ${HDF5_C_LIBRARIES})
```

--------------------------------

### Determine Sonata Version from Git

Source: https://github.com/bluebrain/libsonata/blob/master/CMakeLists.txt

Retrieves the package version using 'git describe --tags' if SONATA_VERSION is not already defined. Handles potential errors during Git command execution.

```cmake
if(NOT SONATA_VERSION)
    execute_process(COMMAND git describe --tags
                    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
                    RESULT_VARIABLE GIT_VERSION_FAILED
                    OUTPUT_VARIABLE GIT_PKG_VERSION_FULL
                    ERROR_VARIABLE GIT_VERSION_ERROR
                    OUTPUT_STRIP_TRAILING_WHITESPACE)
    if(GIT_VERSION_FAILED)
      message(
        FATAL_ERROR
          "Could not retrieve version from command 'git describe --tags'\n"
          ${GIT_VERSION_ERROR})
    endif()

# keep last line of command output
    string(REPLACE "\n"
                   ";"
                   GIT_PKG_VERSION_FULL
                   "${GIT_PKG_VERSION_FULL}")
   list(GET GIT_PKG_VERSION_FULL -1 SONATA_VERSION)
endif()
```

--------------------------------

### Configure libsonata Python Build Directory

Source: https://github.com/bluebrain/libsonata/blob/master/python/CMakeLists.txt

Sets the output directory for the libsonata Python build artifacts.

```cmake
set(SONATA_PYTHON_BUILD ${CMAKE_CURRENT_BINARY_DIR}/libsonata)
```

--------------------------------

### Define Compile Options with Warnings as Errors

Source: https://github.com/bluebrain/libsonata/blob/master/CMakeLists.txt

Sets standard compile options and conditionally adds flags to treat warnings as errors, including specific glibcxx assertions.

```cmake
set(SONATA_COMPILE_OPTIONS -Wall -Wextra -pedantic)
if(SONATA_CXX_WARNINGS)
    set(SONATA_COMPILE_OPTIONS ${SONATA_COMPILE_OPTIONS} -Werror -Wp,-D_GLIBCXX_ASSERTIONS)
endif()
```

--------------------------------

### Add Python Module Target

Source: https://github.com/bluebrain/libsonata/blob/master/python/CMakeLists.txt

Creates the Python extension module named 'sonata_python' using pybind11, compiling the 'bindings.cpp' source file.

```cmake
pybind11_add_module(sonata_python SYSTEM bindings.cpp)
```

--------------------------------

### Load Node Sets from File

Source: https://github.com/bluebrain/libsonata/blob/master/README.rst

Load node set definitions from a JSON file into a libsonata.NodeSets object. This allows querying groups of nodes based on defined criteria.

```python
# load a node set JSON file
>>> node_sets = libsonata.NodeSets.from_file('node_sets.json')

# list node sets
>>> node_sets.names
{'L6_UPC', 'Layer1', 'Layer2', 'Layer3', ....}
```

--------------------------------

### Set Compile Definitions for Sonata Static Library

Source: https://github.com/bluebrain/libsonata/blob/master/CMakeLists.txt

Configures the static library to use fmt as a header-only library.

```cmake
target_compile_definitions(sonata_static
    PRIVATE FMT_HEADER_ONLY=1
)
```

--------------------------------

### Accessing Element Report Properties and Data

Source: https://github.com/bluebrain/libsonata/blob/master/README.rst

Shows how to retrieve time information, node IDs, and fetch specific data for element reports within given time ranges and node IDs.

```pycon
# get times (tstart, tstop, dt)
>>> population_elements.times
(0.0, 4.0, 0.2)

>>> population_elements.get_node_ids()
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20]

# get the DataFrame of the node_id values for the timesteps between tstart and tstop
>>> data_frame = population_elements.get(node_ids=[13, 14], tstart=0.8, tstop=1.0)

# get the data values (list of list of floats with data[time_index][element_index])
>>> data_frame.data
[[46.0, 46.1, 46.2, 46.3, 46.4, 46.5, 46.6, 46.7, 46.8, 46.9], [56.0, 56.1, 56.2, 56.3, 56.4, 56.5, 56.6, 56.7, 56.8, 56.9]]

# get the list of timesteps
>>> data_frame.times
[0.8, 1.0]

# get the list of (node id, element_id)
>>> data_frame.ids
[(13, 30), (13, 30), (13, 31), (13, 31), (13, 32), (14, 32), (14, 33), (14, 33), (14, 34), (14, 34)]
```

--------------------------------

### Link Libraries for Unittests

Source: https://github.com/bluebrain/libsonata/blob/master/tests/CMakeLists.txt

Links the necessary libraries to the 'unittests' executable, including the sonata shared library, HighFive, Catch2, and nlohmann_json.

```cmake
target_link_libraries(unittests
    PRIVATE
    sonata_shared
    HighFive
    Catch2::Catch2
    nlohmann_json::nlohmann_json
)
```

--------------------------------

### Set Version and ABI for Shared Library

Source: https://github.com/bluebrain/libsonata/blob/master/CMakeLists.txt

Assigns the SONATA_VERSION and SONATA_VERSION_ABI to the shared library, crucial for dynamic linking and compatibility.

```cmake
set_target_properties(sonata_shared
    PROPERTIES
        VERSION ${SONATA_VERSION}
        SOVERSION ${SONATA_VERSION_ABI}
)
```

--------------------------------

### Set Include Directories for Sonata Static Library

Source: https://github.com/bluebrain/libsonata/blob/master/CMakeLists.txt

Explicitly sets include directories for the static library, pointing to the interface include directories of its dependencies.

```cmake
target_include_directories(sonata_static
    PRIVATE $<TARGET_PROPERTY:fmt::fmt-header-only,INTERFACE_INCLUDE_DIRECTORIES>
    PRIVATE $<TARGET_PROPERTY:HighFive,INTERFACE_INCLUDE_DIRECTORIES>
    PRIVATE $<TARGET_PROPERTY:nlohmann_json::nlohmann_json,INTERFACE_INCLUDE_DIRECTORIES>
)
```

--------------------------------

### Creating Pandas DataFrame from Element Report Data

Source: https://github.com/bluebrain/libsonata/blob/master/README.rst

Demonstrates using pandas to create a DataFrame from element report data, including data values, IDs, and times, for better data representation.

```pycon
>>> import pandas
```

--------------------------------

### Define Sonata Shared and Static Libraries

Source: https://github.com/bluebrain/libsonata/blob/master/CMakeLists.txt

Creates both shared and static libraries for libsonata using the specified source files. Sets common properties for both targets.

```cmake
set(SONATA_SRC
    src/common.cpp
    src/config.cpp
    src/edge_index.cpp
    src/edges.cpp
    src/hdf5_mutex.cpp
    src/hdf5_reader.cpp
    src/node_sets.cpp
    src/nodes.cpp
    src/population.cpp
    src/report_reader.cpp
    src/selection.cpp
    src/utils.cpp
    ${CMAKE_CURRENT_BINARY_DIR}/src/version.cpp
    )

add_library(sonata_shared SHARED ${SONATA_SRC})
add_library(sonata_static STATIC ${SONATA_SRC})
```

--------------------------------

### Accessing Soma Report Properties

Source: https://github.com/bluebrain/libsonata/blob/master/README.rst

Shows how to retrieve time information, unit attributes, and node ID sorting status from a SomaReportPopulation.

```pycon
# get times (tstart, tstop, dt)
>>> population_somas.times
(0.0, 1.0, 0.1)

# get unit attributes
>>> population_somas.time_units
'ms'
>>> population_somas.data_units
'mV'

# node_ids sorted?
>>> population_somas.sorted
True
```

--------------------------------

### Create Pandas DataFrame from Data, IDs, and Times

Source: https://github.com/bluebrain/libsonata/blob/master/README.rst

This snippet shows how to construct a pandas DataFrame using provided data, multi-index IDs, and time information. It's useful for organizing structured data.

```python
import pandas

df = pandas.DataFrame(data_frame.data, columns=pandas.MultiIndex.from_tuples(data_frame.ids), index=data_frame.times)
print(df)
```

--------------------------------

### Enable Testing and Coverage

Source: https://github.com/bluebrain/libsonata/blob/master/CMakeLists.txt

Enables testing and code coverage if SONATA_TESTS and ENABLE_COVERAGE are defined. Sets up LCOV exclusions for coverage reports.

```cmake
if (SONATA_TESTS)
    enable_testing()
    add_subdirectory(tests)

    if (ENABLE_COVERAGE)
        include(CodeCoverage)
        set(COVERAGE_LCOV_EXCLUDES '/usr/*' '${PROJECT_SOURCE_DIR}/include/*' '${PROJECT_SOURCE_DIR}/extlib/*')
        SETUP_TARGET_FOR_COVERAGE_LCOV(
            NAME coverage
            EXECUTABLE ctest
            DEPENDENCIES unittests
        )
    endif()
endif()
```

--------------------------------

### Python Extensions Option

Source: https://github.com/bluebrain/libsonata/blob/master/CMakeLists.txt

Configures whether to build Python extensions for the project. Defaults to OFF.

```cmake
option(SONATA_PYTHON "Build Python extensions" OFF)
```

--------------------------------

### Extract ABI Version

Source: https://github.com/bluebrain/libsonata/blob/master/CMakeLists.txt

Derives the ABI compatible version (major.minor) from the SONATA_VERSION string.

```cmake
string(REGEX MATCH "^(.*)\\.[^.]*$" dummy ${SONATA_VERSION})
set(SONATA_VERSION_ABI ${CMAKE_MATCH_1})
```

--------------------------------

### Set Target Properties for Sonata Libraries

Source: https://github.com/bluebrain/libsonata/blob/master/CMakeLists.txt

Configures properties like position-independent code, visibility, and output name for both shared and static Sonata libraries. Also sets include directories.

```cmake
foreach(TARGET sonata_shared sonata_static)
    set_target_properties(${TARGET}
        PROPERTIES
            POSITION_INDEPENDENT_CODE ON
            CXX_VISIBILITY_PRESET hidden
            OUTPUT_NAME "sonata"
    )
    target_include_directories(${TARGET}
        PUBLIC
            $<BUILD_INTERFACE:${SONATA_INCLUDE_DIR}>
            $<INSTALL_INTERFACE:include>
    )
    target_compile_options(${TARGET}
        PRIVATE ${SONATA_COMPILE_OPTIONS}
    )

    if (ENABLE_COVERAGE)
        target_compile_options(${TARGET}
            PRIVATE -g -O0 --coverage -fprofile-arcs -ftest-coverage
        )
        target_link_libraries(${TARGET}
            PRIVATE gcov
        )
    endif()

    add_library(sonata::${TARGET} ALIAS ${TARGET})
endforeach(TARGET)
```

--------------------------------

### Access Node Populations

Source: https://github.com/bluebrain/libsonata/blob/master/README.rst

List available population names within a NodeStorage object and open a specific population for further access.

```python
# list populations
>>> nodes.population_names

# open population
>>> population = nodes.open_population(<name>)
```

--------------------------------

### Load Node Sets from JSON String

Source: https://github.com/bluebrain/libsonata/blob/master/README.rst

Create a libsonata.NodeSets object directly from a JSON string, defining node sets programmatically.

```python
# node sets can also be loaded from a JSON string
>>> node_sets_manual = libsonata.NodeSets(json.dumps({"SLM_PPA_and_SP_PC": {"mtype": ["SLM_PPA", "SP_PC"]}}))
>>> node_sets_manual.names
{'SLM_PPA_and_SP_PC'}
```

--------------------------------

### Dependency Management Option

Source: https://github.com/bluebrain/libsonata/blob/master/CMakeLists.txt

Configures whether to use Git submodules for header-only dependencies. Defaults to OFF.

```cmake
option(EXTLIB_FROM_SUBMODULES "Use Git submodules for header-only dependencies" OFF)
```

--------------------------------

### Link Libraries for Python Module

Source: https://github.com/bluebrain/libsonata/blob/master/python/CMakeLists.txt

Links the 'sonata_python' module against its required libraries: 'sonata_static', 'HighFive', 'fmt::fmt-header-only', and 'pybind11::module'. This ensures all necessary components are available at runtime.

```cmake
target_link_libraries(sonata_python
    PRIVATE sonata_static
    PRIVATE HighFive
    PRIVATE fmt::fmt-header-only
    PRIVATE pybind11::module
)
```

--------------------------------

### Link Libraries for Sonata Shared Library

Source: https://github.com/bluebrain/libsonata/blob/master/CMakeLists.txt

Links the shared libsonata library against its required dependencies: HighFive, fmt, and nlohmann_json.

```cmake
target_link_libraries(sonata_shared
    PRIVATE HighFive
    PRIVATE fmt::fmt-header-only
    PRIVATE nlohmann_json::nlohmann_json
)
```

--------------------------------

### Conditionally Include Catch2 for Tests

Source: https://github.com/bluebrain/libsonata/blob/master/extlib/CMakeLists.txt

Includes the Catch2 testing framework if the SONATA_TESTS build option is enabled. This allows for running unit tests.

```cmake
if (SONATA_TESTS)
    add_subdirectory(Catch2)
    include(Catch2/contrib/Catch.cmake)
endif()
```

--------------------------------

### Creating Pandas DataFrame from Soma Report Data

Source: https://github.com/bluebrain/libsonata/blob/master/README.rst

Shows how to create a pandas DataFrame from the data, IDs, and times retrieved from a SomaReportPopulation for enhanced data representation.

```pycon
>>> import pandas

df = pandas.DataFrame(data_frame.data, columns=data_frame.ids, index=data_frame.times)
print(df)
       13    14
0.8  13.8  14.8
0.9  13.9  14.9
```

--------------------------------

### Define Compile Definitions for Sonata Shared Library

Source: https://github.com/bluebrain/libsonata/blob/master/CMakeLists.txt

Adds preprocessor definitions for the shared library, indicating DLL usage and export directives.

```cmake
target_compile_definitions(sonata_shared
    PUBLIC SONATA_DLL
    PRIVATE SONATA_DLL_EXPORTS
)
```

--------------------------------

### Coverage Option Configuration

Source: https://github.com/bluebrain/libsonata/blob/master/CMakeLists.txt

Sets the default for enabling test coverage based on the build type. Debug builds enable coverage by default, others do not.

```cmake
if(CMAKE_BUILD_TYPE STREQUAL "Debug")
  set(SONATA_ENABLE_COVERAGE_DEFAULT ON)
else()
  set(SONATA_ENABLE_COVERAGE_DEFAULT OFF)
endif()
option(SONATA_ENABLE_COVERAGE "Enable measuring test coverage." ${SONATA_ENABLE_COVERAGE_DEFAULT})
```

--------------------------------

### Set Minimum CMake Version

Source: https://github.com/bluebrain/libsonata/blob/master/CMakeLists.txt

Specifies the minimum required version of CMake for this project. Ensures compatibility with required features.

```cmake
cmake_minimum_required(VERSION 3.16)
cmake_policy(VERSION 3.16)
```

--------------------------------

### NodeStorage

Source: https://github.com/bluebrain/libsonata/blob/master/README.rst

Provides access to node data within a SONATA file. Allows listing and opening of node populations.

```APIDOC
## NodeStorage

### Description
Provides access to node data within a SONATA file. Allows listing and opening of node populations.

### Usage
```python
import libsonata

nodes = libsonata.NodeStorage('path/to/H5/file')

# list populations
print(nodes.population_names)

# open population
population = nodes.open_population(<name>)
```

### Attributes
- **population_names**: A list of available node population names.
```

--------------------------------

### NodeSets

Source: https://github.com/bluebrain/libsonata/blob/master/README.rst

Handles the definition and querying of node sets from JSON files or strings, supporting various matching criteria.

```APIDOC
## NodeSets

### Description
Handles the definition and querying of node sets from JSON files or strings, supporting various matching criteria.

### Usage
```python
# Load from a file
node_sets = libsonata.NodeSets.from_file('node_sets.json')
print(node_sets.names)

# Materialize a node set for a given population
selection = node_sets.materialize('Layer1', population)

# Load from a JSON string
node_sets_manual = libsonata.NodeSets(json.dumps({"SLM_PPA_and_SP_PC": {"mtype": ["SLM_PPA", "SP_PC"]}}))
print(node_sets_manual.names)
```

### Attributes
- **names**: A set of available node set names.
```

--------------------------------

### Create Selection from Scalar Values

Source: https://github.com/bluebrain/libsonata/blob/master/README.rst

Instantiate a libsonata.Selection object from a sequence of scalar element IDs. This is useful for selecting specific nodes or edges.

```python
>>> selection = libsonata.Selection([1, 2, 3, 5])
>>> selection.ranges
[(1, 4), (5, 6)]
```

--------------------------------

### Define nlohmann_json Interface Library

Source: https://github.com/bluebrain/libsonata/blob/master/extlib/CMakeLists.txt

Configures the nlohmann_json library as an interface library and creates an alias for easier referencing. This is used for JSON parsing and manipulation.

```cmake
add_library(nlohmann_json INTERFACE)
add_library(nlohmann_json::nlohmann_json ALIAS nlohmann_json)
target_include_directories(nlohmann_json INTERFACE
    nlohmann
    )
```

--------------------------------

### Format Sonata Version

Source: https://github.com/bluebrain/libsonata/blob/master/CMakeLists.txt

Cleans the SONATA_VERSION string to keep only the major.minor.patch format, removing any extra tags or build information.

```cmake
string(REGEX
       REPLACE "v?([0-9]+\\.[0-9]+(\\.[0-9]+)?).*"
               "\\1"
               SONATA_VERSION
               "${SONATA_VERSION}")
```

--------------------------------

### Set CMake Module Path

Source: https://github.com/bluebrain/libsonata/blob/master/CMakeLists.txt

Configures the path where CMake will search for module files. This is typically used to find custom CMake modules.

```cmake
set(CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/CMake)
```

--------------------------------

### EdgeStorage

Source: https://github.com/bluebrain/libsonata/blob/master/README.rst

Provides access to edge data within a SONATA file. Allows listing and opening of edge populations.

```APIDOC
## EdgeStorage

### Description
Provides access to edge data within a SONATA file. Allows listing and opening of edge populations.

### Usage
```python
import libsonata

edges = libsonata.EdgeStorage('path/to/H5/file')

# list populations
print(edges.population_names)

# open population
population = edges.open_population(<name>)
```

### Attributes
- **population_names**: A list of available edge population names.
```

--------------------------------

### NodePopulation

Source: https://github.com/bluebrain/libsonata/blob/master/README.rst

Represents a specific node population within a SONATA file. Allows querying node counts, attributes, and selections.

```APIDOC
## NodePopulation

### Description
Represents a specific node population within a SONATA file. Allows querying node counts, attributes, and selections.

### Usage
```python
# Assuming 'population' is an opened NodePopulation object

# total number of nodes in the population
print(population.size)

# attribute names
print(population.attribute_names)

# get attribute value for single node, say 42
print(population.get_attribute('mtype', 42))

# get attribute values for a selection of nodes
selection = libsonata.Selection(values=[1, 5, 9, 42])
mtypes = population.get_attribute('mtype', selection)
print(list(zip(selection.flatten(), mtypes)))
```

### Attributes
- **size**: The total number of nodes in the population.
- **attribute_names**: A list of available attribute names for nodes in this population.

### Methods
- **get_attribute(attribute_name, node_ids)**: Retrieves the values for the specified attribute for the given node IDs. `node_ids` can be a single ID or a `Selection` object.
```

--------------------------------

### Set C++ Standard Requirement

Source: https://github.com/bluebrain/libsonata/blob/master/CMakeLists.txt

Ensures the C++ standard used for compilation meets a minimum requirement. If the current standard is lower, it causes a fatal error.

```cmake
set(SONATA_CXX_MINIMUM_STANDARD 14)
if(NOT "${CMAKE_CXX_STANDARD}")
  set(CMAKE_CXX_STANDARD ${SONATA_CXX_MINIMUM_STANDARD})
elseif("${CMAKE_CXX_STANDARD}" LESS SONATA_CXX_MINIMUM_STANDARD)
  message(FATAL_ERROR
    "SONATA requires at 'CMAKE_CXX_STANDARD=${SONATA_CXX_MINIMUM_STANDARD}' or newer.")
endif()
set(CMAKE_CXX_STANDARD_REQUIRED ON)
```

--------------------------------

### Selection

Source: https://github.com/bluebrain/libsonata/blob/master/README.rst

Represents a selection of element IDs (nodes or edges), grouped into ranges for efficient access. Can be instantiated from sequences or pairs.

```APIDOC
## Selection

### Description
Represents a selection of element IDs (nodes or edges), grouped into ranges for efficient access. Can be instantiated from sequences or pairs.

### Usage
```python
# From a sequence of scalar values
selection_scalar = libsonata.Selection([1, 2, 3, 5])
print(selection_scalar.ranges)
print(selection_scalar.flatten())
print(selection_scalar.flat_size)
print(bool(selection_scalar))

# From a sequence of pairs (ranges)
selection_ranges = libsonata.Selection([(1, 4), (5, 6)])
print(selection_ranges.flatten())
```

### Attributes
- **ranges**: A list of tuples representing the ranges of selected IDs.
- **flatten**: Returns a flat list of all selected IDs.
- **flat_size**: The total number of individual IDs in the selection.
```

--------------------------------

### Set Python Module Output Name

Source: https://github.com/bluebrain/libsonata/blob/master/python/CMakeLists.txt

Configures the target property 'OUTPUT_NAME' for the 'sonata_python' module to '_libsonata'. This affects the name of the generated shared library file.

```cmake
set_target_properties(sonata_python PROPERTIES
    OUTPUT_NAME "_libsonata"
)
```

--------------------------------

### EdgePopulation

Source: https://github.com/bluebrain/libsonata/blob/master/README.rst

Represents a specific edge population within a SONATA file. Allows querying edge counts, attributes, and selections.

```APIDOC
## EdgePopulation

### Description
Represents a specific edge population within a SONATA file. Allows querying edge counts, attributes, and selections.

### Usage
```python
# Assuming 'population' is an opened EdgePopulation object

# total number of edges in the population
print(population.size)

# attribute names
print(population.attribute_names)

# get attribute value for single edge, say 123
print(population.get_attribute('delay', 123))

# get attribute values for a selection of edges
selection = libsonata.Selection([1, 5, 9])
print(population.get_attribute('delay', selection))
```

### Attributes
- **size**: The total number of edges in the population.
- **attribute_names**: A list of available attribute names for edges in this population.

### Methods
- **get_attribute(attribute_name, edge_ids)**: Retrieves the values for the specified attribute for the given edge IDs. `edge_ids` can be a single ID or a `Selection` object.
```

--------------------------------

### Improve Performance with NumPy Arrays

Source: https://github.com/bluebrain/libsonata/blob/master/README.rst

For large datasets, converting data to numpy arrays before creating a pandas DataFrame can significantly improve performance. This snippet demonstrates the conversion process.

```pycon
>>> import numpy

np_data = numpy.asarray(data_frame.data)
np_ids = numpy.asarray(data_frame.ids).T
np_times = numpy.asarray(data_frame.times)

df = pandas.DataFrame(np_data, columns=pandas.MultiIndex.from_arrays(np_ids), index=np_times)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.