Skip to content

improve documentation of connections and synapses #142

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
floesche wants to merge 11 commits into
base: main
Choose a base branch
from
Open

improve documentation of connections and synapses #142

Changes from 3 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
c5ca57a
improve documentation of connections and synapses
floesche Dec 1, 2025
fde7b1b
update summary statistics section
floesche Dec 1, 2025
1a3aa0a
make help fit types page
floesche Dec 1, 2025
5ccca82
obvious fixes
floesche Dec 1, 2025
274d2ad
removed wrong, added missing docu
floesche Dec 1, 2025
458b256
cleanup docu
floesche Dec 1, 2025
a882cfd
remove old and new issues
floesche Dec 1, 2025
76aed09
Update help.html.jinja
leburnett Dec 1, 2025
72f460e
Merge branch 'main' into syn-vs-conn
floesche Dec 9, 2025
825d0e3
update dev docs
floesche Dec 9, 2025
f196724
update user docs
floesche Dec 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
115 changes: 66 additions & 49 deletions templates/help.html.jinja
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
</div>
</div>

<!-- Table of Contents -->
{# Table of Contents #}
<div class="row">
<div class="col-xs-12 col-md-3">
<h3 class="pm-no-margin">Contents</h3>
Expand All @@ -40,11 +40,10 @@
<ul>
<li><a href="#header-info">Header Information</a></li>
<li><a href="#summary-stats">Summary Statistics</a></li>
<li><a href="#layer-analysis">Layer Analysis</a></li>
<li><a href="#neuroglancer">Neuroglancer 3D Viewer</a></li>
<li><a href="#eyemaps">Eye Maps</a></li>
<li><a href="#layer-column-coverage">Layer and Column Coverage</a></li>
<li><a href="#neuron-visualization">Neuron Visualization</a></li>
<li><a href="#roi-innervation">ROI Innervation</a></li>
<li><a href="#connectivity">Connectivity Data</a></li>
<li><a href="#s-c">Connectivity</a></li>
</ul>
</li>
<li><a href="#terminology">Terminology</a></li>
Expand All @@ -55,7 +54,7 @@

<div class="col-xs-12 col-md-9">
<div>
<!-- Overview -->
{# Overview #}
<section id="overview" class="pm-stacked">
<h2>Overview</h2>
<p>
Expand All @@ -82,7 +81,7 @@

<hr />

<!-- Types Page -->
{# Types Page #}
<section id="types-page" class="pm-stacked">
<h2>Types Index Page</h2>
<p>
Expand All @@ -96,7 +95,7 @@

<img src="static/images/types_page_filter50.gif" width="100%" alt="How to use the types filters.">

<!-- Using Filters -->
{# Using Filters #}
<div id="filters" class="pm-stacked">
<h3>Using Filters</h3>
<p>
Expand Down Expand Up @@ -313,7 +312,7 @@

<hr />

<!-- Individual Neuron Pages -->
{# Individual Neuron Pages #}
<section id="neuron-page" class="pm-stacked">
<h2>Individual Neuron Pages</h2>
<p>
Expand All @@ -327,7 +326,7 @@
side of the page or the menu (☰) to switch between views.
</p>

<!-- Header Info -->
{# Header Info #}
<div id="header-info" class="pm-stacked">
<h3>Header Information</h3>
<p>
Expand All @@ -338,46 +337,60 @@
</p>
</div>

<!-- Summary Stats -->
{# Summary Stats #}
<div id="summary-stats" class="pm-stacked">
<h3>Summary Statistics</h3>
<p>The summary section provides key quantitative information:</p>

<h4>Total Neurons</h4>
<h4>Neurons</h4>
<p>
The number of individual neurons of this type in the dataset. For bilateral neurons, counts and ratios may
The number of individual neurons of this type in the dataset. For bilateral neurons, counts per hemisphere and ratios may
be shown across hemispheres.
</p>

<h4>Total Synapses</h4>
<p>Combined pre-synaptic (outputs) and post-synaptic (inputs), with breakdowns where applicable.
For combined pages the breakdown shows the number of neurons assigned to each hemisphere.
Whereas for unilateral pages the breakdown shows the number of pre and post synapses across all neurons of the type.</p>
<h4>Synapses</h4>
<p>Combined post-synaptic (inputs) and pre-synaptic (outputs), with breakdowns and log ratios where applicable. Technically, this number is a pre-calculated property for each neuron inside the neuprint database.<br/>
For combined pages the breakdown shows the number of neurons assigned to each hemisphere and their ratio.
Whereas for unilateral pages the breakdown shows the number of post and pre synapses across all neurons of the type assigned to that side.</p>

<h4>Mean Synapses</h4>
<p>Average number of synapses per neuron of this type. Useful for comparing connectivity levels.
<h4>Connections</h4>
<p>
Combined upstream and downstream connections. Here, connections are the number of anatomical synapses between neurons. Technically, this number comes from the number of connected <em>synapse</em>s, which are combined to <em>SynapseSet</em>s and part of <em>Neuron</em>s inside the neuprint database.<br/>
For combined pages the breakdown shows the number of neurons assigned to each hemisphere and their ratio.
Whereas for unilateral pages the breakdown shows the number of upstream and downstream connections across all neurons of the type assigned to that side.
</p>

<h4>Neurotransmitter</h4>
<p>
Predicted neurotransmitter for the type and the corresponding confidence level (CL).
For some types, the predicted neurotransmitter may be <em>Unc</em> for unclear.
</p>

<h4>Synapses per Neuron</h4>
<p>Average number of synapses per neuron of this type. Useful for comparing connectivity levels.<br/>
For the combined page, the breakdown shows the mean number of synapses for neurons on the right and left.
Whereas for unilateral pages the breakdown shows the mean number of pre and post synapses per neuron assigned to that side.</p>

<h4>Connections per Neuron</h4>
<p>Average number of connections per neuron of this type. Useful for comparing connectivity levels.<br/>
For the combined page, the breakdown shows the mean number of connections for neurons on the right and left.
Whereas for unilateral pages the breakdown shows the mean number of pre and post connections per neuron assigned to that side.</p>

<h4>Log Ratios</h4>
<p>
Log ratios (<i>ld</i>, base <i>2</i>) indicate balance across hemispheres and inputs/outputs; values below 0 favor right/inputs and
values above 0 favor left/outputs.
</p>

<h4>Neurotransmitter</h4>
<p>
Predicted neurotransmitter for the type and the corresponding confidence level (CL).
For some types, the predicted neurotransmitter may be "Unc" for unclear.
</p>
</div>

<!-- Layer Analysis -->
<div id="layer-analysis" class="pm-stacked">
<h3>Layer Analysis</h3>
<p>Detailed analysis of neuron distribution across layers in visual system neuropils:</p>
{# Columnar Layer and Spatial Coverage (Eye Maps) #}
<div id="layer-column-coverage" class="pm-stacked">
<h3>Layer and Column Coverage</h3>
<p><em>Note: These views are only present for visual system neuron types with columnar organization.</em></p>
<p>Detailed analysis of neuron distribution across layers in visual system neuropils. This section explains how to interpret the “Mean Synapse Count per Layer” tables shown on individual neuron type pages (e.g., Tm3).</p>

<h4>Layer Tables</h4>
<h4>Mean Synapse Count per Layer</h4>
<ul>
<li><strong>Layer names and anatomical locations:</strong> Lamina (LA),
Medulla (ME), Lobula (LO), Accessory Medulla (AME), Lobula Plate (LOP) and Central Brain (CB). </li>
Expand All @@ -394,8 +407,9 @@
the tables include only the counts for the ipsilateral synapses.</li>
</ul>

<h4>Hexagonal Grid Visualizations</h4>
<p>Interactive hexagonal grids show the spatial distribution of neuron terminals across columnar structure of visual system regions.</p>
<h4>Population Spatial Coverage</h4>
<p><em>Note: These Population Spatial Coverage maps are only present for visual system neuron types with columnar organization.</em></p>
<p>This section visualizes how a neuron type covers the columnar structure of visual system regions using interactive hexagonal grids.</p>
<p>The plots show the neural innervation of the <strong>ipsilateral</strong> medulla (ME), lobula (LO) and lobula plate (LOP).
<ul>
<li><strong>Column Analysis:</strong> Which columns within the ROI the neurons innervate.</li>
Expand All @@ -407,10 +421,10 @@
<img src="static/images/eyemap_demo.gif" width="50%" alt="Interactivity of the hexagonal eyemap plots." style="display: block; margin-left: auto; margin-right: auto;">
</div>

<!-- Neuroglancer -->
<div id="neuroglancer" class="pm-stacked">
<h3>Neuroglancer 3D Viewer</h3>
<p>Interactive 3D visualization of neuron morphology:</p>
{# Neuron Visualization #}
<div id="neuron-visualization" class="pm-stacked">
<h3>Neuron Visualization</h3>
<p>Interactive 3D visualization of neuron morphology using the embedded Neuroglancer viewer:</p>

<h4>Viewing the 3D Model</h4>
<ul>
Expand Down Expand Up @@ -443,7 +457,7 @@
<h4>Adding Partners from the Connectivity table</h4></div>
<p>
You can add connected partners to the 3D view directly from the Connectivity tables by selecting their
blue checkboxes (see Connectivity Data). Some connected cell types have filled pink checkboxes because there
blue checkboxes (see Connectivity section below). Some connected cell types have filled pink checkboxes because there
are no neurons of that type that directly innervate the example neuron visible by default in the neuroglancer view.
A random neuron of that type can be added by searching for the type in the search box within the neuroglancer view and adding it manually.
</p>
Expand All @@ -458,7 +472,7 @@
</p>
</div>

<!-- ROI Innervation -->
{# ROI Innervation #}
<div id="roi-innervation" class="pm-stacked">
<h3>ROI Innervation</h3>
<p>Detailed breakdown of connectivity within specific brain regions:</p>
Expand All @@ -470,9 +484,9 @@
</ul>
</div>

<!-- Connectivity -->
<div id="connectivity" class="pm-stacked">
<h3>Connectivity Data</h3>
{# Connectivity #}
<div id="s-c" class="pm-stacked">
<h3>Connectivity</h3>
<p>Comprehensive analysis of synaptic connections with other neuron types:</p>
<ul>
<li><strong>Upstream Partners:</strong> Neurons that provide input (pre-synaptic partners)</li>
Expand Down Expand Up @@ -537,7 +551,7 @@

<hr />

<!-- Terminology -->
{# Terminology #}
<section id="terminology" class="pm-stacked">
<h2>Terminology</h2>
<p>Key terms and concepts used throughout the catalog:</p>
Expand All @@ -556,20 +570,23 @@

<dt>Pre-synaptic / Post-synaptic</dt>
<dd>
Pre-synaptic refers to outputs from a neuron; post-synaptic refers to inputs to a neuron.
Post-synaptic refers to inputs to a neuron, pre-synaptic refers to outputs from a neuron.
Copy link
Copy Markdown
Collaborator

@leburnett leburnett Dec 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I find this a bit confusing. I'm trying to think of when these terms would be used because a "post-synaptic density" refers to the region of the neuron that receives incoming signals but in lectures etc if someone says a neuron is "post-synaptic" to X, it normally means downstream of X. We could get rid of this definition and just leave the "post-synaptic sites" and "pre-synaptic sites" definitions.

</dd>

<dt>Synapse Count</dt>
<dd>The number of synaptic connections. Higher counts indicate stronger or denser connectivity.</dd>
<dd>The number of synaptic connections. Higher counts indicate stronger or denser connectivity. neuView uses the properties from the neurons in the database.</dd>
Copy link
Copy Markdown
Collaborator

@leburnett leburnett Dec 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I changed this to "Higher counts indicate denser connectivity." and removed the "stronger". I'm not sure if this sentence is necessarily useful, but I think it's slightly murky to say "stronger" since in the connectome we don't actually know how strong these individual connections are.


<dt>Post-synaptic Sites</dt>
<dd>Postsynaptic receptor sites where a neuron receives inputs from presynaptic partners.</dd>
<dd>Postsynaptic receptor sites where a neuron receives inputs from presynaptic partners. In the data model, this is the `Neuron.post` property.</dd>

<dt>Pre-synaptic Sites (T-bars)</dt>
<dd>Presynaptic release sites where a neuron outputs signals. Also called t-bars. One presynaptic site can connect to multiple postsynaptic partners.</dd>
<dd>Presynaptic release sites where a neuron outputs signals. Also called t-bars. One presynaptic site can connect to multiple postsynaptic partners. In the neuprint data model, this is the `Neuron.pre` property.</dd>

<dt>Connections</dt>
<dd>Input connections are conceptually similar to post-synaptic sites while a group of post-synaptic sites form a single output connection. We calculate the number of connections by identifying the connecting neurons and then use the `weight` property from the `ConnectsTo` edge between the neurons.</dd>
Copy link
Copy Markdown
Collaborator

@leburnett leburnett Dec 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've updated this based on our discussion before. One pre-synapse can contain multiple downstream connections.


<dt>Connections vs. Synapses</dt>
<dd>A single presynaptic site (t-bar) can form multiple connections to different postsynaptic partners. Therefore, the number of output connections can be greater than the number of presynaptic sites.</dd>
<dd>The numeric difference between post-synaptic sites and input connections stems from the difference in how the numbers are retrieves (see Synapse Count and Connections above). A single presynaptic site (t-bar) can form multiple connections to different postsynaptic partners. Therefore, the number of output connections can be greater than the number of presynaptic sites.</dd>
Copy link
Copy Markdown
Collaborator

@leburnett leburnett Dec 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought putting this in "< blockquote >" might be useful to make it stand out a bit. I'm sure many people will be interested in this.


<dt>Inputs</dt>
<dd>All pre-synaptic connecting cell types upstream from a given cell type (neurons providing input to the cell type).</dd>
Expand Down Expand Up @@ -622,7 +639,7 @@

<hr />

<!-- FAQ and Troubleshooting -->
{# FAQ and Troubleshooting #}
<section id="faq" class="pm-stacked">
<h2>FAQ and Troubleshooting</h2>
<dl class="pm-stacked">
Expand Down Expand Up @@ -662,7 +679,7 @@
</ul>
</section>

<!-- Contact and Feedback -->
{# Contact and Feedback #}
<section id="contact" class="pm-stacked">
<h2>Contact and Feedback</h2>
<p>
Expand All @@ -679,7 +696,7 @@
</p>
</section>

<!-- Footer -->
{# Footer #}
<div class="pm-stacked">
<hr />
<blockquote>
Expand Down
Loading