Verify and explain

Published

Oct 2026

Your task

Check that the saved results for A01 can be reproduced from its original counts. The analysis script uses vegan::diversity(); you will calculate Shannon diversity step by step and compare the answers.

Output column Meaning Expected A01 value in the supplied example
feature_total Sum of the feature counts 6006
observed_features Number of features with a count greater than zero 15
shannon Diversity reflecting richness and evenness, using natural logarithms 2.423797

These values describe the supplied synthetic example. Your own data will give different results.

Generate the results first

Run this in the terminal, from the repository root:

Rscript scripts/R/02-analyse-example.R

The script validates the inputs and writes results/tables/alpha-diversity.tsv. It also checks that the direct Shannon formula agrees with vegan for every sample.

Check one sample yourself

From the repository root, run this command in your terminal at the shell prompt:

Rscript scripts/R/05-verify-sample.R

The script checks A01 by default. Open scripts/R/05-verify-sample.R in your editor to follow the calculation.

  1. Add the counts for A01 and count how many features have a positive count.
  2. Divide each feature count by the sample total to get its proportion.
  3. Use the positive proportions to calculate Shannon diversity with natural logarithms.
  4. Compare all three results with the saved row for A01.

Expected output

All three rows should show TRUE in agrees. For the supplied example, Shannon diversity rounds to 2.423797. Compare the unrounded values in code; small rounding differences in displayed tables are normal.

If a check fails, confirm that you used the same input folder, output folder, and sample ID as the analysis. Rerun the analysis after changing an input table.

From output to evidence

You have reproduced one sample’s summaries from its counts and compared them with the saved results. You can now explain how those numbers were obtained.

Practice with a second dataset

Use the synthetic practice tables in data/my-study/. This dataset has eight samples, two groups, and four fictional features. From the repository root, run the analysis and verify three samples:

Rscript scripts/R/02-analyse-example.R data/my-study results/my-study
Rscript scripts/R/05-verify-sample.R data/my-study results/my-study S01
Rscript scripts/R/05-verify-sample.R data/my-study results/my-study S02
Rscript scripts/R/05-verify-sample.R data/my-study results/my-study S04
  1. Open data/my-study/feature-counts.tsv and find S01. Its counts are 50, 25, 25, and 0. Add them, count the features with positive counts, and divide each count by the total to get its proportion.
  2. Find S02 and S04. How many features are present in each? Which sample has the more even distribution? Explain why that sample has the higher Shannon value.
Sample Total counts Observed richness Shannon diversity
S01 100 3 1.039721
S02 100 4 1.195863
S04 100 4 1.184124

All three checks should show TRUE for each sample. For S01, the positive proportions are 0.50, 0.25, and 0.25. Apply \(H = -\sum_{i=1}^{S} p_i \ln(p_i)\), where \(S\) is the number of observed features and \(p_i\) is the proportion for feature \(i\).

S02 and S04 each have four observed features and 100 total counts. Their counts are 46, 30, 18, 6 and 49, 26, 19, 6, respectively. S02 has a slightly more even distribution across the four features, which explains its higher Shannon value.

Repeat with your own data

Use a separate folder for your input tables and a separate output folder. Run the analysis first, then use those same folders and a sample ID from your count table when you run the verification script.

Note

Shannon diversity uses all original features. The top-eight features and “Other” grouping simplify only the composition plot. Checking the arithmetic does not establish a biological difference between groups or validate the study design.

Explain the figures

  1. What varies within and between groups?
  2. Do diversity values overlap?
  3. Could count totals, filtering, or study design affect interpretation?
  4. Which claims cannot be supported?

Use AI to review your interpretation

Inspect the figures and tables first. Then supply the relevant outputs to your AI assistant with this prompt:

I am comparing community composition and diversity between two groups using 24 synthetic samples and 15 fictional features. Using only the figures and tables I supply, help me describe the patterns in composition, diversity, and count totals. Check whether your descriptions agree with the numerical values. Identify limitations and questions I should investigate. Do not invent results or claim statistical significance or causation from visual differences alone.

For your own study, replace the sample and feature details with your actual study information.

Compare the response with the outputs. Check group labels, numerical values, and figure axes. Count totals describe the supplied counts; they do not by themselves measure absolute microbial abundance.

In results/decision-log.md, record briefly:

  • AI suggested: the explanation or change proposed.
  • I verified: the output, calculation, or code you checked.
  • I decided: what you accepted, revised, or rejected, and why.

For your own study, save this record beside its outputs, for example in results/my-study/decision-log.md.

Note

Higher diversity does not automatically mean a healthier community. Visual differences do not establish significance or causation.

Continue to 6. Export the report.