{"id":18583351,"url":"https://github.com/alexpreynolds/flow-cytometry-visualization","last_synced_at":"2026-04-14T23:31:43.559Z","repository":{"id":75267242,"uuid":"154292428","full_name":"alexpreynolds/flow-cytometry-visualization","owner":"alexpreynolds","description":"Flow cytometry visualization demo using Jupyter, Plotly, and fcsparser","archived":false,"fork":false,"pushed_at":"2018-11-05T15:57:48.000Z","size":17390,"stargazers_count":0,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-01-12T08:24:01.262Z","etag":null,"topics":["bioinformatics","fcs","jupyter","jupyter-notebook","plotly","puppeteer","python3","visualization"],"latest_commit_sha":null,"homepage":"https://nbviewer.jupyter.org/github/alexpreynolds/flow-cytometry-visualization/blob/master/FlowCytometryVisualization.ipynb","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alexpreynolds.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-10-23T08:36:01.000Z","updated_at":"2019-11-19T23:20:56.000Z","dependencies_parsed_at":"2023-06-05T23:30:36.806Z","dependency_job_id":null,"html_url":"https://github.com/alexpreynolds/flow-cytometry-visualization","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/alexpreynolds/flow-cytometry-visualization","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexpreynolds%2Fflow-cytometry-visualization","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexpreynolds%2Fflow-cytometry-visualization/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexpreynolds%2Fflow-cytometry-visualization/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexpreynolds%2Fflow-cytometry-visualization/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alexpreynolds","download_url":"https://codeload.github.com/alexpreynolds/flow-cytometry-visualization/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexpreynolds%2Fflow-cytometry-visualization/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31819718,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T18:05:02.291Z","status":"ssl_error","status_checked_at":"2026-04-14T18:05:01.765Z","response_time":153,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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","fcs","jupyter","jupyter-notebook","plotly","puppeteer","python3","visualization"],"created_at":"2024-11-07T00:22:03.819Z","updated_at":"2026-04-14T23:31:43.541Z","avatar_url":"https://github.com/alexpreynolds.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# flow-cytometry-visualization\n\nThis project demonstrates visualizing flow cytometry datasets, using Jupyter, Plotly, and `fcsparser`. \n\nA command-line script is included called `batchFCSPlot.py` that does batch conversion of FCS files to PNG-formatted scatterplots. This script makes uses of Google Puppeteer and Chromium, in addition to Plotly and `fcsparser`.\n\n## Jupyter notebook\n\nTo run this quickly, you may view the Jupyter notebook in *nbviewer*:\n\nhttps://nbviewer.jupyter.org/github/alexpreynolds/flow-cytometry-visualization/blob/master/FlowCytometryVisualization.ipynb\n\nIt can be useful to run this locally, to make tweaks and see how things work.\n\nFirst, install required Python libraries:\n\n```\n$ pip install fcsparser\n$ pip install jupyter\n$ pip install plotly\n$ pip install numpy\n```\n\nInstalling these libraries could take a few minutes, depending on what is already installed.\n\nThe `fcsparser` library is used to open and process FCS files. The other libraries are used for processing and visualizing the data.\n\nOpen the notebook file `FlowCytometryVisualization.ipynb`:\n\n```\n$ jupyter notebook FlowCytometryVisualization.ipynb\n```\n\nThis will open the notebook in your default web browser.\n\n----\nNote: If you run into `IOPub` errors, adjust `jupyter` settings when loading the notebook:\n\n```\n$ jupyter notebook --NotebookApp.iopub_data_rate_limit=1.0e10 FlowCytometryVisualization.ipynb\n```\n----\n\nMake a couple adjustments, as needed, to load local data and select desired datasets:\n\n 1. Adjust the value of the `fcsBaseFn` variable to point to a locally-saved copy of your FCS file. The desired FCS file could be put into the `data` subdirectory in this notebook's directory.\n 2. Adjust the desired column names in the `colsOfInterest`; these are used to render the three axes of the scatterplot.\n\nAfter making adjustments, re-run the Jupyter notebook. To do this, pull down the `Kernel` menu and select `Restart \u0026 Run All`.\n\nThe scatterplot is available at the bottom of the notebook and can be interacted with click-and-drag and scrollwheel actions, which rotate and zoom the plot. \n\nA PNG file of the scatterplot can be exported by clicking on the camera icon in the top-right corner of the scatterplot window.\n\n## Batch plot generation\n\n### Prerequisites\n\nBatch generation requires the additional installation of the `pyppeteer` Python library, which will in turn install Chromium, a version of Google Chrome that is used here to generate and export PNG files:\n\n```\n$ pip install pyppeteer\n```\n\n### Usage\n\n```\n$ ./batchFCSPlot.py --inputDir \u003cdirectory-of-FCS-files\u003e --outputDir \u003cdirectory-for-image-files\u003e --fcsColumns \u003clist-of-column-headers\u003e [ --gateX \u003cfloat\u003e --gateY \u003cfloat\u003e --gateZ \u003cfloat\u003e] [ --xRangeMin \u003cfloat\u003e --xRangeMax \u003cfloat\u003e --yRangeMin \u003cfloat\u003e --yRangeMax \u003cfloat\u003e --zRangeMin \u003cfloat\u003e --zRangeMax \u003cfloat\u003e ]\n```\n\nThe first time the `batchFCSPlot.py` script is run, you may be prompted to grant permissions for Chromium to access your screen display. Just click on the \"Allow\" button for the script to proceed. You should only need to do this once; afterwards, the browser will make screenshots in the background.\n\nGate values `--gateX`, `--gateY`, and `--gateZ` are optional and are set initially to defaults of `3.55`, `3.2`, and `3.02`, respectively.\n\nEach pair of `--xRangeMin`, `--xRangeMax`, `--yRangeMin`, `--yRangeMax`, `--zRangeMin`, and `--zRangeMax` is set to a default minimum of `0` and a maximum of `6`, respectively.\n\n### Example\n\nWhen run from within this project directory:\n\n```\n$ ./batchFCSPlot.py --inputDir data --outputDir /tmp/fcsImages --fcsColumns \"APC-H,PB450-H,ECD-H\"\nDebug: Writing [/tmp/fcsImages/01-TripDay5-E2-Untreated/index.html] and [/tmp/fcsImages/01-TripDay5-E2-Untreated/figure.png]...\nDebug: Writing [/tmp/fcsImages/01-TripDay5-B1-PD1/index.html] and [/tmp/fcsImages/01-TripDay5-B1-PD1/figure.png]...\nDebug: Writing [/tmp/fcsImages/01-TripDay5-C1-TIM3/index.html] and [/tmp/fcsImages/01-TripDay5-C1-TIM3/figure.png]...\nDebug: Writing [/tmp/fcsImages/01-TripDay5-E1-Untreated/index.html] and [/tmp/fcsImages/01-TripDay5-E1-Untreated/figure.png]...\nDebug: Writing [/tmp/fcsImages/01-TripDay5-B2-PD1/index.html] and [/tmp/fcsImages/01-TripDay5-B2-PD1/figure.png]...\nDebug: Writing [/tmp/fcsImages/01-TripDay5-A3-unstained/index.html] and [/tmp/fcsImages/01-TripDay5-A3-unstained/figure.png]...\nDebug: Writing [/tmp/fcsImages/01-TripDay5-D2-LAG3/index.html] and [/tmp/fcsImages/01-TripDay5-D2-LAG3/figure.png]...\nDebug: Writing [/tmp/fcsImages/01-TripDay5-A2-multiplex/index.html] and [/tmp/fcsImages/01-TripDay5-A2-multiplex/figure.png]...\nDebug: Writing [/tmp/fcsImages/01-TripDay5-C2-TIM3/index.html] and [/tmp/fcsImages/01-TripDay5-C2-TIM3/figure.png]...\nDebug: Writing [/tmp/fcsImages/01-TripDay5-A1/index.html] and [/tmp/fcsImages/01-TripDay5-A1/figure.png]...\nDebug: Writing [/tmp/fcsImages/01-TripDay5-D1-LAG3/index.html] and [/tmp/fcsImages/01-TripDay5-D1-LAG3/figure.png]...\n```\n\nIn this example, each of the subfolders `/tmp/fcsImages/\u003cFCS-dataset\u003e` contain `index.html` and `figure.png`.\n\nThe following, for instance, will open a PNG file in your default image viewer:\n\n```\n$ open /tmp/fcsImages/01-TripDay5-B1-PD1/figure.png\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexpreynolds%2Fflow-cytometry-visualization","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexpreynolds%2Fflow-cytometry-visualization","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexpreynolds%2Fflow-cytometry-visualization/lists"}