Metadata-Version: 2.4
Name: seagan
Version: 0.1.0
Summary: SEAGAN: an edge-aware graph attention network for node classification on A-Ci curve graphs.
Author: Antriksh Srivastava
Project-URL: Repository, https://github.com/GitHub-srivastava/SEAGAN-PyPI
Keywords: graph-neural-network,graph-attention-network,pytorch,torch-geometric,focal-loss
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.23
Requires-Dist: pandas>=1.5
Requires-Dist: scikit-learn>=1.2
Requires-Dist: torch>=2.0
Requires-Dist: torch-geometric>=2.3
Requires-Dist: openpyxl>=3.1
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"

# 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`.

![SEAGAN GAT architecture](Fig5b_GAT_architecture.png)

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

```text
EdgeGAT_checkpoint_G0_0_model_17.pt
```

## Installation

For local development:

```bash
pip install -e .
```

For building the distribution:

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

To upload after verifying the package:

```bash
twine upload dist/*
```

It is usually safest to test on TestPyPI first:

```bash
twine upload --repository testpypi dist/*
```

## Quick Start

```python
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:

```python
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

```python
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.
