seagan 0.1.1

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. It represents each curve as a graph, uses edge features in the attention layers, and supports weighted focal loss. For the sample SEAGAN model, the focal lambda/gamma is 0.0.

Install

Install the published package from PyPI:

pip install seagan

For local development from this repository, use editable mode:

pip install -e .

Editable mode is only for working on the source code locally. Normal users should use pip install seagan.

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: hidden representation from the first layer, output dimension 64, 5 attention heads, dropout 0.2
• MLP head: maps 64 hidden features to 3 node classes

Quick Start

Build graphs from your data:

from seagan import build_graphs_from_df

# 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)

Load the sample checkpoint included with the package:

from seagan import load_pretrained_seagan, standardize_graphs_from_checkpoint

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

Or load your own checkpoint:

from seagan import load_pretrained_seagan

model, checkpoint = load_pretrained_seagan("path/to/your_checkpoint.pt")

Run inference on one graph:

from seagan import predict_graph

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

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, SEAGAN will use it directly.

API

Common imports:

from seagan import (
    EdgeGAT,
    build_graphs_from_df,
    build_graphs_single,
    compute_edge_Ac_Aj,
    focal_loss_multiclass,
    load_checkpoint,
    load_pretrained_seagan,
    predict_graph,
    standardize_graphs_from_checkpoint,
)

Build and Publish

For maintainers:

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

Upload to PyPI:

python -m twine upload dist/*