### Example Configuration Snippet

Source: https://github.com/junhongmit/fraudgt/blob/main/README.md

An example of how to configure dataset paths and output directories in the project's configuration file.

```yaml
......
out_dir: ./results
dataset:
  dir: ./data
......
```

--------------------------------

### Install Project Requirements

Source: https://github.com/junhongmit/fraudgt/blob/main/README.md

Install all other necessary Python packages listed in the requirements.txt file.

```bash
pip install -r requirements.txt
```

--------------------------------

### Make and Run Experiment Script

Source: https://github.com/junhongmit/fraudgt/blob/main/README.md

Make the experiment script executable and then run it to start the fraud detection experiment. Ensure you are in the 'FraudGT' directory.

```bash
cd FraudGT
chmox +x ./run/interactive_run.sh
./run/interactive_run.sh
```

--------------------------------

### Install PyTorch and PyG

Source: https://github.com/junhongmit/fraudgt/blob/main/README.md

Install PyTorch with CUDA support and the PyTorch Geometric (PyG) library using conda. Ensure you have a compatible NVIDIA driver and CUDA toolkit installed.

```bash
conda install pytorch torchvision torchaudio pytorch-cuda=11.8 -c pytorch -c nvidia
conda install pyg -c pyg
```

--------------------------------

### Initialize Custom Logger

Source: https://context7.com/junhongmit/fraudgt/llms.txt

Sets up a logger instance for tracking metrics and GPU memory usage.

```python
from fraudGT.logger import create_logger, CustomLogger
from fraudGT.graphgym.config import cfg
```

--------------------------------

### Run Training with FraudGT Main Entry Point

Source: https://context7.com/junhongmit/fraudgt/llms.txt

Use the main entry point to run the complete training pipeline programmatically or from the command line. Handles configuration, data loading, model creation, and training loops.

```python
python -m fraudGT.main --cfg configs/AML-Small-HI/AML-Small-HI-SparseNodeGT.yaml --repeat 3
```

```python
import fraudGT
from fraudGT.main import run

# The run() function handles the complete training pipeline:
# 1. Parses command line arguments
# 2. Loads configuration from YAML
# 3. Creates data loaders, model, optimizer, and scheduler
# 4. Runs training with checkpointing
# 5. Aggregates results across multiple seeds
run()
```

--------------------------------

### Create Optimizers and Schedulers

Source: https://context7.com/junhongmit/fraudgt/llms.txt

Initializes optimization and scheduling components using configuration dataclasses. Requires model parameters to be passed to the optimizer factory.

```python
from fraudGT.graphgym.optimizer import create_optimizer, create_scheduler
from fraudGT.graphgym.optimizer import OptimizerConfig, SchedulerConfig

# Create optimizer configuration
opt_cfg = OptimizerConfig(
    optimizer='adam',  # Options: 'adam', 'sgd', 'adamW'
    base_lr=0.001,
    weight_decay=1e-5,
    momentum=0.9  # For SGD only
)

# Create optimizer
optimizer = create_optimizer(model.named_parameters(), opt_cfg)

# Create scheduler configuration
sched_cfg = SchedulerConfig(
    scheduler='cos',  # Options: 'cos', 'step', 'none', 'cosine_with_warmup', 'reduce_on_plateau'
    max_epoch=500,
    steps=[30, 60, 90],  # For step scheduler
    lr_decay=0.1  # For step scheduler
)

# Create scheduler
scheduler = create_scheduler(optimizer, sched_cfg)
```

--------------------------------

### Training Execution

Source: https://context7.com/junhongmit/fraudgt/llms.txt

The main entry point for executing the training pipeline, including configuration loading and multi-seed training.

```APIDOC
## Python run()

### Description
Executes the complete training pipeline for FraudGT models, including dataset preparation, model initialization, and training loops.

### Method
Function Call

### Parameters
- **cfg** (object) - Required - Configuration object loaded from YAML.
- **repeat** (int) - Optional - Number of random seeds to repeat the training process.

### Request Example
```python
from fraudGT.main import run
run() # Uses command line args or global cfg
```
```

--------------------------------

### Configure and Initialize GTModel

Source: https://context7.com/junhongmit/fraudgt/llms.txt

Sets up the Graph Transformer model architecture and hyperparameters using the configuration object. Requires a pre-defined dataset and batch input.

```python
from fraudGT.network.gt_model import GTModel, FeatureEncoder
from fraudGT.graphgym.config import cfg

# Configure the complete model
cfg.model.type = "GTModel"
cfg.gt.layer_type = "SparseNodeTransformer"
cfg.gt.layers = 2
cfg.gt.layers_pre_gt = 0  # Pre-transformer layers
cfg.gt.layers_post_gt = 2  # Post-transformer layers (prediction head)
cfg.gt.dim_hidden = 64
cfg.gt.attn_heads = 8
cfg.gt.input_dropout = 0.0
cfg.gt.dropout = 0.2
cfg.gt.attn_dropout = 0.3
cfg.gt.batch_norm = False
cfg.gt.layer_norm = True
cfg.gt.l2_norm = False
cfg.gt.act = "gelu"
cfg.gt.attn_mask = "Edge"  # Options: "Edge", "kHop", "Bias", None
cfg.gt.residual = "Fixed"  # Options: "Fixed", "Learn", "Concat", "none"
cfg.gt.ffn = "Type"  # Feed-forward: "Single", "Type", "none"
cfg.gt.jumping_knowledge = False
cfg.gt.virtual_nodes = 0  # Number of virtual/global nodes

# Create and use model
model = GTModel(dim_in=cfg.share.dim_in, dim_out=cfg.share.dim_out, dataset=dataset)

# Forward pass returns (predictions, ground_truth)
pred, true = model(batch)
```

--------------------------------

### Execute Training Loop

Source: https://context7.com/junhongmit/fraudgt/llms.txt

Manages the training process including epoch iteration, evaluation, and checkpointing. Supports both full training execution and manual epoch-by-epoch control.

```python
from fraudGT.graphgym.train import train, train_epoch, eval_epoch
from fraudGT.graphgym.config import cfg

# Configure training
cfg.optim.max_epoch = 500
cfg.optim.optimizer = "adamW"
cfg.optim.base_lr = 0.001
cfg.optim.weight_decay = 1e-5
cfg.optim.scheduler = "cosine_with_warmup"
cfg.optim.num_warmup_epochs = 5
cfg.train.eval_period = 4  # Evaluate every 4 epochs
cfg.train.ckpt_period = 100  # Save checkpoint every 100 epochs
cfg.train.auto_resume = True  # Resume from latest checkpoint

# Run full training
train(loggers, loaders, model, optimizer, scheduler)

# Or run individual epochs
for epoch in range(cfg.optim.max_epoch):
    train_epoch(loggers[0], loaders[0], model, optimizer, scheduler)
    loggers[0].write_epoch(epoch)

    # Evaluation
    if epoch % cfg.train.eval_period == 0:
        eval_epoch(loggers[1], loaders[1], model, split='val')
        loggers[1].write_epoch(epoch)
        eval_epoch(loggers[2], loaders[2], model, split='test')
        loggers[2].write_epoch(epoch)
```

--------------------------------

### Run Experiments with Shell Script

Source: https://context7.com/junhongmit/fraudgt/llms.txt

Bash script for running experiments with different configurations and datasets. It defines a function to run experiments with specified datasets and configuration overrides.

```bash
#!/bin/bash
# run/interactive_run.sh

function run_repeats {
    dataset=$1
    cfg_suffix=$2
    cfg_overrides=$3

    cfg_file="configs/${dataset}/${dataset}-${cfg_suffix}.yaml"

    if [[ ! -f "$cfg_file" ]]; then
        echo "WARNING: Config does not exist: $cfg_file"
        return 1
    fi

    main="python -m fraudGT.main --cfg ${cfg_file}"
    out_dir="./results/${dataset}"
    common_params="out_dir ${out_dir} ${cfg_overrides}"

    # Run with single seed
    script="${main} --repeat 1 ${common_params}"
    eval $script
}

# Run experiments
DATASET="AML-Small-HI"
run_repeats ${DATASET} SparseNodeGT "name_tag SparseNodeGT"
run_repeats ${DATASET} GINE "name_tag GINE"

DATASET="AML-Large-HI"
run_repeats ${DATASET} SparseNodeGT "name_tag SparseNodeGT"

# Override configuration from command line
run_repeats ${DATASET} SparseNodeGT "name_tag custom gt.layers 4 optim.base_lr 0.0005"
```

--------------------------------

### Create and Activate Conda Environment

Source: https://github.com/junhongmit/fraudgt/blob/main/README.md

Use these commands to create a new conda environment named 'fraudGT' with Python 3.9 and then activate it.

```bash
conda create -n fraudGT python=3.9 -y
conda activate fraudGT
```

--------------------------------

### Create Data Loaders with create_loader

Source: https://context7.com/junhongmit/fraudgt/llms.txt

Generates PyTorch data loaders for training, validation, and testing. Supports various sampling strategies for large-scale graphs. Configure samplers and batch sizes via `cfg.train`.

```python
from fraudGT.graphgym.loader import create_loader, create_dataset
from fraudGT.graphgym.config import cfg

# Create dataset and loaders
dataset = create_dataset()
loaders = create_loader(dataset=dataset, shuffle=True, returnDataset=False)

# loaders[0] = training loader
# loaders[1] = validation loader
# loaders[2] = test loader

# Or get both loaders and dataset
loaders, dataset = create_loader(returnDataset=True)

# Supported samplers (set via cfg.train.sampler):
# - "full_batch": Load entire graph
# - "neighbor": NeighborSampler with configurable sizes
# - "random_node": RandomNodeSampler
# - "saint_rw": GraphSAINT random walk sampler
# - "saint_node": GraphSAINT node sampler
# - "saint_edge": GraphSAINT edge sampler
# - "cluster": ClusterLoader for graph partitioning

# Example configuration for neighbor sampling
cfg.train.sampler = "neighbor"
cfg.train.neighbor_sizes = [50, 50]  # Sample 50 neighbors per layer
cfg.train.batch_size = 2048
```

--------------------------------

### YAML Configuration for AML-Small-HI Dataset

Source: https://context7.com/junhongmit/fraudgt/llms.txt

Complete configuration file for training FraudGT on AML datasets. This includes settings for logging, dataset, training, model, graph transformer, and optimizer.

```yaml
# configs/AML-Small-HI/AML-Small-HI-SparseNodeGT.yaml
out_dir: ./results
metric_best: f1
seed: 42

# Weights & Biases logging
wandb:
  use: True
  project: fraudGT

# Dataset configuration
dataset:
  dir: ./data
  format: AML
  name: Small-HI
  task: hetero_edge  # Edge classification for fraud detection
  task_type: classification
  task_entity: ('node', 'to', 'node')
  transductive: True
  node_encoder: True
  node_encoder_name: Hetero_Raw
  node_encoder_bn: False
  edge_encoder: True
  edge_encoder_name: Hetero_Raw
  edge_encoder_bn: False

# Training configuration
train:
  mode: custom
  sampler: link_neighbor
  neighbor_sizes: [50, 50]
  iter_per_epoch: 256
  batch_size: 2048
  eval_period: 4
  ckpt_period: 100
  tqdm: True

# Model configuration
model:
  type: GTModel
  loss_fun: weighted_cross_entropy
  loss_fun_weight: [1, 6]  # Handle class imbalance

# Graph Transformer configuration
gt:
  layer_type: SparseNodeTransformer
  layers: 2
  layers_pre_gt: 0
  layers_post_gt: 2
  attn_heads: 8
  dim_hidden: 64
  input_dropout: 0.0
  dropout: 0.2
  attn_dropout: 0.3
  batch_norm: False
  layer_norm: True
  act: gelu
  attn_mask: Edge
  residual: Fixed
  ffn: Type

# Optimizer configuration
optim:
  optimizer: adamW
  base_lr: 0.001
  weight_decay: 1e-5
  max_epoch: 500
  scheduler: cosine_with_warmup
  num_warmup_epochs: 5
  batch_accumulation: 8
  clip_grad_norm: True
```

--------------------------------

### Data Loader Creation

Source: https://context7.com/junhongmit/fraudgt/llms.txt

Factory functions for creating PyTorch data loaders with support for various graph sampling strategies.

```APIDOC
## Python create_loader()

### Description
Creates training, validation, and test data loaders for graph datasets.

### Method
Function Call

### Parameters
- **dataset** (object) - Required - The PyG dataset object.
- **shuffle** (bool) - Optional - Whether to shuffle the data.
- **returnDataset** (bool) - Optional - Whether to return the dataset alongside loaders.

### Response
- **loaders** (list) - List containing [train_loader, val_loader, test_loader].
- **dataset** (object) - The dataset object if returnDataset is True.
```

--------------------------------

### Build Models with create_model

Source: https://context7.com/junhongmit/fraudgt/llms.txt

Factory function to create Graph Transformer models based on configuration. Automatically infers dimensions and moves the model to the correct device. Specify model type, attention mechanisms, and dimensions.

```python
from fraudGT.graphgym.model_builder import create_model
from fraudGT.graphgym.config import cfg

# Configure model type
cfg.model.type = "GTModel"  # Graph Transformer model
cfg.gt.layer_type = "SparseNodeTransformer"  # Attention mechanism
cfg.gt.layers = 2  # Number of transformer layers
cfg.gt.dim_hidden = 64  # Hidden dimension
cfg.gt.attn_heads = 8  # Number of attention heads

# Create model (dimensions inferred from dataset)
model = create_model(to_device=True, dataset=dataset)

# Or specify dimensions explicitly
model = create_model(
    to_device=True,
    dim_in=128,
    dim_out=2,  # Binary classification
    dataset=dataset
)

# Print model architecture and parameter count
print(model)
from fraudGT.graphgym.utils.comp_budget import params_count
print(f"Number of parameters: {params_count(model)}")
```

--------------------------------

### Model Builder

Source: https://context7.com/junhongmit/fraudgt/llms.txt

Factory function for instantiating Graph Transformer models based on configuration parameters.

```APIDOC
## Python create_model()

### Description
Instantiates a Graph Transformer model, automatically inferring dimensions from the provided dataset.

### Method
Function Call

### Parameters
- **to_device** (bool) - Optional - Move model to GPU if available.
- **dataset** (object) - Optional - Dataset used to infer input/output dimensions.
- **dim_in** (int) - Optional - Explicit input dimension.
- **dim_out** (int) - Optional - Explicit output dimension.

### Response
- **model** (torch.nn.Module) - The initialized Graph Transformer model.
```

--------------------------------

### Fine-tune Pretrained FraudGT Models

Source: https://context7.com/junhongmit/fraudgt/llms.txt

Loads and fine-tunes pretrained FraudGT models. Configure the pretrained model path, freezing of encoder weights, and resetting of prediction heads.

```python
from fraudGT.finetuning import (
    load_pretrained_model_cfg,
    init_model_from_pretrained,
    get_final_pretrained_ckpt
)
from fraudGT.graphgym.config import cfg

# Configure pretrained model path
cfg.pretrained.dir = "/path/to/pretrained/model"
cfg.pretrained.freeze_main = False  # If True, only train prediction head
cfg.pretrained.reset_prediction_head = True  # Reset head for new task

# Load pretrained configuration (updates cfg with pretrained model's config)
cfg = load_pretrained_model_cfg(cfg)

# Create fresh model
model = create_model(dataset=dataset)

# Initialize from pretrained weights
model = init_model_from_pretrained(
    model,
    pretrained_dir=cfg.pretrained.dir,
    freeze_main=cfg.pretrained.freeze_main,
    reset_prediction_head=cfg.pretrained.reset_prediction_head,
    seed=cfg.seed
)

# Continue training on new task
train(loggers, loaders, model, optimizer, scheduler)
```

--------------------------------

### Define Custom Temporal Dataset

Source: https://context7.com/junhongmit/fraudgt/llms.txt

Extend TemporalDataset for time-based data splitting. Ensure raw data files and processed splits are correctly defined.

```python
from fraudGT.datasets.temporal_dataset import TemporalDataset
from torch_geometric.data import HeteroData

class AMLDataset(TemporalDataset):
    def __init__(self, root, name="Small-HI"):
        self.name = name
        super().__init__(root=root)

    @property
    def raw_file_names(self):
        return [f"{self.name}.csv"]

    @property
    def processed_file_names(self):
        return ['train.pt', 'val.pt', 'test.pt']

    def process(self):
        # Load and process transaction data
        # Split by time periods
        self.data_dict['train'] = train_data  # HeteroData
        self.data_dict['val'] = val_data
        self.data_dict['test'] = test_data

        # Save processed data
        torch.save(self.data_dict['train'], self.processed_paths[0])
        torch.save(self.data_dict['val'], self.processed_paths[1])
        torch.save(self.data_dict['test'], self.processed_paths[2])
```

--------------------------------

### Usage of AMLDataset

Source: https://context7.com/junhongmit/fraudgt/llms.txt

Instantiate the custom dataset and access train, validation, and test splits. Retrieve dataset properties like feature and class counts.

```python
# Usage
dataset = AMLDataset(root="./data", name="Small-HI")
train_data = dataset['train']  # or dataset[0]
val_data = dataset['val']      # or dataset[1]
test_data = dataset['test']    # or dataset[2]

# Properties
print(f"Num node features: {dataset.num_node_features}")
print(f"Num edge features: {dataset.num_edge_features}")
print(f"Num classes: {dataset.num_classes}")
```

--------------------------------

### Compute Loss Functions

Source: https://context7.com/junhongmit/fraudgt/llms.txt

Calculates loss using registered functions like cross-entropy or MSE. Supports weighted loss for handling class imbalance.

```python
from fraudGT.graphgym.loss import compute_loss
from fraudGT.graphgym.config import cfg

# Configure loss function
cfg.model.loss_fun = "cross_entropy"  # Options: "cross_entropy", "mse", "weighted_cross_entropy"
cfg.model.size_average = "mean"  # Options: "mean", "sum"

# For weighted cross-entropy (class imbalance)
cfg.model.loss_fun = "weighted_cross_entropy"
cfg.model.loss_fun_weight = [1, 6]  # Weight for [negative, positive] class

# Compute loss during training
pred, true = model(batch)
loss, pred_score = compute_loss(pred, true)

# pred_score contains normalized predictions:
# - Sigmoid output for binary classification
# - Softmax output for multiclass
# - Raw predictions for regression

loss.backward()
```

--------------------------------

### Update Training Statistics

Source: https://context7.com/junhongmit/fraudgt/llms.txt

Updates training statistics during the training loop. Ensure loggers are created and the model is updated with predictions and true values.

```python
cfg.metric_best = "f1"  # Metric for model selection: "f1", "accuracy", "auc", "precision", "recall"

# Create loggers (train, val, test)
loggers = create_logger()

# Update statistics during training
for batch in loader:
    pred, true = model(batch)
    loss, pred_score = compute_loss(pred, true)

    loggers[0].update_stats(
        true=true.detach().cpu(),
        pred=pred_score.detach().cpu(),
        loss=loss.item(),
        lr=scheduler.get_last_lr()[0],
        time_used=elapsed_time,
        params=cfg.params
    )

# Write epoch summary
loggers[0].write_epoch(epoch)
```

--------------------------------

### GTLayer - Core Graph Transformer Layer

Source: https://context7.com/junhongmit/fraudgt/llms.txt

The primary transformer layer for graph structures, implementing sparse attention. Supports edge-aware attention, multi-hop masks, and normalization options. Requires metadata defining node and edge types.

```python
from fraudGT.layer.gt_layer import GTLayer
import torch

# Layer configuration
metadata = (
    ['node'],  # Node types
    [('node', 'edge', 'node')]  # Edge types
)

layer = GTLayer(
    dim_in=64,
    dim_h=64,
    dim_out=64,
    metadata=metadata,
    local_gnn_type='None',  # Local GNN type
    global_model_type='SparseNodeTransformer',  # Attention type
    index=0,  # Layer index
    num_heads=8,
    layer_norm=True,
    batch_norm=False,
    return_attention=False
)

# Forward pass with PyG batch
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.