Metadata-Version: 2.4
Name: one-stop-analytics
Version: 1.13.11
Summary: Cross-platform one-stop data analytics toolkit for Python.
Author-email: Srijan Das <otanalytics.contact@gmail.com>
License-Expression: AGPL-3.0-only
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: COPYRIGHT
Requires-Dist: pandas<4,>=1.5
Requires-Dist: numpy<3,>=1.23
Requires-Dist: matplotlib<4,>=3.6
Requires-Dist: seaborn<1,>=0.12
Requires-Dist: scipy<2,>=1.9
Requires-Dist: scikit-learn<2,>=1.1
Requires-Dist: openpyxl<4,>=3.0
Requires-Dist: XlsxWriter<4,>=3.1
Requires-Dist: reportlab<5,>=4
Provides-Extra: forecasting
Requires-Dist: statsmodels<1,>=0.13; extra == "forecasting"
Provides-Extra: advanced
Requires-Dist: statsmodels<1,>=0.13; extra == "advanced"
Provides-Extra: connectors
Requires-Dist: SQLAlchemy<3,>=1.4; extra == "connectors"
Provides-Extra: duckdb
Requires-Dist: duckdb<2,>=0.9; extra == "duckdb"
Provides-Extra: large-data
Requires-Dist: duckdb<2,>=0.9; extra == "large-data"
Requires-Dist: pyarrow<25,>=10; extra == "large-data"
Provides-Extra: postgres
Requires-Dist: SQLAlchemy<3,>=1.4; extra == "postgres"
Requires-Dist: psycopg[binary]<4,>=3.1; extra == "postgres"
Provides-Extra: mysql
Requires-Dist: SQLAlchemy<3,>=1.4; extra == "mysql"
Requires-Dist: PyMySQL<2,>=1.1; extra == "mysql"
Provides-Extra: visual
Requires-Dist: plotly<7,>=5.18; extra == "visual"
Provides-Extra: dashboard
Requires-Dist: streamlit<2,>=1.30; extra == "dashboard"
Requires-Dist: plotly<7,>=5.18; extra == "dashboard"
Provides-Extra: all
Requires-Dist: xlrd<3,>=2.0; extra == "all"
Requires-Dist: pyarrow<25,>=10; extra == "all"
Requires-Dist: statsmodels<1,>=0.13; extra == "all"
Requires-Dist: SQLAlchemy<3,>=1.4; extra == "all"
Requires-Dist: duckdb<2,>=0.9; extra == "all"
Requires-Dist: plotly<7,>=5.18; extra == "all"
Requires-Dist: streamlit<2,>=1.30; extra == "all"
Requires-Dist: psycopg[binary]<4,>=3.1; extra == "all"
Requires-Dist: PyMySQL<2,>=1.1; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest<9,>=7; extra == "dev"
Requires-Dist: build<2,>=1; extra == "dev"
Requires-Dist: twine<7,>=4; extra == "dev"
Dynamic: license-file

# One Stop Analytics 1.13.11

Cross-platform analytics toolkit for Python 3.9+.

## Highlights

- Pandas / NumPy based analytics
- Lazy imports for faster startup
- Automatic EDA and data-quality profiling
- CSV streaming/chunk processing for large files
- Parallel batch analysis with bounded workers
- Persistent file-aware cache with automatic invalidation
- SciPy statistical tests
- scikit-learn regression/classification helpers
- Matplotlib/Seaborn visualization
- OpenPyXL Excel reports
- Windows, macOS and Linux

## Install

```bash
python -m pip install one-stop-analytics
```

## Examples

```python
from one_stop_analytics import Analytics

a = Analytics("sales.csv")
report = a.eda(cached=True)
a.clean()
a.export_excel("report.xlsx")
```

### Large CSV

```python
from one_stop_analytics.io import iter_data_chunks

for chunk in iter_data_chunks("huge.csv", chunksize=200_000):
    # process one chunk at a time
    print(len(chunk))
```

### Parallel batch

```python
from one_stop_analytics import batch_analyze

results = batch_analyze(["a.csv", "b.csv", "c.csv"], workers=4)
```

### CLI

```bash
osa eda sales.csv
osa eda sales.csv --no-cache
osa batch data/*.csv --workers 4
osa cache-clear
```

Cache location can be overridden with `OSA_CACHE_DIR`. The default is a per-user cache directory; avoid shared cache directories. Cache keys include the package/cache schema version.

**Output safety:** XLSX exports neutralize spreadsheet-formula-looking text. CSV, JSON and Parquet preserve literal values; if CSV files will be opened in spreadsheet software, apply an application-specific safe-export policy before sharing. Writing legacy `.xls` is intentionally unsupported; use `.xlsx`.

## License and commercial licensing

The public distribution is intended to be licensed under **GNU Affero General Public
License v3.0 only (AGPL-3.0-only)**; see `LICENSE`. The project may offer a separate
commercial license for organizations that need different permissions, subject to a
separate written agreement and confirmation that the licensor owns or is authorized
to license all relevant code.

Commercial licensing contact: **Srijan Das**.
Contact email: **otanalytics.contact@gmail.com**.
The commercial license document in this repository is a draft for legal review only;
it is not a customer-ready offer or contract. Third-party dependencies retain their
own licenses. See `LICENSING_AUDIT.md` and `THIRD_PARTY_LICENSE_AUDIT.md` for the
current, incomplete release audit.

**Release blockers:** confirm copyright ownership and dual-licensing authority for all contributions, finish the exact-version dependency audit, and obtain legal review of the commercial agreement before publication. The contact address above should be monitored before release.


## End-to-end workflow

```python
from one_stop_analytics import Analytics

result = (
    Analytics("sales.csv")
    .analyze(
        clean=True,
        include_statistics=True,
        include_ml=False,
        include_charts=True,
        output_excel="analytics.xlsx",
        output_html="analytics.html",
    )
)
```

For supervised ML:

```python
result = Analytics("sales.csv").analyze(
    target="Sales",
    include_ml=True,
    output_excel="analytics.xlsx",
    output_html="analytics.html",
)
```

The high-level workflow covers import → cleaning → automated EDA → statistics → optional ML → visualization → Excel/HTML reporting.

### Excel / Power BI-style transformations

```python
from one_stop_analytics import Analytics

t = Analytics("sales.csv").transform()
summary = t.group("Region", {"Revenue": "sum", "Cost": "sum"})
filtered = t.filter(Region="West")
```

CLI:

```bash
osa analyze sales.csv --output analytics.xlsx --html analytics.html
osa ml sales.csv --target Sales --task regression
```


## 1.8.8 performance & visualization hardening

- Optimized EDA cardinality reuse to avoid repeated full-column scans.
- Reduced visualization overhead for common bar charts and bounded automatic chart generation.
- Fixed release metadata/cache namespace alignment for 1.8.8.

- Fixed tab-delimited CSV auto-detection.
- Bounded CSV dialect/header sampling without loading the whole source file.
- Large CSV `eda()`, `profile()`, `correlations()` and `kpi()` now use bounded-memory streaming paths instead of dereferencing a missing full DataFrame.
- Decision-report CLI preserves streaming for large CSV inputs.
- Cache serialization is pandas-2.x/3.x compatible and preserves common DataFrame/Series metadata. Non-finite cache scalars are normalized safely.
- Formula-injection sanitization is applied only to XLSX exports; CSV, JSON and Parquet preserve literal text values.
- CLI converts common runtime errors into clean non-zero errors instead of raw tracebacks.

## 1.8.8 reliability baseline

- Raw-vs-analyzed report scopes are explicit and consistent across output formats.

## 1.8.8 transaction analytics

- Returns/cancellations-aware gross, return and net revenue metrics.

## v0.6.1 hardening
- Automatic identifier-column detection for ML (e.g. customerID, order_id, UUID-like columns).
- High-cardinality categorical protection in automatic chart selection.
- Automatic target/churn KPIs when a target is supplied to `analyze()`.
- Numeric scaling in classification preprocessing for more stable Logistic Regression.
- ROC-AUC included when binary classification probabilities are available.


## v0.7.1 Time-Series & Forecasting

Adds lightweight time-series detection, resampling, validation, baseline forecasting (naive, seasonal-naive, moving average, exponential smoothing), forecast metrics, future forecast output, and `Analytics.time_series()` / `Analytics.forecast()`. The workflow aggregates large raw event data before forecasting, making million-row retail datasets practical without requiring statsmodels.


### Time-series forecasting (v0.7.1)

Install optional forecasting models with:

```bash
pip install one-stop-analytics[forecasting]
```

The forecasting layer supports automatic date detection, resampling, leakage-safe missing-period handling, naive/seasonal-naive baselines, moving average, Holt, Holt-Winters, and metrics including MAE, RMSE, MAPE, RMSLE, sMAPE and MASE.

```python
from one_stop_analytics import Analytics

result = Analytics("sales.csv").forecast(
    date_column="date",
    target="sales",
    forecast_periods=30,
    method="auto"
)
```

## 1.8.8 Performance
- Vectorized EDA outlier statistics: shared quantile/IQR computation across numeric columns instead of repeated per-column scans.
- Target-aware categorical analysis converts the target once instead of repeating the same conversion for every categorical column.
- Business cohort indexing uses native pandas period ordinals instead of Python-level `apply()`.
- Existing pandas/NumPy/scikit-learn optimized implementations remain the computational backend; the package avoids reimplementing their core algorithms.
- Release artifacts exclude build caches, test caches, generated reports and previous wheels.

## v0.8.0 Advanced Analytics
- Advanced statistics: Spearman/Kendall, Mann-Whitney, Wilcoxon, Kruskal-Wallis, effect sizes, bootstrap confidence intervals, OLS diagnostics and VIF.
- Advanced ML: Extra Trees, GradientBoosting, SVM and robust model wrappers.
- AutoML: cross-validated model comparison and automatic winner selection.
- Business analytics: RFM, cohort, retention, funnel, CLV and ABC/Pareto.
- Integrated through `Analytics.auto_ml()`, `Analytics.advanced_statistics()`, `Analytics.business_analytics()` and `analyze()` flags.

## Decision-ready reports
`Analytics.analyze()` now adds a schema-aware `decision_report` containing Executive Summary, KPI, Data Quality, Trends, Top/Bottom Products, Customer Segments, Anomalies, Forecast, Key Findings, and Business Recommendations. The report is deterministic and only emits sections when the dataset contains sufficient evidence; unavailable analyses are marked unavailable rather than inferred.


## Decision-ready multi-format reports

Generate one analysis result and export it to HTML, PDF, XLSX, and JSON without re-running the analytics engine:

```bash
osa decision-report data.csv --output-dir reports
```

Or select formats:

```bash
osa decision-report data.csv --output-dir reports --formats html,pdf,xlsx,json
```

Outputs:
- **HTML** — self-contained client-facing report with embedded charts.
- **PDF** — client-ready static report.
- **XLSX** — detailed analyst workbook with report sections as sheets.
- **JSON** — machine-readable report payload for APIs/automation.

The report layer includes Executive Summary, KPI, Data Quality, Trends, Top/Bottom Products, Customer Segments, Anomalies, Forecast availability/results, Key Findings, and Business Recommendations. It is schema-aware and does not fabricate unavailable metrics.

## 1.9.0 reliability and release improvements

- Batch scheduling bounds queued futures to reduce memory overhead for very large input lists.
- Batch inputs reject duplicate paths and invalid worker/timeout/retry settings early.
- Cache override warnings are emitted once per process rather than on every cache access.
- Holt/Holt-Winters optimization avoids brute-force starts and uses a finite iteration budget to reduce worst-case forecast latency.
- Release tooling runs test, compile, wheel build/install, import, CLI and archive-integrity checks; the verification JSON records each executed command.
- Cache schema version is incremented to invalidate incompatible cached values.

## 1.9.2 reliability and release improvements

- Batch scheduling bounds queued futures to reduce memory overhead for very large input lists.
- Batch inputs reject duplicate paths and invalid worker/timeout/retry settings early.
- Cache override warnings are emitted once per process rather than on every cache access.
- Holt/Holt-Winters optimization avoids brute-force starts and uses a finite iteration budget to reduce worst-case forecast latency.
- Release tooling runs test, compile, wheel build/install, import, CLI and archive-integrity checks; the verification JSON records each executed command.
- Cache schema version is incremented to invalidate incompatible cached values.


## 1.9.3 output accuracy and presentation hardening

- Missingness KPIs are recalculated from canonical raw counts and source dimensions when available.
- JSON reports normalize missing/non-finite values to `null` and serialize dates and chart metadata consistently.
- HTML tables handle source columns that collide with index labels.

## 1.9.3 reliability and release improvements

- Batch scheduling bounds queued futures to reduce memory overhead for very large input lists.
- Batch inputs reject duplicate paths and invalid worker/timeout/retry settings early.
- Cache override warnings are emitted once per process rather than on every cache access.
- Holt/Holt-Winters optimization avoids brute-force starts and uses a finite iteration budget to reduce worst-case forecast latency.
- Release tooling runs test, compile, wheel build/install, import, CLI and archive-integrity checks; the verification JSON records each executed command.
- Cache schema version is incremented to invalidate incompatible cached values.

## 1.9.4 streaming report correctness

- Large CSV decision reports compute exact weekly and monthly sums in bounded-memory chunks.
- Aggregate trend charts are built from period summaries, not raw rows.
- Partial calendar periods are flagged and excluded from headline trend comparisons.
- Streaming duplicate counts stay unknown unless explicitly computed.
- HTML, JSON, PDF and XLSX share canonical KPI/trend data; XLSX includes a KPI Summary sheet.

## 1.9.4 reliability and release improvements

- Batch scheduling bounds queued futures to reduce memory overhead for very large input lists.
- Batch inputs reject duplicate paths and invalid worker/timeout/retry settings early.
- Cache override warnings are emitted once per process rather than on every cache access.
- Holt/Holt-Winters optimization avoids brute-force starts and uses a finite iteration budget to reduce worst-case forecast latency.
- Release tooling runs test, compile, wheel build/install, import, CLI and archive-integrity checks; the verification JSON records each executed command.
- Cache schema version is incremented to invalidate incompatible cached values.


## 1.9.6 forecast validation engine

- Chronological development validation and a separately reserved final test window.
- Expanding rolling-origin folds for temporal robustness checks.
- Seasonal-naive baseline always included in model selection and final-test comparisons.
- Forecast metrics include MAE, RMSE, WAPE, RMSLE and MASE (plus MAPE/sMAPE for continuity).
- Metric notes flag zero-actual limitations: WAPE is undefined when total absolute actuals are zero; MAPE excludes zero-actual rows. RMSLE clips negative values and flags that interpretation caveat.
- Hyperparameter/model selection uses development validation only; final test scores are reported separately and are not used for selection.


## Reporting and connector validation (v1.11.0)

```python
from one_stop_analytics.report import html_report, decision_report_xlsx, decision_report_json, export_dashboard
from one_stop_analytics.validation import validate_report_consistency, validate_charts, audit_recommendations
from one_stop_analytics.connectors import extract_sql, extract_crm_pages

# After constructing a canonical `report_result`:
html_report(report_result, "report.html")
decision_report_xlsx(report_result, "report.xlsx")
decision_report_json(report_result, "report.json")
print(validate_report_consistency(report_result, "report.html", "report.xlsx", "report.json"))
export_dashboard(report_result, "dashboard.html")  # offline snapshot
```

SQL extraction yields bounded chunks and permits only a single SELECT statement. Install `one-stop-analytics[connectors]` to use SQLAlchemy engines. `extract_crm_pages` is a generic paginated JSON REST adapter; check your CRM vendor's API contract and scopes before use. Recommendation audit flags missing evidence or limitations instead of manufacturing them.

## 1.11.0 reliability and release improvements

- Batch scheduling bounds queued futures to reduce memory overhead for very large input lists.
- Batch inputs reject duplicate paths and invalid worker/timeout/retry settings early.
- Cache override warnings are emitted once per process rather than on every cache access.
- Holt/Holt-Winters optimization avoids brute-force starts and uses a finite iteration budget to reduce worst-case forecast latency.
- Release tooling runs test, compile, wheel build/install, import, CLI and archive-integrity checks; the verification JSON records each executed command.
- Cache schema version is incremented to invalidate incompatible cached values.

## v1.12.0 — Unified Python analytics workspace

`Workspace` provides a single entry point for common spreadsheet, SQL, pandas/NumPy,
visualization and report workflows. It is a Python-first toolkit, not a pixel-for-pixel
replacement for the Excel, Tableau or Power BI desktop applications.

```python
from one_stop_analytics import Workspace

ws = Workspace("sales.xlsx", name="sales")       # CSV, TSV, Excel, JSON, Parquet, Feather
print(ws.profile())                               # quality + descriptive statistics
by_region = ws.groupby("Region", {"Revenue": "sum", "Cost": "sum"})
wide = ws.pivot(index="Region", columns="Month", values="Revenue", aggfunc="sum")
query = ws.sql("SELECT Region, SUM(Revenue) AS revenue FROM sales GROUP BY Region")
ws.chart(x="Region", y="Revenue", kind="bar", aggregation="sum", output="revenue.png")
ws.export("report.xlsx", include_profile=True)
ws.export("report.html")
ws.export("report.pdf")
ws.export("data.json", include_profile=True)
ws.dashboard("dashboard.html", charts=[{"x": "Region", "y": "Revenue", "kind": "bar"}])
```

For richer analytical SQL, install `pip install one-stop-analytics[duckdb]` and call
`ws.duckdb("SELECT Region, SUM(Revenue) FROM sales GROUP BY Region")`.
For a browser-based interactive application, install `pip install one-stop-analytics[dashboard]`;
use Streamlit/Plotly to build a front end around the same Python workspace and data contracts.
Excel workbook formula recalculation, Tableau Server publishing, Power BI semantic-model/DAX
compatibility, and a full spreadsheet cell editor are not provided by this library.

## Unified BI workspace (v1.13.0)

```python
from one_stop_analytics import Workspace

ws = Workspace("sales.csv", name="sales")
# Interactive browser dashboard (filters, KPI cards, chart drill-down)
ws.interactive_dashboard("dashboard.html", max_rows=50_000)
# Excel-compatible multi-sheet report with optional pivot summaries
ws.export_excel_report("sales_report.xlsx", pivots={
    "Regional Revenue": {"group": "Region", "metric": "Revenue", "agg": "sum"}
})
# Same canonical KPI contract feeds every export format
ws.export_report_bundle("reports", formats=("json", "html", "pdf", "xlsx"), pivots={
    "Regional Revenue": {"group": "Region", "metric": "Revenue", "agg": "sum"}
})

# Out-of-core query on CSV/Parquet files (source data is not loaded into pandas)
engine = Workspace.large_data_engine()  # pip install "one-stop-analytics[large-data]"
result = engine.query_csv("large_sales.csv", "SELECT Region, SUM(Revenue) AS revenue FROM source GROUP BY Region")
profile = engine.profile_arrow("large_sales.csv")  # requires PyArrow

# Database connectors (drivers depend on backend)
with Workspace.database("sqlite:///analytics.db") as db:
    result = db.query("SELECT Region, SUM(Revenue) AS revenue FROM sales GROUP BY Region")
# PostgreSQL: pip install "one-stop-analytics[postgres]"
# MySQL:      pip install "one-stop-analytics[mysql]"
```

The standalone dashboard embeds a bounded row sample to remain portable; it is not a server-side BI service. For larger-than-RAM files, run DuckDB SQL against source files first, then dashboard the bounded result. PostgreSQL/MySQL support depends on the matching SQLAlchemy driver being installed. SQL query helpers accept read-only SELECT/CTE statements; `write_table` is a separate explicit database write API.

## Optional dependency matrix and database integration (v1.13.2)

Install only the feature group needed:

| Extra | Installs / enables | CI validation |
|---|---|---|
| `forecasting` | statsmodels forecasting | Clean install + import smoke |
| `advanced` | statsmodels advanced analytics | Clean install + import smoke |
| `connectors` | SQLAlchemy database APIs | Clean install + import smoke |
| `duckdb` | DuckDB SQL over local files | Clean install + import smoke |
| `large-data` | DuckDB + PyArrow batch scanning | Clean install + import smoke |
| `postgres` | SQLAlchemy + psycopg 3 | Live PostgreSQL service integration |
| `mysql` | SQLAlchemy + PyMySQL | Live MySQL service integration |
| `visual` | Plotly | Clean install + import smoke |
| `dashboard` | Streamlit + Plotly | Clean install + import smoke |
| `all` | All optional feature dependencies | Clean install + import smoke |

Example installs:

```bash
python -m pip install "one-stop-analytics[postgres]"
python -m pip install "one-stop-analytics[mysql]"
python -m pip install "one-stop-analytics[large-data]"
python -m pip install "one-stop-analytics[all]"
```

The repository CI has separate `Optional dependency matrix`, `Clean install`, and `Database integration` workflows. PostgreSQL/MySQL integration tests require disposable test databases and run in CI service containers; locally they skip unless `OSA_TEST_DATABASE_URL` is set. Never point these integration tests at a production database: they create and drop uniquely named test tables.

For maintainers, run `python scripts/check_optional_dependencies.py postgres` (replace `postgres` with an extra name), `python scripts/clean_install_smoke.py` after building a wheel into `dist/`, and `python -m pytest -q tests/test_database_integrations.py` with the test database environment variables configured.

## 1.13.2 optional dependency and database integration

- Adds a CI matrix for each documented optional dependency extra, with import checks in clean runner environments.
- Adds fresh-virtual-environment wheel installation smoke tests across Linux, Windows, macOS, and supported Python lanes.
- Adds PostgreSQL and MySQL service-container integration tests for write/read round trips, parameterized queries, and read-only query enforcement.
- Uses SQLAlchemy dialect-aware identifier quoting for portable table reads, including MySQL without ANSI_QUOTES.
- Expands the `all` extra to include the optional Streamlit dashboard dependency.

## 1.13.2 optional dependency and database integration

- Adds a CI matrix for each documented optional dependency extra, with import checks in clean runner environments.
- Adds fresh-virtual-environment wheel installation smoke tests across Linux, Windows, macOS, and supported Python lanes.
- Adds PostgreSQL and MySQL service-container integration tests for write/read round trips, parameterized queries, and read-only query enforcement.
- Uses SQLAlchemy dialect-aware identifier quoting for portable table reads, including MySQL without ANSI_QUOTES.
- Expands the `all` extra to include the optional Streamlit dashboard dependency.

## 1.13.2 optional dependency and database integration

- Adds a CI matrix for each documented optional dependency extra, with import checks in clean runner environments.
- Adds fresh-virtual-environment wheel installation smoke tests across Linux, Windows, macOS, and supported Python lanes.
- Adds PostgreSQL and MySQL service-container integration tests for write/read round trips, parameterized queries, and read-only query enforcement.
- Uses SQLAlchemy dialect-aware identifier quoting for portable table reads, including MySQL without ANSI_QUOTES.
- Expands the `all` extra to include the optional Streamlit dashboard dependency.


## Credit-note reconciliation (diagnostic only)

```python
from one_stop_analytics import reconcile_credit_note_lines

result = reconcile_credit_note_lines("retail_export.csv")
print(result["report"]["ledger_readiness"])
result["detail"].to_csv("credit_note_line_audit.csv", index=False)
```

The credit-note matcher is a **provisional diagnostic**, not an accounting posting engine. It uses customer, SKU, unit price and chronology to identify candidate prior-sale quantities. It does not prove the original invoice relationship. Statutory-ledger use remains blocked unless source-system references, stable line IDs, tax/currency fields, transaction type, duplicate policy and independent finance controls are supplied and validated.
