Flatmaps

Introduction to Flatmaps

Flatmaps published on the SPARC Portal provide 2D graphical representations of the anatomy, functionality, and topology of the connectivity of the PNS, in a Google Maps-like web-interface.

There are two types of flatmaps: an Anatomical Connectivity (AC) flatmap and a Functional Connectivity (FC) map .

The AC and FC flatmaps allow knowledge captured in the SPARC Connectivity Knowledge base of the Autonomic Nervous system (SCKAN) to be visualized and interactively explored on the SPARC Portal, including presenting relevant SPARC-published data as a user navigates through the interface.

Anatomical Connectivity (AC) Flatmap

The AC flatmaps provide a simple graphical representation of the anatomical structures of different species, including human, rat, mouse, cat, and pig, with overlays of nerve connections. Each flatmap consists of two main regions: the body including the visceral organs, and the central nervous system with more detail of the brain and spinal cord. These two regions are connected through directional edges to demonstrate neural connectivity between the brainstem and the organs of the body. The AC flatmaps also provide links from an anatomical structure on the map to experimental datasets published on the SPARC Portal.

Functional Connectivity (FC) map

An FC map represents a well defined collection of physiology (i.e., function) and includes one or more simulation experiments enabling exploration of key aspects of the physiology combined with visual representation(s) presented as interactive flatmaps. Simulation experiments are integrated in FC maps as COMBINE archive files, which can be interactively executed in the browser using the simulation viewer.

An example Functional Connectivity (FC) map, published on the SPARC Portal as https://doi.org/10.26275/mf4h-kzbs. Here we show the FC map (and corresponding legend) on the SPARC Portal flatmap viewer along with the associated simulation experiments - this view can be directly obtained by visiting this permalink: https://sparc.science/apps/maps?id=91fb6fa1. Also note that the displayed dataset markers enable convenient exploration of potentially relevant data.

📘

Create and display your own flatmaps

Learn how to create and display your own flatmaps by following the detailed instructions found in Map Re-Use.

Flatmap Components

The flatmaps published on the SPARC Portal consist of several distinct components (Figure 1):

• Base Anatomical Diagrams the manually-drawn anatomical cartoons, which form the base of each species’ flatmap, annotated with anatomical identifiers corresponding to those used in SCKAN.
• Connectivity Knowledge captured via ApiNATOMY knowledge models and other knowledge sources and encoded as consistent connectivity knowledge in SCKAN. In AC flatmaps, the connectivity pathways are at the level of neural sheaths, while in FC flatmaps, the pathways reflects single neuron connections.
• Flatmap maker is a tool which combines the annotated base diagrams with the connectivity knowledge to automatically render the connectivity into map tiles to be used when presenting the flatmaps.
• Flatmap server is a web server that contains generated flatmaps.
• Databases on the Flatmap server contain both map tiles and metadata about the flatmaps.
• Flatmap viewer is the JavaScript application that renders flatmaps obtained from the Flatmap server and allow a user to explore them interactively.
• The FlatmapVuer is the widget used on the SPARC Portal that wraps the Flatmap viewer to provide SPARC-specific functionality.

Base Diagrams

Both AC and FC flatmap base diagrams are versioned in GitHub.

AC flatmaps

Manually-drawn cartoons provide the base anatomical diagram for each species’ AC flatmap. They are archived in Physiome Project (PMR) as SVG images (e.g., rat flatmap sources). The SVG is annotated with the anatomical terminology used in SCKAN.

FC flatmaps

An FC map represents a well defined collection of physiology with one or more simulation experiments enabling exploration of key aspects of the physiology combined with visual representation(s) presented as interactive flatmaps. FC maps are published as SPARC datasets on the Portal, and the source data, models, and knowledge from which the dataset is generated is archived in the associated workspace on the Physiome Model Repository (PMR).

Anatomical Diagrams

These are the manually-drawn cartoons which provide the base diagram for each species’ flatmap. They are archived in Physiome Project (PMR) as SVG images (e.g., rat flatmap sources). The SVG is annotated with the anatomical terminology used in SCKAN.

Connectivity Knowledge

SCKAN is built using information from both ApiNATOMY and the Neuron Phenotype Ontology. Learn more about how the ApiNATOMY workflow was used to build part of SCKAN.

SCKAN has a structured semantic form and provides endpoints for accessing and searching its knowledge. The latest version of the form can be found on Zenodo. Instructions on how to get started can be found on SPARC-Curation Github.

Importantly, the consistent use of anatomical terminology across the SPARC program enables rich semantic linking between SCKAN and SPARC data. In the case of the flatmaps, SCKAN is queried for connectivity knowledge which is then used by the map maker to render the topological connections between, through, and around anatomical entities in the anatomical diagrams.

The map knowledge package provides a Python wrapper for flatmap-related SCKAN queries, and an additional package, map tools, allows SCKAN connectivity to be viewed and explored in a Jupyter notebook.

Flatmap maker

Map maker is the tool which combines the anatomical diagrams with the connectivity knowledge to produce the rendered map tiles which form the actual flatmap visualization. Connectivity knowledge from SCKAN is used to identify which segments of a pre-drawn (but hidden) nerve network that the path of each neuron population group traverses. These paths are then ordered within each nerve segment to minimize the number of crossings between paths, and drawn using an offset from the segment’s centreline. Learn more about Map Maker.

Flatmap server

The flatmap server is the infrastructure where the generated map tiles are archived and made accessible to a flatmap viewer for display of flatmaps. Learn more about Map Maker.

The flatmap server’s source code is hosted on Github, which is where issues and feature requests can be raised and flatmap server documentation can be found here.

The flatmap server application includes mapmaker and provides a /make/map endpoint to generate flatmaps described by a source manifest on PMR.

• This process can be started using PMR’s Exposure Creation Wizard (see Publishing a Flatmap as a SPARC Dataset).
• Alternatively it can be started by issuing a HTTP POST request to the make/map endpoint, for instance from a shell prompt:

$ curl -H "Content-Type: application/json" -X POST  
       -H "Authorization: Bearer TOKEN"  
       -d '{"source":"’PMR_MANIFEST_URL'"}'  
       MAP_SERVER_URL/make/map

Generated flatmaps are assigned a unique identifier, being the SHA 256 hash of its manifest’s URL. Additionally the full URL of the manifest becomes part of the flatmap’s metadata (its source attribute), and this URL includes the PMR revision of the map.

The map-server provides both MapBox vector tiles and image tiles to the viewer, using industry standard geographical formats, along with flatmap metadata and annotation. Additionally, a local knowledge store, containing cached SCKAN information, can be queried via a SQL endpoint.

Flatmap Viewer

This is a viewer for anatomical flatmaps generated by map maker. The viewer is intended to be a component of a larger JavaScript web application, although it may be used standalone for local flatmap development and testing. Flatmap content is obtained from a flatmap server.

The viewer is integrated with the SPARC portal via the flatmapvuer Vue component (see below). It can be integrated into a map server to allow a server’s maps to be explored independently to the SPARC Portal. Learn more about Flatmap Viewer on its resource page.

FlatmapVuer

Approved flatmaps can be viewed on the portal with viewers created using the Vue.Js framework and these viewers can be reused and deployed elsewhere.

Learn more about the Flatmap Vuer and how to use it on the SPARC Portal.

Learn more about Flatmps

See the AC and FC Viewers for guides on how to use them on the SPARC Portal.

• Publishing a Flatmap as a SPARC Dataset