Merge pull request #81 from UnravelSports/bug/format

Bug/format

Author: UnravelSports

docs/requirements.txt

@@ -3,3 +3,4 @@ sphinx>=8.0.0,<9.0.0
 sphinx-rtd-theme>=3.0.0
 myst-parser>=2.0.0
 sphinx-autosummary-accessors>=2023.4.0
+sphinxcontrib-youtube

docs/source/api/classifiers.rst

@@ -41,13 +41,7 @@ PyTorch Geometric
    from torch_geometric.loader import DataLoader
 
    # Initialize model
-   model = PyGLightningCrystalGraphClassifier(
-       node_features=12,
-       edge_features=6,
-       global_features=0,
-       output_features=1,
-       learning_rate=0.001,
-   )
+   model = PyGLightningCrystalGraphClassifier()
 
    # Train
    trainer = pyl.Trainer(max_epochs=50)
@@ -56,29 +50,38 @@ PyTorch Geometric
    # Test
    trainer.test(model, test_loader)
 
-   # Predict
-   predictions = trainer.predict(model, pred_loader)
-
 Spektral
 ~~~~~~~~
 
 .. code-block:: python
 
    from unravel.classifiers import CrystalGraphClassifier
 
-   # Initialize model
-   model = CrystalGraphClassifier(
-       node_features=12,
-       edge_features=6,
-       output_features=1,
-   )
+   from tensorflow.keras.metrics import AUC, BinaryAccuracy
+   from tensorflow.keras.losses import BinaryCrossentropy
+   from tensorflow.keras.optimizers import Adam
+   from tensorflow.keras.callbacks import EarlyStopping
+
+   model = CrystalGraphClassifier()
 
-   # Compile
    model.compile(
-       optimizer='adam',
-       loss='binary_crossentropy',
-       metrics=['accuracy']
+      loss=BinaryCrossentropy(), optimizer=Adam(), metrics=[AUC(), BinaryAccuracy()]
    )
 
-   # Train
-   model.fit(x=train_data, y=train_labels, epochs=50, validation_data=(val_data, val_labels))
+   model.fit(
+      loader_tr.load(),
+      steps_per_epoch=loader_tr.steps_per_epoch,
+      epochs=5,
+      use_multiprocessing=True,
+      validation_data=loader_va.load(),
+      callbacks=[EarlyStopping(monitor="loss", patience=5, restore_best_weights=True)],
+   )
+
+   from tensorflow.keras.models import load_model
+
+   model_path = "models/my-first-graph-classifier"
+   model.save(model_path)
+   loaded_model = load_model(model_path)
+
+   loader_te = DisjointLoader(test, epochs=1, shuffle=False, batch_size=batch_size)
+   results = model.evaluate(loader_te.load())

docs/source/conf.py

@@ -27,6 +27,7 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.mathjax",
     "myst_parser",
+    "sphinxcontrib.youtube",
 ]
 
 # Napoleon settings for Google/NumPy style docstrings

docs/source/getting_started/concepts.rst

@@ -135,14 +135,11 @@ Labels
 For supervised learning, you need labels for each graph:
 
 .. code-block:: python
-
-   from unravel.utils import add_dummy_label_column
-
    # Add random binary labels (for demonstration)
-   dataset.dataset = add_dummy_label_column(dataset.dataset)
+   dataset.add_dummy_labels()
 
    # Or join real labels from your own data
-   # dataset.dataset = dataset.dataset.join(your_labels, on="some_key")
+   dataset.dataset = dataset.dataset.join(your_labels, on="some_key")
 
 Graph IDs
 ~~~~~~~~~
@@ -153,13 +150,10 @@ Graph IDs group frames that belong to the same "sample":
 
    from unravel.utils import add_graph_id_column
 
-   # Each frame is a separate graph
-   dataset.dataset = add_graph_id_column(dataset.dataset, by=["frame_id"])
-
-   # Or group by possession
-   dataset.dataset = add_graph_id_column(dataset.dataset, by=["possession_id"])
+   # Each frame (graph) from the same game belongs to a subset
+   dataset.add_graph_ids(by=["game_id"])
 
-**Important**: Always split data by graph_id to avoid data leakage!
+**Important**: Always split data by game_id to avoid data leakage!
 
 Soccer Analytics Models
 -----------------------

docs/source/getting_started/quickstart.rst

@@ -57,9 +57,10 @@ Convert the tracking data to graph structures for training Graph Neural Networks
    from unravel.utils import add_dummy_label_column, add_graph_id_column
 
    # Add labels and graph IDs
-   polars_dataset.dataset = add_dummy_label_column(polars_dataset.dataset)
-   polars_dataset.dataset = add_graph_id_column(
-       polars_dataset.dataset,
+   polars_dataset.add_dummy_labels()
+   # We group by 'frame_id' instead of 'game_id' here because in this example all
+   # data comes from the same game.
+   polars_dataset.add_graph_id_column(
        by=["frame_id"]
    )
 
@@ -97,11 +98,7 @@ Split the data and train a model:
    test_loader = DataLoader(test, batch_size=32)
 
    # Initialize model
-   model = PyGLightningCrystalGraphClassifier(
-       node_features=converter.n_node_features,
-       edge_features=converter.n_edge_features,
-       global_features=converter.n_graph_features,
-   )
+   model = PyGLightningCrystalGraphClassifier()
 
    # Train
    trainer = pyl.Trainer(max_epochs=10)

docs/source/index.rst

@@ -23,6 +23,8 @@ The **unravelsports** package aims to aid researchers, analysts and enthusiasts
 intermediary steps in the complex process of converting raw sports data into meaningful
 information and actionable insights.
 
+.. youtube:: PUXU3SokbW0
+
 Installation
 ------------
 

docs/source/tutorials/american_football.rst

@@ -1,4 +1,4 @@
-American Football (NFL)
+American Football
 =======================
 
 This tutorial covers how to work with NFL tracking data from the Big Data Bowl using the
@@ -93,16 +93,10 @@ For supervised learning, add labels and graph IDs:
 
 .. code-block:: python
 
-   from unravel.utils import add_dummy_label_column, add_graph_id_column
-
-   # Add labels (use your own labels for real tasks)
-   bdb_dataset.dataset = add_dummy_label_column(bdb_dataset.dataset)
+   bdb_dataset.add_dummy_labels()
 
    # Create graph ID for each play
-   bdb_dataset.dataset = add_graph_id_column(
-       bdb_dataset.dataset,
-       by=["gameId", "playId"]
-   )
+   bdb_dataset.add_graph_ids(by=["playId", "gameId"])
 
 Step 3: Convert to Graphs
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -146,11 +140,7 @@ Train a Graph Neural Network:
    test_loader = DataLoader(test, batch_size=32)
 
    # Initialize and train model
-   model = PyGLightningCrystalGraphClassifier(
-       node_features=converter.n_node_features,
-       edge_features=converter.n_edge_features,
-       global_features=converter.n_graph_features,
-   )
+   model = PyGLightningCrystalGraphClassifier()
 
    trainer = pyl.Trainer(max_epochs=10)
    trainer.fit(model, train_loader, val_loader)