### Example Notebook Dependencies

Source: https://github.com/openbraininstitute/obi-one/blob/main/README.md

Command to install dependencies required for running example notebooks.

```bash
make install-notebooks
```

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

### Installation - Full Setup for Development

Source: https://github.com/openbraininstitute/obi-one/blob/main/README.md

Installs all dependencies plus development tools like pytest and ruff.

```bash
make install-dev
```

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

### Deserialization example (commented out)

Source: https://github.com/openbraininstitute/obi-one/blob/main/projects/tiny_circuits/circuit_simulations.ipynb

A commented-out example showing how to deserialize an obi_one object from a JSON file.

```python
# Deserialization
# grid_scan_ds = obi.deserialize_obi_object_from_json_file("../../../obi-output/tiny_circuit_simulations/grid_scan/obi_one_scan.json")
```

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

### Install BlueRecording

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/K_create_recording_array/create_recording_array.ipynb

Clones the BlueRecording repository, checks out the specified branch, and runs the development setup script.

```bash
git clone https://github.com/openbraininstitute/BlueRecording.git
cd BlueRecording
git checkout katta/circuit-config-support
./dev_setup.sh
source env.sh
```

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

### Documentation - Install Dependencies

Source: https://github.com/openbraininstitute/obi-one/blob/main/README.md

Installs MkDocs and MkDocs Material theme dependencies for documentation.

```bash
make install-docs
```

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

### Get simulation configuration path and circuit folder

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/E_run_small_microcircuit/run_circuit_simulation.ipynb

Retrieves the path to the generated simulation configuration file and the directory containing the SONATA circuit files.

```python
# population_name = circuit.default_population_name
simulation_config_path = grid_scan.single_configs[0].coordinate_output_root / "simulation_config.json"
print(simulation_config_path)

circuit_folder = grid_scan.single_configs[0].coordinate_output_root / "sonata_circuit"
```

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

### Deserialization Example (Commented Out)

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/C_forms/circuit_simulation/circuit_simulations_example.ipynb

Example of deserializing an OBI object from a JSON file (currently commented out).

```python
# Deserialization
# grid_scan_ds = obi.deserialize_obi_object_from_json_file("../../../../obi-output/circuit_simulations/grid_scan_vpm_hardcoded/obi_one_scan.json")
```

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

### Initialize client and get circuit metrics with basic level of detail

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/G_circuit_metrics/circuit_metrics_example.ipynb

Initializes the entity client and retrieves circuit metrics with a basic level of detail for nodes and edges.

```python
from entitysdk.client import Client
from obi_one.scientific.library import circuit_metrics
from obi_one.scientific.library.circuit_metrics import CircuitStatsLevelOfDetail, ALL_POPULATIONS

subdomain = "www"
url = f"https://{subdomain}.openbraininstitute.org/api/entitycore"

db_client = Client(project_context=project_context, token_manager=token, environment=environment_)

lod_nodes = {ALL_POPULATIONS: CircuitStatsLevelOfDetail.basic}
lod_edges = {ALL_POPULATIONS: CircuitStatsLevelOfDetail.basic}

metrics = circuit_metrics.get_circuit_metrics(circuit_id=circuit_ids[0],
                                              level_of_detail_nodes=lod_nodes,
                                              level_of_detail_edges=lod_edges,
                                              db_client=db_client)

```

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

### Installation - Core + Science Dependencies

Source: https://github.com/openbraininstitute/obi-one/blob/main/README.md

Installs everything needed for running tasks and data processing scripts.

```bash
make install
```

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

### Installation - Specific Use Cases

Source: https://github.com/openbraininstitute/obi-one/blob/main/README.md

Commands for installing dependencies for service deployment, notebook development, or production builds.

```bash
make install-service
```

```bash
make install-notebooks
```

```bash
make install-all
```

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

### Install All Dependencies (Production Build)

Source: https://github.com/openbraininstitute/obi-one/blob/main/docs/index.md

Installs all dependencies without development tools for a production build.

```bash
make install-all
```

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

### Retrieve and Stage Simulation

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/A_service_and_entitycore/circuit_simulation/entitysdk_circuit_simulations.ipynb

Example of retrieving simulation entities, downloading assets, and staging the simulation.

```python
from entitysdk.models import SimulationCampaign, Simulation
simulation_campaign = db_client.get_entity(entity_id=simulation_campaign_id, entity_type=SimulationCampaign)
simulation = db_client.get_entity(entity_id=simulation_campaign.simulations[0].id, entity_type=Simulation)

for asset in simulation.assets:
    if asset.content_type == "application/json":
        if asset.label == 'sonata_simulation_config':
            # Download the content into memory
            content = db_client.download_file(
                entity_id=simulation.id,
                entity_type=Simulation,
                asset_id=asset.id,
                output_path='simulation_config.json'
            )

from pathlib import Path
from entitysdk.staging.simulation import stage_simulation
stage_simulation(client=db_client, model=simulation, output_dir=Path('temp_sim'), circuit_config_path=Path("../temp_circ/circuit_config.json"))
```

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

### Install obi-one

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/K_create_recording_array/create_recording_array.ipynb

Installs obi-one in editable mode with notebook dependencies, assuming the BlueRecording environment is active.

```bash
pip install -e ".[notebooks]"
```

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

### Circuit Simulation Configuration Example

Source: https://github.com/openbraininstitute/obi-one/blob/main/docs/scircuit.md

An example of how to configure a small circuit simulation using `CircuitSimulationSingleConfig`.

```python
from obi_one import CircuitSimulationSingleConfig, CircuitFromID, AllNeurons

config = CircuitSimulationSingleConfig(
    initialize=CircuitSimulationSingleConfig.Initialize(
        circuit=CircuitFromID(id="..."),
        node_set=NeuronSetReference(block_dict_name="neuron_sets", block_name="All Biophys"),
        simulation_length=3000.0,  # ms
        v_init=-80.0,  # mV
        extracellular_calcium_concentration=1.1,  # mM
        random_seed=1
    ),
    neuron_sets={
        "All Biophys": AllNeurons(sample_percentage=100.0, sample_seed=1)
    },
    stimuli={...},
    recordings={...},
    synaptic_manipulations={...},
    parameter_modifications={...},
    timestamps={...}
)
```

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

### Pre-installation Requirements

Source: https://github.com/openbraininstitute/obi-one/blob/main/README.md

Required package installations using Homebrew.

```bash
brew install uv open-mpi boost cmake
```

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

### Campaign Specification Example

Source: https://github.com/openbraininstitute/obi-one/blob/main/projects/sim_campaign_upload/register_sim_campaigns.ipynb

Example dictionary defining a simulation campaign's metadata, including names, paths, and associated circuit.

```python
# Campaign info & metadata
sim_campaign = {
    "campaign_name": "BBP-SM-whisker-soma",
    "campaign_description": "BBP campaign consisting of a single simulation of the nbS1-O1-SM (Schneider-Mizell) circuit with whisker flick stimulation on VPM fibers, incl. soma recording.",
    "folder_name": "SM-whisker-soma",
    "campaign_config": "config.json",
    "gpfs_path": "/gpfs/bbp.cscs.ch/project/proj83/home/isbister/simulations/elife_sscx_physiology_2024/9-SchneiderMizell/2_whisker_deflections_soma/2_whisker_deflections_soma_0__19_11_24",
    "aws_path": "Simulation_data/Simulation_Campaigns/Rat/SSCx/f132b97aa0",
    "aws_inputs": "e6efa007-e7fa-42ae-ae3d-53385ec57154",  # Subfolder with spike replay inputs
    "circuit": "nbS1-O1-SM"
}

# sim_campaign = {
#     "campaign_name": "BBP-SM-whisker-scan",
#     "campaign_description": "BBP campaign consisting of 72 simulations of the nbS1-O1-SM (Schneider-Mizell) circuit with whisker flick stimulation on VPM fibers, scanned over different values of calcium, Ornstein-Uhlenbeck std to mean ratio R_OU, in-vivo firing rate proportion P_FR, and percentage of VPM fibers. Related publication: Isbister et al., 2025 (DOI: 10.7554/eLife.99693.2)",
#     "folder_name": "SM-whisker-scan",
#     "campaign_config": "config.json",
#     "gpfs_path": "/gpfs/bbp.cscs.ch/project/proj83/home/isbister/simulations/elife_sscx_physiology_2024/9-SchneiderMizell/1_whisker_deflections/1_3_whisker_deflections_scan_16_4_24",
#     "aws_path": "staging/Simulation_data/Simulation_Campaigns/Rat/SSCx/3f6517825f",
#     "aws_inputs": "518fbeaf-f0ba-4f99-a0ff-22cb7e89eed7",  # Subfolder with spike replay inputs
#     "circuit": "nbS1-O1-SM"
# }

# sim_campaign = {
#     "campaign_name": "BBP-SM-recalib",
#     "campaign_description": "BBP campaign consisting of 60 simulations of the nbS1-O1-SM (Schneider-Mizell) circuit with 6.5s spontaneous activity, scanned over different values of calcium, Ornstein-Uhlenbeck std to mean ratio R_OU, and in-vivo firing rate proportion P_FR. Related publication: Isbister et al., 2025 (DOI: 10.7554/eLife.99693.2)",
#     "folder_name": "SM-recalib",
#     "campaign_config": "config.json",
#     "gpfs_path": "/gpfs/bbp.cscs.ch/project/proj83/home/isbister/simulations/elife_sscx_physiology_2024/9-SchneiderMizell/0_recalibration/0_0_recalibration_6thIter_20_3_24",
#     "aws_path": "Simulation_data/Simulation_Campaigns/Rat/SSCx/09151af2d2",
#     "aws_inputs": None,  # Subfolder with spike replay inputs
#     "circuit": "nbS1-O1-SM"
# }

```

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

### Initialize SDK and Client

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/A_service_and_entitycore/circuit_simulation/entitysdk_circuit_simulations.ipynb

Imports necessary libraries and initializes the OBI SDK and EntitySDK client for staging test environment.

```python
import requests
import obi_one as obi
virtual_lab_id=obi.LAB_ID_STAGING_TEST
project_id=obi.PROJECT_ID_STAGING_TEST
from entitysdk import Client, ProjectContext

from obi_auth import get_token
from obi_notebook import get_projects

obi_one_api_url = "http://127.0.0.1:8100"

token = get_token(environment="staging")
project_context = ProjectContext(virtual_lab_id=obi.LAB_ID_STAGING_TEST, project_id=obi.PROJECT_ID_STAGING_TEST)
db_client = Client(api_url="https://staging.openbraininstitute.org/api/entitycore", project_context=project_context, token_manager=token)
```

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

### Import necessary libraries and set up the environment

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/E_run_small_microcircuit/run_circuit_simulation.ipynb

Imports libraries for making requests, interacting with obi-one, and setting up project context and authentication.

```python
import requests
import obi_one as obi
virtual_lab_id=obi.LAB_ID_STAGING_TEST
project_id=obi.PROJECT_ID_STAGING_TEST
from entitysdk import Client, ProjectContext

from obi_auth import get_token

obi_one_api_url = "http://127.0.0.1:8100"

token = get_token(environment="staging")
project_context = ProjectContext(virtual_lab_id=obi.LAB_ID_STAGING_TEST, project_id=obi.PROJECT_ID_STAGING_TEST)
db_client = Client(api_url="https://staging.openbraininstitute.org/api/entitycore", project_context=project_context, token_manager=token)
```

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

### Get authentication token

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/G_circuit_metrics/connectivity_metrics_example.ipynb

Retrieves an authentication token for the specified environment.

```python
token = obi_auth.get_token(environment=environment)
```

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

### Initial Setup

Source: https://github.com/openbraininstitute/obi-one/blob/main/projects/benchmarks/circuit_extraction_benchmarks.ipynb

Imports necessary libraries and sets up environment variables, clients, and headers for interacting with the obi-one service.

```python
import httpx
import obi_one as obi
from entitysdk import Client, ProjectContext, models
from http import HTTPStatus

environment = "staging"
virtual_lab_id = obi.LAB_ID_STAGING_TEST
project_id = obi.PROJECT_ID_STAGING_TEST

token = "<PASTE-HERE>"

# Get DB client
project_context = ProjectContext(virtual_lab_id=virtual_lab_id, project_id=project_id)
db_client = Client(environment=environment, project_context=project_context, token_manager=token)

# Get obi-one API client
OBI_ONE_API_URL = "http://127.0.0.1:8100"
headers = {
    "Authorization": f"Bearer {token}",
    "virtual-lab-id": virtual_lab_id,
    "project-id": project_id,
}
api_client = httpx.Client(base_url=OBI_ONE_API_URL, headers=headers)
```

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

### Get circuit IDs

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/G_circuit_metrics/connectivity_metrics_example.ipynb

Retrieves circuit IDs with specific columns and filtering options.

```python
circuit_ids = get_entities.get_entities(
    "circuit",
    token,
    result=[],
    return_entities=False,
    multi_select=False,
    show_pages=True,
    project_context=project_context,
    page_size=10,
    default_scale="small",
    exclude_scales=["single"],
    add_columns=["subject.name"],
    env=environment
)
```

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

### Documentation - Serve Locally

Source: https://github.com/openbraininstitute/obi-one/blob/main/README.md

Builds and serves the documentation locally for preview.

```bash
make serve-docs
```

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

### Get project context

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/G_circuit_metrics/connectivity_metrics_example.ipynb

Retrieves project context information using the authentication token.

```python
project_context = get_projects.get_projects(token, env=environment)
```

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

### Run Analysis from File

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/D_blueetl_example/blueetl_example.ipynb

This snippet shows how to run an analysis campaign using a configuration file and set the log level.

```python
from blueetl.analysis import run_from_file
analysis_config_file = "analysis_config_01_relative_with_soma.yaml"
loglevel = "INFO"
ma = run_from_file(analysis_config_file, loglevel=loglevel)
# ma = ma.apply_filter()
```

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

### Get circuit metrics with no edge detail

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/G_circuit_metrics/circuit_metrics_example.ipynb

Retrieves circuit metrics with the level of detail for edges set to 'none'.

```python
lod_edges = {ALL_POPULATIONS: CircuitStatsLevelOfDetail.none}

metrics = circuit_metrics.get_circuit_metrics(circuit_id=circuit_ids[0],
                                              db_client=db_client, level_of_detail_edges=lod_edges)

```

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

### Get connectivity metrics

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/G_circuit_metrics/connectivity_metrics_example.ipynb

Calculates connectivity metrics based on the selected circuit, edge population, and neuron selections.

```python
conn_output = connectivity_metrics.get_connectivity_metrics(
    circuit_id=circuit_ids[0],
    db_client=db_client,
    edge_population=e_popul_wdgt.value,
    pre_selection=pre_selection,
    pre_node_set=pre_node_set,
    post_selection=post_selection,
    post_node_set=post_node_set,
    group_by=group_by,
    max_distance=max_distance
)
```

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

### Import necessary libraries and set up environment variables

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/A_service_and_entitycore/ion_channel_modeling/ion_channel_modeling_example.ipynb

Imports libraries from obi_one, entitysdk, and obi_auth, and sets up staging environment variables and project context.

```python
import obi_one as obi
from obi_one.core.info import Info
from obi_one.scientific.from_id.ion_channel_recording_from_id import IonChannelRecordingFromID
from obi_one.scientific.blocks import ion_channel_equations
from obi_one.scientific.tasks import ion_channel_modeling
virtual_lab_id=obi.LAB_ID_STAGING_TEST
project_id=obi.PROJECT_ID_STAGING_TEST
from entitysdk import Client, ProjectContext

from obi_auth import get_token

obi_one_api_url = "http://127.0.0.1:8100"

token = get_token(environment="staging")
project_context = ProjectContext(virtual_lab_id=obi.LAB_ID_STAGING_TEST, project_id=obi.PROJECT_ID_STAGING_TEST)
db_client = Client(api_url="https://staging.openbraininstitute.org/api/entitycore", project_context=project_context, token_manager=token)
```

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

### Initialize DB client

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/L_utils/register_circuit.ipynb

Initializes the database client by specifying the environment (staging), obtaining an authentication token, defining the project context (virtual lab ID and project ID), and creating a Client instance.

```python
# "Shared results + tests"
token = get_token(environment="staging")
project_context = ProjectContext(virtual_lab_id="e6030ed8-a589-4be2-80a6-f975406eb1f6", project_id="2720f785-a3a2-4472-969d-19a53891c817")
client = Client(environment="staging", project_context=project_context, token_manager=token)
```

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

### Setup

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/A_service_and_entitycore/test_endpoints/test_task_launch_endpoint.ipynb

Imports necessary libraries and sets up environment variables, tokens, and clients for interacting with the database and the OBI-One API.

```python
import httpx
import obi_one as obi
from entitysdk import Client, ProjectContext, models
from http import HTTPStatus

environment = "staging"
virtual_lab_id = obi.LAB_ID_STAGING_TEST
project_id = obi.PROJECT_ID_STAGING_TEST

token = "<COPY-TOKEN-HERE>"

# Get DB client
project_context = ProjectContext(virtual_lab_id=virtual_lab_id, project_id=project_id)
db_client = Client(environment=environment, project_context=project_context, token_manager=token)

# Get obi-one API client
OBI_ONE_API_URL = "http://127.0.0.1:8100"
headers = {
    "Authorization": f"Bearer {token}",
    "virtual-lab-id": virtual_lab_id,
    "project-id": project_id,
}
api_client = httpx.Client(base_url=OBI_ONE_API_URL, headers=headers)
```

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

### Get circuit metrics with no node and edge detail

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/G_circuit_metrics/circuit_metrics_example.ipynb

Retrieves circuit metrics with both node and edge detail levels set to 'none'.

```python
lod_edges = {ALL_POPULATIONS: CircuitStatsLevelOfDetail.none}
lod_nodes = {ALL_POPULATIONS: CircuitStatsLevelOfDetail.none}

metrics = circuit_metrics.get_circuit_metrics(circuit_id=circuit_ids[0],
                                              db_client=db_client,
                                              level_of_detail_edges=lod_edges,
                                              level_of_detail_nodes=lod_nodes)

```

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

### Get circuit metrics with specific edge and node detail levels

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/G_circuit_metrics/circuit_metrics_example.ipynb

Demonstrates setting a specific edge population to 'full' detail and node populations to 'basic' detail.

```python
lod_edges[metrics.names_of_chemical_edge_populations[2]] = CircuitStatsLevelOfDetail.full

metrics = circuit_metrics.get_circuit_metrics(circuit_id=circuit_ids[0],
                                              db_client=db_client,
                                              level_of_detail_edges=lod_edges,
                                              level_of_detail_nodes=lod_nodes)

```

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

### Set up a simulation campaign

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/C_forms/circuit_simulation/circuit_simulations_with_manipulations_example.ipynb

Configures a simulation campaign with various parameters including neuron sets, stimuli, recordings, and synaptic manipulations.

```python
# Sim duration
sim_duration = 3000.0

# Empty Simulation Configuration
sim_conf = obi.CircuitSimulationScanConfig.empty_config()

# Info
info = obi.Info(campaign_name="Small microcircuit simulation", campaign_description="Simulation of a small microcircuit with predefined neuron set and constant current stimulus")
sim_conf.set(info, name="info")

# Neuron Sets
sim_neuron_set = obi.IDNeuronSet(neuron_ids=obi.NamedTuple(name="IDNeuronSet1", elements=range(10)))
sim_conf.add(sim_neuron_set, name='ID10')

sync_neuron_set = obi.IDNeuronSet(neuron_ids=obi.NamedTuple(name="IDNeuronSet2", elements=range(3)))
sim_conf.add(sync_neuron_set, name='ID3')

# Regular Timesteps
regular_timestamps = obi.RegularTimestamps(start_time=0.0, number_of_repetitions=3, interval=sim_duration)
sim_conf.add(regular_timestamps, name='RegularTimestamps')

# Stimulus
poisson_input = obi.PoissonSpikeStimulus(duration=800.0, timestamps=regular_timestamps.ref, frequency=20, source_neuron_set=sim_neuron_set.ref, targeted_neuron_set=sim_neuron_set.ref)
sim_conf.add(poisson_input, name='PoissonInputStimulus')

sync_input = obi.FullySynchronousSpikeStimulus(timestamps=regular_timestamps.ref, source_neuron_set=sync_neuron_set.ref, targeted_neuron_set=sim_neuron_set.ref)
sim_conf.add(sync_input, name='SynchronousInputStimulus')

# Recordings
voltage_recording = obi.SomaVoltageRecording(neuron_set=sim_neuron_set.ref, start_time=0.0, end_time=sim_duration)
sim_conf.add(voltage_recording, name='VoltageRecording')

# Synaptic manipulations (executed in order!!)
syn_manip_mg = obi.SynapticMgManipulation(magnesium_value=[2.0, 2.4])
syn_manip_use = obi.ScaleAcetylcholineUSESynapticManipulation(use_scaling=0.7050728631217412)
sim_conf.add(syn_manip_mg, name='SynapticMgManipulation')
sim_conf.add(syn_manip_use, name='ScaleAcetylcholineUSESynapticManipulation')

# Initialization
simulations_initialize = obi.CircuitSimulationScanConfig.Initialize(circuit=circuit, 
                                                        node_set=sim_neuron_set.ref, 
                                                        simulation_length=sim_duration)
sim_conf.set(simulations_initialize, name='initialize')

# Validated Config
validated_sim_conf = sim_conf.validated_config()
```

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

### Configuring Basic Logging

Source: https://github.com/openbraininstitute/obi-one/blob/main/CONTRIBUTING.md

Example of how to configure basic logging, including output to a file.

```python
logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    filename='app.log',  # optional: logs to a file instead of console
    filemode='w'         # optional: overwrite the log file each time
    force=True
)
```

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

### Get circuit metrics with ALL_POPULATIONS set to basic and a specific edge population to full

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/G_circuit_metrics/circuit_metrics_example.ipynb

Retrieves circuit metrics with all populations set to basic detail and a specific edge population to full detail.

```python
lod_nodes["_ALL_"] = CircuitStatsLevelOfDetail.basic
lod_edges[metrics.names_of_chemical_edge_populations[2]] = CircuitStatsLevelOfDetail.full

metrics = circuit_metrics.get_circuit_metrics(circuit_id=circuit_ids[0],
                                              db_client=db_client,
                                              level_of_detail_edges=lod_edges,
                                              level_of_detail_nodes=lod_nodes)

```

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

### Soma Report Analysis - Report Properties

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/E_run_small_microcircuit/run_circuit_simulation.ipynb

Prints the time start, time stop, and time step (dt) of the SomaVoltage report. Includes a warning if dt differs from the simulation's dt.

```python
print(
    soma_report.time_start,
    soma_report.time_stop,
    soma_report.dt
)  # Gives a warning in case the dt differs from simulation.dt
```

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

### Import necessary libraries and set environment

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/G_circuit_metrics/connectivity_metrics_example.ipynb

Imports required libraries and sets the environment to 'staging'.

```python
import obi_auth
import pandas as pd
from entitysdk import Client
from ipywidgets import widgets
from obi_notebook import get_entities, get_projects
from obi_one.scientific.library import circuit_metrics, connectivity_metrics, circuit
import obi_one as obi
environment = 'staging'
```

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

### Install Brian2 if not present

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/J_drosophila_brian2_sonata/brian2_simulation_from_sonata.ipynb

Checks if Brian2 is installed and installs it if necessary using pip.

```python
import importlib.util
import subprocess
import sys

if importlib.util.find_spec('brian2') is None:
    subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'brian2'])
```

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

### Import necessary libraries and initialize the client

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/A_service_and_entitycore/obi_one_entity_tools/entitysdk_example.ipynb

This snippet imports the required libraries from obi_one, entitysdk, and obi_auth, and then initializes the Entity SDK client with staging environment credentials.

```python
import obi_one as obi
virtual_lab_id=obi.LAB_ID_STAGING_TEST
project_id=obi.PROJECT_ID_STAGING_TEST
from entitysdk import Client, ProjectContext, models

from obi_auth import get_token
from obi_notebook import get_projects

token = get_token(environment="staging")
project_context = ProjectContext(virtual_lab_id=obi.LAB_ID_STAGING_TEST, project_id=obi.PROJECT_ID_STAGING_TEST)
db_client = Client(api_url="https://staging.openbraininstitute.org/api/entitycore", project_context=project_context, token_manager=token)
```

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

### Deserialization example (commented out)

Source: https://github.com/openbraininstitute/obi-one/blob/main/projects/tiny_circuits/hippocampus_cylinder_example.ipynb

A commented-out example showing how to deserialize an obi object from a JSON file.

```python
# Deserialization
# grid_scan_ds = obi.deserialize_obi_object_from_json_file("../../../obi-output/circuit_simulations/grid_scan/obi_one_scan.json")
```

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

### Import DB client libraries

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/L_utils/register_circuit.ipynb

Imports necessary classes and functions for interacting with the database client, including Client, ProjectContext, models from entitysdk, and get_token from obi_auth.

```python
from entitysdk import Client, ProjectContext, models
from obi_auth import get_token
```

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

### Install Service Dependencies

Source: https://github.com/openbraininstitute/obi-one/blob/main/docs/index.md

Installs dependencies for service deployment.

```bash
make install-service
```

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

### Select Database and Initialize Client

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/A_service_and_entitycore/test_endpoints/test_endpoints.ipynb

This snippet shows how to select a database (staging in this case) and initialize the OBI-One client with appropriate authentication and project context.

```python
import requests
import os
import obi_one as obi
virtual_lab_id=obi.LAB_ID_STAGING_TEST
project_id=obi.PROJECT_ID_STAGING_TEST
from entitysdk import Client, ProjectContext

from obi_auth import get_token
from obi_notebook import get_projects

obi_one_api_url = "http://127.0.0.1:8100"

token = get_token(environment="staging")
project_context = ProjectContext(virtual_lab_id=obi.LAB_ID_STAGING_TEST, project_id=obi.PROJECT_ID_STAGING_TEST)
db_client = Client(api_url="https://staging.openbraininstitute.org/api/entitycore", project_context=project_context, token_manager=token)
```

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

### GenerateSimulationTask Example

Source: https://github.com/openbraininstitute/obi-one/blob/main/docs/scircuit.md

Example of using GenerateSimulationTask to execute a simulation task.

```python
from obi_one import GenerateSimulationTask

task = GenerateSimulationTask(config=config)
task.execute(db_client=db_client, entity_cache=False)
```

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

### Generate the Simulation Config

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/E_run_small_microcircuit/run_circuit_simulation.ipynb

Builds a detailed simulation configuration including info, neuron sets, timestamps, stimuli, and recording parameters, then validates and prepares it for execution.

```python
from pathlib import Path
import obi_one as obi

# === Parameters ===
sim_duration = 3000.0

# === 1. Build Form (CircuitSimulationScanConfig) ===
sim_form = obi.CircuitSimulationScanConfig.empty_config()

# Info
info = obi.Info(
    campaign_name="Small Microcircuit Simulation",
    campaign_description="Simulation of circuit with predefined neuron set and constant current stimulus"
)
sim_form.set(info, name="info")

# Neuron Sets
sim_nset = obi.AllNeurons()
sim_form.add(sim_nset, name="All Biophys")

# Timestamps
timestamps = obi.RegularTimestamps(start_time=0.0, number_of_repetitions=1, interval=100)
sim_form.add(timestamps, name="Timestamps")

# Stimulus
stimulus = obi.PoissonSpikeStimulus(
    duration=800.0,
    timestamps=timestamps.ref,
    frequency=20,
    source_neuron_set=sim_nset.ref,
    targeted_neuron_set=sim_nset.ref
)
sim_form.add(stimulus, name="PoissonInput")

stimulus = obi.ConstantCurrentClampSomaticStimulus(
    timestamps=timestamps.ref, duration=2000.0, neuron_set=sim_nset.ref, amplitude=0.5
)
sim_form.add(stimulus, name="CurrentClampInput")

# Recording
recording = obi.SomaVoltageRecording(neuron_set=sim_nset.ref)
sim_form.add(recording, name="SomaVoltage")

# Initialization block
init = obi.CircuitSimulationScanConfig.Initialize(
    circuit=obi.CircuitFromID(id_str="13a54362-0c99-43fd-94e4-58bdb5b79466"),
    node_set=sim_nset.ref,
    simulation_length=sim_duration,
)
sim_form.set(init, name="initialize")
# Validated Config
validated_sim_conf = sim_form.validated_config()

print(validated_sim_conf)

# === 2. Wrap into a Simulation ===
grid_scan = obi.GridScanGenerationTask(form=validated_sim_conf, coordinate_directory_option="ZERO_INDEX", output_root='./obi-output/run_circuit_simulations/grid_scan')
grid_scan.execute(db_client=db_client)
obi.run_tasks_for_generated_scan(grid_scan, db_client=db_client)
```

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

### MEModelSimulationSingleConfig Example

Source: https://github.com/openbraininstitute/obi-one/blob/main/docs/scs.md

Example of how to configure a single cell simulation using MEModelSimulationSingleConfig.

```python
from obi_one import MEModelSimulationSingleConfig, MEModelFromID

config = MEModelSimulationSingleConfig(
    initialize=MEModelSimulationSingleConfig.Initialize(
        circuit=MEModelFromID(id="..."),
        simulation_length=1000.0,  # ms
        v_init=-80.0,  # mV
        extracellular_calcium_concentration=1.1,  # mM
        random_seed=1
    ),
    stimuli={...},
    recordings={...},
    timestamps={...}
)
```

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

### Retrieve and Stage Circuit

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/A_service_and_entitycore/circuit_simulation/entitysdk_circuit_simulations.ipynb

Example of retrieving a circuit entity and staging it to a local directory.

```python
from entitysdk.models import Circuit
circuit = db_client.get_entity(entity_id=circuit_id, entity_type=Circuit)

from entitysdk.staging.circuit import stage_circuit
from pathlib import Path
stage_circuit(client=db_client, model=circuit, output_dir=Path('temp_circ/'))
```

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

### Import necessary libraries and authenticate

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/G_circuit_metrics/circuit_metrics_example.ipynb

Imports the required libraries and obtains an authentication token for the specified environment.

```python
import obi_auth
import pandas

from obi_notebook import get_entities, get_projects

environment_ = "staging"
token = obi_auth.get_token(environment=environment_)
project_context = get_projects.get_projects(token, env=environment_)
```

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

### Import necessary libraries and authenticate

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/F_single_cell_simulations/entitysdk_memodel_simulation.ipynb

Imports libraries for client interaction, authentication, project/entity retrieval, and OBI-One simulation configuration. It then obtains an authentication token and sets up the database client.

```python
from entitysdk import Client
from obi_auth import get_token

from obi_notebook import get_projects
from obi_notebook import get_entities
import obi_one as obi

token = get_token(environment="production", auth_mode="daf")
project_context = get_projects.get_projects(token)

db_client = Client(environment="production", project_context=project_context, token_manager=token)
```

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

### Grid Scan Generation Task

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/A_service_and_entitycore/circuit_simulation/entitysdk_circuit_simulations.ipynb

Example of creating and executing a GridScanGenerationTask for circuit simulations.

```python
import tempfile
import obi

# Create a temporary directory (not used in this example, but can be useful for testing)
with tempfile.TemporaryDirectory() as temp_dir:

    """
    Very strange issue with adding assets when a relative path is used here. Need to look into after CNS.
    """
    # grid_scan = obi.GridScanGenerationTask(form=validated_sim_conf, coordinate_directory_option="ZERO_INDEX", output_root='../../../../obi-output/circuit_simulations/grid_scan')
    grid_scan = obi.GridScanGenerationTask(form=validated_sim_conf, coordinate_directory_option="ZERO_INDEX", output_root='../../../../obi-output/circuit_simulations/grid_scan')
    # grid_scan = obi.GridScanGenerationTask(form=validated_sim_conf, coordinate_directory_option="ZERO_INDEX", output_root=temp_dir)
    grid_scan.multiple_value_parameters(display=True)
    grid_scan.coordinate_parameters(display=True)
    grid_scan.execute(db_client=db_client)
    obi.run_tasks_for_generated_scan(grid_scan, db_client=db_client)
```

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

### Load and print second circuit information

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/C_forms/circuit_simulation/circuit_simulations_example.ipynb

Loads a second circuit configuration and prints its details.

```python
circuit2_name = "N_10__top_rc_nodes_dim2_rc"
circuit2 = obi.Circuit(name=circuit2_name, path=str(circuit_path_prefix / circuit2_name / "circuit_config.json"))
print(f"Circuit '{circuit2}' with {circuit2.sonata_circuit.nodes[circuit2.default_population_name].size} neurons and {circuit2.sonata_circuit.edges[circuit2.default_edge_population_name].size} synapses")
```

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

### Example Blueetl Filtering

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/D_blueetl_example/blueetl_example.ipynb

Demonstrates filtering the 'repo' dataframe of the spikes analyzer by neuron class and window.

```python
spikes_analyzer.repo.report.df.etl.q(neuron_class='L2_X', window='w2')
```

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

### Connect to the staging entitycore database

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/F_single_cell_simulations/entitysdk_memodel_with_synapses_simulation.ipynb

Connects to the staging entitycore database using provided credentials and project context.

```python
from entitysdk import Client
from obi_auth import get_token

import obi_one as obi
from entitysdk import Client, ProjectContext


obi_one_api_url = "http://127.0.0.1:8100"

token = get_token(environment="staging")
project_context = ProjectContext(virtual_lab_id=obi.LAB_ID_STAGING_TEST, project_id=obi.PROJECT_ID_STAGING_TEST)
db_client = Client(api_url="https://staging.openbraininstitute.org/api/entitycore", project_context=project_context, token_manager=token)
```

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

### Run the simulation with BlueCelluLab

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/F_single_cell_simulations/entitysdk_memodel_with_synapses_simulation.ipynb

This code snippet shows how to initiate a simulation using the `obi_one` library with the BlueCelluLab simulator.

```python
from obi_one.scientific.library.simulation.entrypoint import run

run(
    simulation_config=simulation_config_path,
    simulator="bluecellulab",
    libnrnmech_path="./arm64",
)
```

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

### Test Endpoint for Circuit Simulation Scan Configuration

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/A_service_and_entitycore/circuit_simulation/entitysdk_circuit_simulations.ipynb

Example of testing the endpoint for generating circuit simulation scan configurations.

```python
import requests

# Construct the full endpoint URL
url = f"{obi_one_api_url}/generated/circuit-simulation-scan-config-generate-grid"
# url = f"{obi_one_api_url}/declared/scan_config/grid-scan-coordinate-count"
# Prepare headers
headers = {
    "Authorization": f"Bearer {token}",
    "Accept": "application/json",
    "Content-Type": "application/json"
}

# Optionally include optional headers if they are set
if virtual_lab_id:
    headers["virtual-lab-id"] = virtual_lab_id
if project_id:
    headers["project-id"] = project_id

# Construct request
# Placeholder example:
request_body = {
 'type': 'CircuitSimulationScanConfig',
 'timestamps': {'RegularTimestamps': {'type': 'RegularTimestamps',
   'start_time': 0.0,
   'number_of_repetitions': 3,
   'interval': 3000.0}},
 'stimuli': {
  'PoissonInputStimulus': {'type': 'PoissonSpikeStimulus',
   'timestamps': {'type': 'TimestampsReference',
    'block_dict_name': 'timestamps',
    'block_name': 'RegularTimestamps'},
   'source_neuron_set': {'type': 'NeuronSetReference',
    'block_dict_name': 'neuron_sets',
    'block_name': 'L1All'},
   'targeted_neuron_set': {'type': 'NeuronSetReference',
    'block_dict_name': 'neuron_sets',
    'block_name': 'L1All'},
   'duration': 800.0,
   'random_seed': 0,
   'frequency': 20.0}
   },
 'recordings': {'VoltageRecording': {'type': 'SomaVoltageRecording',
   'dt': 0.1,
   'neuron_set': {'type': 'NeuronSetReference',
    'block_dict_name': 'neuron_sets',
    'block_name': 'L1All'}}},
 'neuron_sets': {'L1All': {'type': 'IDNeuronSet',
    'sample_percentage': [30, 100],
   'sample_seed': 0,
   'neuron_ids': {'type': 'NamedTuple',
    'name': 'IDNeuronSet1',
    'elements': (0, 1, 2, 3, 4, 5, 6, 7, 8, 9)}}},
 'initialize': {'type': 'CircuitSimulationScanConfig.Initialize',
  'circuit': {'type': 'CircuitFromID',
   'id_str': circuit_id},
  'simulation_length': [2000.0],
  'node_set': {'type': 'NeuronSetReference',
   'block_dict_name': 'neuron_sets',
   'block_name': 'L1All'},
  'random_seed': 1,
  'extracellular_calcium_concentration': [1.1, 1.15],
  'v_init': -80.0},
 'info': {'type': 'Info',
  'campaign_name': 'No name provided',
  'campaign_description': 'No description provided'}
}

# Make the POST request
response = requests.post(url, headers=headers, json=request_body)

# Check the response
if response.status_code == 200:
    data = response.json()
    simulation_campaign_id = data
    print("Success:", data)
else:
    print(f"Error {response.status_code}: {response.text}")
```

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

### Iterate and Print Soma Features

Source: https://github.com/openbraininstitute/obi-one/blob/main/examples/D_blueetl_example/blueetl_example.ipynb

A commented-out example showing how to iterate through soma analyzer feature names and print their corresponding dataframes.

```python
# for feature_name in soma_report_analyzer.features.names:
#     print(feature_name)
#     print(soma_report_analyzer.features._data[feature_name].df)
```