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) flatmap.

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) Flatmap

The FC flatmap is designed to provide a semantic description of all anatomical locations in the mammalian body together with a description of the connectivity of networks that transfer information (neural connectivity) or mass flow (blood vessels and, soon, lymphatics) between these locations.

The anatomical locations are organized in a hierarchy starting with the organ systems of the body (cardiorespiratory, digestive, musculo-skeletal, neural, endocrine, immune, male and female reproductive, integumentary, naso-oral-pharyngeal, and special sense organs). Each of these organ systems contains organs (heart, lung, kidney, liver, stomach, …) and each of these organs contains ‘Functional Tissue Units’ or FTUs. Each FTU is the primary anatomical unit (mostly at a submillimetre scale) in which physiological function emerges from molecular and cellular biology. Examples of FTUs are the nephron in the kidney, the lobule in the liver, the osteon in bone, the alveoli in the lungs, etc. Nearly every FTU is innervated by the autonomic nervous system, blood vessels and lymphatics.

The purpose of the FC map is primarily to capture the semantics and connectivity of the body’s anatomical and physiological organization.

It links with the SCKAN knowledgebase and maps out to both the ‘Anatomical Connectivity’ (AC) flatmap and the 3D whole-body models for each species. It also provides a user interface to modeling studies that are designed to address the integrative physiological function of the body.

📘

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

A manually-drawn base map defines blocks representing all organ systems of the mammalian body. Each organ system contains organs in which the FTUs are defined. An FTU represents tissue function at the level at which physiological function emerges from molecular and cellular biology, e.g. a nephron in the kidney. All entities are annotated with anatomical identifiers consistent with SCKAN. Every FTU includes a sympathetic motor input (red square), a parasympathetic motor input (green square), and sensory output (blue square). This ‘RGB’ connectivity for an FTU represents the multiple neurons of each type needed for control of different types of smooth muscle (vascular and gland) as well as multiple types of sensory receptor within the FTU.

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