HOWTO: Install Cytoflow Modules#

To use the Cytoflow modules in a Jupyter notebook or your own code#

Cytoflow is available as a package for the Anaconda scientific Python distribution. You can install cytoflow through the Anaconda Navigator, or by using the command line.

Installing from the Anaconda Navigator#

  • Start by installing the Anaconda Python distribution. Make sure to install a 64-bit version, unless you will be building cytoflow yourself and you know what you’re doing.

    Download Anaconda here

  • Either from the Start Menu (Windows) or the Finder (Mac), run the Anaconda Navigator

  • Click the Channels button.

    ../../_images/channels.PNG

  • Click Add... and type conda-forge. Select “Update channels.”

  • Click Add... and type cytoflow. Select “Update channels.”

    ../../_images/add-channels.PNG

  • The application cytoflow should appear in the launcher. Click the Install button.

    ../../_images/new-app.PNG

  • Navigator asks if you’d like to install in a new environment. Say Yes..

    ../../_images/new-env.PNG

    NOTE: Be patient. Anaconda Navigator is slow. NOTE: Make sure that you choose an environment that does not already exist!

  • To verify installation, start a Jupyter notebook.

    • First, make sure you have the ``cytoflow`` environment selected.

    • From the Anaconda Navigator, install and then launch JupyterLab.

    • Create a new Python 3 notebook.

    • In the first cell, type import cytoflow and press Shift+Enter. If Python doesn’t complain, you’re good to go. (If it does, please submit a bug report at cytoflow/cytoflow#issues )

  • Note: When you install Cytoflow this way, the point-and-click application is installed as well. You can launch it from the Anaconda Navigator.

Installing from the command line#

  • Start Anaconda Prompt from the Start Menu (Windows) or Finder (Mac).

  • If you don’t have it already, add the conda-forge channel:

    conda config --add channels conda-forge

  • Add the cytoflow channel:

    conda config --add channels cytoflow

  • Create a new environment and install cytoflow and Jupyter Lab. In this example, the new environment will be called cf – feel free to choose a different name:

    conda create --name cf cytoflow jupyterlab

  • Activate the new environment:

    conda activate cf

  • Launch the Jupyter notebook:

    jupyter lab

  • Create a new Python 3 notebook. In the first cell, type import cytoflow and press Shift+Enter. If Python doesn’t complain, you’re good to go. (If it does, please submit a bug report!)

  • This method ALSO installs the GUI. You should be able to run it by activating your new environment and running the cytoflow script.

To hack on the code#

Cytoflow depends on a huge number of libraries from the Scientific Python ecosystem, and a change in any one of their APIs will break the cytoflow library. So, I have pinned the versions of all of cytoflow’s dependencies, which all but guarantees that you’ll need to install into a virtual environment. This will ensure that the rest of your Python installation doesn’t break.

Note

cytoflow cannot be installed using pip, except locally from source with pip install --editable . I am already supporting it across four operating systems, adding another installer is too much.

Finally, cytoflow relies on one C++ extension. On Linux, installing the requirements for building it is straightforward. On MacOS it is harder, and on Windows it is extremely difficult. Instead, as part of rolling a new release, the appropriate files are made available on the GitHub releases page. The procedure below includes instructions for downloading and installing the appropriate file.

  • Install the development dependencies

    • On Ubuntu: apt-get git swig python-dev

    • On Windows: Install a copy of git. I use git-for-windows

    • On MacOS: Install a copy of git from the Git website.

  • Clone the repository, including submodules:

    git clone --recurse-submodules https://github.com/cytoflow/cytoflow.git

  • Edit environment.yml as follows:

    • If you’re using Windows, REMOVE the line that reads - nomkl # [not win]

    • If you’re not using Windows, remove the line that reads - mkl-service # [win]

  • Create a new environment. In this example, I have called it cf_dev. In the new repository you just cloned, say:

    conda env create --name cf_dev --file environment.yml

  • Activate the new environment:

    conda activate cf_dev

  • Install cytoflow in developer’s mode:

    pip install --editable .

  • From the GitHub releases page download the appropriate extension file for the version you’re installing.

    • On Windows (64-bit): _Logicle.cp312-win_amd64.pyd

    • On MacOS (Intel): _Logicle-macos-x86_64.so

    • Onw MacOS (Apple Silicon): _Logicle-macos-arm64.so

  • Copy the file you just download into the cytoflow/utility/logicle_ext/ folder in your source tree.

  • On MacOS only, rename the file to _Logicle.so.

  • Test that everything works. Start a python interpreter and say:

    import cytoflow

If you don’t get any errors, you’re good to go.

Running the point-and-click GUI program#

There are pre-built bundles available at http://cytoflow.github.io/

Alternately, you can follow the instructions above for installing the Anaconda package, then run cytoflow through the Anaconda Navigator or via the command line.