Update model artifacts and explanations

README.md

@@ -1,3 +1,131 @@
----
-license: mit
----
+---
+license: mit
+language: en
+library_name: pytorch
+tags:
+- pytorch
+- tabular-classification
+- pokemon
+- finance
+- scikit-learn
+- shap
+---
+
+# Pokémon TCG Price Predictor
+
+This repository contains a PyTorch model trained to predict whether a Pokémon TCG card's price will rise by at least 30% within the next 6 months.
+
+This model is the backend for the **[PokePrice Gradio Demo](https://huggingface.co/spaces/OffWorldTensor/PokePrice)**. 
+
+## Model Description
+
+The model is a simple Multi-Layer Perceptron (MLP) implemented in PyTorch. It takes various features of a Pokémon card as input—such as its rarity, type, and historical price data—and outputs a single logit. A sigmoid function can be applied to this logit to get a probability score for the price rising.
+
+- **Model type:** Tabular Binary Classification
+- **Architecture:** `PricePredictor` (MLP)
+- **Framework:** PyTorch
+- **Training Data:** A custom dataset derived from the PokemonTCG/pokemon-tcg-data repository, augmented with pricing history.
+
+## How to Use
+
+To use this model, you will need `torch`, `scikit-learn`, `pandas`, and `huggingface_hub`. You can download the model artifacts directly from the Hub.
+
+First, ensure you have `network.py` (which defines the model class) in your working directory.
+
+```python
+import torch
+import joblib
+import json
+import pandas as pd
+from huggingface_hub import hf_hub_download
+from safetensors.torch import load_file
+
+# Make sure you have network.py in the same directory
+from network import PricePredictor
+
+REPO_ID = "your-username/pokemon-price-predictor"
+MODEL_FILENAME = "model.safetensors"
+CONFIG_FILENAME = "config.json"
+SCALER_FILENAME = "scaler.pkl"
+
+print("Downloading model files from the Hub...")
+model_path = hf_hub_download(repo_id=REPO_ID, filename=MODEL_FILENAME)
+config_path = hf_hub_download(repo_id=REPO_ID, filename=CONFIG_FILENAME)
+scaler_path = hf_hub_download(repo_id=REPO_ID, filename=SCALER_FILENAME)
+print("Downloads complete.")
+
+with open(config_path, "r") as f:
+    config = json.load(f)
+
+feature_columns = config["feature_columns"]
+input_size = config["input_size"]
+
+model = PricePredictor(input_size=input_size)
+model.load_state_dict(load_file(model_path))
+model.eval()
+
+scaler = joblib.load(scaler_path)
+
+data_to_predict = {
+    'rawPrice': [10.0], 'gradedPriceTen': [100.0], 'gradedPriceNine': [50.0],
+}
+
+input_df = pd.DataFrame(data_to_predict)
+missing_cols = set(feature_columns) - set(input_df.columns)
+for c in missing_cols:
+    input_df[c] = 0.0 
+input_df = input_df[feature_columns]
+
+
+input_scaled = scaler.transform(input_df.values)
+input_tensor = torch.tensor(input_scaled, dtype=torch.float32)
+
+with torch.no_grad():
+    logits = model(input_tensor)
+    probability = torch.sigmoid(logits).item()
+
+print(f"\nPrediction for the input card:")
+print(f"  - Probability of 30% price rise in 6 months: {probability:.4f}")
+
+if probability > 0.5:
+    print("  - Prediction: Price WILL LIKELY rise.")
+else:
+    print("  - Prediction: Price WILL LIKELY NOT rise.")
+```
+
+## Model Performance
+
+The model was evaluated on a 20% held-out test set.
+
+- **Accuracy:** 0.9515
+- **Precision:** 0.9323
+- **Recall:** 0.8986
+- **F1-Score:** 0.9151
+
+## Model Explainability
+
+To understand the model's decisions, SHAP (SHapley Additive exPlanations) values were computed.
+
+### Global Feature Importance
+
+This plot shows the average impact of each feature on the model's output magnitude. Features at the top are most influential.
+
+![Global Feature Importance](explanation_outputs/summary_plot.png)
+
+### Local Explanation for a Single Card
+
+A static waterfall plot provides a clear view of features pushing the prediction for a single card.
+
+![Local Waterfall Plot](explanation_outputs/force_plot.html)
+
+An interactive force plot is also available. You can view it by downloading `force_plot.html` from this repository and opening it in your browser.
+
+## Limitations and Bias
+
+- The model is trained on historical data and may not predict future trends accurately, especially in a volatile market.
+- The definition of "price rise" is fixed at 30% over 6 months. The model is not trained for other thresholds or timeframes.
+- The dataset may have inherent biases related to card popularity, set releases, or data collection artifacts.
+
+## Author
+
+Callum Anderson

config.json

@@ -0,0 +1,70 @@
+{
+  "input_size": 64,
+  "model_class": "PricePredictor",
+  "feature_columns": [
+    "rawPrice",
+    "gradedPriceTen",
+    "gradedPriceNine",
+    "first_raw",
+    "price_ratio_to_first",
+    "log_raw",
+    "log_g10",
+    "log_g9",
+    "price_vs_rolling_avg",
+    "rawPrice_missing",
+    "gradedPriceTen_missing",
+    "gradedPriceNine_missing",
+    "rarity_ACE SPEC Rare",
+    "rarity_Amazing Rare",
+    "rarity_Black White Rare",
+    "rarity_Classic Collection",
+    "rarity_Code Card",
+    "rarity_Common",
+    "rarity_Double Rare",
+    "rarity_Holo Rare",
+    "rarity_Hyper Rare",
+    "rarity_Illustration Rare",
+    "rarity_Prism Rare",
+    "rarity_Promo",
+    "rarity_Radiant Rare",
+    "rarity_Rare",
+    "rarity_Rare Ace",
+    "rarity_Rare BREAK",
+    "rarity_Secret Rare",
+    "rarity_Shiny Holo Rare",
+    "rarity_Shiny Rare",
+    "rarity_Shiny Ultra Rare",
+    "rarity_Special Illustration Rare",
+    "rarity_Ultra Rare",
+    "rarity_Uncommon",
+    "energyType_Colorless",
+    "energyType_Darkness",
+    "energyType_Dragon",
+    "energyType_Energy",
+    "energyType_Fairy",
+    "energyType_Fighting",
+    "energyType_Fire",
+    "energyType_Grass",
+    "energyType_Lightning",
+    "energyType_Metal",
+    "energyType_Psychic",
+    "energyType_Water",
+    "energyType_nan",
+    "cardType_Energy",
+    "cardType_Item",
+    "cardType_Pokemon",
+    "cardType_Stadium",
+    "cardType_Supporter",
+    "cardType_Tool",
+    "cardType_Trainer",
+    "cardType_nan",
+    "variant_1st Edition",
+    "variant_1st Edition Holofoil",
+    "variant_Holofoil",
+    "variant_Normal",
+    "variant_Reverse Holofoil",
+    "variant_Unlimited",
+    "variant_Unlimited Holofoil",
+    "variant_nan"
+  ]
+}

model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:38b217807a8bf227beba2a74448010f2234742071f415f52ea9429915d37cd54
+size 199132

network.py

@@ -0,0 +1,23 @@
+import torch
+import torch.nn as nn
+
+"""
+    Neural Network Classifier Architecture
+"""
+
+class PricePredictor(nn.Module):
+
+    def __init__(self, input_size: int):
+        super(PricePredictor, self).__init__()
+        self.model = nn.Sequential(
+            nn.Linear(input_size, 256),
+            nn.ReLU(),
+            nn.Dropout(0.4),
+            nn.Linear(256, 128),
+            nn.ReLU(),
+            nn.Dropout(0.4),
+            nn.Linear(128, 1),
+        )
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        return self.model(x)

scaler.pkl

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:57bae1c7e9c16028c4f21def0302ba1514e7a3d8be131937702da75007ccd866
+size 2151