Metadata-Version: 2.4
Name: sportsfeatures-python
Version: 0.1.0
Summary: Dataset loader for sports performance features
Author: Mohammad Abbas
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: pandas>=1.5.0
Dynamic: license-file


# **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:

```bash
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:

```python
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:

```python
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:

```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:

```r
install.packages("sportsfeatures")
```

or

```bash
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.

---
