← All resources

Data Analysis Provenance: What to Record and How

12 min read
data analysis provenance
Data Analysis Provenance: What to Record and How

Data Analysis Provenance: What to Record and How

Researcher reviewing analysis provenance records

Data analysis provenance is the documented history of how a result came to exist: which data went in, which steps changed it, which code and software versions ran, which parameters were set, and who made each decision. If a supervisor, reviewer or collaborator can follow that history from the final number back to the raw file, your analysis has provenance. If they can’t, you have a result they have to take on trust.

This guide covers what provenance means in practice, what to capture, where it differs from data lineage, and how to build it into your workflow before a deadline forces you to reconstruct it from memory.

Plotstudio
plotstudio.ai
Keep Every Analysis Inspectable
PlotStudio AI keeps plans, code, outputs, and statistics together, so researchers can review how an analysis was produced.
Explore PlotStudio AI

TL;DR

  • Provenance is a record of the entities, activities and people involved in producing a result. The W3C PROV family of specifications is the standard way to model it.
  • Capture the raw data reference, code, runtime environment and parameters. Do not try to version-control the raw data itself.
  • Automatic capture records what was done. You still have to write down why.
  • Provenance supports FAIR reuse, peer review and your own thesis defense.
  • PlotStudio AI, our agentic analytics platform for researchers, keeps the plan, code, outputs and statistics together so each analysis can be inspected afterward.

Table of Contents

What data analysis provenance means

The W3C defines provenance as information about the entities, activities and people involved in producing a piece of data or a thing. That information can then be used to judge the quality, reliability or trustworthiness of the result.

Translate that into a research project and three kinds of things need a record:

  • Entities: the raw dataset, each cleaned version, a model object, a table, a figure.
  • Activities: filtering rows, recoding variables, imputing missing values, fitting a model, running a post hoc test.
  • Agents: the person, script or AI agent that performed each activity, and under what instructions.

A useful test: pick any number in your results table and ask whether you can name the exact input file, the exact code that produced it and the exact settings used. If one link is missing, the chain is broken.

Provenance versus lineage

The two terms overlap and are often used interchangeably. In practice, lineage usually describes the path data takes through systems and transformations, which is the engineering view. Provenance is broader: it also covers the people, the methods and the reasons behind each step, which is what a reviewer or an ethics auditor cares about. If you want the lineage angle in more depth, we cover it in our articles on data provenance versus lineage and on how to implement data lineage.

Provenance versus lineage — overview diagram

Why researchers need it

Reviewers and supervisors ask for it

The usual failure is mundane. A reviewer asks why you excluded a group of participants, or a supervisor reruns your script and gets a different coefficient. Neither is accusing you of anything. They are asking for provenance, and if you can’t supply it quickly the paper stalls.

FAIR reuse depends on it

The FAIR principles make provenance an explicit requirement. Principle R1.2 asks that metadata describe how a resource was generated, why, by whom, and what processing or cleansing was applied, so that others can judge whether it meets their quality criteria.

Research waste and trust

A paper on provenance metadata in biomedical research argues that reproducibility lets the community build on validated results and protect patients from harm that could come from incorrect findings. The Workflows Community Initiative makes a related point: claims to follow the evidence are hard to justify when evidence cannot be traced back to primary data.

In clinical work the stakes are practical. A study of provenance tracking in clinical data warehouses notes that recording the origin, history and transformations of data helps address errors and quality issues and makes processing workflows easier to reproduce.

What to record: a practical checklist

The guidance on reproducible computational research converges on one idea: record the raw data, source code, runtime environment and parameters, and link each result to the process that generated it. Here is that list made concrete.

Layer What to capture Example
Source data Where the file came from, when, and a checksum or version ID Registry extract dated 3 March, file hash stored in the project log
Cleaning steps Every exclusion, recode and imputation, in code Dropped 14 rows with implausible ages, with the rule that selected them
Analysis code Scripts or notebooks, under version control Cox model script, committed with its output
Environment Language and package versions, operating system R version and package list, or a Python requirements file
Parameters Seeds, model formulas, thresholds, correction method Random seed, covariates, Benjamini-Hochberg at 0.05
Outputs Tables, figures and statistics tied to the run that made them Figure 2 linked to script, data version and parameters
Rationale Why you chose each method or exclusion Note explaining why a mixed-effects model replaced repeated ANOVA

Version the workflow, not the raw data

One point often gets reversed. Effective provenance tracking is mostly about capturing the state of the workflow, such as code, input files and environment, rather than version-controlling the primary data. Treat raw data as an immutable, secured source in its own archive, and let your records point to it. For patient or other special-category data this also keeps the sensitive file out of repositories where it does not belong.

Do not forget the “why”

Automatic capture is good at logging what ran. It cannot tell a future reader what you were thinking. Work on reproducible research systems points out that manual annotations are essential for explaining intent, the piece most often missing when someone else tries to understand your analytical decisions.

A short note beside each non-obvious decision is enough: “Excluded site C because of a protocol deviation documented in the trial master file.” Two minutes now saves an afternoon of reverse engineering later.

Three common ways provenance breaks

  1. Point-and-click steps with no record. A spreadsheet filter or a manual recode leaves no trace. The cure is to do transformations in code or in a tool that logs them. Our guide to making Excel analyses audit ready walks through moving spreadsheet work into a documented workflow.
  2. Code without its environment. A script that ran last spring may fail or give different output after a package update. Record versions alongside the code.
  3. Results pasted into a manuscript. Once a table is copied into a document, the link to the run that produced it is gone unless you stored it. Export tables and figures straight from the analysis and keep the run identifier next to them.

Tools that capture provenance

There is no single answer, and most researchers combine several layers.

  • Scripts plus version control. The baseline: R or Python code in Git, with a recorded environment. Cheap and flexible, but it depends on discipline.
  • Workflow systems. Platforms such as Galaxy, DataLad and AiiDA link results to the process that generated them automatically. They suit pipelines that run repeatedly, though they add setup overhead.
  • Accountable analysis in R. Published work describes a system for an accountable data analysis process in R, noting that producing transparent analyses can be difficult for beginners and tedious for experienced users alike.
  • Standards and ontologies. If you publish data for reuse, modeling provenance with PROV makes it interoperable with other systems.

A note on cost: tracking can add computational overhead when data volumes are large, but researchers working on clinical data quality describe it as a necessary trade-off for continuous quality management. For a typical thesis-sized dataset the overhead is trivial next to the cost of an irreproducible result.

Provenance as a network, not just a log

Provenance records can do more than sit in an archive. Researchers at the University of Oxford describe provenance network analytics, which treats provenance records as a graph and uses network metrics to infer properties such as data quality or importance. For most thesis projects this is more than you need. It does show why structured, machine-readable records are worth the effort: they can be queried, not just read.

Our perspective: the agent is a new actor that needs a record

We built PlotStudio AI around a simple observation. When an AI agent analyzes your data, it becomes one more agent in the provenance chain, and a one-shot chat answer leaves almost nothing behind. You get a number or a chart, but not the assumptions, the intermediate checks or the code that produced it. For research that is not good enough.

So we designed for the full workflow. In PlotStudio AI, specialized agents plan an investigation, write and run real code, inspect intermediate results and synthesize findings. The methodology, code, outputs, statistics and visualizations stay available for review. With Plan Mode you can read and edit the proposed approach, including methods and assumptions, before anything runs. That is provenance of intent, the “why” that logs alone don’t capture.

Our perspective: the agent is a new actor that needs a record — overview diagram

We also think this layer belongs next to your existing tools, not in place of them. R, Python, Stata, SPSS, SAS, Jupyter and RStudio provide the statistical computing. Agentic analytics adds a layer that can plan, execute, inspect, validate and document a complete analysis. Your methods stay yours. The agent’s work becomes inspectable.

The final point is privacy. Analyses can run locally on your machine, so datasets that should not be uploaded to conventional cloud analytics platforms do not need to be. We say more in our piece on keeping provenance intact with on-device analysis and in audit-ready lineage for sensitive data.

— Aymen

A provenance-first workflow, step by step

You can follow this in any toolchain. Where PlotStudio AI fits is noted at each step.

  1. Freeze the raw data. Store the original file read-only and note its source, date and checksum.
  2. State the objective and method before running anything. Write down the question, the planned tests and the assumptions. In PlotStudio AI this is the plan you review in Plan Mode.
  3. Do every transformation in code. Cleaning, recoding and exclusions each get a line you can read later.
  4. Record the environment. Language, package versions and seeds.
  5. Annotate decisions. One sentence of reasoning per non-obvious choice.
  6. Export outputs with their run. Keep tables and figures tied to the code that made them. PlotStudio AI preserves completed work as searchable Analysis Pages and exports to notebooks and PDF reports.
  7. Test reproducibility. Ask a colleague, or yourself on a clean machine, to rerun it. Our guides on research reproducibility and a one-command reproducible workflow for PhD researchers go deeper on this step.

If your group has house rules, such as required procedures, statistical conventions or reporting expectations, PlotStudio AI Skills let you encode them so the agent follows the same methodology every time.

Trying it on your own data

PlotStudio AI has a free trial, so you can run a real dataset through the plan, execute and review cycle before deciding anything. Paid options on the pricing page are Managed Credits at 69.99 USD per month and Bring Your Own Key at 39.99 USD per month. The academic page lists Bring Your Own Key at 399.90 USD per year. Departments considering a managed rollout can look at the enterprise pilot, which has a one-off 500 USD pilot fee.

FAQ

What is provenance in data science?

It is the record of the people, institutions, entities and activities involved in producing a piece of data or a result. In data science it covers the origin of the data, every transformation applied and the code and parameters used. The W3C PROV specifications are the common standard for modeling it.

What is the difference between data provenance and data lineage?

Lineage usually traces how data moves and changes across systems. Provenance includes that path and adds the agents, methods and reasons behind it. For research, provenance is the more useful frame because reviewers ask about decisions as well as data flow.

What is an example of provenance in a research project?

A regression table in a paper that links to the script that fitted the model, the cleaned dataset version it used, the package versions installed and a note explaining why certain participants were excluded. Anyone can then rerun it and see the same numbers.

Do I need to version-control my raw data?

Usually not. Keep raw data as a secured, unchanged source in an archive and version the code, environment and parameters that act on it. This is especially sensible for sensitive or patient-level data.

Sources