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 B02 of the Collaborative Research Center SFB 1294.
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.
Therefore, both directories must be saved in the same parent directory!
AmoePy is provided with an HTML documentation (generated with Sphinx) which can be found in the following path:
B02/build/html/index.html
This project uses conda to manage its dependencies. Therefore, we recommend to install the newest Anaconda distribution from this link.
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 condaFor 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 srcTo install all dependencies and activate the conda environment, within B02/src use
$ conda env create -n AmoePy -f environment.yml
$ conda activate AmoePyIn case, the conda encironment is not created or any dependency problems or mulfunctions, see here.
For additional commands to remove or to update the above conda environment, see here.
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 further below, see here.
We exported another conda environment file named backup.yml, in which version numbers of each python package are listed.
These version numbers were saved before the last upload date of AmoePy.
In case of dependency problems or any malfunctions, you may consider to install the dependencies by the following commands:
$ cd B02/src
$ conda env create -n AmoePy -f backup.yml
$ conda activate AmoePyIf you already have an AmoePy conda environment, you can add the dependencies by running
$ conda env update -n AmoePy -f environment.yml
$ conda activate AmoePyTo see a list of all environments, use
$ conda env listTo delete the AmoePy environment, use
$ conda activate base
$ conda env remove -n AmoePyAdditional conda environment commands can be found here.
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.shwhich 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.shB02/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
- the desktop icon Desktop\AmoePy, or
- the shortcut B02\AmoePy_Windows, or
- the file B02\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 AmoePy,
go to B02/src and use one of the following commands:
$ conda activate AmoePy
$ python3 -m run.run_amoepy
# alternatively: python -m run.run_amoepyor
$ conda activate AmoePy
$ python3 -m amoepy.gui.amoepygui
# alternatively: python -m amoepy.gui.amoepyguiIf 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.shOpen AmoePy by double-clicking on
- the desktop icon Desktop\AmoePy, or
- the shortcut B02\AmoePy_Windows, or
- the file B02\amoepy.bat.
In order to create all article plots, the folder b02-data must be saved in the same parent directory as B02.
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_figuresor
$ python3 -m run.run_plos_figuresAll 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_kymographsor
$ python3 -m run.run_create_kymographsThe 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_casesor
$ python3 -m run.run_test_cases In order to create all article plots, the folder b02-data must be saved in the same parent directory as B02.
All plots are generated by the following python script run_2022_model_article.py.
Therefore, go to B02/src and use
$ python -m run.run_2022_model_article.pyor
$ python3 -m run.run_2022_model_article.pyAll plots will be saved in B02/src/plots_2022_motility_model.
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 of all simulated cell track is already saved in several subdirectories in b02-data/experiment_data_maike.
However, the same cell tracks can be generated by the python scripts run_oup_data.py and run_hawkes_data.py.
Therefore, go to B02/src and use
$ python -m run.run_oup_data
$ python -m run.run_hawkes_dataor
$ python3 -m run.run_oup_data
$ python3 -m run.run_hawkes_dataCopyright (c) 2020-present AmoePy
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.