English | 简体中文

eGPS4Py

eGPS4Py is a standalone Python wrapper for the eGPS desktop software. It bridges Python to the eGPS Java runtime via JPype, allowing users to launch the eGPS desktop, open visualisation views, and call tree utility functions directly from Python scripts or notebooks.

Its primary runtime model is the installed Windows eGPS package, including the bundled dependency-egps jars and bundled jre. It can still resolve the source-tree layout for development, but normal users should point it at the installed eGPS folder.

The current wrapper exposes three main capabilities:

• launch the eGPS desktop
• open Modern Tree View
• open Pathway Family Browser

It also provides a tree utility bridge for extracting node names through the Java API.

Requirements

• Python >= 3.10
• A working eGPS installation, for example C:/path/to/eGPS_v2.1_windows_x64_selfTest
• The eGPS installation must contain:
  • dependency-egps/
  • eGPS2.args
  • jre/bin/server/jvm.dll
• Python packages:
  • jpype1
  • pandas
  • openpyxl

Install eGPS4Py Locally

From this repository:

cd Py4eGPS
python -m pip install -e .

That editable install path was verified in the current workspace.

Runtime Model

eGPS4Py accepts any of these as repo_root:

• the installed eGPS root, such as C:/path/to/eGPS_v2.1_windows_x64_selfTest
• the installed dependency-egps directory inside that root
• the source-tree root, for development only

When the runtime points to an installed eGPS package:

• the wrapper reads JVM options from eGPS2.args
• the wrapper builds the classpath from dependency-egps/*.jar
• the wrapper uses the bundled jre/bin/server/jvm.dll by default

When the runtime points to the source tree:

• the wrapper reads JVM options from egps-shell/eGPS.args
• the wrapper uses the two compiled out/production/... directories plus both dependency-egps directories

First-Time Configuration

The recommended explicit setup is:

from eGPS4Py import configure_runtime

configure_runtime(
    repo_root="C:/path/to/eGPS_v2.1_windows_x64_selfTest",
)

You can also pass the installed dependency directory directly:

configure_runtime(
    repo_root="C:/path/to/eGPS_v2.1_windows_x64_selfTest/dependency-egps",
)

If jvm_path is omitted for an installed package, eGPS4Py uses:

<install-root>/jre/bin/server/jvm.dll

If nothing has been configured yet and a JVM-backed call is made in an interactive session, eGPS4Py will ask the user to choose the eGPS installation folder and persist the result in:

~/.eGPS4Py/runtime_config.json

If you want to force the package to prompt again, delete that file.

For non-interactive scripts, do not rely on the prompt. Call configure_runtime(...) explicitly before the first GUI or bridge call.

Public API

The main public entry points are:

from eGPS4Py import (
    configure_runtime,
    launch_desktop,
    open_modern_tree_view,
    open_modern_tree_view_from_config,
    open_pathway_family_browser,
    open_pathway_family_browser_from_config,
)

The tree bridge stays available at:

from eGPS4Py.phylo import evoltree

Quick Start

from eGPS4Py import configure_runtime, launch_desktop

configure_runtime(
    repo_root="C:/path/to/eGPS_v2.1_windows_x64_selfTest",
)

hello = launch_desktop()
print(str(hello))

On a healthy runtime this returns a welcome string similar to:

Hello this is eGPS desktop, version: Version: 2.1.97

Modern Tree View

open_modern_tree_view(...) supports two tree inputs:

• tree_path: path to an existing Newick file
• newick_text: raw Newick text

Exactly one of them must be provided.

Other supported parameters:

• layout
• leaf_label
• title
• reverse_axis
• blank_space
• node_visual_config_path

Example with in-memory Newick text:

from eGPS4Py import configure_runtime, open_modern_tree_view

configure_runtime(
    repo_root="C:/path/to/eGPS_v2.1_windows_x64_selfTest",
)

open_modern_tree_view(
    newick_text="(Human:6.5,Chimp:6.5,Gorilla:8.9);",
    layout="CIRCULAR",
    leaf_label=True,
    title="Great apes",
    reverse_axis=False,
    blank_space=(20, 40, 80, 40),
)

The wrapper will materialize a temporary .nwk file automatically when newick_text is used.

If you already have a prepared VOICE config file, use:

open_modern_tree_view_from_config("C:/path/to/modern_tree.voice")

Pathway Family Browser

open_pathway_family_browser(...) supports:

• tree_path or newick_text
• component_counts
• species_info
• species_traits
• gallery_paths
• layout
• leaf_label
• title
• reverse_axis
• blank_space
• node_visual_config_path

Input rules:

• component_counts, species_info, and species_traits can be either file paths or pandas.DataFrame
• DataFrame inputs must contain a Name column
• gallery_paths must be real file paths
• if a table argument is None, the generated VOICE config writes False for that field

Example:

import pandas as pd

from eGPS4Py import configure_runtime, open_pathway_family_browser

configure_runtime(
    repo_root="C:/path/to/eGPS_v2.1_windows_x64_selfTest",
)

component_counts = pd.DataFrame({
    "Name": ["Human", "Chimp"],
    "WNT3A": [2, 1],
})

species_info = pd.DataFrame({
    "Name": ["Human", "Chimp"],
    "Clade": ["Hominini", "Hominini"],
})

species_traits = pd.DataFrame({
    "Name": ["Human", "Chimp"],
    "Habitat": ["Mixed", "Forest"],
})

open_pathway_family_browser(
    tree_path="C:/path/to/species_tree.nwk",
    component_counts=component_counts,
    species_info=species_info,
    species_traits=species_traits,
    gallery_paths=[
        "C:/path/to/wnt_pathway.pptx",
    ],
    layout="RECTANGULAR",
    leaf_label=True,
    title="WNT pathway family",
)

If you already have a prepared VOICE config file, use:

open_pathway_family_browser_from_config("C:/path/to/pathway_browser.voice")

Tree Utility Bridge

The current tree utility call is:

from eGPS4Py.phylo import evoltree

names = evoltree.get_node_names(
    "C:/path/to/species_tree.nwk",
    target_htu=None,
    get_otu=True,
    get_htu=False,
)

This now calls the current Java bridge method:

api.rpython.API4R.extractNodeNames(...)

Important Runtime Notes

• The GUI runs inside the current Python process. If the script exits immediately, the GUI may disappear immediately as well.
• For quick smoke tests, keep the process alive for a few seconds after opening a window.
• open_modern_tree_view(...) and open_pathway_family_browser(...) do not return rich Python objects. Their purpose is to trigger the Java GUI.
• launch_desktop() returns the Java welcome string, which can be wrapped with str(...) before printing.

Example smoke pattern:

import time

from eGPS4Py import configure_runtime, launch_desktop

configure_runtime(
    repo_root="C:/path/to/eGPS_v2.1_windows_x64_selfTest",
)

print(str(launch_desktop()))
time.sleep(8)

Troubleshooting

No GUI appears

• Make sure repo_root points to the installed eGPS root or its dependency-egps directory
• Make sure the installed package contains eGPS2.args, dependency-egps, and jre/bin/server/jvm.dll
• Keep the Python process alive for a few seconds after opening the GUI

The package asks for a path unexpectedly

• That means no persisted runtime is available and no explicit repo_root was provided
• In automated scripts, always call configure_runtime(...) first

DataFrame input fails for Pathway Family Browser

• Check that every DataFrame contains a Name column
• Check that gallery_paths points to real files rather than in-memory objects

You want to reconfigure the eGPS installation path

• Delete ~/.eGPS4Py/runtime_config.json
• Or call configure_runtime(...) again with a different repo_root

Verification

Unit tests:

cd Py4eGPS
python -m unittest tests.test_runtime_and_gui

The local editable install was also verified with:

python -m pip install -e .