Scaffold Mapping Protocol - Version 1.0

Check for the availability of segmentation files for image data.

Ensure the image data has already been segmented with MBF software and the MBF XML file is available. If the MBF XML file has not already been uploaded to 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.

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 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 visualisation of data embedded on the scaffold

 i) After setting up visualisation 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 visualisation 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.

Prepare mapped data for investigators’ review.

a) Using the output files generated from step 3, stage a portal visualisation with the help of the portal team.

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) Share the link with the investigators for their review.

d) 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 visualisation, 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 and thumbnail files are annotated correctly, as follows:

A	B	C	D
metadata.json	inode/vnd.abi.scaffold+file	inode/vnd.abi.scaffold+file	view.json
view.json	inode/vnd.abi.scaffold.view+file	inode/vnd.abi.scaffold.view+file	thumbnail.jpeg
thumbnail.jpeg	inode/vnd.abi.scaffold.thumbnail+file	inode/vnd.abi.scaffold.thumbnail+file

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