Metadata-Version: 2.4
Name: atars
Version: 0.1.0
Summary: Terminal analytics - clean, profile, model and forecast any table.
Author: Priyanshu Kumar
Project-URL: Homepage, https://atars.netlify.app
Project-URL: Documentation, https://atars.netlify.app/methodology.html
Project-URL: Changelog, https://atars.netlify.app/changelog.html
Project-URL: Issues, https://atars.netlify.app/contact.html
Keywords: analytics,data-analysis,terminal,tui,cli,pandas,forecasting,automl,data-quality,reporting,csv,excel,duckdb,charts
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: pandas>=2.2
Requires-Dist: numpy>=1.26
Requires-Dist: scikit-learn>=1.4
Requires-Dist: statsmodels>=0.14
Requires-Dist: duckdb>=1.0
Requires-Dist: pyarrow>=15
Requires-Dist: matplotlib>=3.8
Requires-Dist: reportlab>=4.0
Requires-Dist: textual>=0.60
Requires-Dist: textual-plotext>=1.0
Dynamic: license-file

# ATARS — free terminal analytics

Clean, profile, model, forecast and report on any spreadsheet, from the command
line or from Python. The same engine as the ATARS desktop app, with no AI, no
account and nothing uploaded anywhere.

```bash
pip install atars
```

Python 3.11 or newer.

## The window

Type `atars` with no arguments and you get a window with clickable tabs.

```
 ATARS - january.csv
 january.csv · 120 rows × 4 columns      [ Export CSV ] [ Open ]
 120 rows loaded
 Overview   Data   Quality   SQL   Charts   Models   Report
 -------------------------------------------------------------
  region  revenue
  East    16674.0
  West    15194.0
  South   14792.0
  North   12887.0
 o Open   e Export CSV   f5 Refresh   q Quit
```

Click a tab, or press **1**–**5** for the five groups; the mouse works, and so
do the arrow keys. **o** opens a file, **e** exports the table on screen,
**f5** re-runs everything, **q** quits. All of them are single keys, and a
focused text box takes its own typing first — so `q` in the SQL box is a `q`.

### Opening a file

Press **o** or click **Open**. You get three ways to find it, because a terminal
cannot receive a dropped file:

- **Your system's file dialog** — the normal Windows/macOS/Linux picker, via
  *Browse system…*
- **A folder tree**, showing only folders and files ATARS can read
- **Recent files**, because it is usually the one you had last

…or type a path. `atars -f sales.csv` skips the dialog entirely.

| Group | Tabs |
|---|---|
| **Understand** | Overview · Data · Quality · Metrics |
| **Prepare** | Clean · Prep · Combine · Features · SQL |
| **Explore** | Charts · Stats · Pivot · Trends · Business |
| **Model** | Models · Explain · Drift · Forecast · Discover |
| **Report** | Report |

The same left-to-right workflow the desktop app uses, so if you know the app you
know the window. Groups are real tabs: pick a group, then a tab inside it.

**Prep** builds a recipe step by step from the 22 transform ops — add steps,
undo, apply, save the result, or print the pandas that reproduces it without
ATARS installed. Applying shows the rows it produced, not only how many there
are; **Clean** shows the cleaned table the same way. Anything a Save button
writes has been on screen first.

Every result table has a **Save table** button directly underneath it, which
writes that table as a CSV beside the file you opened and names what it wrote.
Press **e** or click **Export CSV** to do the same for whatever table is on
screen, and click any column heading to sort by it. A table stops at 500 rows
and says so on its last line rather than letting you read a cut as the whole
file. Every pane scrolls, so a small terminal clips nothing.

A workbook with more than one sheet asks which one — opening the first without
asking analyses whichever tab happened to be first.

**Combine** joins a second file — chosen with the same picker as Open — and
**Use as data** makes the joined table the one every other tab works on.

**Add chart** keeps the chart you are looking at and leaves it on the tab, so
the next one is drawn below it rather than instead of it — as many as you make,
each with a **Remove** button, and each one in the report.

### What reaches the report

A report about the file, with none of the work in it, is half a report. What you
run reaches the exported document by the same two doors the desktop app uses:

- **A fixed answer for this data files itself** — cleaning, dataset
  understanding, features, moving averages, decomposition, change points,
  cohorts, growth, concentration, segments, drift. There is nothing to choose
  between, so nothing is asked.
- **A value you went hunting for waits for `Add to report`** — statistical
  tests, models, explanations, pivots, SQL and forecasts. You run these ten
  times to find the one worth stating, and the other nine are not findings.

**Everything arrives as a table, not as a sentence about one.** Each kept
result carries the table the tab drew — a leaderboard and the feature importance
under it, a pivot, a query result, both explanation tables — printed in the
report in full, and where a long one is cut the report says how many rows there
really were. A chart cannot be drawn in Markdown, so each one you add carries
the numbers it was drawn from instead: the same aggregation, the same top-N cut,
plus the two or three sentences a reader would otherwise have to squint at the
bars to work out.

The report also prints the data itself — column profile, descriptive
statistics, the strongest correlations, the category breakdown, missing values
and outliers — so every figure it states can be checked inside the document,
without the app. Markdown, HTML and PDF all carry the same tables.

Each tab says whether what it is showing is in the report yet, and nothing is
filed twice. **Clear kept** on the Report tab takes it all back out, and opening
another file — or making a join the data — empties it for you, because those
numbers were about the old table.

### Charts

**Eighteen types.** Each declares what it needs, so the pickers it does not use
are hidden rather than silently ignored.

| | |
|---|---|
| *Distribution* | Histogram · ECDF · Box · Strip |
| *Relationship* | Line · Area · Scatter · Density heatmap · Correlation |
| *Comparison* | Bar · Bar (horizontal) · Grouped · Stacked · Share · Funnel · Waterfall · Heatmap (pivot) · Count |

Every chart that groups by a category also takes an **aggregation**
(sum, mean, count, median, min, max), a **top-N** cut, a **sort order** and
optional **value labels** — and says how many categories the cut left out,
rather than dropping them quietly.

Everything is shown in the window. Saving a file sits next to each result, never
instead of it — a tool that can only say *"wrote chart.png"* has made you open
something else to find out what it did.

Analysis runs on a worker thread, so the window keeps responding while AutoML
works. `atars -f sales.csv` opens with that file already loaded.

## The line-based shell

`atars shell` gives a prompt instead, for anyone who prefers typing. Open a
file once; every command afterwards runs against it.

```
$ atars
ATARS 0.1.0 - free terminal analytics
open a file to begin:  open sales.csv        ·  help  ·  exit

atars> open sales.csv
sales.csv - 120 rows x 4 columns
atars [sales.csv]> quality
quality score   100.0 / 100
...
atars [sales.csv]> sql SELECT region, SUM(revenue) FROM data GROUP BY 1
atars [sales.csv]> automl --target revenue
atars [sales.csv]> exit
```

Tab completes commands and column names, and the arrow keys walk your history.
`open` accepts an unquoted path with spaces, and everything after `sql` is the
query - no shell quoting, so SQL's own `"quoted identifiers"` just work.

Extras only the shell has: `columns`, `head [N]`, `ls`, `cd`, `pwd`, `close`.

Because the file is opened once, the engine's result cache stays warm for the
whole session - the second command on a dataset is a lookup, not a recompute.

`atars -f sales.csv` opens the shell with that file already loaded.

## One-shot commands

The same commands work without the shell, for scripts and pipes:

```bash
atars quality sales.csv
atars automl sales.csv --target revenue
atars report sales.csv --format pdf
```

```
$ atars quality sales.csv
quality score   100.0 / 100
shape           120 rows x 4 columns

missing values
  none

outliers
 Column  Outliers  % of Data
revenue         1       0.83
```

A full transcript of every command is in [docs/DEMO.md](docs/DEMO.md).

## Commands

| | |
|---|---|
| `atars profile FILE` | shape, types, summary statistics |
| `atars quality FILE` | score, missing values, outliers |
| `atars clean FILE -o out.csv` | cleaning studio; reports every change |
| `atars sql FILE -q "SELECT …"` | DuckDB over the file, as table `data` |
| `atars stats FILE` | correlation, hypothesis tests, A/B |
| `atars automl FILE --target T` | ranked models, with `--importance` |
| `atars forecast FILE --date D --value V` | project a series forward |
| `atars drift FILE --reference R` | compare against a baseline file |
| `atars cluster FILE` | k-means; picks k when you don't say |
| `atars anomaly FILE` | isolation forest |
| `atars business FILE --kind pareto` | growth, pareto or segment |
| `atars insights FILE` | rule-based findings |
| `atars chart FILE --y COL -o c.png` | line, bar, scatter or histogram |
| `atars report FILE --format pdf` | a full report: markdown, html or pdf |
| `atars merge A B --on KEY` | join two files |
| `atars recipe run R.json FILE` | a saved, repeatable transform |

Every command takes `--json`. Exit codes mean something — `0` fine, `2` you
asked for something impossible, `3` that feature is in the app — so these
compose in a shell script:

```bash
atars quality sales.csv --json | jq '.score'
```

### Recipes

A recipe is a JSON list of transform steps that runs the same way every time.

```bash
atars recipe ops                       # the 22 steps available
atars recipe run clean.json sales.csv -o out.csv
atars recipe code clean.json           # the pandas that does the same thing
```

`recipe code` prints runnable pandas with no ATARS import, so a pipeline you
build here keeps working for someone who doesn't have this installed.

## From Python

```python
import atars

ds = atars.load("sales.csv")

ds.quality_report()                     # score plus the tables behind it
frame, audit = ds.clean()               # what changed, step by step
ds.automl(target="revenue")             # ranked models
ds.forecast("month", "revenue", 6)
ds.pareto("product", "revenue")
ds.merge("february.csv", on="product")
ds.report(fmt="pdf", out_dir="reports")
```

The command line is a printer over this API, so anything one can do, the other
can do too.

## What it tells you

Open a file and the Overview reads it — no column picking, no model:

```
$ atars insights sales.csv
severity  finding                         detail
--------  ------------------------------  --------------------------------------------------
medium    Xylene has outliers             657 of 8,459 values (7.8%) sit outside the usual
                                          range; the most extreme is 14.32, well above the
                                          median of 2.7.
low       wind_speed_10m and              they rise together (r = +0.85). Worth checking
          wind_speed_100m move together   whether one explains the other.
low       rain is skewed                  a long tail of large values (skew +16.0); its
                                          median (0) describes a typical row better than
                                          its mean (0.0996).
info      Looks like small business data  total revenue 59,546, avg order value 496.22.
```

Fourteen checks run over the frame, ranked so the most consequential is first:

- **What moves it** — which columns actually explain the main measure
- **How predictable it is** — whether a model can explain it at all, or whether
  most of what drives it simply is not in the file
- **Change points** — when the measure shifted, and by how much
- **Types that block analysis** — numbers and dates stored as text
- Plus missing values, duplicates, constant and identifier columns, skew,
  outliers, correlations, concentration, gaps between groups, and trend

No single check can contribute more than three findings, so twenty skewed
columns cannot crowd out everything else. Every sentence carries the number it
is about, and `--json` returns the evidence each was computed from.

Nothing here calls a model. It is arithmetic, which is why every claim can be
checked.

## Speed

`atars --help` returns in about 9 ms of import: no command loads pandas until it
actually runs. Thread limits for OpenMP, MKL, OpenBLAS and pyarrow are applied
before numpy loads, because those libraries read their thread counts once and
ignore every change afterwards. `n_jobs` comes from the machine's real core
count, never `-1`, so one core stays free. Repeated commands on the same file
reuse the engine's result cache.

Both rules are tests, not intentions — see `tests/test_startup.py`.

## What is not here

The AI analyst, web-aware answers and narrated reports are in the ATARS desktop
app: <https://atars.netlify.app>

This package does not contain that code. Not disabled, not key-gated — absent.
The wheel ships a twelve-line stub where the AI package would be, and
`tests/test_build.py` fails the build if a provider import or a credential read
ever reaches the artifact. `atars report` pins narration off rather than relying
on a default.

## Developing

The engine lives in the parent tree, so a dev checkout needs it importable:

```bash
python -c "import site,os;open(os.path.join(site.getsitepackages()[-1],'atars_engine_dev.pth'),'w').write(os.path.abspath('..'))"
pip install -e .
python -m pytest tests/ -q          # 80 tests
python tools/demo.py                # every command, end to end
```

## Releasing

```bash
python tools/build_wheel.py
```

That vendors the engine into `src/`, builds the wheel, and deletes the copy
again. The delete matters: a copy left in `src/` shadows the live engine, and
every dev run afterwards would silently test a stale snapshot with AI already
stubbed out — the exact drift this layout exists to prevent.

## Licence

Free to install and use, for anything, without an account — see `LICENSE.txt`
beside this file. Not open-source: the code stays the author's.
