Metadata-Version: 2.4
Name: aid-analysis
Version: 0.1.0
Summary: Abnormal Impact Differential (AID) analysis with ANOVA significance testing for year-over-year event impact measurement.
Author: Mohamed Audeh
License: MIT
Keywords: statistics,difference-in-differences,anova,impact-analysis,time-series,data-analysis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=1.5
Requires-Dist: numpy>=1.22
Requires-Dist: statsmodels>=0.13
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Dynamic: license-file

# aid-analysis

**Abnormal Impact Differential (AID)** — a difference-in-differences style tool for measuring how much a metric deviated from its normal year-over-year pattern during a specific event window, with a two-way ANOVA significance test included.

## Installation

```bash
pip install aid-analysis
```

## What it does

Given daily (or other tidy) time-series data for one or more numeric metrics, AID asks:

> *"How much did my metric change from Period 1 to Period 2 this year, compared to how much it normally changes from Period 1 to Period 2 in a baseline year?"*

The answer is a single number in percentage points (the **AID**), plus a p-value from a two-way ANOVA testing whether that difference is statistically significant.

### The formula

$$\text{AID} = 100 \times \left[\left(\frac{\mu_{\text{current}, P_2}}{\mu_{\text{current}, P_1}} - 1\right) - \left(\frac{\mu_{\text{baseline}, P_2}}{\mu_{\text{baseline}, P_1}} - 1\right)\right]$$

A negative AID means the metric performed worse in the current year than prior-year seasonality would predict; positive means better.

## Quick start

```python
from aid_analysis import run_analysis, PeriodConfig

cfg = PeriodConfig(
    current_year=2026,
    baseline_year=2025,
    period_1=("01-29", "02-28"),   # "before" window, inclusive
    period_2=("03-01", "03-31"),   # "after" window, inclusive
)

# Single metric
summary = run_analysis("data.csv", metrics="Revenue", config=cfg)

# Multiple metrics
summary = run_analysis(
    "data.csv",
    metrics=["Transactions", "Count of Users", "Revenue"],
    config=cfg,
)
```

Your CSV just needs a `date` column and one or more numeric columns.

## Input data format

A tidy CSV (or `pandas.DataFrame`) with:

- a **`date` column** (any parseable date format — you can change the column name via `PeriodConfig(date_col="...")`)
- one or more **numeric metric columns** (any names, including names with spaces like `"Count of Users"`)

Example:

```
date,Transactions,Revenue
2025-01-29,142,8930.50
2025-01-30,156,9420.00
...
2026-03-31,98,6110.25
```

## Output

Three things:

1. **A printed report** with the means, step-by-step AID calculation, the full ANOVA table, and plain-English interpretation.
2. **A CSV summary** (`aid_summary.csv` by default) with one row per metric.
3. **A pandas DataFrame** returned from `run_analysis()` for further work.

Example summary:

| metric | mean_2026_period_1 | mean_2026_period_2 | mean_2025_period_1 | mean_2025_period_2 | change_2026_pct | change_2025_pct | aid_pp | anova_interaction_pvalue |
|---|---|---|---|---|---|---|---|---|
| Revenue | 8,430.50 | 6,120.75 | 8,200.10 | 8,350.40 | -27.39 | 1.83 | -29.22 | 0.00023 |

## Class-based API

For more control over intermediate steps:

```python
from aid_analysis import AbnormalImpactAnalyzer, PeriodConfig

cfg = PeriodConfig(
    current_year=2026,
    baseline_year=2025,
    period_1=("01-29", "02-28"),
    period_2=("03-01", "03-31"),
)

analyzer = AbnormalImpactAnalyzer("data.csv", config=cfg)
analyzer.run(metrics=["Revenue", "Transactions"])
analyzer.print_report()

# Access individual results
revenue_result = analyzer.results["Revenue"]
print(revenue_result.delta_pp)            # the AID value
print(revenue_result.anova_table)         # full ANOVA table
print(revenue_result.anova_interaction_pvalue)

# Get the summary as a DataFrame
df = analyzer.summary_frame()

# Or export to CSV
analyzer.export("my_summary.csv")
```

## How to interpret the results

| AID value | p-value | Meaning |
|-----------|---------|---------|
| Large negative | < 0.05 | Real, significant underperformance vs the seasonal baseline |
| Large negative | ≥ 0.05 | Looks like a drop, but could be random noise |
| Large positive | < 0.05 | Real, significant outperformance vs the seasonal baseline |
| Large positive | ≥ 0.05 | Looks like an uplift, but could be random noise |
| Near zero | any | No abnormal impact vs the prior-year pattern |

## Requirements

- Python 3.9+
- pandas ≥ 1.5
- numpy ≥ 1.22
- statsmodels ≥ 0.13

## License

MIT
