This repository helps auto-generate a Jupyter notebook GUI for PhysiCell-related models and output. The directory structure and content of the repository matches a template required for a nanoHUB tool installation. However, creating an actual nanoHUB tool is optional; the GUI created here should also work (with fewer bells & whistles, perhaps) on your personal computer, assuming you have the required Python modules and are able to run a Jupyter notebook server.
It also contains a directory of example GUIs that have been generated using this process. See
So, after cloning this repo, you should be able to at least run an example notebook and see the GUI, even though
you won't be able to 'Run' a simulation since that would require compiling the code (the PhysiCell model)
and copying certain files to appropriate locations, as described below. To run an example notebook:
#---- clone this repo, then from a shell window: $ cd Example_GUIs/pc4biorobots $ jupyter notebook pc4biorobots.ipynb
- We highly recommend installing the Anaconda Python 3.x distribution. This will contain Python and various 3rd party modules needed to create the PhysiCell Jupyter notebook (PhysiCell GUI). It will also contain the Jupyter notebook server to test the GUI.
- You need to be able to run Anaconda's 'python' from the command line. You can 1) edit your PATH system variable, 2) provide the full path command, or 3) create an alias.
- If you are not on Windows, it may be possible to install a Python module (hublib) that will provide customized widgets for the GUI. (The make_my_tool.py script will attempt to install this on OSX or Linux, not Windows)
- You have PhysiCell installed, have an example model compiled, and have successfully run it. The script below assumes you have:
Makefile, main.cpp, config/PhysiCell_settings.xml, and output/initial.xmlfiles in your PhysiCell directory. (If you do not, certain aspects of this automated process will fail and you'll need to manually create and/or copy files)
- the directory where you cloned your "project repo" (next section) is essentially empty (it might contain a README.md)
Steps to follow
- Create a new, public repository on github.com (not the IU github) and clone it to your computer. This will be your "project repo". Call it whatever you want (it doesn't have to match the name of your eventual nanoHUB tool). If you create a README.md, make a backup copy in case it gets overwritten in the steps below. For the example steps below, we choose the name "ise_proj1".
- Clone this tool4nanobio repo to your computer.
- In a command line shell window (terminal or command prompt), from the tool4nanobio directory, run the Python script called
setup_new_proj.py. If successful, this will copy (nearly) all necessary files into your new project repo (step 1). You provide three required arguments (and two optional) to the script:
<full-path-to-new-project> <full-path-to-PhysiCell-project> <tool name> [<makefile name> <main cpp>]
The default names of the optional arguments will simply be "Makefile" and "main.cpp".
Variations of running the script might be - from a Unix-like shell:
~/git/tool4nanobio$ python setup_new_proj.py /Users/heiland/git/ise_proj1 /Users/heiland/dev/PhysiCell_heterogeneity iu399sp19p099 ~/git/tool4nanobio$ python setup_new_proj.py ~/git/ise_proj1 ~/dev/PhysiCell_heterogeneity iu399sp19p099 ~/git/tool4nanobio$ python setup_new_proj.py ~/git/ise_proj1 ~/dev/PhysiCell_heterogeneity iu399sp19p099 Make_hetero main_hetero.cpp [Windows Git Bash] MINGW64 ~/git/tool4nanobio (master) $ python setup_new_proj.py /c/Users/heiland/git/ise_proj1 /c/Users/heiland/dev/PhysiCell_heterogeneity iu399sp19p099 $ python setup_new_proj.py ~/git/ise_proj1 ~/dev/PhysiCell_heterogeneity iu399sp19p099
from a Windows Command Prompt or PowerShell:
C:\Users\heiland\git\tool4nanobio>python setup_new_proj.py C:\Users\heiland\git\ise_proj1 C:\Users\heiland\dev\PhysiCell_heterogeneity iu399sp19p099
- Build your PhysiCell project in your /src directory and copy the resulting
myprojexecutable to ../bin:
(bash commands) ~/git/ise_proj1$ cd src ~/git/ise_proj1/src$ make ... ~/git/ise_proj1/src$ cp myproj ../bin # will be "myproj.exe" on Windows ~/git/ise_proj1$ cd ..
- Try to display the new Jupyter notebook:
~/git/ise_proj1$ jupyter notebook ise_proj1.ipynb
Select ‘Cell’ → ‘Run All’ menu item to display the notebook (or, if necessary, select the 'Kernel' → ‘Restart & Run All’ menu item).
Click the ‘Run’ button in the GUI to see if it works. Output files should appear in the
- If it's successful, commit everything to the GitHub repo for your new project.
- Perform steps to create your nanoHUB tool (optional) - see section below.
Create a nanoHUB tool (optional)
- If you do not have a nanoHUB account, register for one at https://nanohub.org/register/
- Students need to be aware that creating an account on nanoHUB is similar to creating an account on any social media platform. Use your good judgment about publicly sharing personal information. For more background, see https://ferpa.iu.edu/safeguarding/index.html
- On https://nanohub.org/tools/create, fill out the basic information for creating your nanoHUB tool. Tool Name should be 3-15 alphanumeric characters, including at least one non numeric character (e.g.,
iu399sp19p099). Although not required, it’s probably wise to also use only lowercase characters. Provide the URL to your newly created GitHub repo (e.g.,
https://github.com/...) and also select the bullet to
Publish as a Jupyter notebook. When you finally click the
Register Toolbutton, you will be told if that tool name has already been taken, however, it may take a few seconds for that to appear. Also, don't worry if you forget to provide some info on this initial form, you can always edit it later.
Before you request to have your tool installed on nanoHUB, you need to make sure the
invoke file in the
middleware subdirectory is executable:
If you are using Windows, this file seems to lose its "executable" permission when you commit it. You will need to
cd into the
middleware folder of your newly created project and, using
git from the command line:
$ git update-index --chmod=+x invoke $ git commit -m "Changing file permissions" $ git push
then view/refresh the
invoke file from your browser and verify "Executable File" appears in the upper-left as in the screenshot above.
- From the status page of your new tool on nanoHUB (e.g., https://nanohub.org/tools/iu399sp19p099/status), click the link to have it installed for testing (below the "We are waiting for You"). (You must be logged in to nanoHUB). Wait "1-3 days" for that to happen (typically, it's usually within minutes or hours). You'll receive an email from nanoHUB when the tool is installed.
- After your tool in installed and you have tested it and feel like it’s ready to publish, click the link on your tool’s status page that you approve it (for publishing). But as the above screenshot says, you will first need to create a description of your tool. You will eventually be asked to provide the license for your tool and check a box to verify the license is indeed correct. You'll receive an automated email from nanoHUB saying the tool status changed from "Created to Uploaded". The nanoHUB sys admin will then need to compile your code and deploy it there. You will receive another email when the tool is ready to test on nanoHUB.
Details of the above scripts (if you care)
In more detail, the
setup_new_proj.py script should:
Copy the contents of the tool4nanobio repo to your newly created repo (but NOT the hidden
Copy the relevant files from your PhysiCell model into the new repo's /src directory. Basically, you need to get all of your PhysiCell code (and directory structure) into /src so that when you type
makethere, it will build your project. For example, one would typically do:
* copy all /core/ files into the /src/core/ directory * copy all /BioFVM/ files into the /src/BioFVM/ directory * copy all /modules/ files into the /src/modules/ directory * copy all /custom_modules/ files into the /src/custom_modules/ directory * copy your main.cpp into /src * copy your Makefile into src/Makefile and
The src/Makefile needs to be edited so that:
PROGRAM_NAME := myproj
and in the
all target, comment out copying the executable to ../bin:
all: main.cpp $(ALL_OBJECTS) $(COMPILE_COMMAND) -o $(PROGRAM_NAME) $(ALL_OBJECTS) main.cpp # cp $(PROGRAM_NAME) ../bin
also, be sure it has the following targets present (with the necessary leading tabs):
install: all cp $(PROGRAM_NAME) ../bin distclean: clean rm -f ../bin/$(PROGRAM_NAME)
and this target should not have the trailing "*":
clean: rm -f *.o # rm -f $(PROGRAM_NAME)* rm -f $(PROGRAM_NAME)
Build using the Makefile (run
make) - it should build a ‘myproj’ executable.
copy ‘myproj’ to /bin in your repo.
copy your .xml configuration file into data/PhysiCell_settings.xml (overwrite the one there)
edit data/PhysiCell_settings.xml so that:
From the root dir of your repo:
- run “python make_my_tool.py ”, e.g., “python make_my_tool.py ise_proj1"
This script will do a number of things:
- rename two files: the name of the notebook (
.ipynb, in the root directory) and the primary Python module (in /bin).
- run the xml2jupyter.py script on data/PhysiCell_settings.xml and copy the resulting user_params.py and microenv_params.py into the /bin directory.
- attempt to install the “hublib” Python module that provides the fancy “Run” button widget (with Output and Cancel features).
Copy the “initial.xml”, from the output you generated when you ran your project in its original location, into this repo's /data directory.