ADA: Automated Data Analyst

⭐ Star ADA if it saves you an afternoon · Try it in the browser · Docs · What's new in 0.6.0
_{Read this in 中文 · 日本語 · 한국어 · Español · Português · Deutsch · Français · Русский}

ADA computes numbers from data files and checks numbers stated about them. Every number comes from pandas, SciPy or statsmodels, with the calculation and the rows behind it. A stated number is verified against the data, or reported unverified with the reason and the one question that would settle it. It is a Python package and a command line, for people and for coding agents such as Claude Code and Codex.

pip install automated-data-analyst     # Python 3.11 or newer

$ ada claim flights.csv "The average departure delay was about 13 minutes."
verified: The average departure delay was about 13 minutes.
  12.63907026 (328,521 rows) from mean(dep_delay) lies in 12 to 14, which about 13 minutes stands for.
  calc: mean(dep_delay)
  assumes: Read "departure delay" as dep_delay.
  assumes: Left out 8,255 rows with dep_delay missing.
  assumes: Read "about" as 12 to 14.
  assumes: The unit "minutes" comes from the claim; the check compares numbers only.

$ ada claim flights.csv "The average delay was 13 minutes."
unverified: The average delay was 13 minutes.
  The claim's words fit more than one column, and they give different answers: dep_delay gives 12.63907026; arr_delay gives 6.895376757.
  to check it: Which column is meant: dep_delay or arr_delay?

verified means this number, from these rows, by this calculation, with the assumptions listed. unverified is not false: only the reason failed_check says the data give a different number. --json gives the whole record, and ada.check_claim(...) does the same in Python. See Checking claims for the reasons, intervals and units.

ada scan lahman/ --template answers.yml      # the files, how they join, the questions to ask first
ada ask flights.csv "average dep_delay by origin" --json   # the numbers, the calculation, the rows used
ada claim lahman/ "Barry Bonds hit 73 home runs in 2001." --answers answers.yml

ada scan asks what the analysis should find out, what a row is, and each choice ADA would otherwise make by default, with its proposed answer; ada ask and ada claim take the edited file. When an answer rests on a choice, such as leaving World and region rows out of an average, it says which, and --decide picks the other (Decisions). A question or claim about a folder is answered from the file it fits, or from two files joined along a link ADA is sure of. A question ADA can't answer comes back refused, with the reason. See Ask ADA and Reading a folder of tables.

Before it answers, ADA reports the rows it left out and why, counts each subject once when several rows come from one, says when groups reverse a pooled figure, adds up the count column of a table of counts, and gives a reason instead of a number when the data are too thin.

ada skill               # .claude/skills/ada (Claude Code) and .agents/skills/ada (Codex)
ada skill --user        # the same in your home folder, for every project

It also installs as a plugin (how). The skill has the assistant let ADA do the arithmetic, check every number it states with ada claim, and ask you ADA's question instead of choosing a reading.

ada demo mice && cd mice           # an example study to try first
ada init data/measurements.csv     # asks about the study; writes study.yml
ada build                          # writes paper-assets/
ada verify                         # rebuilds and compares every number

ada build makes a data audit, a data dictionary, a record of every exclusion, results tables in Word, LaTeX and CSV, figures with captions and a methods draft. See Paper assets for a study. ada analyze gives a first look at any table, and ada app opens the same in a browser (pip install "automated-data-analyst[app]").

pip install "automated-data-analyst[model]"
ada model titanic/ --metric accuracy --out submission.csv

ada model predicts one column of a table from the others, as a tabular Kaggle competition asks. The features come from rules on the columns' shapes, LightGBM, XGBoost and a linear model are blended on out-of-fold predictions, every score is cross-validated, and the submission is checked before it is written. See Predicting a column.

ada auto does the same with a wider search and takes longer: CatBoost, LightGBM with random split points, extremely randomized trees and a neural network join the blend, a second layer is fitted on their out-of-fold predictions, and the weights come from greedy selection. Each step stays only when the folds say it helps. --jobs N fits N learners at once and gives the same model.

It is scored on Kaggle competitions with no code for any one of them: the runner passes ADA the competition's folder and the name of its metric, and ADA does the rest. On the 22 scored so far it places in the top 10% on 2 (Titanic, and Housing Prices on Kaggle Learn), in the top 15% on 4 and in the top 30% on 12. Store Sales, a forecast of 1,782 series, is its weakest, at 58%. Every score.

Numbers that need three files joined, many phrasings ("horsepower" for hp, slopes, several numbers in one claim), and some year columns read as numbers rather than dates. These come back unverified or refused with a reason. See Not covered yet.

73 cases on 20 public datasets, each expected value computed separately with pandas, SciPy and statsmodels; holdout cases are only scored (details).

Each change is also scored on rounds of new public data, six datasets at a time from statistics offices, city portals and research projects, with claims written as reports write them; the pull request gives the scores.

All documentation · Contributing · Credits · Citing · MIT License