From 19efa3e066245f8978f7bb1a60165d735d915b04 Mon Sep 17 00:00:00 2001 From: willGraham01 Date: Thu, 7 May 2026 10:55:38 +0100 Subject: [PATCH 01/32] Write basic docs introduction page --- docs/source/index.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/source/index.md b/docs/source/index.md index 509e58d..7825a6c 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -7,3 +7,22 @@ getting_started ``` + +This package acts as an interface between neurological region-connectivity data and network (graph) analysis. +Connectivity data generally consists of three components: + +- Information about the brain-regions, whose connections have been explored. + Typically their names, abbreviations, any groupings of regions, and other data like their spatial coordinates. +- The strength of the inter-region connections, which are considered directed. + This means that region A may connect to region B, but there may not be a reverse connection. + A connection is further attributed a weight, which may represent the strength of that connection, the time for a signal to travel along the connection, or other neurological quantity of interest. +- Further information about the connections. + This may consist of information about the studies in which they were examined, any special reference names they might have, or any user- or neurological-groupings of the connections themselves. + +Mathematically, such connection information is represented as a network (or graph), which makes it tractable to analysis via algorithms or manipulations of such objects. +The regions are represented by the nodes of the graph, and the connections by the edges within the graph. +This allows us to phrase questions such as "what is the minimum travel time for a signal from region A to reach region B" as purely mathematical questions ("find the path between region A and region B that minimises the signal travel time") which can be solved using well-established network algorithms. + +## Connectivity Data Input Format + +## Interacting with the Data From 9b6bc6c6c4f141b7538573a05b44bbecd4cc9d09 Mon Sep 17 00:00:00 2001 From: willGraham01 Date: Thu, 7 May 2026 11:42:20 +0100 Subject: [PATCH 02/32] Page for translating maths <-> neuroscience --- docs/source/index.md | 1 + docs/source/neuro_to_math.md | 50 ++++++++++++++++++++++++++++++++++++ 2 files changed, 51 insertions(+) create mode 100644 docs/source/neuro_to_math.md diff --git a/docs/source/index.md b/docs/source/index.md index 7825a6c..b699a98 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -5,6 +5,7 @@ :maxdepth: 2 :caption: Contents: + neuro_to_math getting_started ``` diff --git a/docs/source/neuro_to_math.md b/docs/source/neuro_to_math.md new file mode 100644 index 0000000..4cc9fee --- /dev/null +++ b/docs/source/neuro_to_math.md @@ -0,0 +1,50 @@ +# Neuroscience and Mathematical Terminology + +On this page we aim to provide a short summary that reconciles the terminology used to describe connectivity data in neuroscience, and map it to the corresponding mathematical terminology surrounding networks. + +## Networks + +A network (or graph) consists of: + +- A set of nodes (also called vertices) $V$. + The nodes are indexed by some counter, so we typically write $V := \{ v_0, v_1, ..., v_N\}$ where each $v_i$ is one node, uniquely identified by the value of $i$. + As such, when referring to nodes it is common to drop the $v_i$ notation and simply say "node $i$" in place of "node $v_i$". +- A set of edges $E$. + Each edge $e\in E$ is written as $e = (i, j, w)$ (or $e = (v_i, v_j, w)$ if you prefer to keep the explicit node notation). + The edge $(i, j, w)$ means that there is an edge (connection) direct from node $i$ into node $j$, with a weight of $w$. + +So long as one has a consistent indexing for the nodes, a network can then be built up by listing the edges in $E$. +Such a listing is often referred to as an "edge list" or "edge table", which is simply a 3-column format where each row lists a single edge $e$ in $(i, j, w)$ format. + +## Connectivity Data + +Connectivity data generally consists of three components: + +- Information about the brain-regions, whose connections have been explored. + Typically they will be given some form of unique identifier, as well as names, abbreviations, any groupings of regions, and other data like their spatial coordinates. +- A listing of the connections between regions, which are considered directed. + A connection is further attributed some quantifiable "weight"; which may represent the strength of that connection, the time for a signal to travel along the connection, or other neurological quantity of interest. +- Further information about the connections. + This may consist of information about the studies in which they were examined, any special reference names they might have, or any user- or neurological-groupings of the connections themselves. + +## Reconciling the Terms + +As such, the regions should be thought of as nodes, and the connections as edges. +If the regions are provided with unique identifiers, these same unique identifiers can be used as the indexes $i$ for the mathematical description of the nodes. +In the same way, this also means that list of connections between the regions acts as out edge table, and thus we can build a network to represent our connectivity data. +Any further information about the regions can be stored in some suitable data format (such as a `DataFrame`) that allows indexing via the region identifiers - this information is referred to as "node/region metadata". +Similarly, any further information about the connections (excluding their weights) can be stored in tabular format that allows indexing via the $(i, j)$ pair that describes the connection's start and end - this information is referred to as "edge metadata". + +:::{note} +By convention, regions that are not connected do not appear in the edge list. +This is to distinguish regions that aren't connected, from regions that may happen to be connected with a weight of $0$, for example. + +However, edge metadata _may_ contain information about a pair of regions $(i, j)$ that are not connected, without issue. +This is common when, for example, a study has determined that two regions are not connected and needs to encode this information into the connectivity dataset. +As such, not every connection that appears in the edge metadata may have an edge representing it in the mathematical network, however every edge in the mathematical network _does_ have a corresponding entry in the edge metadata table. +::: + +:::{note} +Node metadata (save for provision of a unique identifier for the regions) and edge metadata are entirely optional from a purely mathematical analysis of the connectivity data. +However, such information is normally incredibly helpful to have on-hand when one wants to run or plan neurologically-relevant analysis! +::: From 69641d629c65a302a4f1c14a9b85bd691112dbec Mon Sep 17 00:00:00 2001 From: willGraham01 Date: Thu, 7 May 2026 11:49:29 +0100 Subject: [PATCH 03/32] Remove placeholder getting-started --- docs/source/getting_started.md | 11 ----------- docs/source/index.md | 1 - 2 files changed, 12 deletions(-) delete mode 100644 docs/source/getting_started.md diff --git a/docs/source/getting_started.md b/docs/source/getting_started.md deleted file mode 100644 index bac959d..0000000 --- a/docs/source/getting_started.md +++ /dev/null @@ -1,11 +0,0 @@ -# Getting started - -Here you may demonstrate the basic functionalities your package. - -You can include code snippets using the usual Markdown syntax: - -```python -from my_package import my_function - -result = my_function() -``` diff --git a/docs/source/index.md b/docs/source/index.md index b699a98..8189a4f 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -6,7 +6,6 @@ :caption: Contents: neuro_to_math - getting_started ``` This package acts as an interface between neurological region-connectivity data and network (graph) analysis. From 90e56a551e658992161f1dca2028c98f2d9b8b91 Mon Sep 17 00:00:00 2001 From: willGraham01 Date: Thu, 7 May 2026 11:54:12 +0100 Subject: [PATCH 04/32] Remove text that's repeated on another page from index.md --- docs/source/index.md | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/docs/source/index.md b/docs/source/index.md index 8189a4f..6150656 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -9,18 +9,6 @@ ``` This package acts as an interface between neurological region-connectivity data and network (graph) analysis. -Connectivity data generally consists of three components: - -- Information about the brain-regions, whose connections have been explored. - Typically their names, abbreviations, any groupings of regions, and other data like their spatial coordinates. -- The strength of the inter-region connections, which are considered directed. - This means that region A may connect to region B, but there may not be a reverse connection. - A connection is further attributed a weight, which may represent the strength of that connection, the time for a signal to travel along the connection, or other neurological quantity of interest. -- Further information about the connections. - This may consist of information about the studies in which they were examined, any special reference names they might have, or any user- or neurological-groupings of the connections themselves. - -Mathematically, such connection information is represented as a network (or graph), which makes it tractable to analysis via algorithms or manipulations of such objects. -The regions are represented by the nodes of the graph, and the connections by the edges within the graph. This allows us to phrase questions such as "what is the minimum travel time for a signal from region A to reach region B" as purely mathematical questions ("find the path between region A and region B that minimises the signal travel time") which can be solved using well-established network algorithms. ## Connectivity Data Input Format From 4639439f68216260e9fc884e132d7837f73fcb5f Mon Sep 17 00:00:00 2001 From: willGraham01 Date: Mon, 11 May 2026 11:46:14 +0100 Subject: [PATCH 05/32] Use Adam's metaphor instead --- docs/source/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/index.md b/docs/source/index.md index 6150656..80b92e6 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -9,7 +9,7 @@ ``` This package acts as an interface between neurological region-connectivity data and network (graph) analysis. -This allows us to phrase questions such as "what is the minimum travel time for a signal from region A to reach region B" as purely mathematical questions ("find the path between region A and region B that minimises the signal travel time") which can be solved using well-established network algorithms. +This allows us to phrase questions such as "how many direct routes are there from region A to region B?" as purely mathematical tasks ("find all non-cyclic paths between region A and region B, sorted by total connection strength") which can be solved using well-established network algorithms. ## Connectivity Data Input Format From 934c503790a5ce537bbeb3a8ca2ec19394c0afa7 Mon Sep 17 00:00:00 2001 From: willGraham01 Date: Tue, 12 May 2026 09:46:14 +0100 Subject: [PATCH 06/32] Sphinx gallery is added and working --- .gitignore | 1 + docs/source/conf.py | 7 +++++ docs/source/examples/GALLERY_HEADER.rst | 2 ++ docs/source/examples/example.py | 4 +++ docs/source/index.md | 2 ++ docs/source/sg_execution_times.rst | 37 +++++++++++++++++++++++++ pyproject.toml | 1 + 7 files changed, 54 insertions(+) create mode 100644 docs/source/examples/GALLERY_HEADER.rst create mode 100644 docs/source/examples/example.py create mode 100644 docs/source/sg_execution_times.rst diff --git a/.gitignore b/.gitignore index 0cbf68d..69604c5 100644 --- a/.gitignore +++ b/.gitignore @@ -58,6 +58,7 @@ instance/ # Sphinx documentation docs/_build/ +docs/source/examples/_gallery_examples # MkDocs documentation /site/ diff --git a/docs/source/conf.py b/docs/source/conf.py index d0ab1ae..a66c7fe 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -42,6 +42,7 @@ "sphinx.ext.autosummary", "sphinx.ext.viewcode", "sphinx.ext.intersphinx", + "sphinx_gallery.gen_gallery", "sphinx_sitemap", "myst_parser", ] @@ -69,6 +70,12 @@ # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] +# Sphinx gallery configuration settings +sphinx_gallery_conf = { + "examples_dirs": "examples", + "gallery_dirs": "_gallery_examples", +} + # Automatically generate stub pages for API autosummary_generate = True autodoc_default_flags = ["members", "inherited-members"] diff --git a/docs/source/examples/GALLERY_HEADER.rst b/docs/source/examples/GALLERY_HEADER.rst new file mode 100644 index 0000000..f8bf3da --- /dev/null +++ b/docs/source/examples/GALLERY_HEADER.rst @@ -0,0 +1,2 @@ +Hi +-- diff --git a/docs/source/examples/example.py b/docs/source/examples/example.py new file mode 100644 index 0000000..40e85ca --- /dev/null +++ b/docs/source/examples/example.py @@ -0,0 +1,4 @@ +"""A basic example""" + +# %% +# Look, some text! diff --git a/docs/source/index.md b/docs/source/index.md index 80b92e6..650eecb 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -5,7 +5,9 @@ :maxdepth: 2 :caption: Contents: + getting_started neuro_to_math + _gallery_examples/index ``` This package acts as an interface between neurological region-connectivity data and network (graph) analysis. diff --git a/docs/source/sg_execution_times.rst b/docs/source/sg_execution_times.rst new file mode 100644 index 0000000..9e593fb --- /dev/null +++ b/docs/source/sg_execution_times.rst @@ -0,0 +1,37 @@ + +:orphan: + +.. _sphx_glr_sg_execution_times: + + +Computation times +================= +**00:00.000** total execution time for 1 file **from all galleries**: + +.. container:: + + .. raw:: html + + + + + + + + .. list-table:: + :header-rows: 1 + :class: table table-striped sg-datatable + + * - Example + - Time + - Mem (MB) + * - :ref:`sphx_glr__auto_examples_example.py` (``examples/example.py``) + - 00:00.000 + - 0.0 diff --git a/pyproject.toml b/pyproject.toml index 100571a..3a1605f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -45,6 +45,7 @@ docs = [ "pydata-sphinx-theme", "sphinx", "sphinx_autodoc_typehints", + "sphinx-gallery", "sphinx_sitemap", "myst_parser[linkify]", ] From da1c19968923a8953d8b72268ff0959d73ae1f64 Mon Sep 17 00:00:00 2001 From: willGraham01 Date: Tue, 12 May 2026 09:53:08 +0100 Subject: [PATCH 07/32] Header is an actual header --- .gitignore | 2 +- docs/source/conf.py | 2 +- docs/source/examples/GALLERY_HEADER.rst | 6 ++++-- 3 files changed, 6 insertions(+), 4 deletions(-) diff --git a/.gitignore b/.gitignore index 69604c5..506b653 100644 --- a/.gitignore +++ b/.gitignore @@ -58,7 +58,7 @@ instance/ # Sphinx documentation docs/_build/ -docs/source/examples/_gallery_examples +docs/source/_gallery_examples # MkDocs documentation /site/ diff --git a/docs/source/conf.py b/docs/source/conf.py index a66c7fe..dfc2bea 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -73,7 +73,7 @@ # Sphinx gallery configuration settings sphinx_gallery_conf = { "examples_dirs": "examples", - "gallery_dirs": "_gallery_examples", + "gallery_dirs": "./_gallery_examples", } # Automatically generate stub pages for API diff --git a/docs/source/examples/GALLERY_HEADER.rst b/docs/source/examples/GALLERY_HEADER.rst index f8bf3da..c69ccc5 100644 --- a/docs/source/examples/GALLERY_HEADER.rst +++ b/docs/source/examples/GALLERY_HEADER.rst @@ -1,2 +1,4 @@ -Hi --- +Examples +-------- + +Some introductory tutorials on interacting with the connectivity API. From e7e9487460fe8f8099498042bb0aa1f64a0d6cef Mon Sep 17 00:00:00 2001 From: willGraham01 Date: Thu, 14 May 2026 14:18:18 +0100 Subject: [PATCH 08/32] getting_started no longer exists --- docs/source/index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/source/index.md b/docs/source/index.md index 650eecb..8b2678d 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -5,7 +5,6 @@ :maxdepth: 2 :caption: Contents: - getting_started neuro_to_math _gallery_examples/index ``` From 93b2901ded4c819d93fec12aa016bfb7d3081985 Mon Sep 17 00:00:00 2001 From: willGraham01 Date: Thu, 14 May 2026 14:37:47 +0100 Subject: [PATCH 09/32] re-write index paragraph with more focus on package purpose --- docs/source/index.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/source/index.md b/docs/source/index.md index 8b2678d..9bed648 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -10,7 +10,10 @@ ``` This package acts as an interface between neurological region-connectivity data and network (graph) analysis. -This allows us to phrase questions such as "how many direct routes are there from region A to region B?" as purely mathematical tasks ("find all non-cyclic paths between region A and region B, sorted by total connection strength") which can be solved using well-established network algorithms. +Connectivity data can be efficiently represented as a [network](./neuro_to_math.md), which means that common questions one want to run as part of an analysis of such data can be handled efficiently and quickly if one can formulate the corresponding mathematical questions and structures. +The purpose of the package is to allow users to ask these neurologically-motivated questions and receive the corresponding answers in an intuitive and helpful format; whilst in the background handling the mathematical representation so the user does not need to concern themselves with translating back and forth. + +For example, the question of "what is the shortest path between brain areas A and B that passes through region C?" can be phrased as the purely mathematical task of "determine the shortest path between region A and region C, and then the shortest path between region C and region B, and concatenate them", which can be handled using well-established network algorithms. ## Connectivity Data Input Format From 0c0bb2a33f599ca418c674ea7eedb4397eb50826 Mon Sep 17 00:00:00 2001 From: willGraham01 Date: Thu, 14 May 2026 16:01:39 +0100 Subject: [PATCH 10/32] Add an example to the translation page --- .../_static/example-connectivity-network.svg | 4 + docs/source/neuro_to_math.md | 129 +++++++++++++++--- 2 files changed, 114 insertions(+), 19 deletions(-) create mode 100644 docs/source/_static/example-connectivity-network.svg diff --git a/docs/source/_static/example-connectivity-network.svg b/docs/source/_static/example-connectivity-network.svg new file mode 100644 index 0000000..ebd344c --- /dev/null +++ b/docs/source/_static/example-connectivity-network.svg @@ -0,0 +1,4 @@ + + + +
l-a
l-b
r-b
r-a
0.5
0.1
1
0.5
0.1
1
0.5
 diff --git a/docs/source/neuro_to_math.md b/docs/source/neuro_to_math.md index 4cc9fee..067295f 100644 --- a/docs/source/neuro_to_math.md +++ b/docs/source/neuro_to_math.md @@ -2,34 +2,125 @@ On this page we aim to provide a short summary that reconciles the terminology used to describe connectivity data in neuroscience, and map it to the corresponding mathematical terminology surrounding networks. -## Networks +## Connectivity Data and Networks -A network (or graph) consists of: +Connectivity data generally consists of three to four components: -- A set of nodes (also called vertices) $V$. +- Information about the brain-regions, whose connections have been explored. + Typically they will be given some form of unique identifier, as well as names, abbreviations, any groupings of regions, and other data like their spatial coordinates. +- A listing of the connections between regions (which are considered directed), and the "strength" of each connection given as a numerical value. +- Further information about the connections. + This may consist of information about the studies in which they were examined, any special reference names they might have, or any user- or neurological-groupings of the connections themselves. +- Any metadata about the dataset, or study that generated the dataset. + These may be fields such as the species, sex, or age of the specimen from which the connectivity information was obtained, the institute at which the experiment was conducted, etc. + +Mathematical networks are an abstract representation of connections between a collection of objects. +A network consists of a collection of **nodes** that are connected to each other by (directed) **edges**, with each edge possessing a **weight** that characterises the connection. +As such, if we have some connectivity data; + +- The brain regions are represented by the nodes. + If the brain regions are provided with unique identifiers, these same identifiers can be used for the nodes. +- The connections between the brain regions are represented by edges. +- The strength of the connections are represented by the edge weights. + +The network that represents a particular dataset can be fully described simply by listing the connections, in what is often called an **edge list** or **edge table**. +This is what our API expects to receive as an input. +An edge table is just a three-column CSV file, where each row specifies one connection in the form + +```csv +source node, target node, connection strength +``` + +:::{note} +Any further information about the regions can be stored in some suitable data format (such as a `DataFrame`) that allows indexing via the region identifiers - this information is referred to as "region metadata" or "node metadata". + +Similarly, any further information about the connections (excluding their strengths) can be stored in tabular format that allows indexing via **pairs of** region identifiers that describes the connection's start and end - this information is referred to as "connection metadata" or "edge metadata". + +Region metadata (save for provision a unique identifiers for the regions) and connection metadata is entirely optional from a purely mathematical analysis of the connectivity data. +However, such information is normally incredibly helpful to have on-hand when one wants to run or plan neuroscientifically-relevant analysis! +::: + +### Example: Connectivity Data and the Corresponding Network + +FIXME: Get Stella to actually suggest sensible names for the brain regions & column names. + +Let us suppose we have gathered the following connectivity dataset, that describes connections between two brain regions on either side of a brain: + +| name | abbr | side of brain | +| :-: | :-: | :-: | +| alpha | l-a | left | +| bravo | l-b | left | +| alpha | r-a | right | +| bravo | r-b | right | + +where the `abbr` column is a unique identifier that we have given to each region in the brain. +Suppose we have then identified the following information about the connections between these regions: + +| source region | target region | connection strength | observation notes | +| :-: | :-: | :-: | :-: | +| l-a | l-b | 1.0 | high confidence | +| l-a | r-a | 0.5 | high confidence | +| l-b | r-a | 0.5 | low confidence | +| l-b | r-b | 0.5 | high confidence | +| r-a | r-b | 1.0 | med confidence | +| r-b | l-a | 0.1 | high confidence | +| r-b | l-b | 0.0 | not present | +| r-b | r-a | 0.1 | low confidence | + +Our connectivity information can be used to construct our edge-table CSV file: + +```csv +l-a, l-b, 1.0 +l-a, r-a, 0.5 +l-b, r-a, 0.5 +l-b, r-b, 0.5 +r-a, r-b, 1.0 +r-b, l-a, 0.1 +r-b, r-a, 0.1 +``` + +This edge table fully describes the network that will represent our connectivity data; there will be four nodes (`l-a`, `l-b`, `r-a`, `r-b`) and a total of seven edges. +We can even illustrate this network: + +![An illustration of the example connectivity data, as a network.](./_static/example-connectivity-network.svg) + +and we can also make a few observations: + +- The connection between `l-a` and `l-b` is bidirectional. + However, the connection from `l-a` to `l-b` is stronger (strength 1) than the connection from `l-b` to `l-a` (strength 0.5). +- The connection between `r-b` and `l-a` is unidirectional, directed from `r-b` into `l-a`. + It is also one of the weakest connections in the network, with a strength of 0.1. +- Each edge in the edge list corresponds to a **direct** connection between the regions. +- In addition to the direct connections, all of the regions are indirectly connected to each other (since there is a path that can be taken to each any particular region from any other region). + +:::{note} +Connections that are excluded from the edge table can fall into several categories: + +- No data: Following an extensive search, no reports were found with data relevant to the connection and suitable for inclusion in the network analysis. +- Unclear: It is unclear from the report if the connection exists or not. It is reasonable to infer that the connection is likely weak (at most), very weak, or absent. +- Evidence of Absence: Evidence indicates that the connection does not exist. +- Same origin & termination: Within‑region connections are not included in the network. + +In our example, we have excluded the `r-b` to `l-b` connection on the grounds of our experiments determining that no such connection exists between these two brain regions. + +Note that a connection being excluded from the edge table (and thus the network) has **different implications** to including a connection between two regions with a strength of 0. +::: + +## Mathematical Details + +However, we will need to establish some slightly more formal mathematical notation, that we'll be using throughout the package. +A network consists of: + +- A set of **nodes** (also called vertices), denoted by $V$. The nodes are indexed by some counter, so we typically write $V := \{ v_0, v_1, ..., v_N\}$ where each $v_i$ is one node, uniquely identified by the value of $i$. As such, when referring to nodes it is common to drop the $v_i$ notation and simply say "node $i$" in place of "node $v_i$". - A set of edges $E$. - Each edge $e\in E$ is written as $e = (i, j, w)$ (or $e = (v_i, v_j, w)$ if you prefer to keep the explicit node notation). - The edge $(i, j, w)$ means that there is an edge (connection) direct from node $i$ into node $j$, with a weight of $w$. + Each edge $e\in E$ is written as $e = (i, j, w)$ (or $e = (v_i, v_j, w)$). + $(i, j, w)$ means that there is an edge (connection) directed from node $i$ into node $j$, with a weight of $w$. So long as one has a consistent indexing for the nodes, a network can then be built up by listing the edges in $E$. Such a listing is often referred to as an "edge list" or "edge table", which is simply a 3-column format where each row lists a single edge $e$ in $(i, j, w)$ format. -## Connectivity Data - -Connectivity data generally consists of three components: - -- Information about the brain-regions, whose connections have been explored. - Typically they will be given some form of unique identifier, as well as names, abbreviations, any groupings of regions, and other data like their spatial coordinates. -- A listing of the connections between regions, which are considered directed. - A connection is further attributed some quantifiable "weight"; which may represent the strength of that connection, the time for a signal to travel along the connection, or other neurological quantity of interest. -- Further information about the connections. - This may consist of information about the studies in which they were examined, any special reference names they might have, or any user- or neurological-groupings of the connections themselves. - -## Reconciling the Terms - -As such, the regions should be thought of as nodes, and the connections as edges. If the regions are provided with unique identifiers, these same unique identifiers can be used as the indexes $i$ for the mathematical description of the nodes. In the same way, this also means that list of connections between the regions acts as out edge table, and thus we can build a network to represent our connectivity data. Any further information about the regions can be stored in some suitable data format (such as a `DataFrame`) that allows indexing via the region identifiers - this information is referred to as "node/region metadata". From b13eb011b4db1464ddee81422d674b94b97f5c43 Mon Sep 17 00:00:00 2001 From: willGraham01 Date: Thu, 14 May 2026 16:06:45 +0100 Subject: [PATCH 11/32] Add a hard maths section with notation --- docs/source/neuro_to_math.md | 27 ++++++++------------------- 1 file changed, 8 insertions(+), 19 deletions(-) diff --git a/docs/source/neuro_to_math.md b/docs/source/neuro_to_math.md index 067295f..e085efd 100644 --- a/docs/source/neuro_to_math.md +++ b/docs/source/neuro_to_math.md @@ -108,8 +108,10 @@ Note that a connection being excluded from the edge table (and thus the network) ## Mathematical Details -However, we will need to establish some slightly more formal mathematical notation, that we'll be using throughout the package. -A network consists of: +Whilst we can get by with a colloquial description of networks, in some places it will be necessary for us to use a more mathematical description of these objects. +We aim to set a standard for our notation - and conventions - in this section. + +A network $G = (V, E)$ consists of: - A set of **nodes** (also called vertices), denoted by $V$. The nodes are indexed by some counter, so we typically write $V := \{ v_0, v_1, ..., v_N\}$ where each $v_i$ is one node, uniquely identified by the value of $i$. @@ -118,24 +120,11 @@ A network consists of: Each edge $e\in E$ is written as $e = (i, j, w)$ (or $e = (v_i, v_j, w)$). $(i, j, w)$ means that there is an edge (connection) directed from node $i$ into node $j$, with a weight of $w$. -So long as one has a consistent indexing for the nodes, a network can then be built up by listing the edges in $E$. -Such a listing is often referred to as an "edge list" or "edge table", which is simply a 3-column format where each row lists a single edge $e$ in $(i, j, w)$ format. - -If the regions are provided with unique identifiers, these same unique identifiers can be used as the indexes $i$ for the mathematical description of the nodes. -In the same way, this also means that list of connections between the regions acts as out edge table, and thus we can build a network to represent our connectivity data. -Any further information about the regions can be stored in some suitable data format (such as a `DataFrame`) that allows indexing via the region identifiers - this information is referred to as "node/region metadata". -Similarly, any further information about the connections (excluding their weights) can be stored in tabular format that allows indexing via the $(i, j)$ pair that describes the connection's start and end - this information is referred to as "edge metadata". +The edge table that describes a network can then simply be seen as a listing of the edges $e\in E$. :::{note} -By convention, regions that are not connected do not appear in the edge list. -This is to distinguish regions that aren't connected, from regions that may happen to be connected with a weight of $0$, for example. +If the (brain)-regions are provided with unique identifiers, these same unique identifiers can be used as the indexes $i$ for the mathematical description of the nodes. -However, edge metadata _may_ contain information about a pair of regions $(i, j)$ that are not connected, without issue. -This is common when, for example, a study has determined that two regions are not connected and needs to encode this information into the connectivity dataset. -As such, not every connection that appears in the edge metadata may have an edge representing it in the mathematical network, however every edge in the mathematical network _does_ have a corresponding entry in the edge metadata table. -::: - -:::{note} -Node metadata (save for provision of a unique identifier for the regions) and edge metadata are entirely optional from a purely mathematical analysis of the connectivity data. -However, such information is normally incredibly helpful to have on-hand when one wants to run or plan neurologically-relevant analysis! +However, in practice the package prefers the use of integer indexes to identify the nodes, rather than names or abbreviations that connectivity data may prefer. +Where this is important, the package keeps a record of the correspondence between "internal indexes" for the nodes and the user-facing identifiers for the brain regions they represent. ::: From 36907460b06a02454c203faccdb118cc66b4fae6 Mon Sep 17 00:00:00 2001 From: willGraham01 Date: Thu, 14 May 2026 16:10:12 +0100 Subject: [PATCH 12/32] Format plaintext blocks correctly --- docs/source/neuro_to_math.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/source/neuro_to_math.md b/docs/source/neuro_to_math.md index e085efd..85b3aa3 100644 --- a/docs/source/neuro_to_math.md +++ b/docs/source/neuro_to_math.md @@ -27,7 +27,7 @@ The network that represents a particular dataset can be fully described simply b This is what our API expects to receive as an input. An edge table is just a three-column CSV file, where each row specifies one connection in the form -```csv +```text source node, target node, connection strength ``` @@ -69,7 +69,7 @@ Suppose we have then identified the following information about the connections Our connectivity information can be used to construct our edge-table CSV file: -```csv +```text l-a, l-b, 1.0 l-a, r-a, 0.5 l-b, r-a, 0.5 @@ -128,3 +128,5 @@ If the (brain)-regions are provided with unique identifiers, these same unique i However, in practice the package prefers the use of integer indexes to identify the nodes, rather than names or abbreviations that connectivity data may prefer. Where this is important, the package keeps a record of the correspondence between "internal indexes" for the nodes and the user-facing identifiers for the brain regions they represent. ::: + +FIXME: add notation for paths, etc. From bbbee17ac927c73091277dbdfc899544cc96b601 Mon Sep 17 00:00:00 2001 From: willGraham01 Date: Fri, 15 May 2026 09:26:58 +0100 Subject: [PATCH 13/32] Relocate examples folder as per s-gallery recommendation --- docs/{source => }/examples/GALLERY_HEADER.rst | 0 docs/examples/example.py | 14 ++++++++++++++ docs/source/conf.py | 3 ++- docs/source/examples/example.py | 4 ---- 4 files changed, 16 insertions(+), 5 deletions(-) rename docs/{source => }/examples/GALLERY_HEADER.rst (100%) create mode 100644 docs/examples/example.py delete mode 100644 docs/source/examples/example.py diff --git a/docs/source/examples/GALLERY_HEADER.rst b/docs/examples/GALLERY_HEADER.rst similarity index 100% rename from docs/source/examples/GALLERY_HEADER.rst rename to docs/examples/GALLERY_HEADER.rst diff --git a/docs/examples/example.py b/docs/examples/example.py new file mode 100644 index 0000000..1152df0 --- /dev/null +++ b/docs/examples/example.py @@ -0,0 +1,14 @@ +""" +A basic example +=============== + +Introductory text. + +""" + +# %% +# Look, some cell-based text! + +import brainglobe_data_api_connectivity as bdac + +print(bdac.__version__) diff --git a/docs/source/conf.py b/docs/source/conf.py index dfc2bea..2fc71ec 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -9,6 +9,7 @@ import os import sys from importlib.metadata import version as get_version +from pathlib import Path # Used when building API docs, put the dependencies # of any class you are documenting here @@ -72,7 +73,7 @@ # Sphinx gallery configuration settings sphinx_gallery_conf = { - "examples_dirs": "examples", + "examples_dirs": Path(__file__).parent / "../examples", "gallery_dirs": "./_gallery_examples", } diff --git a/docs/source/examples/example.py b/docs/source/examples/example.py deleted file mode 100644 index 40e85ca..0000000 --- a/docs/source/examples/example.py +++ /dev/null @@ -1,4 +0,0 @@ -"""A basic example""" - -# %% -# Look, some text! From 62f1aca284e7643645b8b5687990534b0cd9fa7f Mon Sep 17 00:00:00 2001 From: willGraham01 Date: Fri, 15 May 2026 09:40:19 +0100 Subject: [PATCH 14/32] Fix malformed refs --- docs/examples/example.py | 6 ++++-- docs/source/conf.py | 4 ++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/examples/example.py b/docs/examples/example.py index 1152df0..9ffd7b0 100644 --- a/docs/examples/example.py +++ b/docs/examples/example.py @@ -1,6 +1,8 @@ """ -A basic example -=============== +.. _basic_example: + +A basic example. +================ Introductory text. diff --git a/docs/source/conf.py b/docs/source/conf.py index 2fc71ec..0f7e1ac 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -73,8 +73,8 @@ # Sphinx gallery configuration settings sphinx_gallery_conf = { - "examples_dirs": Path(__file__).parent / "../examples", - "gallery_dirs": "./_gallery_examples", + "examples_dirs": Path(__file__).parent / "../examples/", + "gallery_dirs": Path(__file__).parent / "_gallery_examples/", } # Automatically generate stub pages for API From 04ffa8883e9def17c7c16d5c9b9fcf274f52e8e9 Mon Sep 17 00:00:00 2001 From: willGraham01 Date: Fri, 15 May 2026 09:52:49 +0100 Subject: [PATCH 15/32] Still trying to fix sphinx-gallery's weird linking --- .gitignore | 2 +- docs/examples/example.py | 2 -- docs/source/conf.py | 8 +++++++- docs/source/index.md | 2 +- docs/source/sg_execution_times.rst | 6 +++--- 5 files changed, 12 insertions(+), 8 deletions(-) diff --git a/.gitignore b/.gitignore index 506b653..592c49e 100644 --- a/.gitignore +++ b/.gitignore @@ -58,7 +58,7 @@ instance/ # Sphinx documentation docs/_build/ -docs/source/_gallery_examples +docs/source/examples # MkDocs documentation /site/ diff --git a/docs/examples/example.py b/docs/examples/example.py index 9ffd7b0..8e51cf3 100644 --- a/docs/examples/example.py +++ b/docs/examples/example.py @@ -1,6 +1,4 @@ """ -.. _basic_example: - A basic example. ================ diff --git a/docs/source/conf.py b/docs/source/conf.py index 0f7e1ac..421f950 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -71,10 +71,14 @@ # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] +SPHINX_GALLERY_OUTPUT_DIR = "examples/" + # Sphinx gallery configuration settings sphinx_gallery_conf = { "examples_dirs": Path(__file__).parent / "../examples/", - "gallery_dirs": Path(__file__).parent / "_gallery_examples/", + "filename_pattern": "/*.py", + "gallery_dirs": Path(__file__).parent / SPHINX_GALLERY_OUTPUT_DIR, + "run_stale_examples": True, } # Automatically generate stub pages for API @@ -89,6 +93,8 @@ # to ensure that include files (partial pages) aren't built, exclude them # https://github.com/sphinx-doc/sphinx/issues/1965#issuecomment-124732907 "**/includes/**", + f"{SPHINX_GALLERY_OUTPUT_DIR}/*ipynb", + f"{SPHINX_GALLERY_OUTPUT_DIR}/*.py", ] # -- Options for HTML output ------------------------------------------------- diff --git a/docs/source/index.md b/docs/source/index.md index 9bed648..e2d3fd4 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -6,7 +6,7 @@ :caption: Contents: neuro_to_math - _gallery_examples/index + examples/index ``` This package acts as an interface between neurological region-connectivity data and network (graph) analysis. diff --git a/docs/source/sg_execution_times.rst b/docs/source/sg_execution_times.rst index 9e593fb..80b8bb4 100644 --- a/docs/source/sg_execution_times.rst +++ b/docs/source/sg_execution_times.rst @@ -6,7 +6,7 @@ Computation times ================= -**00:00.000** total execution time for 1 file **from all galleries**: +**00:00.002** total execution time for 1 file **from all galleries**: .. container:: @@ -32,6 +32,6 @@ Computation times * - Example - Time - Mem (MB) - * - :ref:`sphx_glr__auto_examples_example.py` (``examples/example.py``) - - 00:00.000 + * - :ref:`sphx_glr_examples_example.py` (``../examples/example.py``) + - 00:00.002 - 0.0 From e686c5e1fdaa7e6bcb764fc0d425ae970e581572 Mon Sep 17 00:00:00 2001 From: willGraham01 Date: Fri, 15 May 2026 09:55:07 +0100 Subject: [PATCH 16/32] Prevent execution times file being part of the repo --- .gitignore | 3 ++- docs/source/sg_execution_times.rst | 37 ------------------------------ 2 files changed, 2 insertions(+), 38 deletions(-) delete mode 100644 docs/source/sg_execution_times.rst diff --git a/.gitignore b/.gitignore index 592c49e..5740e5e 100644 --- a/.gitignore +++ b/.gitignore @@ -57,8 +57,9 @@ local_settings.py instance/ # Sphinx documentation -docs/_build/ +docs/build/ docs/source/examples +docs/**/sg_execution_times.rst # MkDocs documentation /site/ diff --git a/docs/source/sg_execution_times.rst b/docs/source/sg_execution_times.rst deleted file mode 100644 index 80b8bb4..0000000 --- a/docs/source/sg_execution_times.rst +++ /dev/null @@ -1,37 +0,0 @@ - -:orphan: - -.. _sphx_glr_sg_execution_times: - - -Computation times -================= -**00:00.002** total execution time for 1 file **from all galleries**: - -.. container:: - - .. raw:: html - - - - - - - - .. list-table:: - :header-rows: 1 - :class: table table-striped sg-datatable - - * - Example - - Time - - Mem (MB) - * - :ref:`sphx_glr_examples_example.py` (``../examples/example.py``) - - 00:00.002 - - 0.0 From 471057f9e22876e2476d5aa45e8e9854f38a5537 Mon Sep 17 00:00:00 2001 From: willGraham01 Date: Fri, 15 May 2026 10:22:57 +0100 Subject: [PATCH 17/32] Build fails on GH actions because no matplotlib?? --- pyproject.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/pyproject.toml b/pyproject.toml index 3a1605f..198ecf5 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -42,6 +42,7 @@ dev = [ "setuptools-scm", ] docs = [ + "matplotlib", "pydata-sphinx-theme", "sphinx", "sphinx_autodoc_typehints", From fd2b08fc34740f8f9ec8de000adb9e872767e0da Mon Sep 17 00:00:00 2001 From: willGraham01 Date: Fri, 15 May 2026 11:01:12 +0100 Subject: [PATCH 18/32] Add some expanded notes on the graph representation in the package --- docs/source/neuro_to_math.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/source/neuro_to_math.md b/docs/source/neuro_to_math.md index 85b3aa3..5fef461 100644 --- a/docs/source/neuro_to_math.md +++ b/docs/source/neuro_to_math.md @@ -106,7 +106,7 @@ In our example, we have excluded the `r-b` to `l-b` connection on the grounds of Note that a connection being excluded from the edge table (and thus the network) has **different implications** to including a connection between two regions with a strength of 0. ::: -## Mathematical Details +## Mathematical Details and Implementation Whilst we can get by with a colloquial description of networks, in some places it will be necessary for us to use a more mathematical description of these objects. We aim to set a standard for our notation - and conventions - in this section. @@ -129,4 +129,10 @@ However, in practice the package prefers the use of integer indexes to identify Where this is important, the package keeps a record of the correspondence between "internal indexes" for the nodes and the user-facing identifiers for the brain regions they represent. ::: -FIXME: add notation for paths, etc. +In practice, the API relies on the [`rustworkx`](https://www.rustworkx.org/) library for all network-related queries. +Connectivity data is represented by a [`PyDiGraph` class](https://www.rustworkx.org/apiref/rustworkx.PyDiGraph.html), which is exposed through the [`Connections.network`](FIXME) attribute to allow for flexible querying of the network structure if specialised analyses are required. + +The API also separates the "metadata" concerning the nodes/regions and edges/connections from the underlying network object itself. +As such, the nodes in the `.network` use integer indexing, which is referred to as their "internal indexes". +These internal indexes are appended as a column to the node metadata, so there is a means of translating between the neuroscientific information about a brain region and its abstract representation. +Several functions also exist to aid in obtaining a selection of nodes by matching metadata criteria, and vice-versa. From 76faceeee9245f3ee6c72df881854fcd60dd011b Mon Sep 17 00:00:00 2001 From: willGraham01 Date: Fri, 15 May 2026 11:05:14 +0100 Subject: [PATCH 19/32] Link checker is very zealous --- docs/source/neuro_to_math.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/source/neuro_to_math.md b/docs/source/neuro_to_math.md index 5fef461..a4f9cb6 100644 --- a/docs/source/neuro_to_math.md +++ b/docs/source/neuro_to_math.md @@ -130,7 +130,9 @@ Where this is important, the package keeps a record of the correspondence betwee ::: In practice, the API relies on the [`rustworkx`](https://www.rustworkx.org/) library for all network-related queries. -Connectivity data is represented by a [`PyDiGraph` class](https://www.rustworkx.org/apiref/rustworkx.PyDiGraph.html), which is exposed through the [`Connections.network`](FIXME) attribute to allow for flexible querying of the network structure if specialised analyses are required. +Connectivity data is represented by a [`PyDiGraph` class](https://www.rustworkx.org/apiref/rustworkx.PyDiGraph.html), which is exposed through the `Connections.network` attribute to allow for flexible querying of the network structure if specialised analyses are required. + + The API also separates the "metadata" concerning the nodes/regions and edges/connections from the underlying network object itself. As such, the nodes in the `.network` use integer indexing, which is referred to as their "internal indexes". From 779d278c41c62747ec6dfe40815a3ff8d6ba0a31 Mon Sep 17 00:00:00 2001 From: Stella <30465823+stellaprins@users.noreply.github.com> Date: Wed, 27 May 2026 16:27:12 +0100 Subject: [PATCH 20/32] Add clarifications to Connectivity Data and Networks section three to four components -> following components (because three to four components leaves some ambiguity about which component is optional, I am assuming the metadata one?) specimen -> animal (charachteristics like age and sex refer to the living animal before the samples or specimens were collected, specimens are typically preserved animals, samples or tissue) --- docs/source/neuro_to_math.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/neuro_to_math.md b/docs/source/neuro_to_math.md index a4f9cb6..654df51 100644 --- a/docs/source/neuro_to_math.md +++ b/docs/source/neuro_to_math.md @@ -4,7 +4,7 @@ On this page we aim to provide a short summary that reconciles the terminology u ## Connectivity Data and Networks -Connectivity data generally consists of three to four components: +Connectivity data generally consists of the following components: - Information about the brain-regions, whose connections have been explored. Typically they will be given some form of unique identifier, as well as names, abbreviations, any groupings of regions, and other data like their spatial coordinates. @@ -12,7 +12,7 @@ Connectivity data generally consists of three to four components: - Further information about the connections. This may consist of information about the studies in which they were examined, any special reference names they might have, or any user- or neurological-groupings of the connections themselves. - Any metadata about the dataset, or study that generated the dataset. - These may be fields such as the species, sex, or age of the specimen from which the connectivity information was obtained, the institute at which the experiment was conducted, etc. + These may be fields such as the species, sex, or age of the animal from which the connectivity information was obtained, the institute at which the experiment was conducted, etc. Mathematical networks are an abstract representation of connections between a collection of objects. A network consists of a collection of **nodes** that are connected to each other by (directed) **edges**, with each edge possessing a **weight** that characterises the connection. From 7e64bddde6ec4ea6bcb029a4f31fd8b189a690c9 Mon Sep 17 00:00:00 2001 From: Stella <30465823+stellaprins@users.noreply.github.com> Date: Wed, 27 May 2026 17:29:11 +0100 Subject: [PATCH 21/32] Fix grammar and use easier to understand wording I did not know what "save for provision" meant --- docs/source/neuro_to_math.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/neuro_to_math.md b/docs/source/neuro_to_math.md index 654df51..baca400 100644 --- a/docs/source/neuro_to_math.md +++ b/docs/source/neuro_to_math.md @@ -36,7 +36,7 @@ Any further information about the regions can be stored in some suitable data fo Similarly, any further information about the connections (excluding their strengths) can be stored in tabular format that allows indexing via **pairs of** region identifiers that describes the connection's start and end - this information is referred to as "connection metadata" or "edge metadata". -Region metadata (save for provision a unique identifiers for the regions) and connection metadata is entirely optional from a purely mathematical analysis of the connectivity data. +Region metadata (except for unique region identifiers) and connection metadata is entirely optional from a purely mathematical analysis of the connectivity data. However, such information is normally incredibly helpful to have on-hand when one wants to run or plan neuroscientifically-relevant analysis! ::: From 7f6fc7ee7719b16ca0681384863c5bf38309ee24 Mon Sep 17 00:00:00 2001 From: Stella <30465823+stellaprins@users.noreply.github.com> Date: Wed, 27 May 2026 17:35:23 +0100 Subject: [PATCH 22/32] correct typo / mistake (from -> for) --- docs/source/neuro_to_math.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/neuro_to_math.md b/docs/source/neuro_to_math.md index baca400..1384487 100644 --- a/docs/source/neuro_to_math.md +++ b/docs/source/neuro_to_math.md @@ -36,7 +36,7 @@ Any further information about the regions can be stored in some suitable data fo Similarly, any further information about the connections (excluding their strengths) can be stored in tabular format that allows indexing via **pairs of** region identifiers that describes the connection's start and end - this information is referred to as "connection metadata" or "edge metadata". -Region metadata (except for unique region identifiers) and connection metadata is entirely optional from a purely mathematical analysis of the connectivity data. +Region metadata (except for unique region identifiers) and connection metadata is entirely optional for a purely mathematical analysis of the connectivity data. However, such information is normally incredibly helpful to have on-hand when one wants to run or plan neuroscientifically-relevant analysis! ::: From 27d94bab3b1b70beaba0fd60242b85ed64b837fa Mon Sep 17 00:00:00 2001 From: Stella <30465823+stellaprins@users.noreply.github.com> Date: Wed, 27 May 2026 17:42:49 +0100 Subject: [PATCH 23/32] change hyphen to em dash where appropriate for correct punctuation --- docs/source/neuro_to_math.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/neuro_to_math.md b/docs/source/neuro_to_math.md index 1384487..5ef03cb 100644 --- a/docs/source/neuro_to_math.md +++ b/docs/source/neuro_to_math.md @@ -32,9 +32,9 @@ source node, target node, connection strength ``` :::{note} -Any further information about the regions can be stored in some suitable data format (such as a `DataFrame`) that allows indexing via the region identifiers - this information is referred to as "region metadata" or "node metadata". +Any further information about the regions can be stored in some suitable data format (such as a `DataFrame`) that allows indexing via the region identifiers—this information is referred to as "region metadata" or "node metadata". -Similarly, any further information about the connections (excluding their strengths) can be stored in tabular format that allows indexing via **pairs of** region identifiers that describes the connection's start and end - this information is referred to as "connection metadata" or "edge metadata". +Similarly, any further information about the connections (excluding their strengths) can be stored in tabular format that allows indexing via **pairs of** region identifiers that describes the connection's start and end—this information is referred to as "connection metadata" or "edge metadata". Region metadata (except for unique region identifiers) and connection metadata is entirely optional for a purely mathematical analysis of the connectivity data. However, such information is normally incredibly helpful to have on-hand when one wants to run or plan neuroscientifically-relevant analysis! @@ -109,7 +109,7 @@ Note that a connection being excluded from the edge table (and thus the network) ## Mathematical Details and Implementation Whilst we can get by with a colloquial description of networks, in some places it will be necessary for us to use a more mathematical description of these objects. -We aim to set a standard for our notation - and conventions - in this section. +We aim to set a standard for our notation—and conventions—in this section. A network $G = (V, E)$ consists of: From 46fafca180a659282ff6f120f24b5e107f535bd9 Mon Sep 17 00:00:00 2001 From: Stella <30465823+stellaprins@users.noreply.github.com> Date: Wed, 27 May 2026 17:46:18 +0100 Subject: [PATCH 24/32] fix grammar (is -> are) --- docs/source/neuro_to_math.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/neuro_to_math.md b/docs/source/neuro_to_math.md index 5ef03cb..f085a2c 100644 --- a/docs/source/neuro_to_math.md +++ b/docs/source/neuro_to_math.md @@ -36,7 +36,7 @@ Any further information about the regions can be stored in some suitable data fo Similarly, any further information about the connections (excluding their strengths) can be stored in tabular format that allows indexing via **pairs of** region identifiers that describes the connection's start and end—this information is referred to as "connection metadata" or "edge metadata". -Region metadata (except for unique region identifiers) and connection metadata is entirely optional for a purely mathematical analysis of the connectivity data. +Region metadata (except for unique region identifiers) and connection metadata are entirely optional for a purely mathematical analysis of the connectivity data. However, such information is normally incredibly helpful to have on-hand when one wants to run or plan neuroscientifically-relevant analysis! ::: From 4200f546386c650d3cb208236b2ed0164e4cf83a Mon Sep 17 00:00:00 2001 From: Stella <30465823+stellaprins@users.noreply.github.com> Date: Wed, 27 May 2026 18:07:37 +0100 Subject: [PATCH 25/32] Add recommendation to have the metadata not only for planning and interpreting anlyses but also for reproducibility also, on-hand should be without hyphen (on hand) --- docs/source/neuro_to_math.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/neuro_to_math.md b/docs/source/neuro_to_math.md index f085a2c..49fa386 100644 --- a/docs/source/neuro_to_math.md +++ b/docs/source/neuro_to_math.md @@ -37,7 +37,7 @@ Any further information about the regions can be stored in some suitable data fo Similarly, any further information about the connections (excluding their strengths) can be stored in tabular format that allows indexing via **pairs of** region identifiers that describes the connection's start and end—this information is referred to as "connection metadata" or "edge metadata". Region metadata (except for unique region identifiers) and connection metadata are entirely optional for a purely mathematical analysis of the connectivity data. -However, such information is normally incredibly helpful to have on-hand when one wants to run or plan neuroscientifically-relevant analysis! +However, adding this information is normally recommended, as it helps guide analyses, makes the results easier to interpret, and improves reproducibility. ::: ### Example: Connectivity Data and the Corresponding Network From d49b1fba3744569e5202747f294d990536ef8e21 Mon Sep 17 00:00:00 2001 From: Stella <30465823+stellaprins@users.noreply.github.com> Date: Wed, 27 May 2026 21:57:00 +0100 Subject: [PATCH 26/32] Split page in two (I hope this makes sense?!) --- docs/source/connectivity-data.md | 117 ++++++++++++++++++++++++++ docs/source/connectivity-math.md | 29 +++++++ docs/source/index.md | 16 ++-- docs/source/neuro_to_math.md | 140 ------------------------------- 4 files changed, 156 insertions(+), 146 deletions(-) create mode 100644 docs/source/connectivity-data.md create mode 100644 docs/source/connectivity-math.md delete mode 100644 docs/source/neuro_to_math.md diff --git a/docs/source/connectivity-data.md b/docs/source/connectivity-data.md new file mode 100644 index 0000000..bf9da84 --- /dev/null +++ b/docs/source/connectivity-data.md @@ -0,0 +1,117 @@ +# Connectivity Data +We can divide connectivity data into: +- a network consisting of nodes, edges, and weights +- the metadata (everything we know about the regions, connections, and dataset) + +While graph analysis can be done using only the network, the metadata is essential for guiding analyses, understanding results, and making the work reproducible. + +## Networks + +Mathematical networks are an abstract representation of connections between a collection of objects. +A network consists of a collection of **nodes** that are connected to each other by (directed) **edges**, with each edge possessing a **weight** that characterises the connection. +As such, if we have some connectivity data; + +- The brain regions are represented by the nodes. + If the brain regions are provided with unique identifiers, these same identifiers can be used for the nodes. +- The connections between the brain regions are represented by edges. +- The strength of the connections are represented by the edge weights. + +The network that represents a particular dataset can be fully described simply by listing the connections, in what is often called an **edge list** or **edge table**. + +This is what our API expects to receive as an input. + +An edge table is just a three-column CSV file, where each row specifies one connection in the form: + +```text +source node, target node, connection strength +``` + +### Example: Edge Table and Corresponding Network + +Our connectivity information can be used to construct our edge table CSV file: + +```text +l-a, l-b, 1.0 +l-a, r-a, 0.5 +l-b, r-a, 0.5 +l-b, r-b, 0.5 +r-a, r-b, 1.0 +r-b, l-a, 0.1 +r-b, r-a, 0.1 +``` + +This edge table fully describes the network that will represent our connectivity data; there will be four nodes (`l-a`, `l-b`, `r-a`, `r-b`) and a total of seven edges. + +We can illustrate this network: + +![An illustration of the example connectivity data, as a network.](./_static/example-connectivity-network.svg) + +and we can also make a few observations: + +- The connection between `l-a` and `l-b` is bidirectional. + However, the connection from `l-a` to `l-b` is stronger (strength 1) than the connection from `l-b` to `l-a` (strength 0.5). +- The connection between `r-b` and `l-a` is unidirectional, directed from `r-b` into `l-a`. + It is also one of the weakest connections in the network, with a strength of 0.1. +- Each edge in the edge list corresponds to a **direct** connection between the regions. +- In addition to the direct connections, all of the regions are indirectly connected to each other (since there is a path that can be taken to each any particular region from any other region). + +:::{note} +Often the description of nodes, edges, and weights given here is all you need. But sometimes you may need a more precise, mathematical description of how nodes, edges, and weights are defined, for this see [Mathematical Description of a Network](..\connectivity-math.md). +::: + +## Metadata +Although a great deal can be learned from the network structure alone, to make sense of what the nodes and edges actually represent you also need the metadata. + +Connectivity metadata generally consists of the following components: +- **Dataset Metadata**: Information about the dataset, or study that generated the dataset. + These may be fields such as the species, sex, or age of the animal from which the connectivity information was obtained, the institute at which the experiment was conducted, etc. +- **Node Metadata**: Information about the brain-regions, whose connections have been explored. + Typically they will be given some form of unique identifier, as well as names, abbreviations, any groupings of regions, and other data like their spatial coordinates. +- **Edge Metadata**: Information about the connections. + This may consist of information about the studies in which they were examined, any special reference names they might have, or any user- or neurological-groupings of the connections themselves. + +### Example: Metadata + +**Dataset Metadata** + +| | | +| ------------ | --------------------- | +| project | Alpha–Bravo Connectivity | +| contributors | Jane Doe | +| year | 2024 | +| species | Rattus bravalpha | +| age | 12 weeks | +| sex | F | + + +**Node Metadata** + +| name | abbr | side of brain | +| ----- | -----| -------------- | +| alpha | l‑a | left | +| bravo | l‑b | left | +| alpha | r‑a | right | +| bravo | r‑b | right | + +**Note**: The `abbr` column provides the unique identifiers used in the edge table. + +**Edge Metadata** + +| source | target | method | reference | notes | +| ------ | ------ | ---------- | ---------------- | ----- | +| l‑a | l‑b | anterograde | Doe & Roe, 1992 | | +| l‑a | r‑a | retrograde | Doe & Roe, 1992 | | +| l‑b | r‑a | anterograde | Doe et al., 1999 | | +| l‑b | r‑b | retrograde | Doe et al., 1999 | | +| r‑a | r‑b | anterograde | Doe et al., 1999 | | +| r‑b | l‑a | retrograde | Li et al., 2012 | | +| r‑b | l‑b | anterograde | Doe et al., 1996 | injection too large to interpret positive labeling; evidence used for “absent” classification | +| r‑b | r‑a | retrograde | Li et al., 2012 | | + +**Note**: The `source` and `target` columns provide the unique identifiers used in the edge table. + +## Identifiers + +It is important to be able to match the metadata to the network structure so that each node and connection in the edge table can be related back to the biological regions and studies they represent. + +In this example, the common identifiers used the abbreviations `l‑a`, `l‑b`, `r‑a`, and `r‑b`. These appear in the edge table as the node labels, and the same labels appear in the node metadata so that each entry in the network can be matched to the corresponding brain region. diff --git a/docs/source/connectivity-math.md b/docs/source/connectivity-math.md new file mode 100644 index 0000000..6c01288 --- /dev/null +++ b/docs/source/connectivity-math.md @@ -0,0 +1,29 @@ +# Mathematical Description of a Network + +Whilst we can get by with a colloquial description of networks, in some places it will be necessary for us to use a more mathematical description of these objects. +We aim to set a standard for our notation—and conventions—in this section. + +A network $G = (V, E)$ consists of: + +- A set of **nodes** (also called vertices), denoted by $V$. + The nodes are indexed by some counter, so we typically write $V := \{ v_0, v_1, ..., v_N\}$ where each $v_i$ is one node, uniquely identified by the value of $i$. + As such, when referring to nodes it is common to drop the $v_i$ notation and simply say "node $i$" in place of "node $v_i$". +- A set of edges $E$. + Each edge $e\in E$ is written as $e = (i, j, w)$ (or $e = (v_i, v_j, w)$). + $(i, j, w)$ means that there is an edge (connection) directed from node $i$ into node $j$, with a weight of $w$. + +The edge table that describes a network can then simply be seen as a listing of the edges $e\in E$. + +:::{note} +If the (brain)-regions are provided with unique identifiers, these same unique identifiers can be used as the indexes $i$ for the mathematical description of the nodes. + +However, in practice the package prefers the use of integer indexes to identify the nodes, rather than names or abbreviations that connectivity data may prefer. +Where this is important, the package keeps a record of the correspondence between "internal indexes" for the nodes and the user-facing identifiers for the brain regions they represent. +::: + + + +The API also separates the "metadata" concerning the nodes/regions and edges/connections from the underlying network object itself. +As such, the nodes in the `.network` use integer indexing, which is referred to as their "internal indexes". +These internal indexes are appended as a column to the node metadata, so there is a means of translating between the neuroscientific information about a brain region and its abstract representation. +Several functions also exist to aid in obtaining a selection of nodes by matching metadata criteria, and vice-versa. diff --git a/docs/source/index.md b/docs/source/index.md index e2d3fd4..7c8cde0 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -5,16 +5,20 @@ :maxdepth: 2 :caption: Contents: - neuro_to_math + connectivity-math + connectivity-data examples/index ``` -This package acts as an interface between neurological region-connectivity data and network (graph) analysis. -Connectivity data can be efficiently represented as a [network](./neuro_to_math.md), which means that common questions one want to run as part of an analysis of such data can be handled efficiently and quickly if one can formulate the corresponding mathematical questions and structures. -The purpose of the package is to allow users to ask these neurologically-motivated questions and receive the corresponding answers in an intuitive and helpful format; whilst in the background handling the mathematical representation so the user does not need to concern themselves with translating back and forth. +This package acts as an interface between brain connectivity data and graph‑based analyses. -For example, the question of "what is the shortest path between brain areas A and B that passes through region C?" can be phrased as the purely mathematical task of "determine the shortest path between region A and region C, and then the shortest path between region C and region B, and concatenate them", which can be handled using well-established network algorithms. +The purpose of the package is to provide neuroscientists with an interface for asking questions about a connectivity network without having to translate those questions into mathematical graph operations. -## Connectivity Data Input Format +For example, the question "what is the shortest path between brain areas A and B that passes through region C?" translates to "determine the shortest path between region A and region C, and then the shortest path between region C and region B, and concatenate them", which can be handled using well-established network algorithms. + +In practice, the API relies on the [`rustworkx`](https://www.rustworkx.org/) library for all network-related queries. Connectivity data is represented by a [`PyDiGraph` class](https://www.rustworkx.org/apiref/rustworkx.PyDiGraph.html), which is exposed through the `Connections.network` attribute to allow for flexible querying of the network structure if specialised analyses are required. + +## Connectivity Data +See [Connectivity Data](./connectivity-data.md) for details on the structure of the input data, including networks and metadata. ## Interacting with the Data diff --git a/docs/source/neuro_to_math.md b/docs/source/neuro_to_math.md deleted file mode 100644 index 49fa386..0000000 --- a/docs/source/neuro_to_math.md +++ /dev/null @@ -1,140 +0,0 @@ -# Neuroscience and Mathematical Terminology - -On this page we aim to provide a short summary that reconciles the terminology used to describe connectivity data in neuroscience, and map it to the corresponding mathematical terminology surrounding networks. - -## Connectivity Data and Networks - -Connectivity data generally consists of the following components: - -- Information about the brain-regions, whose connections have been explored. - Typically they will be given some form of unique identifier, as well as names, abbreviations, any groupings of regions, and other data like their spatial coordinates. -- A listing of the connections between regions (which are considered directed), and the "strength" of each connection given as a numerical value. -- Further information about the connections. - This may consist of information about the studies in which they were examined, any special reference names they might have, or any user- or neurological-groupings of the connections themselves. -- Any metadata about the dataset, or study that generated the dataset. - These may be fields such as the species, sex, or age of the animal from which the connectivity information was obtained, the institute at which the experiment was conducted, etc. - -Mathematical networks are an abstract representation of connections between a collection of objects. -A network consists of a collection of **nodes** that are connected to each other by (directed) **edges**, with each edge possessing a **weight** that characterises the connection. -As such, if we have some connectivity data; - -- The brain regions are represented by the nodes. - If the brain regions are provided with unique identifiers, these same identifiers can be used for the nodes. -- The connections between the brain regions are represented by edges. -- The strength of the connections are represented by the edge weights. - -The network that represents a particular dataset can be fully described simply by listing the connections, in what is often called an **edge list** or **edge table**. -This is what our API expects to receive as an input. -An edge table is just a three-column CSV file, where each row specifies one connection in the form - -```text -source node, target node, connection strength -``` - -:::{note} -Any further information about the regions can be stored in some suitable data format (such as a `DataFrame`) that allows indexing via the region identifiers—this information is referred to as "region metadata" or "node metadata". - -Similarly, any further information about the connections (excluding their strengths) can be stored in tabular format that allows indexing via **pairs of** region identifiers that describes the connection's start and end—this information is referred to as "connection metadata" or "edge metadata". - -Region metadata (except for unique region identifiers) and connection metadata are entirely optional for a purely mathematical analysis of the connectivity data. -However, adding this information is normally recommended, as it helps guide analyses, makes the results easier to interpret, and improves reproducibility. -::: - -### Example: Connectivity Data and the Corresponding Network - -FIXME: Get Stella to actually suggest sensible names for the brain regions & column names. - -Let us suppose we have gathered the following connectivity dataset, that describes connections between two brain regions on either side of a brain: - -| name | abbr | side of brain | -| :-: | :-: | :-: | -| alpha | l-a | left | -| bravo | l-b | left | -| alpha | r-a | right | -| bravo | r-b | right | - -where the `abbr` column is a unique identifier that we have given to each region in the brain. -Suppose we have then identified the following information about the connections between these regions: - -| source region | target region | connection strength | observation notes | -| :-: | :-: | :-: | :-: | -| l-a | l-b | 1.0 | high confidence | -| l-a | r-a | 0.5 | high confidence | -| l-b | r-a | 0.5 | low confidence | -| l-b | r-b | 0.5 | high confidence | -| r-a | r-b | 1.0 | med confidence | -| r-b | l-a | 0.1 | high confidence | -| r-b | l-b | 0.0 | not present | -| r-b | r-a | 0.1 | low confidence | - -Our connectivity information can be used to construct our edge-table CSV file: - -```text -l-a, l-b, 1.0 -l-a, r-a, 0.5 -l-b, r-a, 0.5 -l-b, r-b, 0.5 -r-a, r-b, 1.0 -r-b, l-a, 0.1 -r-b, r-a, 0.1 -``` - -This edge table fully describes the network that will represent our connectivity data; there will be four nodes (`l-a`, `l-b`, `r-a`, `r-b`) and a total of seven edges. -We can even illustrate this network: - -![An illustration of the example connectivity data, as a network.](./_static/example-connectivity-network.svg) - -and we can also make a few observations: - -- The connection between `l-a` and `l-b` is bidirectional. - However, the connection from `l-a` to `l-b` is stronger (strength 1) than the connection from `l-b` to `l-a` (strength 0.5). -- The connection between `r-b` and `l-a` is unidirectional, directed from `r-b` into `l-a`. - It is also one of the weakest connections in the network, with a strength of 0.1. -- Each edge in the edge list corresponds to a **direct** connection between the regions. -- In addition to the direct connections, all of the regions are indirectly connected to each other (since there is a path that can be taken to each any particular region from any other region). - -:::{note} -Connections that are excluded from the edge table can fall into several categories: - -- No data: Following an extensive search, no reports were found with data relevant to the connection and suitable for inclusion in the network analysis. -- Unclear: It is unclear from the report if the connection exists or not. It is reasonable to infer that the connection is likely weak (at most), very weak, or absent. -- Evidence of Absence: Evidence indicates that the connection does not exist. -- Same origin & termination: Within‑region connections are not included in the network. - -In our example, we have excluded the `r-b` to `l-b` connection on the grounds of our experiments determining that no such connection exists between these two brain regions. - -Note that a connection being excluded from the edge table (and thus the network) has **different implications** to including a connection between two regions with a strength of 0. -::: - -## Mathematical Details and Implementation - -Whilst we can get by with a colloquial description of networks, in some places it will be necessary for us to use a more mathematical description of these objects. -We aim to set a standard for our notation—and conventions—in this section. - -A network $G = (V, E)$ consists of: - -- A set of **nodes** (also called vertices), denoted by $V$. - The nodes are indexed by some counter, so we typically write $V := \{ v_0, v_1, ..., v_N\}$ where each $v_i$ is one node, uniquely identified by the value of $i$. - As such, when referring to nodes it is common to drop the $v_i$ notation and simply say "node $i$" in place of "node $v_i$". -- A set of edges $E$. - Each edge $e\in E$ is written as $e = (i, j, w)$ (or $e = (v_i, v_j, w)$). - $(i, j, w)$ means that there is an edge (connection) directed from node $i$ into node $j$, with a weight of $w$. - -The edge table that describes a network can then simply be seen as a listing of the edges $e\in E$. - -:::{note} -If the (brain)-regions are provided with unique identifiers, these same unique identifiers can be used as the indexes $i$ for the mathematical description of the nodes. - -However, in practice the package prefers the use of integer indexes to identify the nodes, rather than names or abbreviations that connectivity data may prefer. -Where this is important, the package keeps a record of the correspondence between "internal indexes" for the nodes and the user-facing identifiers for the brain regions they represent. -::: - -In practice, the API relies on the [`rustworkx`](https://www.rustworkx.org/) library for all network-related queries. -Connectivity data is represented by a [`PyDiGraph` class](https://www.rustworkx.org/apiref/rustworkx.PyDiGraph.html), which is exposed through the `Connections.network` attribute to allow for flexible querying of the network structure if specialised analyses are required. - - - -The API also separates the "metadata" concerning the nodes/regions and edges/connections from the underlying network object itself. -As such, the nodes in the `.network` use integer indexing, which is referred to as their "internal indexes". -These internal indexes are appended as a column to the node metadata, so there is a means of translating between the neuroscientific information about a brain region and its abstract representation. -Several functions also exist to aid in obtaining a selection of nodes by matching metadata criteria, and vice-versa. From f087382711b4ef9acccae823ad8862bca8436cf2 Mon Sep 17 00:00:00 2001 From: Stella <30465823+stellaprins@users.noreply.github.com> Date: Thu, 28 May 2026 07:38:35 +0100 Subject: [PATCH 27/32] fix internal reference --- docs/source/connectivity-data.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/connectivity-data.md b/docs/source/connectivity-data.md index bf9da84..6e10eb3 100644 --- a/docs/source/connectivity-data.md +++ b/docs/source/connectivity-data.md @@ -56,7 +56,7 @@ and we can also make a few observations: - In addition to the direct connections, all of the regions are indirectly connected to each other (since there is a path that can be taken to each any particular region from any other region). :::{note} -Often the description of nodes, edges, and weights given here is all you need. But sometimes you may need a more precise, mathematical description of how nodes, edges, and weights are defined, for this see [Mathematical Description of a Network](..\connectivity-math.md). +Often the description of nodes, edges, and weights given here is all you need. But sometimes you may need a more precise, mathematical description of how nodes, edges, and weights are defined, for this see [Mathematical Description of a Network](.\connectivity-math.md). ::: ## Metadata From d2f3cf060cd1be3a636bb17b07266d8c9d0c8683 Mon Sep 17 00:00:00 2001 From: Stella <30465823+stellaprins@users.noreply.github.com> Date: Thu, 28 May 2026 07:47:46 +0100 Subject: [PATCH 28/32] fix internal reference (forward slash only) --- docs/source/connectivity-data.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/connectivity-data.md b/docs/source/connectivity-data.md index 6e10eb3..006aca5 100644 --- a/docs/source/connectivity-data.md +++ b/docs/source/connectivity-data.md @@ -56,7 +56,7 @@ and we can also make a few observations: - In addition to the direct connections, all of the regions are indirectly connected to each other (since there is a path that can be taken to each any particular region from any other region). :::{note} -Often the description of nodes, edges, and weights given here is all you need. But sometimes you may need a more precise, mathematical description of how nodes, edges, and weights are defined, for this see [Mathematical Description of a Network](.\connectivity-math.md). +Often the description of nodes, edges, and weights given here is all you need. But sometimes you may need a more precise, mathematical description of how nodes, edges, and weights are defined, for this see [Mathematical Description of a Network](./connectivity-math.md). ::: ## Metadata From 212246d8b5719bbae36eb90afa4d9a5ee881b289 Mon Sep 17 00:00:00 2001 From: Stella <30465823+stellaprins@users.noreply.github.com> Date: Thu, 28 May 2026 09:15:12 +0100 Subject: [PATCH 29/32] Add structure and internal indexes example to math docs --- docs/source/connectivity-math.md | 74 +++++++++++++++++++++++++------- 1 file changed, 58 insertions(+), 16 deletions(-) diff --git a/docs/source/connectivity-math.md b/docs/source/connectivity-math.md index 6c01288..5090fdc 100644 --- a/docs/source/connectivity-math.md +++ b/docs/source/connectivity-math.md @@ -1,29 +1,71 @@ # Mathematical Description of a Network Whilst we can get by with a colloquial description of networks, in some places it will be necessary for us to use a more mathematical description of these objects. -We aim to set a standard for our notation—and conventions—in this section. -A network $G = (V, E)$ consists of: +We aim to set a standard for our notation and conventions in this section. -- A set of **nodes** (also called vertices), denoted by $V$. - The nodes are indexed by some counter, so we typically write $V := \{ v_0, v_1, ..., v_N\}$ where each $v_i$ is one node, uniquely identified by the value of $i$. - As such, when referring to nodes it is common to drop the $v_i$ notation and simply say "node $i$" in place of "node $v_i$". -- A set of edges $E$. - Each edge $e\in E$ is written as $e = (i, j, w)$ (or $e = (v_i, v_j, w)$). - $(i, j, w)$ means that there is an edge (connection) directed from node $i$ into node $j$, with a weight of $w$. +## Networks +A network—also called a *graph* in mathematical contexts—is written as $G = (V, E)$. +It consists of two components: +1. A set of **nodes** (or *vertices*), denoted by $V$. +2. A set of **edges**, denoted by $E$. + +When modelling brain connectivity, the nodes ($V$) represent the **brain regions**, and the edges ($E$) represent the **connections** between them. + +### 1. Nodes +The nodes are indexed by some counter, so we typically write $V := \{ v_0, v_1, ..., v_N\}$ where each $v_i$ is one node, uniquely identified by the value of $i$. + +As such, when referring to nodes it is common to drop the $v_i$ notation and simply say "node $i$" in place of "node $v_i$". + +### 2. Edges +Each edge $e\in E$ is written as $e = (i, j, w)$ (or $e = (v_i, v_j, w)$). + +$(i, j, w)$ represents a directed, weighted edge that: + +- starts **from** node $i$ +- goes **to** node $j$ +- has **weight** $w$ + +### Edge Table The edge table that describes a network can then simply be seen as a listing of the edges $e\in E$. -:::{note} -If the (brain)-regions are provided with unique identifiers, these same unique identifiers can be used as the indexes $i$ for the mathematical description of the nodes. +For an example of how an edge table corresponds to a network, see [Example: Edge Table and Corresponding Network](./connectivity-data.md#example-edge-table-and-corresponding-network). -However, in practice the package prefers the use of integer indexes to identify the nodes, rather than names or abbreviations that connectivity data may prefer. -Where this is important, the package keeps a record of the correspondence between "internal indexes" for the nodes and the user-facing identifiers for the brain regions they represent. -::: +### Internal Indexes +If the brain regions are provided with unique identifiers, these same unique identifiers can be used as the indexes $i$ for the mathematical description of the nodes. + +However, the tools used in this package prefer the use of integer indexes to identify the nodes, rather than names or abbreviations. + +The API separates the metadata from the underlying network object itself. The nodes in the `.network` use integer indexing, which is referred to as their "internal indexes". -The API also separates the "metadata" concerning the nodes/regions and edges/connections from the underlying network object itself. -As such, the nodes in the `.network` use integer indexing, which is referred to as their "internal indexes". -These internal indexes are appended as a column to the node metadata, so there is a means of translating between the neuroscientific information about a brain region and its abstract representation. +Where this is important, the package keeps a record of the correspondence between "internal indexes" for the nodes and the user-facing identifiers for the brain regions they represent. + +These "internal indexes" are appended as a column to the node metadata, so there is a means of translating between the neuroscientific information about a brain region and its abstract representation. + Several functions also exist to aid in obtaining a selection of nodes by matching metadata criteria, and vice-versa. + +#### Example: Internal Indexes + +When the [example edge table](./connectivity-data.md#example-edge-table-and-corresponding-network) is loaded, the package assigns each unique region label an internal integer index. + +| region | internal index | +|--------|----------------| +| l‑a | 0 | +| l‑b | 1 | +| r‑a | 2 | +| r‑b | 3 | + +The corresponding edge table (using internal indexes instead of region labels) becomes: + +| source | target | weight | +|--------|--------|--------| +| 0 | 1 | 1.0 | +| 0 | 2 | 0.5 | +| 1 | 2 | 0.5 | +| 1 | 3 | 0.5 | +| 2 | 3 | 1.0 | +| 3 | 0 | 0.1 | +| 3 | 2 | 0.1 | From e9273c1d81c6aa0ab0ad2644d922ad8388629480 Mon Sep 17 00:00:00 2001 From: Stella <30465823+stellaprins@users.noreply.github.com> Date: Thu, 28 May 2026 09:17:23 +0100 Subject: [PATCH 30/32] remove updated edge table example --- docs/source/connectivity-math.md | 16 ++-------------- 1 file changed, 2 insertions(+), 14 deletions(-) diff --git a/docs/source/connectivity-math.md b/docs/source/connectivity-math.md index 5090fdc..4e13def 100644 --- a/docs/source/connectivity-math.md +++ b/docs/source/connectivity-math.md @@ -25,7 +25,7 @@ $(i, j, w)$ represents a directed, weighted edge that: - starts **from** node $i$ - goes **to** node $j$ -- has **weight** $w$ +- with **weight** $w$ ### Edge Table The edge table that describes a network can then simply be seen as a listing of the edges $e\in E$. @@ -51,21 +51,9 @@ Several functions also exist to aid in obtaining a selection of nodes by matchin When the [example edge table](./connectivity-data.md#example-edge-table-and-corresponding-network) is loaded, the package assigns each unique region label an internal integer index. -| region | internal index | +| region label | internal index | |--------|----------------| | l‑a | 0 | | l‑b | 1 | | r‑a | 2 | | r‑b | 3 | - -The corresponding edge table (using internal indexes instead of region labels) becomes: - -| source | target | weight | -|--------|--------|--------| -| 0 | 1 | 1.0 | -| 0 | 2 | 0.5 | -| 1 | 2 | 0.5 | -| 1 | 3 | 0.5 | -| 2 | 3 | 1.0 | -| 3 | 0 | 0.1 | -| 3 | 2 | 0.1 | From 0422b445d6d49b6b69fd4911d1ced31a6d44248d Mon Sep 17 00:00:00 2001 From: Stella <30465823+stellaprins@users.noreply.github.com> Date: Thu, 28 May 2026 09:23:56 +0100 Subject: [PATCH 31/32] for clarity remove seperate heading for edge table --- docs/source/connectivity-math.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/source/connectivity-math.md b/docs/source/connectivity-math.md index 4e13def..07bf3bf 100644 --- a/docs/source/connectivity-math.md +++ b/docs/source/connectivity-math.md @@ -13,12 +13,12 @@ It consists of two components: When modelling brain connectivity, the nodes ($V$) represent the **brain regions**, and the edges ($E$) represent the **connections** between them. -### 1. Nodes +### Nodes The nodes are indexed by some counter, so we typically write $V := \{ v_0, v_1, ..., v_N\}$ where each $v_i$ is one node, uniquely identified by the value of $i$. As such, when referring to nodes it is common to drop the $v_i$ notation and simply say "node $i$" in place of "node $v_i$". -### 2. Edges +### Edges Each edge $e\in E$ is written as $e = (i, j, w)$ (or $e = (v_i, v_j, w)$). $(i, j, w)$ represents a directed, weighted edge that: @@ -27,8 +27,7 @@ $(i, j, w)$ represents a directed, weighted edge that: - goes **to** node $j$ - with **weight** $w$ -### Edge Table -The edge table that describes a network can then simply be seen as a listing of the edges $e\in E$. +The **edge table** that describes a network can then simply be seen as a listing of the edges $e\in E$. For an example of how an edge table corresponds to a network, see [Example: Edge Table and Corresponding Network](./connectivity-data.md#example-edge-table-and-corresponding-network). From 62d90ad4a87c7c8ef540a3c1ac7a1bf693c33572 Mon Sep 17 00:00:00 2001 From: Stella <30465823+stellaprins@users.noreply.github.com> Date: Thu, 28 May 2026 09:26:31 +0100 Subject: [PATCH 32/32] Clarify internal indexes example --- docs/source/connectivity-math.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/connectivity-math.md b/docs/source/connectivity-math.md index 07bf3bf..336aca1 100644 --- a/docs/source/connectivity-math.md +++ b/docs/source/connectivity-math.md @@ -48,7 +48,7 @@ Several functions also exist to aid in obtaining a selection of nodes by matchin #### Example: Internal Indexes -When the [example edge table](./connectivity-data.md#example-edge-table-and-corresponding-network) is loaded, the package assigns each unique region label an internal integer index. +When the [example edge table](./connectivity-data.md#example-edge-table-and-corresponding-network) is loaded, the package assigns an internal integer index to each unique region label. This mapping allows the network to be stored and processed using integers, while still preserving the original region labels for interpretation. | region label | internal index | |--------|----------------|