seagan 0.1.0

SEAGAN: an edge-aware graph attention network for node classification on A-Ci curve graphs.

SEAGAN

SEAGAN is an edge-aware Graph Attention Network (GAT) for node classification on A-Ci curve graphs. The packaged model uses two GAT layers with edge attributes and a weighted focal-loss training objective. For the bundled SEAGAN checkpoint, the focal lambda/gamma is 0.0.

Model Overview

SEAGAN represents each curve as a graph:

• Node features: Ci, Anet, computed Ac, and computed Aj
• Edge index: k-nearest-neighbor graph in the [Ci, Anet] space
• Edge features: pairwise differences [dAc, dAj]
• GAT layer 1: input dimension 4, output dimension 64, 5 attention heads, dropout 0.2
• GAT layer 2: input dimension 320, output dimension 64, 5 attention heads, dropout 0.2
• MLP head: maps 64 hidden features to 3 node classes

The package includes the saved checkpoint:

EdgeGAT_checkpoint_G0_0_model_17.pt

Installation

For local development:

pip install -e .

For building the distribution:

python -m pip install -U build twine
python -m build
twine check dist/*

To upload after verifying the package:

twine upload dist/*

It is usually safest to test on TestPyPI first:

twine upload --repository testpypi dist/*

Quick Start

from seagan import build_graphs_from_df, load_pretrained_seagan, standardize_graphs_from_checkpoint

# df_points needs curve_id, Ci, Anet, and ID columns.
# df_params needs curve_id and Tleaf columns.
graphs, class_map = build_graphs_from_df(df_points, df_params)

model, checkpoint = load_pretrained_seagan()
graphs = standardize_graphs_from_checkpoint(graphs, checkpoint)

Run inference on a single graph:

from seagan import predict_graph

predicted_classes = predict_graph(model, graphs[0])
print(predicted_classes)

By default, predictions are returned as zero-indexed class ids (0, 1, 2). Add one_indexed=True to return labels as 1, 2, 3.

Expected Data Format

df_points should contain one row per point in a curve:

column	meaning
curve_id	curve identifier
Ci	intercellular CO2 concentration
Anet	net assimilation
ID	node class label, commonly 1, 2, or 3

df_params should contain one row per curve:

column	meaning
curve_id	curve identifier
Tleaf	leaf temperature in Celsius

If curve_id is already the DataFrame index, the helper functions will use it directly.

Python API

from seagan import (
    EdgeGAT,
    compute_edge_Ac_Aj,
    edge_index_knn_from_ci_anet,
    make_edge_attr_from_edges,
    build_graphs_single,
    build_graphs_from_df,
    focal_loss_multiclass,
    load_pretrained_seagan,
    predict_graph,
)

Repository Contents

• src/seagan/: importable Python package
• src/seagan/assets/: bundled SEAGAN checkpoint
• GNN_FC_GAT_Focal.ipynb: original training and testing notebook
• Fig5b_GAT_architecture.png: architecture overview
• EdgeGAT_checkpoint_G0_0_model_17.pt: original saved checkpoint

Notes Before Public PyPI Release

• Confirm the final PyPI package name is available. If seagan is taken, change project.name in pyproject.toml.
• Add the final license before public release if this will be open source.
• Add your email and project links in pyproject.toml if you want them displayed on PyPI.