First edition: July 7, 2022

Revised: February 6, 2023
Revised July 2023

Revised March 2024

Revised October 2024

BRA Data Preparation Manual

Hiroshi Yamakawa

This document explains the creation of BRA (Brain Reference Architecture) data.  We recommend to first readBrain-morphic Software Design Guide_ver.2 and paper [1] to get general ideas.

* Note: Japanese version of the BRA Data Preparation Manual can be found here.

Overview

This document explains how to construct BRA (Brain Reference Architecture) data in BRA-driven development that embodies the WBA approach.  BRA consists of BIF (Brain Information Flow) diagrams, which represent the anatomical structure of the brain, and HCD (Hypothetical Component Diagrams), which are hypothetical component diagrams that correspond to BIF.

A HCD is a component diagram^[1], on which the function achieved by a region of interest (ROI) of the brain is decomposed in a way compatible with the anatomical structure of the BIF (Figure 1).  For functional decomposition, a Function Realization Graph (FRG), or a functional hierarchy diagram, is associated with the HCD.  This manual explains how to register data for BIFs, HCDs, and FRGs.

Figure 1: Schematic diagram of BRA-driven development

When HCD being created may refer to the anatomical structure data (WholeBIF) that has already been created, or if necessary, BIF data and References can be added.

For more information on BRA-driven development, refer to the paper [1].

Sheets and Columns

BRA data is created on a Google Spreadsheet.

Below, the file that describes the data corresponding to HCD is called a work file, and the person who creates the HCD is called a contributor.

Variables are shown in italics in the following.

Work file sheet list

The work file corresponding to the project includes the following sheets.

Table 1: List of sheets included in the work file

Columns

Columns are explained below.

• Col.: Column number on the sheet
• Attribute: Name of the attribute to be described
• Description: Description for the attribute
• Values: Value format
• Mandatory: Required or not

Attributes are color-coded according to the need for description:

• mandatory: description is required
• optional: description is optional. (it may become mandatory depending on the conditions.)
• automatic: the value is automatically calculated and displayed.
• Admin columns: for management

• pull request: used when requesting integration into WholeBIF
• review: used when reviewing the contents of a record

Note: Adding records (rows) may require calculation formulas for automatic input to be copied from the surrounding rows.

Multiple items in a column

When writing multiple items in a column, separate them with a semicolon ";", as a general rule, and line break should be inserted after semicolon.

Shared Management Columns

Management columns commonly used to manage records have the following attributes. Activities that contributed to HCD design are identified by Contributor and Project ID.

Table 2: Management columns (common)

Data Creation Procedure

HCDs are created referring to WholeBIF, a database of anatomical data of the entire brain, to align the HCDs with the brain anatomy.  Specifically, HCD components corresponds to Circuits on WholeBIF, and the dependencies on HCD are mapped to connections on WholeBIF.  In creating an HCD, the ROI (Region of Interest) and the TLF (Top-Level Function) to be achieved with the ROI are determined, and the TLF is decomposed to create FRG.  For details, seeBrain-morphic Software Design Guide_ver.2.

When HCD being created may refer to the anatomical structure data (WholeBIF) that has already been created, or if necessary, BIF data and References can be added.

For more information, see § Creating BIF data.

Preparation

Description procedure

Step.1 Preparation

• Determine the Project ID for designing HCD

• See § Project ID naming convention

• Securing your work space on Google Drive

• Secure a work area on Google Drive for yourself to work on.

Step.2 Creating an HCD work file

Copy it ([File] → [Make a copy]) Template-v2-2.bra into the work area and change the file name to "(project name).bra".

This file will be called the work file below.

Step.3 Preparation of BIF data

Add anatomical structures (Circuits and Connections) and References data that supports their validity as necessary.  For more information, see § Creating BIF data.

Creating a Project (“Project” sheet)

Define a Project in the “Project” sheet of the work file.

Column description

Project sheet has records with the following columns.

Table 3-1: Column #1/2 included in Project sheet

Description procedure

1. Write a Contributor
2. Write the Project ID

1. If you register a Project ID that is already registered in WholeBIF, an error will be output.

1. However, if you have already registered the circuit in Whole BIF, ignore the error.

3. Write the List of contributors as necessary
4. Write a Description if necessary

Project ID naming convention

A String with the format: initial + year + runingTitle

Do not use special characters (e.g. *, @, %, $) or spaces.

• initial : A string of up to 5 uppercase letters (a string consisting of alphabets)

• As a general rule, it is the initial of the name of Contributor, but other strings can be used.

• year : Last two digits of the Gregorian calendar (CE) of the year the project started
• runningTitle : Up to 30 alphanumeric characters. The first letter of each word is capitalized without spaces (upper camel case)

• The running title must be set so that the entire string of this project ID does not overlap with any existing project ID.

Example:

Description of target record range for automatic review

Set the range of records that are subject to automatic review in the Project sheet. Specifically, for the Sheet subject to automatic review (References, Circuits, Connections, FRG), enter the number of rows in the final record that is subject to review in the following columns of Table 3-2.

Column description

Table 3-2: Column #2/2 included in Project sheet

Recording Procedure

1. Write the Review End Line for the References sheet in the first line
2. Write the Review End Line for the Circuits sheet in the second line
3. Write the Review End Line for the Connections sheet on the third line
4. Write the Review End Line about FRG on the 4th line

Creating BIF Data

BIF data can be created by adding the following:

• Adding References (“References” sheet)
• Adding Circuits (“Circuits” sheet)
• Adding Connections (“Connections” sheet)

Creation of Function Realization Graph (“FRG” sheet)

Use the “FRG” sheet in the work file to register data for the function realization graph. For details on function realization graphs and evaluation of function realization graphs, refer to the following materials.

• Brain-morphic Software Design Guide_ver.2

Column description

Table 5: Column description steps included in the FRG sheet

※By specifying the "Circuit ID" of column AE, the values ​​of columns B~AB are automatically calculated.

The description of an FRG consists of Node/Subnode information, Circuit ID information, projection information, and function information.  Edit the FRG sheet on the work file.

*About FRG visualization tools

An FRG visualization tool is available as an auxiliary tool for FRG creation. We recommend to use it as appropriate to check the hierarchical relationships of nodes. About visualization tools, see 可視化ツールXML-Viewの使用方法 ver2.0 (Japanese only).

Data registration of a Node and its dependencies

Step.1 Node ID registration

Register Node ID (columns AC – a required item). The same ID will be automatically displayed in column A.

• In the Node ID column, write either Requirement/Capability/Assembly/Uniform Circuit based on the notation in the table below.

• It is recommended to use Requirement.

• Use Kebab-case for Requirement and Capability names, and avoid including special characters or spaces.

Table. Node ID constructs

Step.2 Registering subnodes

Register the Node ID immediately below the Node ID for each row in the Subnodes column (AD column).  It is desirable that the higher the row, the higher the node in the FRG.  If Node is a Leaf Node, leave it blank.  A Leaf Node is the terminal node of the FRG (for details, seeBrain-morphic Software Design Guide_ver.2).

If multiple Subnodes are included, separate the IDs with ";" and register the IDs, and line break should be inserted after semicolon.

Entry example:

Step.3 Register Circuit ID

* Execute this step only on rows where the node is a Leaf Node.

• Select the Circuit ID that appears in the pull-down menu and register the circuit you want to use.
• If you want to add and use a circuit that does not appear in the pull-down menu, add circuits based on §Circuit addition steps.

Step.4 Registration of projection information

* Execute this step only for Leaf Node rows.

For each row of the Projected Circuits column (AF column), register and check the information for the columns below.

• Leaf Nodeにあたるコンポーネントから投射出力するCircuit IDをProjected Circuits列(AG列)に、項目ごとに改行しながら記述する（行末にデリミタセミコロン”;”を付加する）。
  Write Circuit IDs of the circuits to which the component corresponds to the Leaf Node, with a new line for each item (add a delimiter semicolon ";" at the end of the line).

• ただし、Uniform CircuitのみにおいてProjected Circuitsを登録可能である。
• Uniform Circuitでない場合は、空欄のままにしておく。
• Projected Circuits can only be registered for Uniform Circuits.
• If it is not a Uniform Circuit, leave it blank.

When this operation is completed, Projected Circuits Validation (AG column) / Uniform Circuits (AH column) / Input Circuits (AI column) / Output Circuits (AJ column) are automatically calculated and displayed. Check the following contents.

• Look at the Projected Circuit Validation column (AG column) and confirm that the above output projection is written in the Projections column (Z column).

• If the display is “-”: Registration has been completed without any problems.
• If the display is "x": There is a problem with the registered content, and in many cases, this is because the projection relationship between the registered Projected Circuit and the Uniform Circuit corresponding to the Node leaf is not described in the Connection sheet.  Make corrections on the Connection sheet, while referring to §Error handling in Output Circuit Validation.

• Look at the Uniform Circuits column and confirm the following:

• If Node is a Leaf Node row:

• Check whether the Circuit ID displayed in Uniform Circuits is the Circuit ID assigned to the Leaf Node component.

• For non Leaf Node rows:

• Check if all Circuit IDs included in the node are displayed

• If the appropriate Uniform Circuit is not displayed, review the entire Subnodes column and make sure there is no omission.

• In the Input Circuits column, verify that the component has the required projected inputs.

• If the input projection from a specific circuit X required for design is insufficient for the circuit Y in this row, the following measures are taken.
• Add circuit Y as a projection destination in the Output Circuit column of circuit X.

• Finally, look at the Output Circuits column to see the basic information that supports a particular circuit's functionality.

Indirect Connection Evidence (Error handling in Output Circuit Validation)

BRA-driven development requires that the connections utilized in the HCD design are backed by the anatomy.  However, in HCD design, it becomes necessary to handle connections between uniform circuits that are smaller than the currently known anatomical connections, or to handle larger circuits.

In order to deal with this situation, if the connection relationship between larger circuits is known, connections can be described between Uniform Circuits that are part of the structure on the Connection sheet, or connections between larger Circuits can be described.

Specifically, write as follows on the Connection sheet (see Column Descriptions in Adding Connections (“Connections” sheet).

For example, the circuit on the sending side is written as follows. Describe the circuit identifier (Sender Circuit ID (sCID)) of the sender you want to handle and the inclusion relationship (sCID relation) described in the circuit corresponding to the sCID described in the Literature (Notation of sCID in Literature) column.

Similarly, the circuit on the receiving side is described using the Receiver Circuit ID (rCID) column, rCID relation column, and Notation of rCID in the Literature column.

Data registration regarding functions

This section describes the notation of Requirement / Capability / Interface / Implementation, related to node functions in FRG. The contents and format of description are as follows.

Table. Requirement / Capability / Interface / Implementation description contents and description format

* See 脳型ソフトウェア設計技術の再検討 for conceptual details of the functional attributes.

Implementation column notation

*Implementation registration is only for Leaf Nodes.

In the Implementation column, describe implementation calculations with the notation of Node ID and transmitter type. The notation is as follows.

Procedure

1. Input UC: Prepare a list of "Input Circuits" (AI column)

2. Get the output "Uniform Circuit" (AH column)

3. Using the Input Circuits and output Circuit ID obtained in 1 and 2, write:

[“Modulation type”(Circuit ID of output), “Modulation type(I,E)”(Circuit ID of output),...] = “Function expression”(“Modulation type(I,E)”(Input Circuit ), “Modulation type(I,E)”(Input Circuit), ...)

An example of pseudo code description is shown below.

When expressing information propagation using conditional probabilities:

 ・[I(U.INAvm)] =  P(U.INAvm | U.INAvm, R.KeepFearState, U.BAE)

Capability column notation

In the Capability column, write the Node ID Capability ID and description in natural language.

The notation is

 C.[Capability ID]: Capability description

A description example is shown below.

・C.Switching: Switches between 2 inputs.

・C.Gating: Controls the on/off state of propagating input to the Projected Circuits of this node.

Requirements column notation

Requirements, functions as requests for function nodes, will be explained in natural language.

The notation is

 R.”NodeID”: “Requirements description”

Output Semantics Column notation

In the Output Semantics column, describe the following characteristics of the output from the Node in English.

• Meaning from the outside world (external referentiality) [required]
• Spatial aspects [recommended]

• Coordinate system (e.g., omentum coordinate system, body part center coordinate system, external center coordinate system)
• Format of representation (e.g. vector representation, map representation)
• Valid number of dimensions

• Side of time [if any]

• Temporal properties of neural activity (tonic/burst/phasic, etc.)
• Time constants related to modeling (can also be written in the Process column)

When adding references, add them at the end of the text and write the references on the Reference sheet.

If this component is a Uniform Circuit, the number of O(Circuit ID) is one, and Circuit ID is its own ID.  In cases other than Uniform Circuit, one or more O(Circuit ID) is specified.

Example:

Registration of data related to evaluation of relationships related to functional design

To evaluate the relationships related to the designed functions, the following data are registered. These are written in natural language.

Adding References (“References” sheet)

Reference information used in the “FRG” sheet is listed in the “References” sheet.

In this sheet, while the “wbReference” information in the WholeBIF file is referenced in advance, you can also add additional references for records.

Column description

The Reference sheet is described by records containing the following columns.

Table 7: Columns included in the References sheet

Steps to add a reference

The red cells in column A in this data are references to WholeBIF's wbReferences.

Therefore, records are added to the area above the red cell.

If there are not enough rows, insert a row above the red cell and duplicate the formula.

For documents for which a DOI is available:

If the DOI of the document is known, you can easily register documents using the doi2bib site's functions.

procedure:

1. Get the DOI of the document you want to add.
2. Enter the DOI in the DOI column, click the BiB link in the BibTex link column.

1. Once the error is displayed,https://www.doi2bib.org/ If you click directly, it may recover. (Especially when accessing for the first time)

3. On doi2bib, “Copy Bib to Clipboard" to obtain Bib information.
4. Paste the information into the BibTex column.
5. Values ​​are automatically inserted into columns.
6. If the automatically inserted value is inappropriate, modify the contents of the BibTex column accordingly.
7. Enter the contents in the Literature type column.
8. Register the name of the person who mainly contributed to the creation in the Contributor column (§Common columns for management)
9. Register ProjectID in the ProjectID column (§Common columns for management)

For documents for which a DOI cannot be obtained:

If you cannot obtain a DOI for a document, register the document by creating your own BibTex information.

procedure:

1. Create BibTex information for the document you want to add (enclose each information in “{”, “}”.
2. Paste the above information into the BibTex column.
3. Values ​​are automatically inserted into columns.
4. If the automatically inserted value is inappropriate, modify the contents of the BibTex column accordingly.
5. Enter the contents of the Literature type column.
6. Register the name of the person who mainly contributed to the creation in the Contributor column (§Common columns for management).
7. Register ProjectID in the ProjectID column (§Common columns for management).

Adding Circuits (“Circuits” sheet)

The Circuits information used in the “FRG” sheet is listed in the “Circuits” sheet.

In this sheet, the “wbCircuits” information in the WholeBIF file is referenced in advance, but you can also add additional references for each record.

How to add Uniform Circuit when designing HCD

When designing an HCD, a uniform circuit is often required to output the desired output semantics at a specific anatomical region in order to describe the functional hypothesis to be realized. However, if WholeBIF cannot find an appropriate Uniform Circuit for that brain region, it is necessary to add a Uniform Circuit that outputs the desired Output Semantics. The uniform circuit to be additionally registered is preferably a group of neurons known to exist anatomically. However, if this is not possible for various reasons, the value of the Source of ID column will be registered as “makeshift”. Here, HCD is being designed so that each Uniform Circuit in the brain has unique Output Semantics within the brain. Therefore, Uniform Circuits that output the same Output Semantics should be aggregated as unique ones. Conversely, you should avoid registering multiple Uniform Circuits that output the same Output Semantics.

Column description

The Circuit sheet is described by records containing the following columns.

Table 8: Columns included in Circuit sheet

Supplementary Explanation of Attributes

Names

It is a circuit label and can be written multiple times. If the Circuit ID is an abbreviation (acronym), write the full name on the left and list synonyms separated by ;. If you want to use a name other than English, add the ISO639 code after @. If it is the same as Circuit ID, it does not need to be written.

example:

Example:

DHBA: graph_order

Size

It represents the number of neurons in the Uniform Circuit.

format

“[“author, year, size, taxon”]”

here

size :Number of neurons

taxon :Animal species name (Project (See Sheet section)
author,year = reference ID(See Reference Sheet)

Output Semantics (0)

Output Semantics (0) contains one or more References (“[“Reference ID "]") including.
(References will be checked in the official review.)

Steps to Add a Circuit

The red cells in column A in this data are references to wbCircuit in WholeBIF. Therefore, records are added to the area above the red cell.

If there are not enough rows, insert a row above the red cell and duplicate the formula.

Procedure:

1. Define the string of newly added Circuit ID

• Define a string that is unique from existing Circuit ID strings
• An error is output when entering a Circuit ID that exists in WholeBIF
• use only alphanumeric characters, ".", "_", and "~"

2. Write the character string defined in the Circuit ID column of a specific record
3. In the Source of ID column of the same record, write the following that represents the anatomical source of the Circuit ID. The value is one of the following: This sheet describes anatomical facts, so for example, due to the necessity of constructing an HCD, etc.  In the circuit introduced as a hypothesis, “makeshift” is specified.

• ontology : Identifiers such as external realm name sets such as DHBA, MBA, UBERON, etc.
• “collection”: A circuit that is a combination of multiple circuits
  Sub-CircuitsOne or more Circuit IDs other than makeshift must be described in
• “makeshift”: Temporarily introduced circuit
• reference ID: Write the document ID for the circuit used in a specific paper
  (See Reference Sheet section)

4. Write the names of common brain organs in the Names column of the same record.
5. Add a decimal number to DHBA: graph_order of the circuit derived from the smallest DHBA that includes the brain organ to be registered, and register it in the DHBA: graph_order column.
6. Describe Sub-Circuits columns and Super Class columns as necessary
7. Describe a Uniform column
8. If Uniform=TRUE, describe the Transmitter column and Modulation Type column.
9. Describe the Size column, Output Semantics (0), Physiological Data column, and Process (0) column as necessary.
10. Register the name of the person who mainly contributed to the creation in the Contributor column (§Common columns for management)

Adding Connections (“Connections” sheet)

The Connections information used in the “FRG” sheet is listed in the “Connections” sheet.

In this sheet, the “wbConnectons” information in the WholeBIF file is referenced in advance, but you can also add additional references for each record.

Regarding the handling of circuits including inclusion relationships related to columns A to F, see Indirect Connection Evidence (Error handling in Output Circuit Validation).

Column description

The Connections sheet is described by records containing the following columns.

The contributor writes columns A to N, and the subsequent columns N to AC are automatically calculated.

Table 9: Columns included in Connections sheet

Steps to Add a Connection

The red cells in column A in this data and subsequent cells are references to wbConnections of WholeBIF. Therefore, records are added to the area above the red cell.

If there are not enough rows, insert a row above the red cell and duplicate the formula.

Procedure

1. Registration of transmitter circuit (described in columns A to C)

1. Register the sender circuit identifier (sCID) in column A

1. If an appropriate circuit identifier does not exist, add it to the row of the Circuit sheet.

2. Describe the anatomical inclusion relationship in column B with the corresponding circuit described in the literature.

1. If they match, write “‘=” (= sign with an apostrophe), if it is included in a circuit in a document, write “<”, and if it includes a circuit in a document, write “>”. (However, do not select “=” that appears in the pull-down menu.^[3]。）

3. If the above does not match, write the identifier of the circuit described in the literature in column C.

2. Registration of receiver circuit identifier (rCID) (described in columns D to F)

1. The description method is the same as the sending circuit

3. Write comments in column G as appropriate.
4. Write the Reference ID in column H

1. Describe evidence that can be supported even if it is indirect (e.g., there is evidence of a connection at a coarse granularity)

1. c.f .Indirect Connection Evidence (Error handling in Output Circuit Validation)

2. The connection introduced as a hypothesis without indirect evidence is specified as “makeshift”.

5. In column I, write the animal species.
6. Write the measurement method in column J.

1. When there is no measurement method option

1. If no suitable options are displayed, ignore the error and write.

2. What to do when the measurement method is not clear in the relevant document

1. Select (No description) in the relevant cell.
2. Investigate the documents referenced in the document as evidence and add them as a new Connection line.

7. Describe at least one of the following reports in the literature:

1. Cite sentences that mention projection in the literature in column K.
2. Specify the drawing showing the projection in the document in column L.

8. In order to increase the credibility of this projection, the Reference ID of the document that has been dug in depth based on the references in the document is written in column M.
9. Register the name of the person who mainly contributed to the creation in the Contributor column (§Common columns for management).

License

Refer to the License sheet in  WholeBIF.

References

Please refer to theBRA駆動開発関連資料リスト

[1] Yamakawa, H. (2021). The whole brain architecture approach: Accelerating the development of artificial general intelligence by referring to the brain. Neural Networks: The Official Journal of the International Neural Network Society, 144, 478–495. https://doi.org/10.1016/j.neunet.2021.09.004 

[2] Hiroshi Yamakawa. (2022). Whole-brain architecture ─ Designing and developing brain-shaped AI while understanding its functions ─. In Kazuhiko Yokozawa (Ed.),Cognitive Science Lecture 4: Development of a framework that captures the mind (pp. 209–249). University of Tokyo Press.http://www.utp.or.jp/book/b609203.html

[3] Hiroshi Yamakawa, Kamasa Tawatsuji, Tatsuya Miyamoto, Naoya Arakawa, Yuta Ashihara, Ayako Fukawa, Koichi Takahashi, Yutaka Matsuo (2024). Data description format for efficient reverse engineering of brain computational functions, IEICE Technical Report NC Study Group, 123:418, 53-58.https://ken.ieice.org/ken/paper/20240312JccC/