Metadata-Version: 2.4
Name: seagan
Version: 0.1.4
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. 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`.

![SEAGAN GAT architecture](GAT_architecture.png)

## Install

Install the published package from PyPI:

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

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

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

```python
from seagan import load_pretrained_seagan

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

Run inference on one graph:

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

```python
from seagan import (
    SEAGAN,
    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:

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

Upload to PyPI:

```bash
python -m twine upload dist/*
```
