Research methods · Analysis handoff
How to hand over a reproducible research analysis package
A handoff is not just a ZIP file. It is a checkable route from authorized inputs to specified results. Document versions, order, environment and acceptance criteria, then rerun in a separate directory and record differences.
This guide concerns public or synthetic research materials you are entitled to use. It answers where a collaborator should start and how to check the outputs. The pre-submission guide checks consistency in a manuscript; this guide asks whether the same materials and code can regenerate those results.
We use The Turing Way definition of computational reproducibility: recreating results with the same data and analysis steps. Terminology varies across disciplines. Testing new data, assessing robustness with different methods and establishing generalisability are not replaced by a single rerun.
A minimal directory with an explicit purpose for every file
These names are teaching suggestions, not required software or a RigorMed export format. Adapt them to the project and explain how each input is obtained and each output is produced.
| Example location | What to document | What the recipient checks |
|---|---|---|
| README | Scope, material permissions, entry point, order, expected outputs, stopping conditions and contact role | A starting point and limitations without oral instructions |
| inputs/ and data-dictionary | Source version or file ID, relative paths, units, codes and missing-value conventions; lawful acquisition instructions if redistribution is prohibited | Accessible inputs matching the analysis version |
| scripts/ and analysis-plan | Cleaning, analysis and table/figure order, parameters and eligibility rules | A generating step for every key result, not manually copied numbers |
| environment | Actual OS, language and package versions and installation instructions; seeds, threads and hardware limits where relevant | Execution in the stated environment, not just “latest version” |
| expected/ and output-map | Expected files, table/figure mapping, comparison fields and prespecified tolerances | Content agreement, not file existence or similar rounded values |
| rerun-record | Actual date, environment, steps, exit status, differences and unfinished work | Not run, failed, partially passed and the checked scope remain distinct |
Remove secrets, access tokens, personal absolute paths and row-level materials that cannot be shared. State code licensing, data-use terms and access restrictions separately. Downloadable does not mean redistributable.
Build the inventory, then rerun without borrowing old results
Fix the target results
Identify the manuscript or analysis version, main tables/figures and plan. Do not mix exploratory outputs into the formal results. List missing materials or unclear permissions; do not reconstruct raw data from the paper.
Connect inputs, steps and outputs
For each table or figure, record input locations, generating scripts, parameters and output paths. Use relative paths and explicit dependencies. Document rules and actual records for manual decisions instead of calling them automatic.
Document an executable environment and entry point
The package README should contain installation and run commands actually tested by its author, with working directory and order. This page does not invent a universal command. A seed does not guarantee bitwise agreement across software, threads or hardware.
Run in a new directory
Preserve original inputs and formal outputs, and write rerun results separately. Do not copy files from expected/ and call them new computations. Online sources need fixed versions and lawful acquisition paths, not changing private links.
Compare against prespecified criteria
Compare sample sizes, denominators, variables, models and effect units before estimates, intervals and table/figure data. Separate non-scientific changes such as dates. Specify floating-point tolerances beforehand; do not widen them after seeing discrepancies.
Record failures before handing over
Keep execution and difference records. Missing inputs, dependency failures or mismatched key results stop the affected conclusions: do not fill zeros or edit outputs to match. Complete files without execution are “awaiting rerun”; one success is not cross-environment or quality certification.
Synthetic teaching fragment: more specific than “a CSV was produced”
A self-authored teaching input has one column x and 5 rows: 1, 2, 3, 4 and a blank. Only for this arithmetic example, the preset rule is a non-missing mean without imputation: total 5, valid 4, missing 1, mean 2.5. These are not patient data, research findings, statistical advice or a product run.
An output map can link summary.csv fields n_total/n_valid/n_missing/mean_x to README checks. The rerun record separately documents actual commands, environment and comparison. Creating a file containing 2.5 does not establish that computation ran.
If the mean is 2.0, first check whether a blank became 0. If the valid count becomes 5, inspect parsing and preprocessing. Do not change the expectation first. The package must expose rules and denominators, not just a visually similar table.
Ask AI to organize handoff gaps, not declare reproduction successful
Suggested materials: an authorized file inventory, public or synthetic data dictionary, existing README, confirmed run instructions and a sanitized execution summary. Do not upload patient rows, credentials or text you cannot share merely to organize a checklist.
Adaptable request: using only the supplied materials, draft a handoff table and README mapping target result → input version/location → steps/parameters → output → acceptance fields → gaps. Mark absent commands, versions or execution evidence as unresolved; do not invent environments, results or passing records.
Requested deliverables can be a handoff map, README draft and unresolved questions. These are proposed specifications, not an actual execution or customer outcome. Running particular code requires separate checks of materials, capability, permissions and pre-execution confirmation.
Five questions at delivery
Five questions at delivery
- Can the recipient lawfully obtain the same input version, with clear dictionary and parameters?
- Does every key output have a generating step rather than a hand-edited file on the author’s machine?
- Were environment, commands and order actually tested, with untested parts labelled?
- Were contents, denominators, units and preset tolerances checked, not only exit code 0 or file existence?
- Are failures, unrun work, manual decisions and non-public portions reported honestly?
A clear reproduction path does not establish appropriate design, bias control, data permission or causal validity. PLOS policies apply to that publishing system, not automatically to every journal. Explain restrictions and lawful access under the applicable policy; do not disclose sensitive data.
Verified sources
The official sources below were checked on 2026-10-21. Access conditions and update dates are rechecked before publication.
- The Turing Way: definitions of reproducibility
Same-data, same-workflow reproducibility and its distinction from new-data testing; terminology varies.
- PLOS: materials, software and code sharing
Code, run documentation, dependencies, test materials and sharing restrictions within the policy’s scope.
Reproducibility and research delivery
Turn existing materials into a reviewable handoff
In the RigorMed workspace, describe your permissions, available files and handoff question; the request above is a starting point. Confirm the supported scope and actual deliverables, then check sources, execution records and differences yourself. Organizing a checklist is not completing a rerun.