Metadata-Version: 2.4
Name: honeychrome
Version: 0.7.0
Summary: Open Source GUI App for Cytometry Acquisition and Analysis 
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE.txt
Requires-Dist: anytree==2.13.0
Requires-Dist: bitarray==3.8.0
Requires-Dist: bokeh==3.8.2
Requires-Dist: certifi==2026.1.4
Requires-Dist: charset-normalizer==3.4.4
Requires-Dist: colorama==0.4.6
Requires-Dist: colorcet==3.1.0
Requires-Dist: contourpy==1.3.3
Requires-Dist: cycler==0.12.1
Requires-Dist: deepdiff==8.6.1
Requires-Dist: FlowIO==1.4.0
Requires-Dist: FlowKit==1.3.0
Requires-Dist: FlowUtils==1.2.2
Requires-Dist: fonttools==4.61.1
Requires-Dist: ft4222==1.12.0
Requires-Dist: idna==3.11
Requires-Dist: Jinja2==3.1.6
Requires-Dist: joblib==1.5.3
Requires-Dist: kiwisolver==1.4.9
Requires-Dist: lxml==6.0.2
Requires-Dist: MarkupSafe==3.0.3
Requires-Dist: matplotlib==3.10.8
Requires-Dist: narwhals==2.15.0
Requires-Dist: networkx==3.6.1
Requires-Dist: numpy==2.4.1
Requires-Dist: orderly-set==5.5.0
Requires-Dist: packaging==25.0
Requires-Dist: pandas==3.0.2
Requires-Dist: pathvalidate==3.3.1
Requires-Dist: pillow==12.1.0
Requires-Dist: psutil==7.2.1
Requires-Dist: pyarrow==22.0.0
Requires-Dist: pyparsing==3.3.1
Requires-Dist: pyqtgraph==0.14.0
Requires-Dist: PySide6==6.10.1
Requires-Dist: PySide6_Addons==6.10.1
Requires-Dist: PySide6_Essentials==6.10.1
Requires-Dist: python-dateutil==2.9.0.post0
Requires-Dist: python-docx==1.2.0
Requires-Dist: pytz==2025.2
Requires-Dist: PyYAML==6.0.3
Requires-Dist: requests==2.32.5
Requires-Dist: scikit-learn==1.8.0
Requires-Dist: scipy==1.17.0
Requires-Dist: seaborn==0.13.2
Requires-Dist: shiboken6==6.10.1
Requires-Dist: six==1.17.0
Requires-Dist: threadpoolctl==3.6.0
Requires-Dist: tornado==6.5.4
Requires-Dist: typing_extensions==4.15.0
Requires-Dist: tzdata==2025.3
Requires-Dist: urllib3==2.6.3
Requires-Dist: xyzservices==2025.11.0
Provides-Extra: dev
Dynamic: license-file

[Cytkit](https://cytkit.com) | [Honeychrome](https://honeychrome.cytkit.com/) 
---


# <img src="src/honeychrome/view_components/assets/cytkit_web_logo.png" width="60"> Honeychrome

Open-Source Cross-Platform GUI App for Cytometry Acquisition and Analysis. Built in Python. [Source code on GitHub.](https://github.com/salmansamson/honeychrome) Part of the [Cytkit](https://cytkit.com) project to provide a complete open-source spectral cytometer.

<div>
  <a href="https://youtu.be/RQ4-RQkDCm4"><img src="other/honeychrome screenshot animation.webp" alt="Animated Demo" width="800"></a>
</div>

Our aim is to make Honeychrome so intuitive that you don't need instructions. But just in case, we have prepared this instructional video on YouTube: [Introduction to Honeychrome in 30 Minutes](https://youtu.be/RQ4-RQkDCm4). 

We also have a set of guides to using Honeychrome: 

* Installation (below)
* [Acquire Data](/docs/acquisition)
* [Spectral Analysis](/docs/spectral_analysis)
* [AutoSpectral in Honeychrome](/docs/autospectral_in_honeychrome)
* [Conventional Analysis](/docs/conventional_analysis)
* [Manipulate Plots and Gates](/docs/cytometry_plots_and_gates)
* [Reports, Exports & Sample Comparison](/docs/reports)
* [Programming and Plugins](/docs/programming_plugins)

## Mission statement

For too long, our field lacked a general purpose, 
free and open-source cytometry software package. 
We are plugging that gap to provide a software package that is useful for everybody: 
power cytometrists, biologists, students, innovators. 
The app is lightweight but provides all the features one expects: 

- acquire data (starting with Cytkit, perhaps with drivers for other instruments in the future)
- analyse data from any instrument's FCS files 
- provide both conventional compensation and spectral unmixing
- give simple statistical comparisons between samples, publication-quality graphs and exports
- provide intuitive usability with minimal instructions
- support the major operating systems (Windows, MacOS, Linux...)
- no collection or processing of personal information

Honeychrome is fully open source to provide a platform that innovators can exploit, 
for developing both new instrumentation and new methods in data analysis/visualisation.

See more about Honeychrome and the Cytkit project here: [cytkit.com](https://cytkit.com/)

## Installation
You have the following options, depending on whether you want to use the Python source 
code or just download an executable. For most users, it is sufficient to download
an executable for your platform (Windows/Linux/MacOS).

Note that the plugin system is only available if Honeychrome is run from the Python source code.

### For non-programmers: download and run executable
A set of compressed binary packages are available in the releases section.
> **Note:** Since Honeychrome is very new, you may get warnings on Windows/Mac that the application is unrecognised. If so, please post the warning on the Github issues page, or contact Samson ([cytkit.com/contact](https://cytkit.com/contact)). You can normally click through any warnings; starting the app should function normally after that.

#### Windows
1. Download [Honeychrome for Windows x64](https://github.com/salmansamson/honeychrome/releases/download/v0.6.1-beta/Honeychrome-v0.6.1-windows-x64.exe)
2. Double click to run the installer

#### Linux (Ubuntu > 24.04)
1. Download [Honeychrome for Linux x64 Ubuntu > 24.04](https://github.com/salmansamson/honeychrome/releases/download/v0.6.1-beta/honeychrome-v0.6.1-linux-x64.tar.gz)
2. Extract the honeychrome folder and put it somewhere appropriate for the single user or system
3. Change to the honeychrome folder and run ./install_linux.sh

(For other Linux systems, please use the Python instructions below.)

#### MacOs
1. Download [Honeychrome for MacOS](https://github.com/salmansamson/honeychrome/releases/download/v0.6.1-beta/honeychrome-v0.6.1-macos.dmg)
2. Open the disk image and drag honeychrome.app to your Applications folder.
3. Double click the app in your Applications folder to run 

#### Other systems
For all other systems, please follow the Python instructions below. 

> **Note:** If you want to use the plugin functionality, please clone and run the full Python package according to the instructions below.

### Run Honeychrome from Python source
Follow these steps to clone the repository and run the application from source:

1.  **Clone the repository:**
    ```bash
    git clone https://github.com/salmansamson/honeychrome.git
    cd honeychrome
    ```

2.  **Create a virtual environment:**
    *Requires Python 3.12 or higher.*
    ```bash
    python3 -m venv .venv
    ```

3.  **Activate the virtual environment:**
    * **Linux/macOS:** `source .venv/bin/activate`
    * **Windows:** `.venv\Scripts\activate`

4.  **Upgrade pip and install dependencies:**
    ```bash
    pip install --upgrade pip
    pip install -r requirements.txt
    ```

5.  **Install the package in editable mode:**
    *This ensures all internal modules are correctly mapped to your path.*
    ```bash
    pip install -e .
    ```

6.  **Run the application:**
    ```bash
    python3 -m honeychrome.main
    ```

## Contributions
We have many ideas for Honeychrome and welcome new ones. 
We also welcome anyone wishing to contribute to and improve the software!

We will shortly release fuller instructions and documentation for programmers wishing to build on Honeychrome in
new open source cytometry projects. In the meantime, please contact us if you require assistance.

Honeychrome builds on several great open source Python packages:
- [FlowKit](https://github.com/whitews/flowkit) - for definition of gates, gating hierarchies, transforms, and FCS input/output
- [PySide6](https://pypi.org/project/PySide6/) - the GUI system, Qt for Python
- [pyqtgraph](https://www.pyqtgraph.org/) - extremely fast plotting and manipulation of plots in Qt
- Several others for processing of data, including numpy, scikit, sklearn
- Seaborn and Matplotlib for publication-quality graphics

Samson Rogers has been the main developer so far. Oliver Burton contributed the AutoSpectral AF function and many aspects of the spec and usability. 
Thanks to support and advice from many people including C. Vant, Lotte Carr, Scott Tasker, Philip Jones, Robyn Pritchard.

## Roadmap
By January 2027, we hope to get to a stable release labeled v1.0.0, including the following:
- all bugs fixed
- documentation for users
- documentation for developers
