UFCData 0.3.0__tar.gz → 0.4.0__tar.gz

{ufcdata-0.3.0 → ufcdata-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: UFCData
-Version: 0.3.0
+Version: 0.4.0
 Summary: Obtain UFC data and functions to manipulate it
 Requires-Python: >=3.10
 License-File: LICENSE.md

{ufcdata-0.3.0 → ufcdata-0.4.0}/README.md

@@ -18,8 +18,8 @@ Rating Function
   - [Elo](#elo)
 
 Fighter Functions
-- [Fighter History](#elo)
-- [Fighter Statistic](#elo)
+- [Fighter History](#fighter-history)
+- [Fighter Statistic](#fighter-statistics)
 
 Helper Functions
   - [Odds Convert](#elo)
@@ -144,7 +144,7 @@ The resulting `fight_elo` dataframe can then be used to examine or incorporate p
 
 ## Fighter History
 
-The `get_fighter_history()` function retrieves all UFC fights for a specific fighter and formats the results from the fighter's perspective. The requested fighter is always represented as `"Fighter 1"`, regardless of which side of the original fight dataframe they appeared on.
+The function `get_fighter_history()` retrieves all UFC fights for a specific fighter and formats the results from the fighter's perspective. The requested fighter is always represented as `"Fighter 1"`, regardless of which side of the original fight dataframe they appeared on.
 
 The function also calculates the age of both fighters at the time of each fight and assigns a `"UFC Fight"` number to each fight.
 
@@ -192,6 +192,169 @@ jon_jones_history = ufc.get_fighter_history(
 
 This function is useful for analyzing an individual fighter's career, constructing fighter-level features, or preparing historical data for predictive modeling.
 
+## Fighter Statistics
+
+
+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.
+
+
+```python
+get_fighter_statistic(
+    fighter_link,
+    fighter_bio,
+    fights_df,
+    rounds_df,
+    r=1500,
+    k=30,
+    s=400
+)
+```
+
+
+
+### Parameters
+
+| Parameter      | Type                    | Description                                                                                        |
+| -------------- | ----------------------- | -------------------------------------------------------------------------------------------------- |
+| `fighter_link` | `str`                   | UFCStats link or identifier for the fighter.                                                       |
+| `fighter_bio`  | `pd.DataFrame`          | Fighter biography DataFrame containing fighter names and links.                                    |
+| `fights_df`    | `pd.DataFrame`          | Fight-level UFC data containing fight results and metadata.                                        |
+| `rounds_df`    | `pd.DataFrame`          | Round-level UFC statistics.                                                                        |
+| `future_df`    | `pd.DataFrame`          | DataFrame containing the upcoming fight. The first row is used to determine the future fight date. |
+| `r`            | `float`, default `1500` | Initial Elo rating.                                                                                |
+| `k`            | `float`, default `30`   | Elo K-factor controlling the magnitude of rating updates.                                          |
+| `s`            | `float`, default `400`  | Elo scaling factor used when calculating expected scores.                                          |
+
+### Returns
+
+The function returns two DataFrames:
+
+```python
+current_statistic, past_statistic = get_fighter_statistic(...)
+```
+
+#### `current_statistic`
+
+A one-row DataFrame containing the fighter's current statistic.
+
+This includes:
+
+* UFC fight number
+* UFC record
+* UFC win rate
+* Elo rating
+* Cumulative fight time
+* Significant strikes landed per minute (`SLpM`)
+* Significant strike accuracy (`Str Acc`)
+* Significant strikes absorbed per minute (`SApM`)
+* Significant strike defense (`Str Def`)
+* Takedown average (`TD Avg`)
+* Takedown accuracy (`TD Acc`)
+* Takedown defense (`TD Def`)
+* Submission attempts per 15 minutes (`Sub Avg`)
+
+#### `past_statistic`
+
+A DataFrame containing the same types of statistics for each previous UFC fight.
+
+Each row represents the fighter's information **immediately before that fight**.
+
+For example:
+
+```text
+Fight 1 → statistics before Fight 1
+Fight 2 → statistics before Fight 2
+Fight 3 → statistics before Fight 3
+...
+```
+
+This makes the data suitable for constructing historical features for a predictive model.
+
+
+### Example
+
+```python
+current_statistic, past_statistic = get_fighter_statistic(
+    fighter_link=fighter_link,
+    fighter_bio=fighter_bio,
+    fights_df=fights_df,
+    rounds_df=rounds_df,
+)
+```
+
+
+## Data Requirements
+
+The function expects the input DataFrames to contain the relevant fighter, fight, and round-level information.
+
+### `fighter_bio`
+
+Must contain at least:
+
+```text
+Name
+Fighter Link
+```
+
+### `fights_df`
+
+Must contain fighter links, outcomes, fight dates, and fight metadata required by the function.
+
+### `rounds_df`
+
+Must contain round-level striking, takedown, submission, and control statistics.
+
+### `future_df`
+
+Must contain:
+
+```text
+Date
+```
+
+The first row is used to determine the date of the upcoming fight.
+
+## Design
+
+The function follows this general pipeline:
+
+```text
+Fighter
+   │
+   ▼
+Retrieve fight history
+   │
+   ▼
+Construct chronological fight history
+   │
+   ▼
+Calculate UFC record
+   │
+   ▼
+Calculate Elo ratings
+   │
+   ▼
+Calculate cumulative fight statistics
+   │
+   ├── Striking
+   ├── Takedowns
+   └── Submissions
+   │
+   ▼
+Generate pre-fight statistics
+   │
+   ├── Past fights
+   └── Upcoming fight
+   │
+   ▼
+Return current_statistic, past_statistic
+```
+
+The resulting data can then be combined with opponent statistics and other fight-level features to create inputs for UFC fight prediction models.
+
+
 
 ## Online Sources
 

{ufcdata-0.3.0 → ufcdata-0.4.0}/UFCData.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: UFCData
-Version: 0.3.0
+Version: 0.4.0
 Summary: Obtain UFC data and functions to manipulate it
 Requires-Python: >=3.10
 License-File: LICENSE.md

{ufcdata-0.3.0 → ufcdata-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "UFCData"
-version = "0.3.0"
+version = "0.4.0"
 description = "Obtain UFC data and functions to manipulate it"
 requires-python = ">=3.10"
 

{ufcdata-0.3.0 → ufcdata-0.4.0}/ufcdata/fighter.py

@@ -112,7 +112,7 @@ def get_fighter_history(fighter_link, fighter_bio, fights_df):
 
 
 
-def get_fighter_statistic(fighter_link, fighter_bio, fights_df, rounds_df, future_df,
+def get_fighter_statistic(fighter_link, fighter_bio, fights_df, rounds_df,
                           r=1500, k=30, s=400):
     
     """
@@ -140,10 +140,6 @@ def get_fighter_statistic(fighter_link, fighter_bio, fights_df, rounds_df, futur
         DataFrame containing UFC fight-level results.
     rounds_df : pandas.DataFrame
         DataFrame containing round-level UFC statistics.
-    future_df : pandas.DataFrame
-        DataFrame containing the fighter's upcoming fight. The first row
-        is used to determine the date for which current statistics are
-        calculated.
     r : float, default=1500
         Initial Elo rating assigned to fighters with no previous Elo history.
     k : float, default=30
@@ -185,8 +181,7 @@ def get_fighter_statistic(fighter_link, fighter_bio, fights_df, rounds_df, futur
 
     record = get_fighter_history(fighter_link, fighter_bio, fights_df)
 
-    date = future_df.iloc[0]["Date"]
-    date = pd.to_datetime(date).date()
+    date = ("2001-01-01")
 
     if len(record) == 0:
         columns = [
@@ -234,6 +229,7 @@ def get_fighter_statistic(fighter_link, fighter_bio, fights_df, rounds_df, futur
         df[["UFC W", "UFC L", "UFC D", "UFC NC"]] = (
             df[["UFC W", "UFC L", "UFC D", "UFC NC"]].astype("Int64")
         )
+        df.iloc[0, 0] = np.nan
 
         return (df, df)