Package: ark-analysis
ark-analysisCI / CDPackageMetaToolbox for analyzing multiplexed imaging data.Full documentation for the project can be foundhere.Table of ContentsPipeline FlowchartGetting StartedOverview1. Segmentation2. Pixel clustering with Pixie3. Cell clustering with Pixie4. Post clustering tasks5. Spatial analysisInstallation Steps.Download the RepoSetting up DockerRunning on WindowsUsing the Repository (Running the Docker)External ToolsMantis ViewerMantis directory structureLoading image-specific filesLoading project-wide filesView cell featuresExternal Hard Drives and Google File StreamUpdating the RepositoryExample DatasetQuestions?Want to contribute?How to CitePipeline FlowchartGetting StartedOverviewThis repo contains tools for analyzing multiplexed imaging data. The assumption is that you've already performed any necessary image processing on your data (such as denoising, background subtraction, autofluorescence correction, etc), and that it is ready to be analyzed. For MIBI data, we recommend using thetoffyprocessing pipeline.We have recorded workshop talks which complement the repository.MIBI Workshop Playlist.1. SegmentationThesegmentation notebookwill walk you through the process of usingMesmerto segment your image data. This includes selecting the appropriate channel(s) for segmentation, running your data through the network, and then extracting single-cell statistics from the resulting segmentation mask.Workshop Talk - Session V - Part 1: SegmentationNote:It is assumed that the cell table uses the default column names as inark/settings.py. Refer to thedocsto get descriptions of the cell table columns, and methods to adjust them if necessary.If you plan to segment out non-traditional cellular structures such as protein aggregates or cytoplasmic projections often found in brain cells (e.g. microglia, astrocytes, and neuropil), try out the companion notebookezSegmentereither as a stand-alone or in combination with the above standard cell segmentation process.2. Pixel clustering with PixieThe first step in thePixiepipeline is to run thepixel clustering notebook. The notebook walks you through the process of generating pixel clusters for your data, and lets you specify what markers to use for the clustering, train a model, use it to classify your entire dataset, and generate pixel cluster overlays. The notebook includes a GUI for manual cluster adjustment and annotation.Workshop Talk - Session IV - Pixel Level Analysis3. Cell clustering with PixieThe second step in thePixiepipeline is to run thecell clustering notebook. This notebook will use the pixel clusters generated in the first notebook to cluster the cells in your dataset. The notebook walks you through generating cell clusters for your data and generates cell cluster overlays. The notebook includes a GUI for manual cluster adjustment and annotation.Workshop Talk - Session V - Cell-level Analysis - Part 2: Cell Clustering4. Post Clustering TasksAfter the Pixie Pipeline, the user can inspect and fine tune their results with thepost clustering notebook. This notebook will go over cleaning up artifacts left from clustering, and working with functional markers.5. Spatial AnalysisWorkshop Talk - Session VI - Spatial Analysis - Part 1: Choosing the Right Analysis Tool.Pairwise Enrichment AnalysisThepairwise enrichment notebookallows the user to investigate the
interaction between the phenotypes present in their data. In addition users can
cluster based on phenotypes around a particular feature such asarteryorgland.Workshop Talk - Session VI - Spatial Analysis - Part 2: Pairwise Spatial Enrichment.K-means Neighborhood AnalysisTheneighborhood analysis notebooksheds light on neighborhoods made of micro-environments which consist of a collection of cell phenotypes.Workshop Talk - Session VI - Spatial Analysis - Part 3: K-means Neighborhood Analysis.Spatial LDAThepreprocessingandtraining / inferencedraws from language analysis, specifically topic modelling. Spatial LDA overlays a probability distribution on cells belonging to a any particular micro-environment.Workshop Talk - Session VI - Spatial Analysis - Part 4: Spatial LDA.Installation StepsPip InstallationYou can install the latest version ofarkwith:pipinstallark-analysisHowever, the repository will still need to be cloned if you wish to use the Jupyter Notebooks.Download the RepoWe recommend using the latest release ofark. You can find all the versions available in theReleases Section.
Open terminal and navigate to where you want the code stored.If you would like to use the latest version ofarksimply clone the project and create the Conda environment.gitclone-bv0.7.0https://github.com/angelolab/ark-analysis.gitcdark-analysis
condaenvcreate-fenvironment.ymlSetting up DockerThere is a complementarysetup video.Next, you'll need to download Docker Desktop:First,downloadDocker Desktop.Once it's successfully installed, make sure it is running by looking in toolbar for the Docker whale icon.Running on WindowsOur repo runs best on Linux-based systems (including MacOS). If you need to run on Windows, please consult ourWindows guidefor additional instructions.Using the Repository (Running the Docker)Enter the following command into terminal from the same directory you ran the above commands:./start_docker.shIf running for the first time, or if our Docker image has updated, it may take a while to build and setup before completion.This will generate a link to a Jupyter notebook. Copy the last URL (the one with127.0.0.1:8888at the beginning) into your web browser.Be sure to keep this terminal open.Do not exit the terminal or entercontrol-cuntil you are finished with the notebooks.NOTE:If you already have a Jupyter session open when you run./start_docker.sh, you will receive a couple additional prompts.Copy the URL listed afterEnter this URL instead to access the notebooks:You will need to authenticate. Note the last URL (the one with127.0.0.1:8888at the beginning), copy the token that appears there (it will be aftertoken=in the URL), paste it into the password prompt of the Jupyter notebook, and log in.You can shut down the notebooks and close docker by enteringcontrol-cin the terminal window.REMEMBER TO DUPLICATE AND RENAME NOTEBOOKSIf you didn't change the name of the notebooks within thetemplatesfolder, they will be overwritten when you decide to update the repo. Read about updating ArkhereExternal ToolsMantis ViewerMantisis a multiplexed image viewer developed by the Parker Institute. It has built in functionality for easily
viewing multichannel images, creating overlays, and concurrently displaying image features alongisde raw channels. We have found it to be extremely useful for analying the output of our analysis pipeline. There are detailed instructions on
theirdownload pagefor how to install and use the tool. Below are some details specifically related to how we use it inark.Workshop Talk - Session V - Cell-level Analysis - Part 3: Assessing Accuracy with Mantis Viewer.Mantis directory structureMantis expects image data to have a specific organization in order to display it. It is quite similar to how MIBI data is already stored,
with a unique folder for each FOV and all channels as individual tifs within that folder. Any notebooks that suggest using Mantis Viewer to inspect results
will automatically format the data in the format shown below.mantis
│├──fov0
│├──cell_segmentation.tiff
│├──chan0.tiff
│├──chan1.tiff
│├──chan2.tiff
│├──...
│├──population_mask.csv
│└──population_mask.tiff
├──fov1
│├──cell_segmentation.tiff
│├──chan0.tiff
│├──chan1.tiff
│├──chan2.tiff
│├──...
│├──population_mask.csv
│└──population_mask.tiff
└──marker_counts.csvLoading image-specific filesIn addition to the images, there are additional files in the directory structure which can be read into mantis.cell_segmentation: This file contains the predicted segmentation for each cell in the image, and allows mantis to identify individual cells.population_pixel_mask: This file maps the individual pixel clusters generated by Pixie in thepixel clustering notebookto the image data.population_cell_mask: Same as above, but for cell clusters instead of pixel clustersThese files should be specified when first initializing a project in mantis as indicated below:Loading project-wide filesWhen inspecting the output of the clustering notebooks, it is often useful to add project-wide .csv files, such asmarker_counts.csv. These files contain
information, such as the average expression of a given marker, across all the cells in the project. Project-wide files can either be loaded at project initialization, as shown below:Or they can be loaded into an existing project via Import -> Segment Features -> For project from CSVView cell featuresOnce you have loaded the project-wide files into Mantis, you'll need to decide which of the features you want to view.
Click onShow Plot Planeat the bottom right, then select the marker you want to assess. This will then allow you to view
the cell expression of that marker when you mouse over the cell in Mantis.External Hard Drives and Google File StreamTo configure external hard drive (or google file stream) access, you will have to add this to Dockers file paths in the Preferences menu.On Docker for macOS, this can be found in Preferences -> Resources -> File Sharing.  Adding/Volumeswill allow docker to see external drivesOn Docker for Windows with the WSL2 backend, no paths need to be added.  However, if using the Hyper-V backend, these paths will need to be added as in the macOS case.Once the path is added, you can run:bash start_docker.sh --external 'path/added/to/preferences'orbash start_docker.sh -e 'path/added/to/preferences'to mount the drive into the virtual/data/externalpath inside the docker.Updating the RepositoryThis project is still under development, and we are making frequent changes and improvements. If you want to update the version on your computer to have the latest changes, perform the following steps. Otherwise, we recommend waiting for new releases.First, get the latest version of the repository.git pullThen, run the command below to update the Jupyter notebooks to the latest version./start_docker.sh --updateor./start_docker.sh -uIf you have made changes to these notebooks that you would like to keep (specific file paths, settings, custom routines, etc), rename them before updating!For example, rename your existing copy of1_Segment_Image_Data.ipynbto1_Segment_Image_Data_old.ipynb. Then, after running the update command, a new version of1_Segment_Image_Data.ipynbwill be created with the newest code, and your old copy will exist with the new name that you gave it.After updating, you can copy over any important paths or modifications from the old notebooks into the new notebook.Example DatasetIf you would like to test out the pipeline, then we have incorporated an example dataset within the notebooks. Currently the dataset contains 11 FOVs with 22 channels (CD3, CD4, CD8, CD14, CD20, CD31, CD45, CD68, CD163, CK17, Collagen1, ECAD, Fibronectin, GLUT1, H3K9ac, H3K27me3, HLADR, IDO, Ki67, PD1, SMA, Vim), and intermediate data necessary for each notebook in the pipeline.The dataset is split into several smaller components, with each Jupyter Notebook using a combination of those components. We utilizeHugging Facefor storing the dataset and using their API's for creating these configurations. You can view thedataset's repository as well.Dataset CompartmentsImage Data:This compartment stores the tiff files for each channel, for every FOV.image_data/
├──fov0/
│├──CD3.tiff
│├──...
│└──Vim.tiff
├──fov1/
│├──CD3.tiff
│├──...
│└──Vim.tiff
├──.../Cell Table:This compartment stores the various cell tables which get generated by Notebook 1.segmentation/cell_table/
├──cell_table_arcsinh_transformed.csv
├──cell_table_size_normalized.csv
└──cell_table_size_normalized_cell_labels.csvDeepcell Output:This compartment stores the segmentation images after running deepcell.segmentation/deepcell_output/
├──fov0_whole_cell.tiff
├──fov0_nuclear.tiff
├──...
├──fov10_whole_cell.tiff
└──fov10_nuclear.tiffExample Pixel Output:This compartment stores feather files, csvs and pixel masks generated by pixel clustering.segmentation/example_pixel_output_dir/
├──cell_clustering_params.json
├──channel_norm.feather
├──channel_norm_post_rowsum.feather
├──pixel_thresh.feather
├──pixel_channel_avg_meta_cluster.csv
├──pixel_channel_avg_som_cluster.csv
├──pixel_masks/
│├──fov0_pixel_mask.tiff
│└──fov1_pixel_mask.tiff
├──pixel_mat_data/
│├──fov0.feather
│├──...
│└──fov10.feather
├──pixel_mat_subset/
│├──fov0.feather
│├──...
│└──fov10.feather
├──pixel_meta_cluster_mapping.csv
└──pixel_som_weights.featherExample Cell Output:This compartment stores feather files, csvs and cell masks generated by cell clustering.segmentation/example_cell_output_dir/
├──cell_masks/
│├──fov0_cell_mask.tiff
│└──fov1_cell_mask.tiff
├──cell_meta_cluster_channel_avg.csv
├──cell_meta_cluster_count_avg.csv
├──cell_meta_cluster_mapping.csv
├──cell_som_cluster_channel_avg.csv
├──cell_som_cluster_count_avg.csv
├──cell_som_weights.feather
├──cluster_counts.feather
├──cluster_counts_size_norm.feather
└──weighted_cell_channel.csvDataset Configurations1 - Segment Image Data:Image Data2 - Pixie Cluster Pixels:Image DataCell TableDeepcell Output3 - Pixie Cluster Cells:Image DataCell TableDeepcell OutputExample Pixel Output4 - Post Clustering:Image DataCell TableDeepcell OutputExample Cell OutputQuestions?If you have a general question or are having trouble with part of the repo, you can refer to ourFAQor head to thediscussionstab to get help. If you've found a bug with the codebase, first make sure there's not already anopen issue, and if not, you can thenopen an issuedescribing the bug.Want to contribute?If you would like to help makearkbetter, please take a look at ourcontributing guidelines.How to CitePlease directly cite thearkrepo (https://github.com/angelolab/ark-analysis) if it was a part of your analysis. In addition, please cite the relevant paper(s) below where applicable to your study.Greenwald, Miller et al. Whole-cell segmentation of tissue images with human-level performance using large-scale data annotation and deep learning [2021]Liu et al. Robust phenotyping of highly multiplexed tissue imaging data using pixel-level clustering [2023]