AmoePy is a python-based toolbox for analyzing and simulating amoeboid cell motility, including a graphical user interface (GUI) under development.
In addition to this README, the CHEATSHEET will give you an overview over the most important GUI features.
The AmoePy software package consists of two main directories:
B02 andb02-data.B02 contains the code base of the project <a href="https://www.sfb1294.de/research/research-area-b/b02">B02</a> of the Collaborative Research Center <a href="https://www.sfb1294.de">SFB 1294</a>.
In B02, you will find:
B02/src,B02/build/html/index.html andB02/data.b02-data contains additional data, necessary to reproduce every result of our research. Many routines in B02, especially those regarding our research work, depend on the data from b02-data.
<b>Therefore, both directories must be saved in the same parent directory!</b>
AmoePy is provided with an html documentation (generated with Sphinx) which can be found the following path:
B02/build/html/index.html
This project uses <a href="https://www.anaconda.com/products/individual">conda</a> to manage its dependencies. Therefore, we recommend to install the newest Anaconda distribution from <a href="https://www.anaconda.com/products/individual">this link</a>.
During the installation, a conda environment (called AmoePy) will be created. For this conda environment, a list of python packages listed in B02/src/environment.yml will be downloaded. The default conda environment (named base) stays untouched. See below for additional information on conda environment commands.
First, depending on your operating system, open a new
In this tutorial, the sign $ indicates a new line only.
Therefore, all commands must be entered without $
You might update conda with the following command
$ conda update conda
For a given directory DIR, where the package B02 is saved, you can now change the working directory by the following commands:
$ cd DIR
$ cd B02
$ cd src
To install all dependencies and activate the conda environment, within B02/src use
$ conda env create -n AmoePy -f environment.yml
$ conda activate AmoePy
After this step, all Python dependencies should be installed. Now, you can start the graphical user interface of AmoePy by using the python commands listed in the section below (named Starting graphical user interface).
If you already have an AmoePy conda environment, you can add the dependencies by running
$ conda env update -n AmoePy -f environment.yml
$ conda activate AmoePy
To see a list of all environments, use
$ conda env list
To delete the AmoePy environment, use
$ conda activate base
$ conda env remove -n AmoePy
Additional conda environment commands can be found <a href="https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html">here</a>.
In order to install AmoePy, click on B02/Install AmoePy.app (MacOS).
An opening window may ask for permissions regarding:
A terminal window should open which installs or updates the conda environment in order to install necessary python packages for AmoePy. If it asks for permission to overwrite packages, type y.
Afterwards, you can easily open AmoePy by clicking on
B02/AmoePy.app.
You can install AmoePy by calling the shell script B02/install.sh (Mac/Linux) by the following command:
$ cd B02
$ sh install.sh
which installs (and updates) the conda environment, necessary to open AmoePy. After installing AmoePy succesfully, the graphical user interface should open.
Now, AmoePy can be also opened by the shell script B02/amoepy.sh:
$ cd B02
$ sh amoepy.sh
B02/amoepy.sh does not check whether the underlying conda environment is installed correctly. Therefore, it opens AmoePy faster than B02/install.sh (but only if the conda environment is correctly installed).
You can install AmoePy by double-clicking on the batch file
B02\install.bat (Windows).A terminal window should open which installs or updates the conda environment in order to install necessary python packages for AmoePy. If it asks for permission to overwrite packages, type y.
Also, a desktop icon is created, which is a copy of the shortcut B02\AmoePy_Windows. After installing AmoePy succesfully, the graphical user interface should open.
Afterwards, you can easily open AmoePy by double-clicking on
Desktop\AmoePy, orB02\AmoePy_Windows, orB02\amoepy.bat.B02\amoepy.bat does not check whether the underlying conda environment is installed correctly. Therefore, it opens AmoePy faster than B02\install.bat (but only if the conda environment is correctly installed).
In order to open the graphical user interface of <b>AmoePy</b>,
go to B02/src and use one of the following commands:
$ conda activate AmoePy
$ python -m run.run_amoepy
or
$ conda activate AmoePy
$ python3 -m amoepy.gui.amoepygui
If the command python3 is not defined/found, try using the command python instead.
The graphical user interface will then be opened by the run script
B02/src/run/run_amoepy.py or by the file B02/src/amoepy/gui/amoepygui.py.
Open AmoePy by clicking on B02/AmoePy.app.
Open AmoePy by running the shell script B02/amoepy.sh:
$ cd B02
$ sh amoepy.sh
Open AmoePy by double-clicking on
Desktop\AmoePy, orB02\AmoePy_Windows, orB02\amoepy.bat.<b> In order to create all article plots, the folder b02-data must be saved in the same parent directory as B02. </b>
All plots are generated by the following python script run_plos_figures.py.
Therefore, go to B02/src and use
$ python -m run.run_plos_figures
or
$ python3 -m run.run_plos_figures
All plots will be saved in B02/src/plots.
For this script, it is necessary to install ffmpeg in /usr/local/bin in order to generate videos of example cell tracks. Alternatively, customized ffmpeg paths can be chosen in the graphical user interface of AmoePy.
Otherwise, the cell track will be saved as a collection of *.png files only.
The kymograph data is already saved in several subdirectories in b02-data/experiment_data_maike.
However, the kymograph files can be generated by the python script run_create_kymographs.py.
Therefore, go to B02/src and use
$ python -m run.run_create_kymographs
or
$ python3 -m run.run_create_kymographs
The kymograph data is already saved in several subdirectories in b02-data/test_cases.
However, the test case data can be generated by the python script run_test_cases.py.
Therefore, go to B02/src and use
$ python -m run.run_test_cases
or
$ python3 -m run.run_test_cases