Sep 06, 2022
Version 3
Scaffold Mapping Protocol - Version 1.1.1 V.3
- 1Auckland Bioengineering Institute, The University Of Auckland
Protocol Citation: Mabelle Lin, Hugh Sorby, Sonia Sharma, David Nickerson 2022. Scaffold Mapping Protocol - Version 1.1.1. protocols.io https://dx.doi.org/10.17504/protocols.io.n2bvj6o35lk5/v3Version created by Anita Bandrowski
License: This is an open access protocol distributed under the terms of the Creative Commons Attribution License, which permits unrestricted use, distribution, and reproduction in any medium, provided the original author and source are credited
Protocol status: Working
We use this protocol and it's working
Created: August 11, 2022
Last Modified: September 06, 2022
Protocol Integer ID: 68493
Keywords: Organ scaffold mapping, SPARC dataset mapping
Abstract
The scope of this protocol covers the steps involved in the mapping of image data to organ scaffolds.
Check for the availability of segmentation files for image data.
This scaffold mapping protocol requires image data segmentations to be available in the MBF Bioscience Neuromorphological File Format (MBF XML, https://doi.org/10.1007/s12021-021-09530-x). This can be created directly using the MBF segmentation tools. Information on converting neural and anatomical reconstruction data (or “segmentation data”), derived from defined sources outside of MBF Bioscience software into the Neuromorphological File Format is available at: https://docs.sparc.science/docs/demonstration-on-the-use-of-the-segmentation-conversion-tools-for-map-core-scaffold-mapping.
If the MBF XML file has not already been included in the dataset on Pennsieve, advise the investigators to do so. Check the segmentation file to make sure the data has been properly annotated with the necessary fiducial markers and annotation groups. The necessary fiducial markers are the set of markers that are required to align and fit the target scaffold. Markers on the target scaffold can be added to the scaffold manually during the mapping process.
Establish an understanding of the data sample.
Information on the type of data can usually be found in the overview section of the Pennsieve dataset. Review the protocol.io link that is listed in the dataset_description.xlsx of the Pennsieve dataset to get a general idea of how the data was prepared. If information from the dataset is insufficient, contact the investigators to clarify.
Important information that will be required before carrying the next step are:
a) Which organ was the sample data obtained from?
b) What species was that organ from?
c) Where in the organ was the sample derived from? Does the investigator know the exact location? If the investigator did not keep a record of such information, check with them to see if the sample data is a good representation of a specific region of the organ and if they are happy for the data to be mapped to any location within that region.
d) How was the organ prepared for extraction of the sample? Was the data sample extracted from a flat-mount preparation? Or is it a micro-CT or MRI image of an in situ organ?
Map data to the scaffold.
Open the scaffold mapping tool and start the sparc-data-mapping workflow. Note that a step-by-step guide on how to use the scaffold mapping tool is available here. This protocol requires version v0.17.2 or newer of the scaffold mapping tools. This document will instead focus on the specific items that need to be checked during the workflow process:
a) Selecting the data file: Ensure the correct MBF XML file is used as the input file under the MBFXMLFile plugin.
b) Selecting a scaffold: Check that you have selected the correct organ and species scaffold.
c) Fitting the scaffold to data
i) Inspect the data and check that it corresponds to the image data.
ii) Under Model coordinates, make sure you select the correct coordinates that best describe the configuration of the organ when the data sample was prepared. For instance, if the data was derived from a flat preparation, select “flat coordinates”. If the data was a biopsy from an intact organ or imaging of a whole organ, select “coordinates”.
iii) After performing the fit, check that every part of the data has been fitted to the correct scale and the data is in the correct location on the scaffold and is complete before proceeding to the next step.
d) Creating a visualization of data embedded on the scaffold
i) After setting up the visualization of the scaffold and the embedded data, have a visual inspection to make sure that the embedded data is at the expected location of the scaffold. The visualization should convey an adequate representation of the spatial orientation of the embedded data with respect to the scaffold.
ii) Check that the embedded data is complete and there are no missing parts.
iii) Check that the embedded data is not obscured by any surfaces of the scaffold.
iv) Check that the graphics (surface, lines, points, contours) are assigned to the correct subgroups.
v) If certain annotations are to be displayed in the legend on the portal, make sure the graphics for those annotations have been created and assigned to the correct sub-groups.
vi) Create different views to capture essential features of the scaffold map so that the details can be presented to portal users.
vii) Context card - Use context card annotation functionality in the scaffold mapping tool to populate information for displaying contextual information for the scaffold map on the SPARC portal. Information includes a heading title for the context card, followed by a short and comprehensive description illustrating what is depicted on the scaffold map. Use the tool to add a contextual annotation for each sample mapped onto the scaffold. This will allow each sample to be linked to their DOI (if the sample came from a different dataset), the path to the sample data file in the dataset, their unique identifiers, and the specific view created for highlighting the mapped sample on the scaffold. Information about the sample (for example, what does the blue dots or color field represent) can be entered into the description field to provide the portal users with more context of the legend. Lastly, use the tool to annotate each of your created views to link them back to corresponding samples. We can also add physiological annotations (UBERON identifiers etc.) to apply to a sample or view, which will enhance the findability of the item.
Prepare mapped data for investigators’ review.
a) Using the output files generated from step 3, stage a portal visualization.
b) Review portal visualisation to ensure that scaffold and embedded data are showing up correctly, annotations are correct and there is no unexpected behavior when the visualisation is manipulated.
c) To stage a portal visualization, zip (compress) the required files and share them with the investigator (via email or google drive link).
d) The investigator downloads the zip file.
e) The investigator opens https://mapcore-demo.org/current/scaffoldvuer/ in the web browser and then drag-and-drop the zip file onto the viewer to explore the scaffold and provide feedback.
f) If investigators have suggestions, discuss with investigators and repeat earlier steps in (3) to incorporate reasonable requests. If the investigators are happy with the portal visualization, proceed to the next step.
Prepare files for Pennsieve.
a) Generate provenance
Generate a provenance report to capture the version of the software used in the mapping process.
b) Annotate files for manifest
Generate a manifest file and ensure that the metadata, view, thumbnail, and context information files are annotated correctly, as follows:
| Filename | additional types | isDerivedFrom | isSourceOf | supplemental JSON metadata | |
| metadata.json | application/x.vnd.abi.scaffold+json | view.json | |||
| view.json | application/x.vnd.abi.scaffold.view+json | metadata.json | thumbnail.jpeg | ||
| thumbnail.jpeg | image/x.vnd.abi.thumbnail+jpeg | view.json | |||
| context_info.json | application/x.vnd.context-information+json | {"version": "0.2.0", "id": "sparc.science.annotation_data"} | |||
c) Upload files to Pennsieve
Check the derivative folder of the Pennsieve dataset from which the data was derived. Create a Scaffolds folder in the derivative folder if one has not yet been created. If multiple scaffolds have been created to map each data sample separately, create additional folders with appropriate names (that will help in distinguishing different samples) within the Scaffolds folder to store the files required for generating the visualization for each data sample. Upload the mapping files, provenance file, and manifest file to each of the folders.
Request dataset owners to republish their dataset.
Politely ask dataset owners to notify us when their dataset has been republished and inform the portal team accordingly so that we can ensure the visualisation is deployed correctly to their dataset and is accessible via the gallery tab of their dataset on https://sparc.science/.