{"id":23583908,"url":"https://github.com/kanaverse/kana","last_synced_at":"2025-05-07T02:26:28.419Z","repository":{"id":38042093,"uuid":"434092107","full_name":"kanaverse/kana","owner":"kanaverse","description":"Single cell analysis in the browser","archived":false,"fork":false,"pushed_at":"2024-04-24T15:55:45.000Z","size":133839,"stargazers_count":131,"open_issues_count":27,"forks_count":12,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-04-24T22:21:58.376Z","etag":null,"topics":["bioinformatics","cite-seq","exploratory-data-analysis","interactive-analysis","interactive-visualizations","rna-seq","single-cell","webassembly"],"latest_commit_sha":null,"homepage":"https://kanaverse.org/kana/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kanaverse.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.bib","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2021-12-02T05:21:14.000Z","updated_at":"2024-04-24T15:53:56.000Z","dependencies_parsed_at":"2023-02-14T05:16:21.957Z","dependency_job_id":"a344e21a-a5be-48a5-b717-d971f9098dfa","html_url":"https://github.com/kanaverse/kana","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kanaverse%2Fkana","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kanaverse%2Fkana/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kanaverse%2Fkana/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kanaverse%2Fkana/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kanaverse","download_url":"https://codeload.github.com/kanaverse/kana/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":231427263,"owners_count":18375016,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bioinformatics","cite-seq","exploratory-data-analysis","interactive-analysis","interactive-visualizations","rna-seq","single-cell","webassembly"],"created_at":"2024-12-27T02:18:18.643Z","updated_at":"2024-12-27T02:18:19.312Z","avatar_url":"https://github.com/kanaverse.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kana: Single cell analysis in the browser\n\n[![DOI](https://joss.theoj.org/papers/10.21105/joss.05603/status.svg)](https://doi.org/10.21105/joss.05603)\n[![DOI:10.1101/2022.03.02.482701](http://img.shields.io/badge/bioRxiv-10.1101/2022.03.02.482701-B31B1B.svg)](https://doi.org/10.1101/2022.03.02.482701)\n\n\n*Kana* comes from the [Telugu](https://en.wikipedia.org/wiki/Telugu_language) word [kaṇaṁ (కణం)](https://www.shabdkosh.com/dictionary/english-telugu/%E0%B0%95%E0%B0%A3%E0%B0%82/%E0%B0%95%E0%B0%A3%E0%B0%82-meaning-in-telugu), which means ...  drumroll... ***cell***\n\n## Overview\n\n**kana** is a web application for single-cell data analysis that works directly in the browser.\nThat's right - the calculations are performed client-side, by your browser, on your computer!\nThis differs from the usual paradigm of, e.g., Shiny applications where data needs to be sent to a backend server that does the actual analysis.\nOur client-side approach has a number of advantages:\n\n- Your data is never transferred anywhere, so you don't have to worry about problems with data privacy.\n  These can be especially hairy when your backend server lies in a different jurisdiction from your data source.\n  By performing the analysis on the client, we avoid all of these issues.\n- **kana** is super-cheap to run and deploy, just serve it as a static website.\n  There's no need to maintain a server or cloud compute instance - let the user's machine take care of it.\n  It also naturally scales to any number of users as they're automatically providing the compute.\n- By removing network latency, we can achieve a smooth interactive experience.\n  This ranges from steps such as animated dimensionality reductions to user-driven marker detection and celltype annotation.\n\n![Overview and Analysis zillonis mouse lung dataset](assets/v3_release.gif)\n\n## For users\n\nIf you have a Matrix Market (`.mtx`) file or HDF5 (tenx V3 or `AnnData` representation stored as h5ad), or `SummarizedExperiment` (or derivatives like `SingleCellExperiment`) stored as an RDS file, or an [ExperimentHub](https://bioconductor.org/packages/release/bioc/html/ExperimentHub.html) id, you're ready to go.\n\n1. Launch the application by clicking [**here**](https://www.kanaverse.org/kana/).\n2. Select the Matrix Market file (this may be Gzip-compressed).\n   We recommend also providing the corresponding `genes.tsv` or `features.tsv` file to identify marker genes properly.\n3. Click the \"Analyze\" button, and we'll run a standard single-cell analysis for you.\n\nThe standard analysis follows the flow described in the [**Orchestrating Single-Cell Analysis with Bioconductor**](https://bioconductor.org/books/release/OSCA/).\nBriefly, this involves:\n\n- Removal of low-quality cells \n- Normalization and log-transformation\n- Modeling of the mean-variance trend across genes\n- A principal components analysis on the highly variable genes\n- Clustering with graph-based methods\n- The usual dimensionality reductions (t-SNE/UMAP)\n- Marker detection for each cluster\n- Compute gene set enrichment for each cluster\n- Support Multi-modal analysis for Cite-seq data and/or CRISPR\n- Make custom cell selections and detect markers for this selection\n- Cell type annotation for each cluster across user selected reference datasets\n- Perform Integration or Batch correction using MNN correction. You can provide a single dataset containing multiple batches and specify the `batch` column in the cell annotations, or load multiple datasets where each dataset is considered a batch\n- Perform analysis on subsets (filter based on cell annotation)\n\nThe interface provides a depiction of the dimensionality reduction of choice,\na ranking of marker genes for the cluster of interest,\nand diagnostic plots from the individual analysis steps.\n\n***Checkout the [wiki](https://github.com/kanaverse/kana/wiki) for tutorials on the functionality Kana provides.***\n\n![Features](assets/v3_release.png)\n\n**Tips and tricks:**\n\n- Clicking on a cluster name in the legend will highlight that cluster in the t-SNE/UMAP plot.\n- Clicking on the droplet icon in the marker table will color the t-SNE/UMAP plot by the expression of the selected gene.\n- Clicking on the plus icon in the marker table will give some details about that gene's expression in the selected cluster, including a histogram relative to cells in other clusters.\n- Hovering over the bars in the Markers section for a gene displays a tooltip on different statistics for that gene vs the selected cluster.\n- Filter markers either by searching for a gene or using the sliders to filter by various statistics.\n- Clicking on Save in the t-SNE or UMAP section will capture the current state of the visualization to Gallery\n- Clicking on Animate will interactively visualize dimensions at various iterations as the t-SNE or UMAP algorithms computes these embeddings\n- Clicking on \"What's happening\" will show logs describing how long each step of the analysis took (and any errors during the analysis).\n- Clicking Export will save the analysis either to the browser or download the analysis as a .kana file. Loading these files will restore the state of the application\n\nIf you use **Kana** for analysis or exploration, consider citing our JOSS publication -\n\n```bibtex\n@article{Kana2023, \n  doi = {10.21105/joss.05603}, \n  url = {https://doi.org/10.21105/joss.05603}, \n  year = {2023}, \n  publisher = {The Open Journal}, \n  volume = {8}, \n  number = {89}, \n  pages = {5603}, \n  author = {Aaron Tin Long Lun and Jayaram Kancherla}, \n  title = {Powering single-cell analyses in the browser with WebAssembly}, \n  journal = {Journal of Open Source Software} \n}\n```\n\n## For developers\n\n***Check out [Contributing](./CONTRIBUTING.md) for guidelines on opening issues and pull requests.***\n\n### Deployment \n\nDeployment is as easy as serving the static files in this repository via HTTPS.\nIndeed, our [**deployment**](https://kanaverse.org/kana/) is just being served via GitHub Pages. other providers include static hosting on AWS S3, Google buckets, netlify or *name-your-own-provider*.\nAs promised, there's no need to set up a backend server.\n\n#### Docker based builds\n\nThanks to [llewelld](https://github.com/llewelld) for creating a docker image that can generate static HTML files without the hassle of setting up `npm` and `node`.\n\nBuild the docker images and tag them as ***kana***. \n\n```sh\ndocker build . -t kana\n\n# if you are on a macos with m1 or m2, you MIGHT have to use the platform tag\ndocker build . -t kana --platform linux/arm64\n```\n\nRun the container to generate the production builds,\n\n```sh\ndocker run -v .:/kana -t kana\n\n# or depending on your operating system (noticed this on windows with WSL)\ndocker run -v $(pwd):/kana -t kana \n```\n\nand voila, you should now see a builds directory. you can also run the npm commands to generate the builds. checkout either the [Dockerfile](./Dockerfile) or the [contributing section](#contributing) in this README.\n\n\n#### Serving HTML locally\n\nThere are numerous options to serve the html files locally using tools that are ***probably*** already available on your machine. \n\n\nPython's http.server\n\n```sh\npython -m http.server 3000 -d builds\n```\n\nnpm's [serve](https://www.npmjs.com/package/serve)\n\n```sh\nnpm install -g serve\nserve builds\n```\n\nor [caddy](https://caddyserver.com/docs/quick-starts/static-files),  apache, nginx or static hosting solutions, or anything else you are familiar with.\n\n\n### Architecture\n\n***We have significantly revamped the entire application and the underlying infrastructure to support hybrid compute - either purely client-side with webassembly, or on backend systems through node, or both.***\n\n**kana** uses the [**scran.js**](https://github.com/kanaverse/scran.js) library for efficient client-side execution of single-cell analysis steps.\nThis uses a variety of C/C++ libraries compiled to [WebAssembly](https://webassembly.org/) to enable heavy-duty calculations in the browser at near-native speed.\n\n\u003c!--\nTraditional data analysis applications use ***function shipping***, where a client (or an application in the browser) wants to perform an operation on a dataset on a backend server.\nThe client makes an API call to the server asking it to compute a function, the server responds with the results of the operation and the client/app displays them. \nIn **kana**, we replace the server with the users's own laptop/machine. \n--\u003e\n\nAll computations performed by **kana** run in a [Web Worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers).\nThis avoids blocking on the main thread and allows the application to be more responsive.\nData is sent to the main thread on an as-needed basis, e.g., for visualizations. \nWe also create separate Web Workers for the t-SNE and UMAP steps so that they can be run concurrently for maximum efficiency.\n\n![Worker Model](assets/scran.js.app.workers.png)\n\nThe WASM code itself is compiled with PThreads support to enable parallelization of some analysis steps.\nThis involves the use of a [`SharedArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer) to efficiently share memory across Web Workers,\nwhich in turn requires cross origin isolation of the site.\nWe achieve this by using a service worker to cache the resources and load the blobs with the relevant headers - hence the need for HTTPS.\n\n### Friends of Kana\n\n \n- [ba***kana***](https://github.com/kanaverse/bakana): The core analysis workflow is refactored into an independent package to provide the same functionality in browser and node environments. The Kana front-end is now a wrapper around bakana.\n- [***kana***pi](https://github.com/kaanverse/kanapi): provides a node API (using WebSockets) to run single-cell analysis in backend environments (extending `bakana`). One can extend **Kana** to interact to this API (#good-first-issue)\n- [***kana***-formats](https://github.com/kanaverse/kana-formats): as we add new functionality and features, we need to store and read the exported analysis state (`.kana` files). This package specifies the formats and provides readers for parsing various versions.\n- [***kana***val](https://github.com/kanaverse/kanaval): validate the exported analysis results. \n\n![Kana Full Architecture](assets/kana.arch.png)\n\nFor the curious: this project was bootstrapped with the [Create React App](https://github.com/facebook/create-react-app).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkanaverse%2Fkana","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkanaverse%2Fkana","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkanaverse%2Fkana/lists"}