Documentation of SONATA Circuit Config

[1uc]

Regarding the documentation of the SONATA circuit config, as published here:
https://sonata-extension.readthedocs.io/en/latest/sonata_overview.html#circuit-config

I'd like to point out that the example for Circuit Config files at BBP does not include the field "population" for nodes. Which is said to be mandatory at BBP on the next page. Furthermore, the following sentence:

Within BBP we do not use .csv files as defined in the specification!

is unfortunately unclear to me. It could mean one of

1. Despite what the example is showing, at BBP we don't use CSV and this conflicts with the specification.
2. At BBP we don't use CSV and it is required by the specification that we don't use CSV.
3. We're using CSV in a manner different from what the specification requires.

[mgeplf]

Sorry for the delay.

I'd like to point out that the example for Circuit Config files at BBP does not include the field "population" for nodes.

Let me know which ones you find with that - they are from before we enforced it, and we should update them.

Regarding CSV; this is hard to word.
At BBP we don't use CSV and forbid its use; but by the official spec we should have support for it. IE: we explicitly don't use it.

[1uc]

The circuit config I'm referring to is the one in the documentation. This is the direct link:
https://sonata-extension.readthedocs.io/en/latest/sonata_overview.html#circuit-config

and this is the example given:

A standard circuit config at BBP is :

$ cat circuit_config.json
{
  "manifest": {
    "$BASE_DIR": ".",
    "$COMPONENT_DIR": "./component",
    "$NETWORK_DIR": "$BASE_DIR/network"
  },
  "components": {
    "morphologies_dir": "$COMPONENT_DIR/morphologies",
    "biophysical_neuron_models_dir": "$COMPONENT_DIR/biophysical_neuron_models"
  },
  "node_sets_file": "$BASE_DIR/node_sets.json",
  "networks": {
    "nodes": [
      {
        "nodes_file": "$NETWORK_DIR/neurons.h5",
        "node_types_file": "$NETWORK_DIR/node_types.csv"
      },
      {
        "nodes_file": "$NETWORK_DIR/projections.h5",
        "node_types_file": null
      }
    ],
    "edges": [
      {
        "edges_file": "$NETWORK_DIR/edges.h5",
        "edge_types_file": null
      }
    ]
  }
}

Hence, I expected it to show a BBP-style circuit config file. Personally, what I found confusing about the example was why "nodes" is a list and how to pick an entry from the list. If this example would include the field "populations", I suspect it would have been clear to me why "nodes" is a list, i.e. because different populations can be stored in separate files. (Also the file would be BBP-compatible as claimed.)

As for rewording the sentence about CSV:

• Despite the SONATA specification {allowing,requiring} use of CSV files {,for "*_types"}, CSV files are not used within BBP and libsonata {does, does not} support CSV {,instead XYZ files are used}.

Please note that again the example mentions a CSV file. It's unclear if this use of CSV files is affected by the statement regarding no CSV files at BBP.