UFCData 0.1.2__tar.gz → 0.2.0__tar.gz

{ufcdata-0.1.2 → ufcdata-0.2.0}/PKG-INFO

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

ufcdata-0.2.0/README.md

@@ -0,0 +1,173 @@
+# UFCData
+
+An open-source Python package for accessing, manipulating, and analyzing UFC data.
+
+https://pypi.org/project/UFCData/
+
+add helper functions like convert odds
+
+## Table of Contents
+
+- [Installation](#installation)
+
+Accessing Data
+  - [Loading Data](#loading-data)
+  - [Search](#search)
+
+Rating Functions
+  - [Elo](#elo)
+  - [Glicko-2](#glicko-2)
+
+Fighter Functions
+- [Fighter Record](#elo)
+- [Fighter Statistic](#elo)
+
+Model Evaluation
+- [Odds Baseline Example](#elo)
+
+Helper Functions
+  - [Odds Convert](#elo)
+  - [Weight Convert](#elo)
+  - [Gender Convert](#elo)
+  - [Mirror](#elo)
+
+Data Sources
+  - [Online Sources](#online-sources)
+  - [Discrepancies in Data](#discrepancies-in-data)
+  - [Update Frequency](#update-frequency)
+
+## Installation
+
+```bash
+pip install ufcdata
+```
+
+##  Loading Data
+
+```python
+import ufcdata as ufc
+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.
+
+## Search
+
+Due to various event naming conventions and fighters sharing the same name, the primary keys for the dataframes are links, which can be difficult for humans to interpret. The `search()` function uses fuzzy string matching to make it easier to find fighters, events, and other records.
+
+```python
+search(data, column, query, matches=1)
+```
+
+### Parameters
+
+* `data` — The dataframe you are searching.
+* `column` — The name of the column to search.
+* `query` — The name or text you are searching for.
+* `matches` — The number of closest matches to return. Defaults to `1`.
+
+### Example
+
+```python
+john_jones = ufc.search(fighter_bio, "Name", "Jon Jones", 3)
+```
+
+This searches the `"Name"` column of the `fighter_bio` dataframe for the three closest matches to `"Jon Jones"`.
+
+The results are returned as a dataframe, with the closest match appearing first.
+
+Output:
+
+```text
+Name             Nickname   Height   Weight   Reach   Stance      Total W   Total L   Fighter Link
+Jon Jones        Bones      76.0     248.0    84.0    Orthodox    28        1         ufcstats.com/...
+Roshaun Jones    NaN        68.0     135.0    NaN     NaN         2         6         ufcstats.com/...
+Mason Jones      The Dragon 70.0     155.0    74.0    Orthodox    18        2         ufcstats.com/...
+```
+
+This is useful when the exact value stored in the dataset is unknown or when there are multiple similar names. The same function can be used with any dataframe and column containing searchable text.
+
+
+## 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**.
+
+This allows Elo ratings to be used as features for predictive modeling without incorporating information from the fight being predicted.
+
+
+```python
+ufc.get_elo(fight_df, fighter_df, r=1500, k=30, s=400)
+```
+
+### Parameters
+
+* `fight_df` — The UFC fight dataframe, sorted from most recent to least recent.
+* `fighter_df` — The fighter information dataframe containing a `"Fighter Link"` column.
+* `r` — Initial Elo rating for each fighter. Defaults to `1500`.
+* `k` — K-factor controlling how much ratings change after each fight. Defaults to `30`.
+* `s` — Scaling factor used when calculating expected scores. Defaults to `400`.
+
+### Returns
+
+The function returns a tuple containing:
+
+1. `fighter_elo` — A dictionary mapping each fighter's UFCStats link to their final Elo rating.
+2. `elo` — A dataframe containing fight-level Elo ratings. `"Fighter 1 Elo"` and `"Fighter 2 Elo"` represent each fighter's rating immediately before the corresponding fight.
+
+### Example
+
+```python
+import ufcdata as ufc
+
+data = ufc.get_data()
+
+fight_df = data["past_fights"].copy()
+fighter_df = data["fighter_bio"].copy()
+
+fighter_elo, fight_elo = ufc.get_elo(
+    fight_df,
+    fighter_df
+)
+```
+
+The resulting `fight_elo` dataframe can then be used to examine or incorporate pre-fight Elo ratings into analysis and predictive models.
+
+
+### 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.
+
+
+## Glicko-2
+Glicko-2 extends the Elo system by incorporating rating deviation (RD) and volatility. Unlike Elo, which represents a fighter's ability with a single rating, Glicko-2 also estimates the uncertainty and consistency of that rating.
+
+fighter_glicko, fight_glicko = ufc.glicko_2(
+    fight_df,
+    fighter_df
+)
+
+## Online Sources
+
+Odds and birthplace data was obtained from https://www.tapology.com
+ 
+Venue and attendance data was obtained from https://en.wikipedia.org/wiki/List_of_UFC_events
+
+All other data was obtained from http://ufcstats.com
+
+## Discrepancies in Data
+
+UFCStats is treated as the authoritative source for UFCData. When discrepancies exist between UFCStats and other sources, such as Wikipedia or Tapology, the UFCStats data is used.
+
+The UFCStats completed events page serves as the authoritative source for event, fight, and round data. Individual fighter profiles may contain fights from organizations or events that are not included in the completed events database, including WEC, Strikeforce, and PRIDE. These events are therefore excluded from UFCData.
+
+## Update Frequency
+
+The dataset is updated at the start of the scheduled broadcast time for each event. This update captures changes to betting odds, as well as any cancelled, postponed, or otherwise modified fights.
+
+A second update occurs 24 hours after the start of the broadcast. This update captures the finalized event, fight, and round data, as well as information on upcoming events and fights.
+
+Changes occurring between these scheduled updates are not automatically captured. Users are responsible for manually updating the dataset if they require the most current data for analysis or prediction.

{ufcdata-0.1.2 → ufcdata-0.2.0}/UFCData.egg-info/PKG-INFO

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

{ufcdata-0.1.2 → ufcdata-0.2.0}/UFCData.egg-info/SOURCES.txt

@@ -8,6 +8,8 @@ UFCData.egg-info/requires.txt
 UFCData.egg-info/top_level.txt
 ufcdata/__init__.py
 ufcdata/data.py
+ufcdata/ratings.py
+ufcdata/search.py
 ufcdata.egg-info/PKG-INFO
 ufcdata.egg-info/SOURCES.txt
 ufcdata.egg-info/dependency_links.txt

{ufcdata-0.1.2 → ufcdata-0.2.0}/UFCData.egg-info/requires.txt

@@ -2,3 +2,4 @@ huggingface-hub
 pandas
 numpy
 glicko2
+rapidfuzz

{ufcdata-0.1.2 → ufcdata-0.2.0}/pyproject.toml

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

ufcdata-0.2.0/ufcdata/__init__.py

@@ -0,0 +1,3 @@
+from .data import get_data
+from .search import search
+from .ratings import get_elo

{ufcdata-0.1.2 → ufcdata-0.2.0}/ufcdata/data.py

@@ -3,6 +3,20 @@ import pickle
 import logging
 
 def get_data():
+    """
+    Obtains all UFC related data
+
+    Returns
+    dict
+        Dictionary containing UFC data as pandas DataFrames.
+        Individual DataFrames can be accessed using their
+        corresponding dictionary keys.
+
+    Examples
+    --------
+    >>> data = get_data()
+    >>> past_events = data["past_events"].copy()
+    """
 
     logging.getLogger("huggingface_hub").setLevel(logging.ERROR)
     

ufcdata-0.2.0/ufcdata/ratings.py

@@ -0,0 +1,130 @@
+import pandas as pd
+from glicko2 import Player
+
+#@title Elo function
+def expected_score(rating, opponent_rating, s):
+  return (1)/(1 + 10**((opponent_rating - rating)/(s)))
+
+#Rating update
+def update_rating(rating, k, outcome, expected):
+  return rating + k*(outcome - expected)
+
+# Elo function
+#  Make sure fights are sorted from most recent to least recent. Gets Elo prior to fight.
+def get_elo(fight_df, fighter_df, r=1500, k=30, s=400):
+  """
+    Calculates pre-fight Elo ratings for UFC fighters.
+
+    Fights are processed chronologically from oldest to newest, with
+    each fighter's Elo rating recorded immediately before each fight.
+    Fighter ratings are initialized to `r` and updated after each fight
+    using the specified K-factor and Elo scale.
+
+    Parameters
+    ----------
+    fight_df : pandas.DataFrame
+        UFC fight data sorted from most recent to least recent.
+        Must contain fighter links, fight outcomes, and the fight
+        information required to construct the output.
+    fighter_df : pandas.DataFrame
+        DataFrame containing fighter information. Must contain a
+        "Fighter Link" column used to identify each fighter.
+    r : float, default=1500
+        Initial Elo rating assigned to each fighter.
+    k : float, default=30
+        K-factor controlling the magnitude of Elo rating changes
+        after each fight.
+    s : float, default=400
+        Elo scaling factor used when calculating expected scores.
+
+    Returns
+    -------
+    current_elo : dict
+        Dictionary mapping each fighter's link to their current Elo rating
+        after processing all fights.
+
+    past_elo : pandas.DataFrame
+        Fight-level DataFrame containing the original fight information
+        and the Elo rating of each fighter immediately before the fight.
+
+    Notes
+    -----
+    The input fight data should be sorted from most recent to least
+    recent. The function reverses this order internally to process
+    fights chronologically, then returns the resulting data in the
+    original order.
+
+    Examples
+    --------
+    >>> fighter_elo, fight_elo = get_elo(fight_df, fighter_df)
+    >>> fight_elo[["Fighter 1", "Fighter 1 Elo",
+    ...            "Fighter 2", "Fighter 2 Elo"]].head()
+  """
+
+  fight_df = fight_df[::-1]
+
+  original_fight_df = fight_df.copy()
+
+  fighter_1_elo = []
+  fighter_2_elo = []
+
+  ## Create a dictionary of fighters and their Elo
+  fighter_df = fighter_df.copy()
+  fighter_df["Elo"] = r
+  fighter_df = dict(zip(fighter_df["Fighter Link"], fighter_df["Elo"]))
+
+  ## Create a list of fights
+  fight_df = fight_df[["Fighter 1 Link", "Fighter 1 Outcome", "Fighter 2 Link", "Fighter 2 Outcome"]]
+  fight_df = fight_df.values.tolist()
+
+
+  ## Loop through each fight in order
+  for fight in fight_df:
+    ## Get fighters Elo from fighter_df
+    elo_1 = fighter_df[fight[0]]
+    elo_2 = fighter_df[fight[2]]
+    ## Add to final list
+    fighter_1_elo.append(elo_1)
+    fighter_2_elo.append(elo_2)
+    ## Update Elo
+    if (fight[1] == "W") and ((fight[3] == "L")):
+      expected_1 = expected_score(elo_1, elo_2, s)
+      elo_1_new = update_rating(elo_1, k, 1, expected_1)
+      expected_2 = expected_score(elo_2, elo_1, s)
+      elo_2_new = update_rating(elo_2, k, 0, expected_2)
+      fighter_df[fight[0]] = elo_1_new
+      fighter_df[fight[2]] = elo_2_new
+    elif (fight[1] == "L") and (fight[3] == "W"):
+      expected_1 = expected_score(elo_1, elo_2, s)
+      elo_1_new = update_rating(elo_1, k, 0, expected_1)
+      expected_2 = expected_score(elo_2, elo_1, s)
+      elo_2_new = update_rating(elo_2, k, 1, expected_2)
+      fighter_df[fight[0]] = elo_1_new
+      fighter_df[fight[2]] = elo_2_new
+    elif (fight[1] == "D") and (fight[3] == "D"):
+      expected_1 = expected_score(elo_1, elo_2, s)
+      elo_1_new = update_rating(elo_1, k, 0.5, expected_1)
+      expected_2 = expected_score(elo_2, elo_1, s)
+      elo_2_new = update_rating(elo_2, k, 0.5, expected_2)
+      fighter_df[fight[0]] = elo_1_new
+      fighter_df[fight[2]] = elo_2_new
+
+
+  elo_1 = pd.DataFrame(fighter_1_elo, columns=["Fighter 1 Elo"])
+  elo_2 = pd.DataFrame(fighter_2_elo, columns=["Fighter 2 Elo"])
+  elo = pd.concat(
+    [
+        original_fight_df.reset_index(drop=True),
+        elo_1.reset_index(drop=True),
+        elo_2.reset_index(drop=True)
+    ],
+    axis=1
+  )
+  elo = elo[['Date', 'Event Link', 'Fight Number', 'Fight Link', 'Weight Class',
+       'Gender', 'Title', 'Fighter 1', 'Fighter 1 Elo', 'Fighter 1 Odds', 'Fighter 1 Link',
+       'Fighter 1 Outcome', 'Fighter 1 Bonus', 'Fighter 2','Fighter 2 Elo', 'Fighter 2 Odds',
+       'Fighter 2 Link', 'Fighter 2 Outcome', 'Fighter 2 Bonus', 'Method',
+       'Round', 'Time', 'Time Format', 'Referee', 'Details']]
+  past_elo = elo[::-1].copy()
+  current_elo = fighter_df
+  return (current_elo, past_elo)

ufcdata-0.2.0/ufcdata/search.py

@@ -0,0 +1,39 @@
+from rapidfuzz.fuzz import ratio
+
+def search(data, column , query, matches=1):
+    """
+    Searches a UFC DataFrame for rows matching a query.
+
+    Uses fuzzy string matching to identify the rows in the specified
+    column that most closely match the query.
+
+    Parameters
+    ----------
+    data : pandas.DataFrame
+        UFC DataFrame to search.
+    column : str
+        Name of the column to search.
+    query : str
+        Search query to match against the specified column.
+    matches : int, default=1
+        Number of closest matches to return.
+
+    Returns
+    -------
+    pandas.DataFrame
+        DataFrame containing the closest matching rows, sorted from
+        highest to lowest similarity.
+
+    Examples
+    --------
+    >>> data = get_data()
+    >>> results = search(data["fighters"], "Name", "Jon Jones")
+    """
+    scores = data[column].fillna("").apply(
+    lambda x: ratio(str(x), query))
+
+    result = data.loc[scores.nlargest(matches).index].copy()
+    result["score"] = scores.loc[result.index]
+    result = result.sort_values("score", ascending=False).drop(columns="score")
+
+    return result

ufcdata-0.1.2/ufcdata/__init__.py

@@ -1 +0,0 @@
-from .data import get_data