StructuralGT

A software tool that allows graph theory analysis of nanostructures. This is a modified version of StructuralGT initially proposed by Drew A. Vecchio, DOI: 10.1021/acsnano.1c04711.

Installation

1. Install as software

• Download link: https://github.com/owuordickson/structural-gt/releases/tag/v3.6.8
• Install and enjoy.
• 5 minute YouTube tutorial: https://www.youtube.com/watch?v=bEXaIKnse3g
• We would love to hear from you, please give us feedback.

2. Install via pip

• Install Python version 3.14 on your computer.
• Execute the following commands:

pip install sgtlib

3. Install via source code

Therefore, please follow the manual installation instructions provided below:

• Install Python version 3.14 on your computer.
• Git Clone this repo: https://github.com/owuordickson/structural-gt.git
• Extract the source code folder named 'structural-gt' and save it to your preferred location on your PC.
• Open a terminal application such as CMD.
• Navigate to the location where you saved the 'structural-gt' folder using the terminal.
• Execute the following commands:

cd structural-gt
pip install --upgrade pip
pip install -r requirements.txt
pip install .

3. Usage

3(a) Executing GUI App

To run the GUI version, please follow these steps:

• Open a terminal application such as CMD.
• Execute the following command:

StructuralGT

3(b) Executing Terminal App

Before executing StructuralGT-cli, you need to specify these parameters:

• image file path or image directory/folder: [required and mutually exclusive] you can set the file path using -f path-to-image or set the directory path using -d path-to-folder. If the directory path is set, StructuralGT will compute the GT metrics of all the images simultaneously,
• configuration file path: [required] you can set the path to config the file using -c path-to-config. To make it easy, find the file sgt_configs.ini (in the ''root folder'') and modify it to capture your GT parameters,
• type of GT task: [required] you can either 'extract graph' using -t 1 or compute GT metrics using -t 2,
• output directory: [optional] you can set the folder where the GT results will be stored using -o path-to-folder,
• allow auto-scaling : [optional] allows StructuralGT to automatically scale images to an optimal size for computation. You can disable this using -s 0.

Please follow these steps to execute:

• Open a terminal application such as CMD.
• Execute the following command:

StructuralGT-cli -d datasets/ -c datasets/sgt_configs.ini -o results/ -t 2

OR

StructuralGT-cli -f datasets/InVitroBioFilm.png -c datasets/sgt_configs.ini -t 2

OR

StructuralGT-cli -f datasets/InVitroBioFilm.png -c datasets/sgt_configs.ini -t 1

3(c) Using Library API

To use StructuralGT library:

• Make sure you install via pip
• Create a Python script or Jupyter Notebook and import modules as shown:

import matplotlib.pyplot as plt
from sgtlib import modules as sgt

# set paths
img_path = "path/to/image"
cfg_file = "path/to/sgt_configs.ini"  # Optional: leave blank


# Define a function for receiving progress updates
def print_updates(progress_val, progress_msg):
    print(f"{progress_val}: {progress_msg}")


# Create a Network object
ntwk_obj, _ = sgt.ImageProcessor.from_image_file(img_path, config_file=cfg_file)

# Apply image filters according to cfg_file
ntwk_obj.add_listener(print_updates)
ntwk_obj.apply_img_filters()
ntwk_obj.remove_listener(print_updates)

# View images
sel_img_batch = ntwk_obj.selected_batch
bin_images = [obj.img_bin for obj in sel_img_batch.images]
grayscale_images = [obj.img_grayscale for obj in sel_img_batch.images]
plt.imshow(bin_images[0])
plt.axis('off')  # Optional: Turn off axis ticks and labels for a cleaner image display
plt.title('Binary Image')
plt.show()

plt.imshow(grayscale_images[0])
plt.axis('off')  # Optional: Turn off axis ticks and labels for a cleaner image display
plt.title('Grayscale Image')
plt.show()

# Extract graph
ntwk_obj.add_listener(print_updates)
ntwk_obj.build_graph_network()
ntwk_obj.remove_listener(print_updates)

# View graph
net_images = [ntwk_obj.graph_obj.img_ntwk]
plt.imshow(net_images[0])
plt.axis('off')  # Optional: Turn off axis ticks and labels for a cleaner image display
plt.title('Graph Image')
plt.show()

# Compute graph theory metrics
compute_obj = sgt.GraphAnalyzer(ntwk_obj)
sgt.GraphAnalyzer.safe_run_analyzer(compute_obj, print_updates)
print(compute_obj.output_df)

# Save in PDF
sgt.GraphAnalyzer.write_to_pdf(compute_obj)

3(d) Generating Synthetic Networks

The synthesis button, second from the left on the ribbon, opens NetworkSynth, which builds synthetic networks modelled on an extracted graph. It runs as its own program, so you choose the settings and the output folder in its window.

Extract a graph first and the button hands it straight over: the network travels down a pipe to NetworkSynth and the image is passed by path, so nothing is exported, saved or picked by hand. It opens with both already in place and drawn together, reading the network in the coordinate space StructuralGT traced it in, which is a scaled copy of the image rather than the file itself. The graph in view is the one that travels, so it is one network per click.

Point it at other inputs there and change your mind, and a button in its Input card puts the extracted network back. Open it with no graph extracted and it starts empty, ready for whatever inputs you choose there.

NetworkSynth is a separate program, and this application finds it either as an installed package or as a checkout.

Install the package. Nothing to configure afterwards, and it works the same on every platform:

pip install "networksynth @ https://github.com/WilliamLuminary/NetworkSynth/archive/refs/heads/dist.zip"

That URL is always the newest release. Install it into the environment StructuralGT runs in, and the button finds it on the import path. Swap dist for dist-dev to take the newest pre-release instead, which is for developers. Every release also carries a built wheel if you would rather not build one.

Or take the submodule, which is what a source checkout of this repository is set up for:

git submodule sync networksynth
git submodule update --init --checkout networksynth
git -C networksynth fetch origin dist --depth 1
git -C networksynth checkout -B dist FETCH_HEAD

--checkout is needed because the submodule is set to update = none, so a plain --init skips it. Run git submodule sync again any time .gitmodules changes, or the old URL stays cached in your clone.

To update a submodule, or to move between releases and pre-releases:

BRANCH=dist    # dist-dev for pre-releases, developers only
git -C networksynth fetch origin $BRANCH --depth 1
git -C networksynth checkout -B $BRANCH FETCH_HEAD

Those two commands are the whole of it: run them with dist to take the newest release, with dist-dev to try a pre-release, and with dist again to come back.

If NetworkSynth fails, the last lines of its output appear in the SGT Logs window.

The checkout runs in StructuralGT's own environment, so that environment has to cover NetworkSynth's dependencies as well. Most are shared already; install the rest from the checkout's pyproject.toml, currently pot and psutil:

pip install "pot~=0.9.7" "psutil~=7.2.2"

You can also point the button at a different folder or a different Python under [synthesis-settings] in sgt_configs.ini.

Contributors ✨

Thanks go to these incredible people:

Made with contrib.rocks.