flowmepy 0.4.0
a C++ FCS Loader

# FlowMePy - a Python API for FlowMe
Load FCS 2.0/3.0/3.1 files with super fast C++ code. The FCS processing includes compensation and logicle transform. If FacsDiva projects (XMLs) or Kaluza projects (analysis) are provided, the FlowMePy will label events according to the gates contained. 

[Read the Docs](https://kwc.pages.cvl.tuwien.ac.at/dev/flowme-python-api/)

## Install
We provide a pre-compiled package (currently Windows only) which can be installed using:
````console
pip install flowmepy
````


### Dependencies
- `python` (>= 3.6)
- `CMake` (>= 3.14.1)
- `Qt` SDK or the compiled sources (>= 5.11.0)
- `OpenCV` (>= 4.0.0)
- Visual Studio (>= 2015) or gcc

### Configure FlowMe using CMake (Windows only)
- dir to ./flowme
- copy `CMakeUserPathsGit.cmake` and rename it to `CMakeUserPaths.cmake`
- add your library paths to the `${CMAKE_PREFIX_PATH}` in `CMakeUserPaths.cmake`

## Clone

We use submodules for `flowme` and `pybind11` if you clone using
````console
$ git clone --recursive git@smithers.cvl.tuwien.ac.at:kwc/dev/flowme-python-api.git
````
everything should be fine. In case the repository's `flowme` or `pybind11` folders are empty, check if the pull worked as expected:
- don't forget `--recursive`
- windows users: it's easiest if you do not password protect the ssh key


## Build

````console
$ virtualenv env
$ source /env/bin/activate
$ python setup.py install
````

If anything did not work as expected, try building FlowMe as standalone package (see [README](./flowme/README.md)). Then run the above command again.

You can remove old versions using pip:
````console
$ pip uninstall FlowMePy
Successfully uninstalled flowmepy-0.0.3
````

## Packaging FlowMePy
Update pip (on Windows & Linux), then create the wheel:
````console
python -m pip install --upgrade setuptools wheel
python setup.py sdist bdist_wheel
````
where `sdist` creates the source archive (without C++ files) and bdist_wheel creates the build package.

Then, upload the package:

````console
python -m twine upload dist/*
````

in case you want to test your package, use this for uploading:
````console
python -m twine upload --repository-url https://test.pypi.org/legacy/ dist/*
````
Unfortunately, test.pypi.org rejects linux binary wheels - so linux users must build packages on their own.
You can install this package using:
````console
pip install -i https://test.pypi.org/simple/ flowmepy --extra-index-url https://pypi.org/simple
````

## Test
Test flowmepy using:
````console
$ python -m unittest discover -v test
````

## build the docs
````console
$ cd docs
$ make html
````

The compiled docs are here: [`docs/_build/index.html`](docs/_build/index.html)

## FlowMePy in 2 minutes
load an FCS using
````python
import flowme

filepath = "./flowme/src/data/samples/FacsDiva.xml"
sample = flowme.fcs(filepath)
events = sample.events()       # get the event data (pandas.DataFrame)
gates = sample.gate_labels()   # get gating (GT) information (pandas.DataFrame)
````

Per default events are **not** filtered by any Gate. However, it is possible to pass the name of a filtering gate:

````python
import flowme

filepath = "./flowme/src/data/samples/FacsDiva.xml"
filter_gatename = "viable"
sample = flowme.fcs(filepath, filter_gatename)
````

FlowMe provides a built-in data cleaning function that prunes events accumulated at the measured maximum.

````python
import flowme

filepath = "./flowme/src/data/samples/FacsDiva.xml"
sample = flowme.fcs(filepath)
events, gates = sample.filtered_data(cleanDataPercent=0.001)
````

### Handling multi tube files

Some files may contain multiple tubes. The following code shows how available tubes can be queried as well as how to select from which tube to load the data.

````python
import flowme


tube_names = sample.get_tube_names()
sample.set_tube_index(len(tub_names) - 1)
events = sample.events() #events of last tube in sample
````


![mascot](https://upload.wikimedia.org/wikipedia/en/thumb/0/02/Tweety.svg/133px-Tweety.svg.png)