Advanced

The Py-GraSPI package also included scripts with advanced functionality mostly for developers.

To Run on DEBUG mode

To run graph.py on debug mode so that all debug statements are printed to the terminal, set the DEBUG environment to 1 (True)

If on Windows Powershell,

run $env:DEBUG=1

If on Windows Command Prompt

run set DEBUG=1

If on MacOS/Linux

run export DEBUG=1

After setting the compilation mode to DEBUG mode, you can now run graph.py regularly through command line, which should print out debug statements to the terminal.

Converting .plt files to .txt files

Numerical simulations can be saved using .plt file. Py-GraSPI provides tool to convert the plt file into txt file - following array format, see syntax and the example below (assuming in the tools/converters directory):

python plt_to_txt.py [pathname]

Example:

python plt_to_txt.py plt/5x4x3.plt

Translate Image File Into Rescaled .txt File

Py-GraSPI provide also tool to convert black and white image into txt file and rescale it with assumed ratio (provided as fraction, e.g., 0.5). See syntax and the example (assuming in the tools/converters directory):

python img_to_txt.py {pathname of image file} {Resize calculation amount}

Example:

python img_to_txt.py ../../data/2phase/2D-morphologies/data/images/data_0.5_2.2_001900.png 0.15

Example Visualization

This section explains how to visualize a microscopy image by filtering both it’s white and black vertices. The tool converts from image to graph.

python img_to_graph.py {pathname of image file} {Resize calculation amount}

Example:

python img_to_graph.py ../../data/2phase/2D-morphologies/images/data_0.5_2.2_001900.png 0.15

This creates a truncated version of the mycelium image (for runtime purposes) and outputs the largest subgraph of the following filtered graphs:

The first one is a white only vertex graph
The second one is a black only vertex graph.

You can interact with the plots to find the appropriate visualization.

2D & 3D Morphologies Tests

To run the 2d and 3d morphologies you will need to setup notebook and pip install the graspi_igraph package.

First you will need to git clone the current repo, and install packages:

git clone https://github.com/owodolab/py-graspi.git
pip install py-graspi
pip install notebook

Finally, you will be able to use the command:

jupyter notebook

This will bring you to the testing files on jupyter.

Navigate to the file graspi_igraph_notebook.ipynb under the notebook directory.

Running Py-GraSPI on the Library of Morphologies

Change folder to py-graspi/tests, generate the executable for the script, and run the code

cd tests
chmod +x run.sh
./run.sh <file_type>

Substitute <file_type> with either txt or pdf for the desired output type.

Example:

./run.sh txt

After running the command, the automatic report generation will begin. The following will print when the report generation begins:

Generating PDF (If on pdf mode)
Generating Text Files

Tortuosity HeatMap Visualization

In folder tools, you find scripts to visualize tortuosity:

python tortuosity.py {pathname of file}

Example:

python tortuosity.py ../../data/2phase/2D-morphologies/data/data_0.5_2.2_001900.txt

Jupyter NoteBook to Visualize HeatMap

Make sure Jupyter Notebook is installed:

pip install jupyter

Run jupyter notebook with following command:

jupyter notebook

Open up tortuosity.ipynb under the tools/tortuosity directory.

Generate API Documentation

In order to generate an API using sphinx, you need to follow the installation of py-graspi.

Install Sphinx and all required packages to generate documentation in the project root directory:

pip install sphinx sphinx_rtd_theme setuptools sphinxcontrib.details.directive

Install ghp-import to host documentation in the project root directory:

pip install ghp-import

To pull docstrings from Py-Graspi modules, run the following command:

(Note: docs/source/ is the location of the .rst files, and src/py_graspi is the location of the project modules where sphinx will pull docstrings from.)

sphinx-apidoc -o docs/source/ src/py_graspi

To generate the local html files using the rst files, run this command:

sphinx-build -b html docs/source docs/build

Ensure that the files have been generated in docs/build.

To push the changes reflected on the html to the gh-pages branch on GitHub, essentially pushing changes to the site, run this command:

ghp-import -n -p -f docs/build/

Go to the GitHub repo and verify that the files were pushed to the gh-pages branch

Access and verify the documentation through the following URL: https://owodolab.github.io/py-graspi/.

Update Py-Pi Package

If there are changes made to the to the PyGraspi package locally, these instructions can help push to Py-Pi.

To install setuptools, wheel and twine, run this command in terminal:

pip install setuptools wheel twine

Ensure that the project already contains setup.py, README.md, _init_.py, LICENSE and other core files.

Note: Make sure you update the version number in the setup.py file.

Build the distribution files, which creates a dist/ directory containing the .tar.gz and .whl files.

First, CD into project root directory (where setup.py exists). Then, run this command in terminal:

python setup.py sdist bdist_wheel

(Optional) It’s safe to delete the .tar.gz and .whl file of old versions so that the correct version gets pushed to PyPI

Login to PyPI, and retrieve your API token to upload the package using twine.

Note: You need to be a manager or owner of the package on PyPI to upload new versions.

Use twine to upload the distribution securely by running this command in terminal:

twine upload dist/*

When prompted for your API token, retrieve the API token that you can generate from PyPI.

Note: The token will not be visible on the terminal for security reasons, so press enter after entering the token.

Verify that the new version has been uploaded successfully at the link https://pypi.org/project/py-graspi/