Reproducible Analysis With Scripts

Why Use a Script?

A cleaning decision is useful only if it can be applied consistently. When steps are carried out by hand, it can be difficult to remember their exact order or repeat them without variation. A script records those steps as instructions: given the same original file and the same computing setup, the script can run them again to produce the same cleaned output.

Here, “reproducible” has a practical meaning. Another run of the recorded workflow should produce the same result from the same source data, rather than depending on a person remembering what to click or change. A script does not decide whether a cleaning choice is appropriate; the choices still need to be documented and justified. Earlier material on documenting data-cleaning decisions provides the foundation for turning those choices into explicit instructions.

A basic workflow has three parts: an original input file, a script that carries out the documented steps, and a saved output. The original file is read, not silently overwritten. The script creates the cleaned output at a known location, so the workflow can be run again without reconstructing the steps from memory.

A Small Dataset and Its Cleaning Decisions

Suppose a hypothetical clinic dataset contains four records. The original file, named study_raw.csv, has these rows:

For this demonstration, the documented decisions are limited and explicit: remove extra spaces from group labels, standardize the two group names to “Control” and “Intervention,” interpret dates in year-month-day format, and retain an empty weight value as missing. These decisions do not imply that missing weights should be filled in or that any record should be removed. They specify how the recorded values are to be represented.

The example uses Python with the pandas library. The script is stored in a project folder alongside a data folder containing the original CSV. It writes the cleaned CSV to an output folder. Keeping the source separate from the output makes it clear which file the script reads and helps prevent accidental changes to the original.

Writing a Short Script

The following script uses paths relative to the location of the script file. For this example, save it in the project folder, with the original CSV in data/study_raw.csv. The script creates the output folder if it does not already exist.

The first lines import the tools the script needs. Path helps specify file locations, while pandas reads and writes tabular data. The root path is set to the folder containing the script. From there, the input and output paths are specified, so the script does not depend on which folder happens to be active when it is run.

The read step loads the CSV into a table called df. The group-label step applies the decisions in order: remove leading and trailing spaces, convert the text to lowercase, then map each recognized label to its standard form. The date step parses each value according to the stated format. Using errors="raise" means an unparseable date causes the script to stop with an error rather than silently being treated as a valid date. The save step creates the output folder if needed and writes the cleaned table as a CSV. The index=False option prevents pandas from adding an extra row-number column.

What the Script Saves

For this example, the resulting CSV has the following content. A blank field in the weight column represents the retained missing value.

CSV is a plain-text table format, so the saved dates appear as date strings even though the script parsed them as dates before saving. The script leaves the row order unchanged and does not alter the weight values. Saving a transformed file is distinct from changing the original: the source remains available for comparison or for another run.

Why Repeating the Steps Works

For the example’s group labels, the transformation maps each recognized form to a single standard label. Once a label is “Control,” applying the same cleaning again still gives “Control”; the same is true for “Intervention.” This is an idempotent transformation: applying it twice has the same result as applying it once. For a value \(x\) that is one of the recognized labels, write the label transformation as \(g\). Then:

This property is useful because minor differences in capitalization or surrounding spaces do not accumulate across repeated applications. However, idempotence alone does not guarantee a reproducible workflow. If the script reads a different file, uses different mapping rules, or depends on a different software behavior, the output may differ. Reproducibility requires the input and the instructions to be sufficiently well specified as well as the steps to be repeatable.

What Makes a Workflow Reproducible?

A script is a record of actions, but several practical details determine whether it can be rerun successfully. The input path must point to the intended original file. The script must state the transformations clearly enough that another person can understand what each one does. The output path should be explicit. The required software, such as Python and pandas, must be available, and differences in software versions may matter for some operations.

The scope of this example is deliberately modest. It demonstrates how to record transformations; it does not establish that the chosen cleaning decisions are scientifically appropriate. For instance, standardizing category labels is suitable when the variations are known to represent the same categories. If a label is unfamiliar, a script should not automatically guess its meaning. The decision about what to do with an unexpected value needs to be made and documented rather than hidden inside a transformation.

Common Mistakes

• Overwriting the source file. The wrong reasoning is that saving the cleaned data over the original is simpler. The correction is to keep the original intact and write the transformed data to a separate output file.
• Assuming a script automatically makes every decision appropriate. Code can repeat a mistaken transformation consistently. Document and justify the cleaning choices before encoding them.
• Relying on memory for a step that is absent from the script. If a person edits a value by hand after the script runs, that change will not necessarily appear on the next run. Include intended transformations in the recorded workflow.
• Ignoring the input and software setup. Running the same instructions on a different source file or under different software conditions may not reproduce the same output. Specify the intended input and relevant computational requirements.