UFCData 0.5.0__tar.gz → 0.7.0__tar.gz

{ufcdata-0.5.0 → ufcdata-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: UFCData
-Version: 0.5.0
+Version: 0.7.0
 Summary: Obtain UFC data and functions to manipulate it
 Requires-Python: >=3.10
 License-File: LICENSE.md
@@ -9,4 +9,5 @@ Requires-Dist: pandas
 Requires-Dist: numpy
 Requires-Dist: glicko2
 Requires-Dist: rapidfuzz
+Requires-Dist: matplotlib
 Dynamic: license-file

{ufcdata-0.5.0 → ufcdata-0.7.0}/README.md

@@ -4,8 +4,6 @@ An open-source Python package for accessing, manipulating, and analyzing UFC dat
 
 https://pypi.org/project/UFCData/
 
-add helper functions like convert odds
-
 ## Table of Contents
 
 - [Installation](#installation)
@@ -23,13 +21,17 @@ Fighter Functions
 - [Fighter Statistic](#fighter-statistic)
 
 Helper Functions
-  - [Odds Convert](#elo)
-  - [Weight Convert](#elo)
-  - [Gender Convert](#elo)
-  - [Mirror](#elo)
+  - [Odds Convert](#odds-convert)
+  - [Weight Convert](#weight-convert)
+  - [Gender Convert](#gender-convert)
+  - [Mirror](#mirror)
 
 Model Evaluation
-- [Odds Baseline Example](#elo)
+- [Train Test Split](#train-test-split)
+- [Get Expanding Window](#get-expanding-window)
+- [Plotting Accuracy](#plotting-accuracy)
+- [Expanding Window Baseline Example](#expanding-window-cv-and-final-test-example)
+
 
 Data Sources
   - [Online Sources](#online-sources)
@@ -56,7 +58,6 @@ data = ufc.get_data()
 
 ## Obtain fighter_bio dataframe
 fighter_bio = data["fighter_bio"].copy()
-
 ```
 
 Note that data in here and other functions below reference data that is available prior to the data.
@@ -101,7 +102,7 @@ This is useful when the exact value stored in the dataset is unknown or when the
 
 ## Elo
 
-UFCData provides an Elo rating system for calculating fighter ratings based on their previous fight results. Ratings are calculated chronologically, with each fighter's rating recorded **immediately before each fight**.
+UFCData provides an Elo rating system for calculating fighter ratings based on their previous fight results. Ratings are calculated chronologically, with each fighter's rating recorded immediately before each fight.
 
 This allows Elo ratings to be used as features for predictive modeling without incorporating information from the fight being predicted.
 
@@ -147,7 +148,7 @@ The resulting `fight_elo` dataframe can then be used to examine or incorporate p
 
 ### Important
 
-`fight_df` should be sorted from **most recent to least recent** before being passed to `get_elo()`. The function reverses the dataframe internally to process fights chronologically and returns the resulting data in the original order.
+`fight_df` should be sorted from most recent to least recent before being passed to `get_elo()`. The function reverses the dataframe internally to process fights chronologically and returns the resulting data in the original order.
 
 ## Fighter History
 
@@ -182,14 +183,12 @@ data = ufc.get_data()
 fighter_bio = data["fighter_bio"].copy()
 fights_df = data["past_fights"].copy()
 
-# Obtain Jon Jones' UFCStats link
 jon_jones = ufc.search(
     fighter_bio,
     "Name",
     "Jon Jones"
 ).iloc[0]["Fighter Link"]
 
-# Get Jon Jones' fight history
 jon_jones_history = ufc.get_fighter_history(
     jon_jones,
     fighter_bio,
@@ -202,7 +201,7 @@ This function is useful for analyzing an individual fighter's career, constructi
 ## Fighter Statistic
 
 
-The function `get_fighter_statistic()`, transforms a fighter's UFC fight history into a time-series dataset where each row represents the fighter's statistics **as they were known before a particular fight**.
+The function `get_fighter_statistic()`, transforms a fighter's UFC fight history into a time-series dataset where each row represents the fighter's statistics as they were known before a particular fight.
 
 This is designed for machine-learning applications where using information from the future would cause data leakage.
 
@@ -266,7 +265,7 @@ This includes:
 
 A DataFrame containing the same types of statistics for each previous UFC fight.
 
-Each row represents the fighter's information **immediately before that fight**.
+Each row represents the fighter's information immediately before that fight.
 
 For example:
 
@@ -292,14 +291,12 @@ fights_df = data["past_fights"].copy()
 rounds_df = data['past_rounds'].copy()
 future_df = data['future_fights']
 
-# Obtain Jon Jones' UFCStats link
 jon_jones = ufc.search(
     fighter_bio,
     "Name",
     "Jon Jones"
 ).iloc[0]["Fighter Link"]
 
-# Get Jon Jones' statistic
 jon_jones_current, jon_jones_past = ufc.get_fighter_statistic(
     jon_jones,
     fighter_bio,
@@ -309,7 +306,294 @@ jon_jones_current, jon_jones_past = ufc.get_fighter_statistic(
 
 jon_jones_current
 ```
+## Odds Convert
+
+The function `convert_odds()` converts American betting odds from strings into integers or floating point numbers.
+
+```python
+convert_odds(odds, probability)
+```
+
+### Parameters
+
+* `odds` — American betting odds as a string.
+
+### Returns
+
+If probability=True, it returns a `float` representing the implied probability of the betting odds.
+
+For positive American odds:
+
+```text
+Probability = 100 / (odds + 100)
+```
+
+For negative American odds:
+
+```text
+Probability = -odds / (-odds + 100)
+```
+If probability=False, takes the string and converts it to an integer.
+
+### Example
+
+```python
+import ufcdata as ufc
+
+data = ufc.get_data()
+
+fights_df = data["past_fights"].copy()
+
+fights_df["Fighter 1 Odds"] = fights_df["Fighter 1 Odds"].apply(ufc.convert_odds)
+fights_df["Fighter 1 Probability"] = fights_df["Fighter 1 Odds"].apply(ufc.convert_odds, probability=True)
+fights_df
+```
+## Gender Convert
+
+The function `convert_gender()` converts gender labels into binary numeric values, with `"Male"` represented as `1` and `"Female"` represented as `0`.
+
+```python
+convert_gender(gender)
+```
+
+### Parameters
+
+* `gender` — Gender label as a string.
+
+### Returns
+
+Returns `1` for `"Male"` and `0` for `"Female"`.
+
+If the gender is missing or does not match either `"Male"` or `"Female"`, it returns `None`.
+
+### Example
+
+```python
+import ufcdata as ufc
+
+data = ufc.get_data()
+
+fights_df = data["past_fights"].copy()
+fights_df["Gender"] = fights_df["Gender"].apply(ufc.convert_gender)
+fights_df
+```
+
+## Weight Convert
+
+The function `convert_weight()` converts UFC weight class labels into their corresponding weight limits in pounds.
+
+```python
+convert_weight(weight)
+```
+
+### Parameters
+
+* `weight` — Weight class as a string.
+
+### Returns
+
+Returns the weight limit in pounds for recognized weight classes.
+
+| Weight Class      | Weight (lb) |
+| ----------------- | ----------: |
+| Strawweight       |         115 |
+| Flyweight         |         125 |
+| Bantamweight      |         135 |
+| Featherweight     |         145 |
+| Lightweight       |         155 |
+| Welterweight      |         170 |
+| Middleweight      |         185 |
+| Light Heavyweight |         205 |
+| Heavyweight       |         265 |
+| Super Heavyweight |         265 |
+
+For `"Catch Weight"` and `"Open Weight"`, as well as unrecognized or missing values, the function returns `NaN`.
+
+### Example
+
+```python
+import ufcdata as ufc
+
+data = ufc.get_data()
+
+past_fights = data["past_fights"].copy()
+past_fights["Weight Class"] = past_fights["Weight Class"].apply(ufc.convert_weight)
+
+past_fights
+```
+
+## Mirror
+
+The function `mirror()` creates mirrored versions of a DataFrame by swapping corresponding pairs of columns. This is useful when analyzing UFC fights from both fighters' perspectives.
+
+```python
+mirror(df, cols_1, cols_2, in_order=True)
+```
+
+### Parameters
+
+* `df` — The DataFrame to mirror.
+* `cols_1` — List of column names representing the first fighter or side.
+* `cols_2` — List of column names representing the second fighter or side. Each column is swapped with the corresponding column in `cols_1`.
+* `in_order` — Determines the order of the returned rows. Defaults to `True`.
+
+If `in_order=True`, each original row is immediately followed by its mirrored row.
+
+If `in_order=False`, all original rows are followed by all mirrored rows.
+
+### Returns
+
+Returns a DataFrame containing both the original and mirrored versions of each row.
+
+### Example
+
+```python
+import ufcdata as ufc
+
+data = ufc.get_data()
+
+fights_df = data["past_fights"].copy()
+fights_df = fights_df[["Date", "Event Link", "Fighter 1", "Fighter 1 Odds","Fighter 2", "Fighter 2 Odds"]]
+
+cols_1 = [
+    "Fighter 1",
+    "Fighter 1 Odds",
+]
+
+cols_2 = [
+    "Fighter 2",
+    "Fighter 2 Odds",
+]
+
+mirrored_fights = ufc.mirror(
+    fights_df,
+    cols_1,
+    cols_2
+)
+
+mirrored_fights
+```
+
+Using `in_order=True` produces rows in the following order:
+
+```text
+Original Fight 1
+Mirrored Fight 1
+Original Fight 2
+Mirrored Fight 2
+...
+```
+Using `in_order=True` produces rows in the following order:
+```text
+Original Fight 1
+Original Fight 2
+Mirrored Fight 1
+Mirrored Fight 2
+...
+```
+
+This is useful when creating fighter-level datasets where each fight should be represented from both fighters' perspectives.
+
+## Train Test Split
+The function `train_test_split()` splits a UFC fight DataFrame into training and test sets while preserving the chronological order of the data. Unlike `sklearn.model_selection.train_test_split()`, this function does not randomly shuffle the data.
+
+The input `fights_df` should be ordered from newest to oldest. The most recent fights are assigned to the test set, while the older fights are assigned to the training set. Both returned DataFrames are then reordered from oldest to newest.
+
+```python
+train_test_split(fights_df, test_size=0.2)
+```
+### Parameters
+
+* `fights_df` — UFC fight DataFrame ordered from newest to oldest.
+* `test_size` — Determines the size of the test set. If less than 1, it is interpreted as a proportion of the total number of fights. If greater than or equal to 1, it is interpreted as the exact number of fights to include in the test set. Defaults to 0.2.
+### Returns
+The function returns two dataFrames. The first is a dataFrame containing the older fights used for training, ordered from oldest to newest. The second is a dataFrame containing the most recent fights used for testing, ordered from oldest to newest.
+
+### Example
+
+```python
+import ufcdata as ufc
+
+data = ufc.get_data()
+
+past_fights = data["past_fights"].copy()
+train, test = ufc.train_test_split(past_fights, 0.2)
+train
+```
+
+## Get Expanding Window
+The function `get_expanding_window()` creates multiple training and test sets for time-series cross-validation using an expanding training window.
+
+The input `fights_df` should be ordered from oldest to newest. With each fold, the training set expands to include more historical fights, while the test set remains a fixed size.
+
+```python
+fold_results = ufc.get_expanding_window(
+    fights_df,
+    folds=5,
+    test_size=500
+)
+```
+### Parameters
+
+* `fights_df` — UFC fight DataFrame ordered from oldest to newest.
+* `folds` — The number of train/test folds to create.
+* `test_size` — The number of fights included in each test set.
+
+### Returns
+The function returns a dictionary containing the training and test DataFrames for each fold.
+```python
+{
+    "Fold 1": {
+        "train": train_dataframe,
+        "test": test_dataframe
+    },
+    "Fold 2": {
+        "train": train_dataframe,
+        "test": test_dataframe
+    },
+    ...
+}
+```
+### Example
+
+```python
+import ufcdata as ufc
+
+data = ufc.get_data()
+
+past_fights = data["past_fights"].copy()
+train, test = ufc.train_test_split(past_fights, 0.2)
+
+folds = ufc.get_expanding_window(train, 10, 500)
+folds['Fold 2']['test']
+```
+
+## Plotting Accuracy
+
+The function `plot_cv` plots out a line graph showing the accuracy of each fold along with a line showing the mean.
+
+```python
+plot_cv(cv_labels, cv_accuracies, title="Cross Validation Accuracy")
+```
+
+### Parameters
+
+* `cv_labels` — The list of fold names.
+* `cv_accuracies` — The list of accuracies.
+* `title` — The title of the plot.
+
+The function `plot_test` plots out a single bar graph showing the accuracy of a single test.
+
+```python
+plot_test(accuracy, title="Test Accuracy")
+```
+
+### Parameters
+
+* `accuracy` — The accuracy.
+* `title` — The title of the plot.
 
+## Expanding Window Baseline Example
 
 ## Online Sources
 

{ufcdata-0.5.0 → ufcdata-0.7.0}/UFCData.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: UFCData
-Version: 0.5.0
+Version: 0.7.0
 Summary: Obtain UFC data and functions to manipulate it
 Requires-Python: >=3.10
 License-File: LICENSE.md
@@ -9,4 +9,5 @@ Requires-Dist: pandas
 Requires-Dist: numpy
 Requires-Dist: glicko2
 Requires-Dist: rapidfuzz
+Requires-Dist: matplotlib
 Dynamic: license-file

{ufcdata-0.5.0 → ufcdata-0.7.0}/UFCData.egg-info/SOURCES.txt

@@ -8,6 +8,7 @@ UFCData.egg-info/requires.txt
 UFCData.egg-info/top_level.txt
 ufcdata/__init__.py
 ufcdata/data.py
+ufcdata/evaluation.py
 ufcdata/fighter.py
 ufcdata/helper.py
 ufcdata/ratings.py

{ufcdata-0.5.0 → ufcdata-0.7.0}/UFCData.egg-info/requires.txt

@@ -3,3 +3,4 @@ pandas
 numpy
 glicko2
 rapidfuzz
+matplotlib

{ufcdata-0.5.0 → ufcdata-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "UFCData"
-version = "0.5.0"
+version = "0.7.0"
 description = "Obtain UFC data and functions to manipulate it"
 requires-python = ">=3.10"
 
@@ -10,4 +10,5 @@ dependencies = [
     "numpy",
     "glicko2",
     "rapidfuzz",
+    "matplotlib",
 ]

{ufcdata-0.5.0 → ufcdata-0.7.0}/ufcdata/__init__.py

@@ -2,4 +2,5 @@ from .data import get_data
 from .search import search
 from .ratings import get_elo
 from .fighter import get_fighter_history, get_fighter_statistic
-from .helper import convert_odds, convert_gender, convert_weight, mirror
+from .helper import convert_odds, convert_gender, convert_weight, mirror
+from .evaluation import train_test_split, get_expanding_window, plot_cv, plot_test

ufcdata-0.7.0/ufcdata/evaluation.py

@@ -0,0 +1,192 @@
+import numpy as np
+import matplotlib.pyplot as plt
+
+def train_test_split(fights_df, test_size=0.2):
+  """
+    Split a UFC fight DataFrame into chronological training and test sets.
+
+    The input DataFrame must be ordered from the newest fight to the oldest
+    fight. The most recent fights are assigned to the test set, while the
+    remaining older fights are assigned to the training set. Both returned
+    DataFrames are reversed so that they are ordered from oldest to newest.
+
+    Parameters
+    ----------
+    fights_df : pandas.DataFrame
+        UFC fight DataFrame ordered from newest to oldest.
+    test_size : float or int, default=0.2
+        Determines the size of the test set. If less than 1, it is interpreted
+        as a proportion of the total number of fights. If greater than or
+        equal to 1, it is interpreted as the exact number of fights to include
+        in the test set.
+
+    Returns
+    -------
+    tuple of pandas.DataFrame
+        A tuple containing:
+
+        - train : pandas.DataFrame
+            Training data consisting of the older fights, ordered from
+            oldest to newest.
+        - test : pandas.DataFrame
+            Test data consisting of the most recent fights, ordered from
+            oldest to newest.
+  """
+  fights_df = fights_df.copy()
+
+  fights_df["Winner"] = np.select(
+    [
+        fights_df["Fighter 1 Outcome"] == "W",
+        fights_df["Fighter 2 Outcome"] == "W"
+    ],
+    [
+        fights_df["Fighter 1 Link"],
+        fights_df["Fighter 2 Link"]
+    ],
+    default=None
+  )
+
+  if test_size < 1:
+    n_test = int(len(fights_df) * test_size)
+  else:
+    n_test = test_size
+
+  test = fights_df[:n_test]
+  train = fights_df[n_test:]
+
+  test = test.iloc[::-1].reset_index(drop=True)
+  train = train.iloc[::-1].reset_index(drop=True)
+
+  return (train, test)
+
+def get_expanding_window(fights_df, folds, test_size):
+    """
+    Create expanding training windows with fixed-size test sets for
+    time-series cross-validation.
+
+    Parameters
+    ----------
+    fights_df : pandas.DataFrame
+        UFC fight DataFrame ordered chronologically from oldest to newest.
+    folds : int
+        Number of train/test folds to create.
+    test_size : int
+        Number of fights included in each test set.
+
+    Returns
+    -------
+    dict
+        Dictionary containing the training and test DataFrames for each fold.
+        Each fold is stored using the key ``"Fold 1"``, ``"Fold 2"``, etc.,
+        with the following structure:
+
+        {
+            "train": train_dataframe,
+            "test": test_dataframe
+        }
+
+    Notes
+    -----
+    The training window expands with each fold while the test window remains
+    fixed at `test_size` rows.
+
+    For example, the folds follow the structure:
+
+        Fold 1: [Train] [Test]
+        Fold 2: [------ Train ------] [Test]
+        Fold 3: [------------ Train ------------] [Test]
+
+    This approach is suitable for time-series cross-validation because each
+    training set only contains observations that occur before its
+    corresponding test set.
+    """
+    fold_results = {}
+
+    train_sizes = np.linspace(
+        test_size,
+        len(fights_df) - test_size,
+        folds,
+        dtype=int
+    )
+
+    for i, train_size in enumerate(train_sizes, start=1):
+        train = fights_df.iloc[:train_size].reset_index(drop=True)
+        test = fights_df.iloc[train_size:train_size + test_size].reset_index(drop=True)
+
+        fold_results[f"Fold {i}"] = {
+            "train": train,
+            "test": test
+        }
+
+    return fold_results
+
+def plot_cv(cv_labels, cv_accuracies, title="Cross Validation Accuracy"):
+    plt.figure(figsize=(10, 5))
+
+    plt.plot(
+        cv_labels,
+        cv_accuracies,
+        color="#666666",
+        linestyle="-",
+        linewidth=2,
+        marker="o",
+        markersize=7,
+        markerfacecolor="#D20A0A",  # UFC red dots
+        markeredgecolor="#FFFFFF",
+        markeredgewidth=1.5,
+        label="Fold Accuracy"
+    )
+
+
+    # Mean accuracy across folds
+    mean_accuracy = np.mean(cv_accuracies)
+
+    plt.axhline(
+        mean_accuracy,
+        color="#D20A0A",
+        linestyle="--",
+        linewidth=2,
+        label=f"Mean Accuracy: {mean_accuracy:.1%}"
+    )
+
+
+    plt.xlabel("Fold")
+    plt.ylabel("Accuracy")
+    plt.title(title)
+    # plt.ylim(0, 1)
+
+    plt.xticks(rotation=45)
+    plt.grid(True, alpha=0.3)
+    plt.legend()
+
+    plt.tight_layout()
+    plt.show()
+
+def plot_test(accuracy, title="Test Accuracy"):
+    plt.figure(figsize=(6, 5))
+
+    plt.bar(
+        0,
+        accuracy,
+        color="#D20A0A",
+        width=0.25
+    )
+
+    plt.ylabel("Accuracy")
+    plt.title(title)
+    plt.ylim(0, 1)
+
+    plt.xlim(-0.5, 0.5)
+    plt.xticks([0], ["Test Set"])
+
+    plt.text(
+        0,
+        accuracy + 0.02,
+        f"{accuracy:.1%}",
+        ha="center",
+        fontweight="bold",
+        color="#444444"
+    )
+
+    plt.tight_layout()
+    plt.show()