Atlas Known Issues
The KPMP Atlas software team acknowledges that the tools may not always work ideally or the same from browser to browser. We want to acknowledge these issues for users and, if possible, provide potential workarounds until these issues can be resolved.
Have you run into an issue not reported here? Please report issues through our Give us your feedback link (above).
The Atlas Repository
The Atlas Repository provides access to the datasets being generated by KPMP. The datasets available in the repository are a combination of raw and processed data from KPMP participant biopsies and reference tissue samples. Datasets are routinely added as they are generated and QCed. Some data files shown in the repository are "controlled access", meaning they can only be retrieved after a data use agreement is in place between KPMP and your organization. A summary of the data available in the repository is available on the Kidney Tissue Atlas homepage.
Navigation
Users can search for datasets using the filter panel on the left-hand side of the screen. There are two different facets available for searching and filtering: by Participants and by Files.
Participant-level filters allow a user to search for files that contain particular participants or participants with various attributes (e.g. sample type, tissue type). File-level filters allow a user to search for different types of files, such as certain file formats or experiment types.
The Atlas Explorer
The Atlas Explorer incorporates an easy-to-use search engine which allows users to search for markers or cell types of interest and view summary data visualizations across the following data types:
- Single-nucleus RNA-seq
- Single-cell RNA-seq
- Regional transcriptomics
Summary of participants by data type
A summary of the data available in the Atlas Explorer is available on the Kidney Tissue Atlas homepage.
The single-nucleus and single-cell datasets are described in detail in this preprint (Note: the v1.0 Atlas Explorer includes only a subset of the samples described); the manuscript also details the approach to assigning cell types to the clustered data.
The cell types noted in the application were established as a joint effort with the HuBMAP Consortium. The HuBMAP ASCT+B Reporter tool can be used to visualize the anatomical structures, cell types, and biomarkers (ASCT+B) authored by the domain experts. The cell types and anatomical structures are also being represented in the Cell Ontology and Uberon, respectively.
Search by gene
Searching for a gene presents the user with various visualizations and data tables displaying how the gene is expressed in the selected data type.
Choosing the single-nucleus or single-cell RNA-seq data types yields a visualization page with a "reference UMAP" showing how the full dataset was clustered as well as the inferred cell type/state of each cluster (see this preprint for more details on the clustering and cell attribution methods); a feature plot showing the expression of the selected gene, and a table detailing the expression of the selected gene in each cluster (compared to all other clusters) (Figure 1). Users can also filter the dataset down to only include AKI, CKD, or healthy reference samples - this updates the gene feature plot and the table (but not the reference UMAP image).
.png)
Searching for a gene and choosing the regional transcriptomics data type yields a visualization page with a "bubble plot" showing the expression of the selected gene across all tissue types (AKI, CKD, and healthy reference tissue) and microdissected regions, and a table detailing the expression of the selected gene in each region compared to all other regions (Figure 2). Users can also filter the dataset down to only include AKI, CKD, or healthy reference samples.
Search by cell type
Users can also begin their search with a cell type instead of a gene. After searching for a cell type or selecting one from the renal corpuscle or nephron schemata (Figure 3), a user can see all of the data currently mapped to that cell type. As of Atlas Explorer v1.0, the available data will be single-nucleus and single-cell clusters or microdissected regions. After choosing one of the clusters/regions, users are presented with a table showing which genes are most differentially expressed in the selected cluster/region.
The Atlas Spatial Viewer
The following data types have been incorporated into the Atlas Spatial Viewer:
- Light Microscopic Whole Slide Images
- 3D Tissue Imaging and Cytometry
- Spatial Transcriptomics
- CODEX
- Spatial Metabolomics
The data available in the Spatial Viewer are routinely added as they are generated and quality checked. A summary of the data available in the Spatial Viewer can be found on the Kidney Tissue Atlas homepage.
The spatial images presented in the application have been pre-processed in order to convert them to OME (Open Microscopy Environment) TIFF (tagged image file format) using Bio-Formats bftools version 5.8.
Each dataset is identified by a sample ID, which is derived from a segment of a participant's biopsy tissue. Every sample ID may be traced back to a single participant ID.
NAVIGATION
The Atlas Spatial Viewer allows you to search the available KPMP spatial datasets by data-level and participant-level attributes and visualize the associated datasets.
DATASET LIST
Filter panel
Narrowing your search to a focused selection of datasets is accomplished using the filter panel on the left-hand side of the screen. The filter panel is divided in two tabs, DATASET and PARTICIPANT, with each tab containing attributes by which to filter the dataset list to the right of the filter panel.
Participant-level filters allow searching for datasets that contain particular participant-level attributes such as age range, tissue type, etc. Dataset-level filters allow a user to search for different types of datasets (Light Microscopy vs 3D Cytometry).
To open a dataset in the viewer, click on the link in the SAMPLE ID column.
Sorting and resizing columns
Click on a column heading to sort the data in the column ascending order. Click on the column header a second time to sort in descending order.
When hovering over the column heading you will see a blue line that appears at the right hand side of the column. Click and drag the blue line to increase or decrease the column width.
Showing/hiding columns
By default the dataset list displays the SAMPLE ID, DATA TYPE, and IMAGE TYPE columns. Click the left button at the top of the dataset list and a field chooser will appear which allows you show additional columns or hide the active columns. NOTE:e SAMPLE ID column cannot be hidden.
Participant information panel
Click on the Participant ID in the dataset list or when viewing an image to view the Participant Information panel. This panel contains clinical information (e.g. disease, age, eGFR) and data available within the Atlas for the selected participant.
VISUALIZATIONS
The Spatial Viewer uses the Vitessce visualization platform as its visualization engine. The layout and features/functionality of the visualization page will be specific to the data type selected.
Light Microscopic Whole Slide Images
Data Set panel
The Data Set panel on the left displays information on the selected image, including a reiteration of the type of the selected dataset (e.g. “RGB max projection of 8-channel immunofluorescence image volume.”) The Data Set panel also contains additional image information such as X and Y dimension, pixel size, number of channels, etc.
Spatial panel
In the Spatial panel, you can zoom in and out of the image by using the scroll wheel on a mouse or with a trackpad. To download the current image, click on the download icon in the upper-right corner of the Spatial panel.
3D Tissue Imaging and Cytometry
Spatial Layers
For images with multiple channels, a Spatial Layers panel will appear under the Data Set panel. This panel allows you to control which channels appear, designate channel colors, adjust the z axis, and set the opacity of the image.
Spatial Transcriptomics
Expression Levels / Espression Histogram
Search for a gene of interest by typing the gene symbol of interest, select it, and the normalized expression level and corresponding number of cells will be graphed below in the Expression Histogram panel. Additionally, the Spatial and Scatterplot components will be updated to show the relative expression levels at different locations on the tissue.
Lassoing/Selecting data
In both the Spatial view and the Scatterplot view, there are a few tools that allow you to select certain points and have them highlight on the other view. This can be especially helpful when looking at the expression levels on the scatterplot. If you see a grouping of spots you can see where they live on the tissue itself by using the lasso or box tool to select the points of interest.
In order to clear your selection, simply reselect the gene of interest from the Expression Levels component on the left.
Search for a gene of interest by typing the gene symbol of interest, select it, and the normalized expression level and corresponding number of cells will be graphed below in the Expression Histogram panel. Additionally, the Spatial and Scatterplot components will be updated to show the relative expression levels at different locations on the tissue.
Spatial panel
The Spatial panel produces a heatmap showing the expression level for the selected gene on the various points on the tissue sample.
Scatterplot (UMAP) panel
Displays a scatterplot showing gene expression clusters and expression level for the selected gene as a heatmap.
In the Scatterplot (UMAP) you can click the gear icon at the top in order to control a number of attributes on the scatterplot itself. The most useful control we have found is the ability to adjust the radius of the points in the scatterplot. In order to do this, you first change the Cell Radius Mode to Manual, and then you can adjust the slider to adjust the size of the points.
CODEX (CO-DETECTION BY INDEXING)
Image metadata
The image metadata on the left conveys the following information specific to the image:
- experimental strategy
- tissue type
- sample ID
- participant ID
Data Set panel
The Data Set panel displays the image information for the image shown in the Spatial panel:
- Image description/type (type)
- file name/type of the downloadable image
Spatial Layers panel
For images with multiple channels, a Spatial Layers panel appears under the Data Set panel. It allows you to add or remove channels, allowing a maximum of six total channels at one time.
Click on the arrow next to the channel / marker name to choose from over 50 markers for the channels. You may also choose from eight different colors for your channels.
Spatial panel
Zoom in and out of the image by using the scroll wheel on a mouse or with a trackpad.
To download the current image, click on the download icon in the upper-right corner of the Spatial panel.
SPATIAL METABOLOMICS, SPATIAL LIPIDOMICS, AND SPATIAL N-GLYCOMICS
METASPACE
Spatial metabolomics, spatial lipidomics, and spatial N-glycomics data visualizations are available via hyperlinks within the Spatial Viewer to metaspace2020.eu.
Users may select data to view as normal and then follow the active hyperlinks for the appropriate visualizations.
Atlas Tools Releases
MARCH 2023
Atlas Ecosystem Release v9.0
ATLAS REPOSITORY
New data available
See: Atlas Data Release Notes section
ATLAS SPATIAL VIEWER
New spatial data available:
- Light Microscopy Whole Slide Images (196)
- Spatial Lipidomics (86)
- Spatial Metabolomics (25)
- CODEX (6)
New feature - Participant Information:
By clicking on the Participant ID, in either the file list or when viewing an image, users will be able to view the Participant Information panel. This panel contains participant-specific information (e.g. disease, age, eGFR) and data available within the Atlas for that specific participant.
Spatial Metabolomics links updated
The links taking users out to METASPACE have been updated to direct users to a summary landing page for the sample selected. From there, users can navigate to the spatial views with detailed annotations of the data by selecting “Browse annotations”.
NOVEMBER, 2022
Atlas Ecosystem Release v7.0
ATLAS REPOSITORY
New data available
See: Atlas Data Release Notes section
SEPTEMBER, 2022
Atlas Ecosystem Release V6.0
ATLAS SPATIAL VIEWER
New image types available
- Spatial Metabolomics
- Spatial N-glycomics
- Spatial Lipidomics
ATLAS REPOSITORY
Changes to Participant ID display
- When a file contains information for more than one participant, “Multiple participants” will appear in the participant column instead of the list of participants
New data available
See: Atlas Data Release Notes section
JULY, 2022
Atlas Spatial Viewer
New image types available:
- CODEX images for 11 participants
New data available:
- Level added as a data type to be made viewable in the table
- 259 additional Whole Slide Images
Software Applications Help documentation
- Updated to include documentation on the CODEX images.
Atlas Explorer
Improved gene search
- Allows two-letter gene searches.
Please note that some two-letter genes may not show up in the search as there is a cutoff.
Users can also search by known aliases that have more than two letters.
Data Released to Atlas Repository
MARCH 2023
Atlas Data Repository Release v5.5
Number of files in Atlas Repository
Clinical File
The clinical file has had both changes and updates as outlined below. 10 new participants were added to the clinical file. Please note that some participants now have additional or changed data from the previous clinical file. The following improvements have been made to the clinical file:
- Tissue Type: Diabetic Nephropathy Resistor was added as a new type replacing CKD for some participants
- Age, Diabetes Duration, Hypertension Duration: These variables contain binned values that are often converted to a date format in Excel. In order to eliminate that issue we have added the unit of “Years”within the value field.
- Baseline eGFR: This variable contains binned values that are often converted to a date format in Excel. In order to eliminate that issue we have added the unit of “Years”within the value field.
Opportunity Pool Biomarker Data
Each data type is downloadable as an individual zip package containing:
- Protocol and documentation file(s) from each lab that ran the experiments
- Documentation from KPMP describing QC steps and containing the data dictionary
- Coefficient of Variation file from KPMP QC documentation
Whole Slide Image file changes
There was a naming convention error in 20 Whole Slide Image files. Originally the file name contained the participant ID when it should have contained the sample ID. In order to alleviate any confusion please refer to the list below of file names that have changed in Q1 2023.
Single-cell RNAseq fastq file updates:
Within a set of 21 fastq files, for 10 samples, we found that each fastq file was duplicated within the raw file. We've replaced these fastq files with non-duplicated versions. The links in the metadata files were also changed to reflect the renamed fastq files. This issue was found during internal data assessments in February 2023. Cell Ranger deduplicates the reads so this issue was probably not noticed by most users.
DECEMBER, 2022
Atlas Data Repository Release v5.4.1
Opportunity Pool Biomarker Data
The SomaScan Plasma biomarker data (Plasma Biomarker Data-SomaScan-2022.zip) has been temporarily removed from the Atlas Repository until further QC is completed.
Clinical File
A bug fix has been implemented correcting an error in calculating baseline eGFR for AKI participants. The change was made for column ‘Baseline eGFR(ml/min/1.73m2) (Binned)’. This is not an issue in prior releases, only the November 2022, v5.4 release of the clinical file.
NOVEMBER, 2022
Atlas Data Repository Release v5.4
Opportunity Pool Biomarker Data
Each data type is downloadable as an individual zip package containing:
- Protocol and documentation file(s) from each lab that ran the experiments
- Documentation from KPMP Biomarker Quality Control Working Group (BQCWG) describing QC steps and Data dictionary for data file
- Coefficient of Variation file from the KPMP BQCWG
Number of files in Atlas Repository
DOI collections
DOI doi.org/10.48698/3z31-8924 has been associated with KPMP files used in "An atlas of healthy and injured cell states and niches in the human kidney" from Lake et. al. (see https://www.kpmp.org/doi-collection/10-48698-3z31-8924 - for data download link)
Clinical File
Updated as of October 24, 2022
SEPTEMBER, 2022
Atlas Data Repository Release v5.3
JUNE, 2022
Data Changes
Slides were found to be mislabeled either based on stain, frozen sample, or incorrect sample ID. The following slide image files have been renamed to accurately reflect their contents:
Atlas Known Issues
The KPMP Atlas software team acknowledges that the tools may not always work ideally or the same from browser to browser. We want to acknowledge these issues for users and, if possible, provide potential workarounds until these issues can be resolved.
Have you run into an issue not reported here? Please report issues through our Give us your feedback link (above).
The KPMP Data Visualization Center (DVC) has developed a variety of internal and external applications to support the gathering, integration, and display of the data generated through this project. All software is freely accessible from our KPMP GitHub page.
