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.

📘

Creating and displaying your own flatmap

Detailed instructions on creating and displaying your own flatmaps are available on the Anatomical Flatmap Resources page.

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 pathways present on the FC map represent the neuronal connections between the brainstem and the FTUs within each organ system. The various colors of these pathways represent different types of nerves (see the Controls section for information on the legend for these pathways).

The purpose of the FC map is primarily to capture the semantics and connectivity of the body’s anatomical and physiological organization, and to provide an interface for building composite models.

The information is provided by the SCKAN knowledge base and is consistent with 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.

Flatmap Building Blocks

The flatmaps published on the SPARC Portal consist of several distinct components:

• Base Diagrams or Flatmap Source files for the AC flatmaps are manually-drawn anatomical cartoons, which form the base of each species’ flatmap, annotated with anatomical identifiers corresponding to those used in SCKAN. For the FC flatmaps, the base diagram is a hand-drawn map of blocks representing 12 organ systems, including all organs and FTUs within each organ. All entities are annotated with anatomical identifiers consistent with SCKAN.
• Connectivity Knowledge is provided by SCKAN, which encodes consistent connectivity knowledge from ApiNATOMY knowledge models and other knowledge sources. In AC flatmaps, the connectivity pathways are at the level of neural sheaths, while in FC flatmaps, the pathways reflects single neuron connections.
• Flatmap makeris 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: Flatmap Source Files

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

AC flatmap

Manually-drawn cartoons, or anatomical diagrams, provide the base 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 flatmap

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

Connectivity Knowledge

The SPARC Connectivity Knowledge base of the Autonomic Nervous system (SCKAN) provides the connectivity knowledge for both the AC and FC flatmaps. SCKAN has a structured semantic form and provides endpoints for accessing and searching its knowledge. Importantly, the consistent use of anatomical terminology across SPARC enables rich semantic linking between SCKAN and SPARC published 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.

Mapmaker

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.

Map maker’s source code is hosted on GitHub, which is where issues and feature requests can be raised, and documentation can be found here.

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.

Releases are versioned in GitHub.

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.

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 application is based on the MapLibre open-source mapping library and uses industry standard interchange formats for web-based geographical maps.

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

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, as described in the map server’s documentation.

Releases are versioned in Github and available from the NPM repository.

Flatmap Vuer

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.

• Flatmapvuer demo
• Example of flatmap zoomed into a region on the Portal
• Repository and documentation

Integrated MapVuer

MapVuer is the integration of multiple different modules to provide a streamline workflow, the modules include scaffoldvuer, flatmapvuer, plotvuer and simulationvuer and a search engine (sidebar).

Flatmapvuer is the primary viewing tool on the mapvuer and the markers are added to the flatmap to indicate locations of interest (e.g., locations of SPARC datasets), clicking on these will trigger a search on the sidebar, then displays all relevant datasets and the corresponding actions such as open scaffolds, plots, simulations, and etc.

• MapVuer on Portal
• Repository and documentation

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