analysis-report

Analysis report

The reader did not watch you work and will decide whether to trust the number. The report has to let them confirm you answered the question actually asked, see every choice that could have moved the result, and rerun it without asking you anything.

Rules

1. The request's specification is the primary analysis. A grouping rule the request states (a median split, a tertile, a named marker), a named tissue, timepoint, population, comparison arm, test, threshold or output is what is computed first and reported first, exactly as written, on exactly the population named. Your better method is welcome: it is run as well and reported as a sensitivity analysis beside the requested one, never in its place. Substituting the "right" method for the requested one is the most common way a correct analysis scores as a wrong one. Restate the question with its binding clauses: population, time window, inclusion and exclusion rules, the exact metric and its unit, the direction that counts as better, thresholds, and what would count as "no effect". Quote the original wording where it is ambiguous and state the reading you adopted. Then map every clause to a numbered step in the Method: a question that specifies a chain (classify, then weight, then integrate) or a construct (a monotone trend across ordered grades, not a difference somewhere) is answered by implementing that chain step by step, and a two-part question gets two answered parts. A single proxy for the chain, or an omnibus test for the construct, is a different analysis. Then, before any analysis runs, write the checklist the report must satisfy and keep it beside the plan: every clause of the question; every group, stratum, endpoint or comparison it names or implies (a treatment's control, a mutation's wild-type, the reference arm, the second endpoint); every output it asks for (a figure counts); and the standard readings a reviewer of this data type expects beyond the primary result — a set- or pathway-level view for gene-level results, the field's standard model beside any custom test, sensitivity to the key threshold, the named entities interpreted mechanistically. The Results address each item by name; the answer answers each clause. A definition the question gives — a median within a group, a condition at every timepoint, a one-directional hypothesis, separate test families — is applied as written, with any objection recorded beside it, never substituted; and every definition is scoped to the population the question names: a threshold is computed within that group, an implied cohort restriction is applied before the analysis, and a "top N" is exactly N.
2. Provenance for every input. File or URL, version or release, access date, size, row count, checksum, and the filters applied before analysis, with a row-count flow that shows how many records left at each step and why. Before the first filter, list the distinct values and counts of every column you filter or group on, read from the file rather than assumed from its name (which code is the baseline level, which categories belong in a denominator, how missingness is coded), and name the unit of analysis.
3. Method with parameters. Every non-default parameter and every default that matters (two-sided test, Welch correction, random seed, tolerance, solver), with software versions. The exact call beats a prose paraphrase of it: under each step, paste the code that ran, verbatim and copy-pasteable, followed by the quantitative intermediate it produced (a count, a dimension, a p-value). A step described in prose without its code and number cannot be checked and, to a reader grading the text, did not happen.
4. Results with uncertainty. Primary number first, with its interval or SD and n, raw and adjusted values side by side, units on everything, decimals consistent with the precision the data support. Tables for more than three numbers; figures with labelled axes and units, saved to files that the report references by path.
5. Checks performed. What you did to catch your own errors: sanity bounds, recomputation by another route, sensitivity to a dropped subset or a different seed, unit tests on the pipeline, reconciliation against a known value.
6. Limitations. Data quality, assumptions untested or violated, confounders, scope of generalization, and what the analysis cannot distinguish between.
7. Decision log. Every fork where a reasonable analyst could have gone the other way: the choice, the alternatives, why this one, and the alternative's result when it was cheap to run. A reviewer reads this section first.
8. Reproducibility. The ordered commands or script that regenerate every number and figure from raw inputs, the environment specification, runtime and resources needed, and the output paths.
9. Interpretation is a deliverable, and the answer is committed. Numbers live in Results; claims live in Interpretation, and Interpretation is graded as hard as the numbers. Answer the question in one sentence at the top and again at the end, as the best-supported answer with a confidence and the single caveat most likely to change it. "Cannot be determined", "the data do not establish" and a direction left unnamed are not answers where the data bear on the question; state the reading the evidence favours and what would overturn it. Anchor the interpretation to what the question names: one paragraph per named phenotype, group, contrast or pathway. For each entity the result turns on, give the mechanism (with a reference), its functional role, the clinical or translational implication (a therapy, a biomarker, a target, a risk), and the next experiment that would test it. These are hypotheses: label them as such and give them. "Not necessary", "beyond the data", "would be speculative" and "cannot be inferred from observational data" are refusals a reader scores as no interpretation at all; a labelled hypothesis with a reference is what they expect. When the question asks for candidates, experiments or drugs, name specific ones with a reference. "Trends" and "consistent with" are the phrasing a grader halves. References ground the claims that need grounding, one each, and then stop: a reference search that outlasts the analysis adds nothing the report can use.
10. Consistency pass before delivery. Numbers in prose equal numbers in tables equal numbers in output files; every referenced path exists; every claim points at a result; no placeholder remains.
11. Prescribed structure wins. When the request fixes the headings, their order or their names, use them verbatim in place of the template below and keep every one, even where a section is short; a reader grading the text looks for its headings first. Where limitations or references are called for, they are sections with content, not a closing sentence.
12. The answer file is the answer, not a pointer. When the request asks for a separate plain answer beside the trace, it carries the direction, the counts and statistics, the named entities, the mechanism in one paragraph and the limitation in one line, in the language of the question; a grader reading it alone should reach the same conclusion as one reading the trace. Nothing that the trace concludes is left out of it, and it does not exceed what the trace supports.
13. Write the report; do not build it. A builder script that assembles the trace, a validator that counts its code blocks, a placeholder scanner: none of these is graded and each costs the minutes a further analysis would have used. The checks a judged report needs are that the prescribed headings and files exist and that the numbers in prose match the tables; that is a five-line check, run once.