Introduction

Computational studies are team efforts. A typical study brings together a domain expert who knows the application and its data, a methods specialist who designs the algorithmic solution, a data scientist who curates and analyses what flows through the study, and a research software engineer who keeps the machinery running. Experience levels span the whole range, from a master's student contributing a single piece of code to a principal investigator steering the study as a whole.

Each of these people arrives with their own setup. One works on macOS in Python, another on Windows in R, a third on Linux across several languages. The models they contribute may need to run on a laptop today and on an HPC cluster next month. None of this diversity is a flaw; it is what makes interdisciplinary research work. The trouble is what happens when the pieces meet: environments conflict, data written by one tool cannot be read by another, and a study that ran fine in March quietly breaks by June because a dependency moved on. Most teams patch around these problems case by case, and the patches themselves become the thing that is hard to maintain.

SHOWME.how is an approach for building computational studies that survive this heterogeneity. It rests on three pillars. Isolation gives every computational unit its own self-contained environment, so units never interfere with each other. Interoperation makes data cross unit boundaries in language-agnostic formats over standard protocols, so no unit cares what language its neighbour speaks. Orchestration hands scheduling, data movement, and resumption after failure to a workflow management system, so the study runs end-to-end without a human pushing files around. The pillars are independent: you can adopt one today and add the others as your study grows.

The full argument for the approach, including the analysis of why heterogeneous studies fail and the evidence from three complete research studies, is in the paper: Alan Correa, V Mithlesh Kumar, Anil Yildiz, and Julia Kowalski, SHOWME.how: Isolation, Interoperation, and Orchestration for FAIR Computational Research (in preparation). This website is the paper's practice companion. The paper explains why; the guide you are reading shows how, with the concrete files, commands, and pitfalls that a paper has no room for.

The figure shows the setting the approach is built for. Data, computational units, and the people operating them form one system, and a workflow only covers part of it. The collaborators themselves are a source of heterogeneity, which is exactly why an approach that only manages software falls short.

Where to start

If you have a study in mind, start with the workflow patterns page. It helps you decompose your study into recurring structures, and each structure points to the recommendations it depends on.

If you first want the map, the three pillars page lists all eleven recommendations of the approach in one place, each with a link to its own page.