sportsfeatures-python 0.1.0

Dataset loader for sports performance features

Dataset Loader for Sports Performance Features

Longitudinal Sports Performance Features Dataset

A Rule‑Based Synthetic Framework Designed for Multi‑Level Athlete Session Profiling

Author & Creator: Mohammad Abbas
Role: Data Analyst / Developer
Purpose: Research, Development, and Creative Statistical Validation
Date: July 2026

Overview

The sportsfeatures dataset is a synthetic, hierarchical collection of athletic performance records built to enhance modern statistical learning. Developed through a transparent, rule‑based simulation framework, it captures longitudinal activity sessions across multiple athletes, environmental conditions, and wellness indicators. Unlike traditional teaching datasets that are small or overly simplified, sportsfeatures offers realistic structure, controlled missingness, and rich variable interactions — making it ideal for exploring descriptive statistics, modelling, visualisation, and missing‑data methods. Its design encourages learners to experiment, question, and build their own analytical pathways while working with data that feels realistic and multidimensional.

Installation

To install the package locally in editable development mode, navigate to your root package directory and run:

pip install -e .

1. Usage Guide

The package exposes a single, parameter‑driven loader function alongside an integrated, audited data schema dictionary.

1.1. Accessing the Datasets

Both the baseline clean data and the synthetically sparse dataset can be streamed directly into memory as individual Pandas DataFrames:

import sportsfeatures as sf

# Load the clean, complete baseline dataset (default)
df_clean = sf.load_sports_features(subset="complete")

# Load the companion dataset embedded with missing-value gaps
df_missing = sf.load_sports_features(subset="missing")

# Verify structural shapes
print(f"Clean Baseline:  {df_clean.shape[0]} rows x {df_clean.shape[1]} columns")
print(f"Missing Dataset: {df_missing.shape[0]} rows x {df_missing.shape[1]} columns")

# Inspect initial records
print(df_clean.head())
print(df_missing.head())

---

1.2. Accessing the Data Dictionary

To review target variables, metric boundaries, and column constraints on the fly without leaving your notebook or console environment:

import sportsfeatures as sf

# Print the verified structural variables mapping schema
print(sf.DATA_DICTIONARY)

---

2. Workspace Integration (VS Code Pro‑Tip)

When working within a standard Python script (.py) inside your VS Code workspace:

1. Click “Run Current File in Interactive Window” at the top‑right corner of your editor.
2. Select the “Show Variables” icon in the Interactive menu header.
3. Click the tabular data viewer icon next to df_clean or df_missing to launch them straight into Data Wrangler for instant visual data profiling, missingness maps, and column distributions.

---

3. Data Dictionary

The sportsfeatures package includes a comprehensive data dictionary that defines every variable available in the dataset.
This dictionary ensures transparency and reproducibility for all users working with sports performance metrics.

Variable	Type	Description	Range/Values	Unit
session_id	Integer	Unique session identifier	1–500	–
athlete_id	Integer	Unique athlete identifier	1001–1010	–
datetime	DateTime	Activity date and time	Jan–Dec 2024	DD/MM/YYYY
activity_type	Categorical	Type of activity	15 types	–
region	Categorical	Geographic region	9 regions	–
distance_km	Continuous	Distance covered	2.0–21.0	km
weather_type	Categorical	Weather conditions	8 types	–
temperature_c	Continuous	Temperature	1.2–31.3	°C
personal_status	Categorical	Physical/mental state	4 levels	–
is_group_activity	Binary	Group participation	Yes/No	–
gender	Binary	Athlete gender	Male/Female	–
age	Integer	Athlete age	20–60	years
base_fitness	Continuous	Baseline fitness	43.4–92.9	score
base_speed	Continuous	Baseline speed	9.3–14.9	km/h
base_stamina	Continuous	Baseline stamina	51.1–87.6	score
base_weight	Continuous	Body weight	62.5–91.8	kg
resting_heart_rate	Integer	Resting HR	50–83	bpm
device_type	Categorical	Tracking device	7 types	–
speed_kmh	Continuous	Average speed	8.4–16.3	km/h
duration_min	Continuous	Activity duration	7.9–122.8	min
heart_rate_avg	Integer	Average HR	120–157	bpm
calories_burned	Continuous	Calories expended	86.4–1428.5	kcal
exhaustion_level	Continuous	Exhaustion score	37.1–72.8	score
hydration_status	Continuous	Hydration level	73.7–95.3	%
fatigue_score	Continuous	Fatigue index	17.9–46.6	score

---

4. Accessing the Dictionary Programmatically

You can also access this dictionary directly from within Python:

import sportsfeatures as sf

# Print the verified structural variables mapping schema
print(sf.DATA_DICTIONARY)

5. License and Data Availability

The sportsfeatures datasets are available for free use under the MIT License, but not for commercial gain.
You can install the package directly from CRAN (for R) or PyPI (for Python) using:

install.packages("sportsfeatures")

or

pip install sportsfeatures

---

5.1. Citation

If you use this package in your research or teaching materials, please cite:

Abbas, M. (2026). sportsfeatures: Dataset Loader for Sports Performance Features. MIT License.

---