MapMyCells User Guide

SvenOtto · October 16, 2023, 5:21pm

Documentation resources

Reviewing these resources helps you use MapMyCells to its full potential:

Access & navigation

MapMyCells can be accessed in a variety of ways.

Access it via the information page linked on https://portal.brain-map.org/ highlighted below. You can also access it via Atlases and Data > Brain Knowledge Platform > MapMyCells via the header menu.

Alternatively, you can access MapMyCells via the Tools section in header menu on https://knowledge.brain-map.org/:

Lastly, go straight to MapMyCells via http://knowledge.brain-map.org/mapmycells/process/.

Step 1

File upload

Select a file or drag it into the dotted-line area. Click the X next to the file to remove the uploaded file and start over.

More information about the file requirements and how to create a compatible h5ad file is available via the linked Learn about input file requirements, limits, and creation help page.

Step 2

Select taxonomy & algorithm

Select the mapping algorithm and reference taxonomy from the drop down menus.

Additional information about the taxonomies and algorithms is available via the Learn about available cell type references, algorithms, and output files help page.

Click the START button to initiate the mapping process.

Mapping estimate, progress, and output

We estimate the approximate runtime of the mapping, e.g. 5 minutes.

A progress indicator illustrates the different stages of the process and the overall progress.

IMPORTANT: Do NOT close the browser tab while the mapping is running. Your progress will be lost.

Once the mapping concludes, download your results via the DOWNLOAD RESULTS button.

NOTE: The download triggers in a pop-up message. Please ensure that you allow pop-ups for the MapMyCells page.

IMPORTANT: Once you close the browser tab, all files will be deleted.

rmc0106 · November 27, 2023, 8:49pm

Hi! When will it be available for Seurat objects?

SvenOtto · November 27, 2023, 9:42pm

Hi @rmc0106 , thank you for your interest in MapMyCells.

We currently don’t have a timeline for MapMyCells to accept and automatically convert Seurat objects as input files. However, I’ve documented your request for future consideration.

In the meantime, you can transform your existing data into a MapMyCells suitable format through a two-step process:

Transposing your cell x gene information (MapMyCells requires rows = cells, columns = genes - Seurat provides the opposite as default)
Converting your csv to an h5ad with the document available here: File Requirements and Limits - brain-map.org

Please let me know if you have any further questions.

rmc0106 · November 27, 2023, 10:48pm

Hi!
Thanks for the fast reply. Do you think the conversion described here can generate the data format required by you? Thanks

danielsf · November 28, 2023, 5:37pm

HI @rmc0106

I strongly suspect that the last cell in that vignette is what you want. I, however, have no personal experience with Seurat (or really R), so I am only guessing.

jeremyinseattle · November 28, 2023, 5:43pm

I agree that that should work. If you try it and it turns out that it does NOT work, please let us know in the chat and we can update the “Creating h5ad input files in R & Python” section from the document available here: File Requirements and Limits - brain-map.org with appropriate steps.

sbhamidipati · January 16, 2024, 8:48pm

Hello!

I’ve been using MapMyCells, and it works great! I really appreciate the Allen Institute’s efforts to make this possible!

I was wondering if it is possible to run MapMyCells with non-default parameters and get prediction scores for the cluster labels—similar to what one would get by using the TransferData function and doing label transfer on Seurat? I’ve obtained cluster labels from MapMyCells but would like to gain more insights into my data.

Thank you!

Best,
Sai

danielsf · January 16, 2024, 10:17pm

Hi @sbhamidipati

I’m glad that you are getting good use out of MapMyCells.

I have no experience working with Seurat, so I do not know what metric it returns, but the default MapMyCells configuration should already be giving you two confidence metrics for its cell type assignments as described on this page

github.com

AllenInstitute/cell_type_mapper/blob/main/docs/output.md

# Output file contents

`cell_type_mapper.cli.from_specified_markers` produces two output files.
An optional CSV output file, and an "extended" JSON output file (though this
file is actually the one that is always created). The JSON file contains all
of the data in the CSV file along with some extra confidence metrics and
metadata from the mapping run. Below, we document the contents of each file.

## CSV output file

If the `csv_result_path` config parameter is specified, then a CSV file
will be written with some basic mapping results. The first three (or four,
depending) lines contain metadata about the mapping run. These lines are
prefixed with a `#`. The first line indicates the name of the extended
JSON output file associated with this CSV file. The second line denotes
the hierarchy of taxonomy levels to which the data was mapped. The third
line denotes the human-readable hierarchy of taxonomy levels to which the
data was mapped (assuming that differs from the machine-readable hierarchy).
The final line contains metadata describing the version of the software
used to generate these results. An example of these three lines would be

This file has been truncated. show original

The CSV file will only list one of these confidence metrics, but the extended JSON file contains both the bootstrapping probability (the fraction of assignment iterations that chose the final cell type) and the average correlation (the average over all iterations of the correlation between the cell and its assigned cell type). You ought to also see runner_up_assignment, runner_up_correlation, and runner_up_probability listing the five most likely cell type assignments that weren’t chosen (assuming there are that many runners up).

Is this the kind of metric you were looking for?

If it helps to put what I said in context, the actual mapping algorithm that was run is described here