Add support for compartment reports (soma + named section) as well as spike reports

[ilkilic]

Introduces functionality for writing SONATA-compatible compartment reports from NEURON simulations in bluecellulab. The example notebook 2-sonata-network has been updated to demonstrate spike and compartment report generation.

Supported Features

• Compartment reports:

  • Soma reports: "section": "soma" is resolved to soma[0], supporting "center" (0.5) and "all" segments.
  • Grouped sections: "section": "dend" or similar resolves to all matching sections like dend[0], dend[1], etc.
  • Output path handling: Uses config['output']['output_dir'] to construct <output_dir>/<report_name>.h5.

• Spike reports:

  • Writes spike times grouped by population in SONATA HDF5 format under /spikes/.
  • Populations with no spikes are still written with empty datasets.
  • Spike threshold is retrieved from conditions.spike_threshold in the simulation config.

Additions

• write_reports(): Writes all report in SONATA HDF5 format (currently supports compartment and spike reports).
• resolve_segments(): Determines target segments from section/compartment config.
• get_section() / get_sections():
  • get_section(): Resolves fully specified names like "soma[0]".
  • get_sections(): Resolves base names like "dend" to all matching sections.
• "variable_name": "v" support; other variables are logged and skipped.
• Test coverage includes:
  • Section resolution
  • Node-based compartment targeting
  • Output file structure
  • Error handling for invalid configs

Limitations

• "sections": "compartment_set" is parsed but not fully supported in LibSONATA output.
• Explicit section names like "dend[4]" in the config are not supported—only group names like "dend" are accepted—because LibSONATA currently does not support addressing individual sections directly in reports.
• Only voltage ("v") is currently recorded.
• Only spike recordings from "soma" are implemented.

Notes

• If output_dir is provided in the config, reports are written there, otherwise, defaults to ./<report_name>.h5.
• Files are overwritten if they already exist, consistent with existing plot behavior.
• Spike files are written to spikes_file defined in output.spikes_file (default: out.h5).

[codecov]

Codecov Report

Attention: Patch coverage is 91.32321% with 40 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
bluecellulab/simulation/report.py	83.72%	21 Missing ⚠️
bluecellulab/circuit_simulation.py	88.13%	7 Missing ⚠️
bluecellulab/tools.py	90.24%	4 Missing ⚠️
...ellulab/circuit/config/sonata_simulation_config.py	90.90%	3 Missing ⚠️
tests/test_circuit/test_iotools.py	90.90%	3 Missing ⚠️
bluecellulab/cell/core.py	90.90%	1 Missing ⚠️
bluecellulab/circuit/iotools.py	0.00%	1 Missing ⚠️

Files with missing lines	Coverage Δ
tests/test_circuit/test_reports.py	100.00% <100.00%> (ø)
tests/test_circuit/test_section_tools.py	100.00% <100.00%> (ø)
tests/test_circuit/test_simulation_config.py	100.00% <100.00%> (ø)
tests/test_ssim_sonata.py	100.00% <100.00%> (ø)
bluecellulab/cell/core.py	75.55% <90.90%> (+0.42%)	⬆️
bluecellulab/circuit/iotools.py	0.00% <0.00%> (ø)
...ellulab/circuit/config/sonata_simulation_config.py	96.87% <90.90%> (-2.09%)	⬇️
tests/test_circuit/test_iotools.py	90.90% <90.90%> (ø)
bluecellulab/tools.py	96.57% <90.24%> (-0.51%)	⬇️
bluecellulab/circuit_simulation.py	85.87% <88.13%> (+0.36%)	⬆️
... and 1 more

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[ilkilic]

I added spike report support to this PR as well

[darshanmandge]

Do you think we should update the Example 2 to show the generated reports?

[ilkilic]

@darshanmandge I already did ;)

[darshanmandge]

Thanks! Do you want to store an example output and describe how to access the data via the example notebook e.g. using bluepysnap or efel?

[ilkilic]

Thanks! Do you want to store an example output and describe how to access the data via the example notebook e.g. using bluepysnap or efel?

Maybe a next time?

[AurelienJaquier]

looks good to me

[darshanmandge]

Thanks for adding this functionality!