Metadata-Version: 2.4
Name: quicklearnkit
Version: 0.3.2
Summary: Learning-first machine learning utilities library for simplified imports, sampling, splitting, and probabilistic preprocessing.
Author: Hazi Afrid
License: MIT License
        
        Copyright (c) 2025 Masterhazi
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: scikit-learn
Requires-Dist: xgboost
Requires-Dist: seaborn
Requires-Dist: matplotlib
Dynamic: license-file

# QuickLearnKit

QuickLearnKit is a **learning-first machine learning utilities library** designed to make common ML and data science workflows simple, readable, and beginner-friendly — without blocking advanced users from full customization.

The philosophy is:

> **Remove mechanical friction so students can focus on concepts, not syntax.**

QuickLearnKit provides:

* Easy model imports
* Random sampling utilities
* Train–test splitting
* Probabilistic, group-aware imputation
* Teaching-friendly plotting with optional value labels

---

## Installation

```bash
pip install quicklearnkit
```

---

## Quick Start

```python
from quicklearnkit import (
    Sampler,
    train_test_split,
    ProbabilisticImputer,
    bar_plot
)

import seaborn as sns

# Load example dataset
df = sns.load_dataset("titanic")

# Sample data
sampler = Sampler(df, n=5, random_state=42)
print(sampler.sample())

# Split data
train, test = train_test_split(df, test_size=0.25)

# Impute missing values
imputer = ProbabilisticImputer("pclass", "deck", random_state=42)
df_imputed = imputer.fit_transform(df)

# Plot
bar_plot(df, x="class", y="fare", show_values="yes")
```

---

# Model Imports

QuickLearnKit allows you to import commonly used machine learning models without navigating deep module paths.

### Example

```python
from quicklearnkit import (
    LinearRegressionmodel,
    RandomForestRegressionmodel,
    XGBoostRegressionmodel,
    KNeighborsClassifiermodel,
    GradientBoostingClassifiermodel
)

lr_model = LinearRegressionmodel()
rf_model = RandomForestRegressionmodel()
xgb_model = XGBoostRegressionmodel()

knn_classifier = KNeighborsClassifiermodel()
gb_classifier = GradientBoostingClassifiermodel()
```

---

## Supported Models

### Regression Models

* `LinearRegressionmodel()`
* `KNNRegressionmodel()`
* `DecisionTreeRegressionmodel()`
* `RandomForestRegressionmodel()`
* `GradientBoostingRegressionmodel()`
* `AdaBoostRegressionmodel()`
* `XGBoostRegressionmodel()`
* `ElasticNetRegressionmodel()`

### Classification Models

* `LogisticRegressionmodel()`
* `KNeighborsClassifiermodel()`
* `DecisionTreeClassifiermodel()`
* `RandomForestClassifiermodel()`
* `AdaBoostClassifiermodel()`
* `GradientBoostingClassifiermodel()`
* `XGBClassifiermodel()`
* `SVClassifiermodel()`

---

# Utilities

## 1. Sampler

The `Sampler` class allows you to randomly select elements from:

* Python lists
* NumPy arrays
* pandas DataFrames

It supports both **stateless** (reproducible) and **stateful** (streaming/simulation) modes.

### Initialization

```python
Sampler(data, n=1, random_state=None, replace=False, axis=0, stateful=False)
```

### Parameters Explained

| Parameter      | Type                                  | Description                                                                                      |
| -------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `data`         | list, numpy.ndarray, pandas.DataFrame | The dataset to sample from                                                                       |
| `n`            | int                                   | Number of samples to return                                                                      |
| `random_state` | int or None                           | Seed for reproducibility. Same seed = same result                                                |
| `replace`      | bool                                  | If `True`, sampling is done **with replacement** (duplicates allowed). If `False`, no duplicates |
| `axis`         | int                                   | Only applies to DataFrames. `0` = sample rows, `1` = sample columns                              |
| `stateful`     | bool                                  | If `True`, RNG state continues across calls. If `False`, sampling is reproducible on every call  |

### Example

```python
from quicklearnkit import Sampler
import seaborn as sns

df = sns.load_dataset("tips")

sampler = Sampler(df, n=3, random_state=42, replace=False)

sample1 = sampler.sample()
sample2 = sampler.sample()  # Same output if stateful=False
```

---

## 2. Train–Test Split

Split datasets into training and testing sets with support for:

* Shuffling
* Stratification
* NumPy arrays
* pandas DataFrames

### Function

```python
train_test_split(data, test_size=0.25, shuffle=True, stratify=None, random_state=None)
```

### Parameters Explained

| Parameter      | Type                           | Description                                                |
| -------------- | ------------------------------ | ---------------------------------------------------------- |
| `data`         | array-like or pandas.DataFrame | Dataset to split                                           |
| `test_size`    | float                          | Proportion of data to use as test set (e.g., `0.25` = 25%) |
| `shuffle`      | bool                           | If `True`, data is shuffled before splitting               |
| `stratify`     | array-like or str              | Column or labels to preserve class distribution in splits  |
| `random_state` | int or None                    | Seed for reproducibility                                   |

### Example

```python
from quicklearnkit import train_test_split

train, test = train_test_split(df, test_size=0.3, shuffle=True, random_state=42)
```

---

## 3. ProbabilisticImputer

A **group-aware, probabilistic categorical imputer**. It learns probability distributions from observed data and fills missing values by sampling from those distributions.

This allows:

* Realistic missing data handling
* Teaching probability-based imputation
* Reproducible preprocessing

### Initialization

```python
ProbabilisticImputer(group_col, target_col, random_state=None, stateful=False)
```

### Parameters Explained

| Parameter      | Type        | Description                                                                                            |
| -------------- | ----------- | ------------------------------------------------------------------------------------------------------ |
| `group_col`    | str         | Column used to group data (e.g., class, category)                                                      |
| `target_col`   | str         | Column where missing values will be imputed                                                            |
| `random_state` | int or None | Seed for reproducibility                                                                               |
| `stateful`     | bool        | If `True`, RNG state advances across calls (useful for simulation). If `False`, output is reproducible |

### Methods

| Method              | Description                                        |
| ------------------- | -------------------------------------------------- |
| `fit(df)`           | Learns probability distributions from known values |
| `transform(df)`     | Imputes missing values using learned distributions |
| `fit_transform(df)` | Fit and transform in one step                      |

### Example

```python
from quicklearnkit import ProbabilisticImputer
import seaborn as sns

df = sns.load_dataset("titanic")

imputer = ProbabilisticImputer(
    group_col="pclass",
    target_col="deck",
    random_state=42
)

imputed_df = imputer.fit_transform(df)
```

---

# Plotting (Teaching-Friendly Visualization)

QuickLearnKit provides wrappers around **seaborn + matplotlib** that allow students to display values on plots using a simple switch:

```python
show_values="yes"
```

All plotting functions:

* Return a **matplotlib Axes object**
* Allow full customization (labels, limits, grids, styles)
* Automatically display the plot by default

---

## Common Parameters (All Plot Functions)

| Parameter     | Type             | Description                                                                      |
| ------------- | ---------------- | -------------------------------------------------------------------------------- |
| `data`        | pandas.DataFrame | Dataset used for plotting                                                        |
| `x`           | str              | Column for x-axis                                                                |
| `y`           | str              | Column for y-axis (if applicable)                                                |
| `title`       | str or None      | Plot title                                                                       |
| `show_values` | str              | "yes" or "no" — whether to display numeric values                                |
| `fmt`         | str              | Format string for value labels (e.g. `{:.2f}`)                                   |
| `show`        | bool             | If `True`, displays plot immediately. If `False`, returns Axes for customization |

---

## bar_plot

```python
bar_plot(data, x, y, title=None, show_values="no", fmt="{:.1f}", show=True)
```

### Example

```python
from quicklearnkit import bar_plot
import seaborn as sns

_df = sns.load_dataset("tips")

ax = bar_plot(
    _df,
    x="day",
    y="total_bill",
    show_values="yes",
    show=False
)

ax.set_xlabel("Day of Week")
ax.set_ylabel("Average Bill")
ax.set_ylim(0, 40)

import matplotlib.pyplot as plt
plt.show()
```

---

## line_plot

```python
line_plot(data, x, y, title=None, show_values="no", fmt="{:.2f}", show=True)
```

---

## scatter_plot

```python
scatter_plot(data, x, y, title=None, show_values="no", fmt="{:.2f}", show=True)
```

---

## count_plot

```python
count_plot(data, x, title=None, show_values="no", show=True)
```

---

## box_plot

Displays **mean values** when `show_values="yes"`.

```python
box_plot(data, x=None, y=None, title=None, show_values="no", fmt="{:.2f}", show=True)
```

---

## hist_plot

Displays **bin counts** when `show_values="yes"`.

```python
hist_plot(data, x, bins=10, title=None, show_values="no", fmt="{:.0f}", show=True)
```

---

# Random Data Generation

Generate random numerical arrays for experiments and demonstrations.

```python
from quicklearnkit import create_random

random_data = create_random(mean=0, std_dev=1, size=100)
```

---

# Design Philosophy

QuickLearnKit is designed for:

* **Students** learning ML and data science
* **Educators** teaching concepts, not boilerplate
* **Practitioners** who want fast, clean workflows

It balances:

> **Beginner simplicity + Advanced control**

---

# Contributing

Want to improve QuickLearnKit?

1. Fork the repository
2. Create a feature branch
3. Add tests and documentation
4. Submit a pull request

---

# License

MIT License

---

QuickLearnKit helps you move from *learning* to *building* faster — without sacrificing clarity or control. 🚀
