{
  "manifest_version": "0.1",
  "work_slug": "plant-ecology-marcescence-decomposition",
  "protocol": "protocol:secondary-analysis 0.1",
  "module": "agent/tools.py",
  "analysis_unit": "analysis.py",
  "published_results": "results.json",
  "source_dataset_doi": "10.6084/m9.figshare.25062800",
  "environment": {
    "language": "python",
    "tested_version": "3.13",
    "requirements": "requirements-reproduction.txt",
    "network": "deny-except-pinned-inputs"
  },
  "execution": {
    "boundary": "docs/72-reproduction-contract.md",
    "live_invocation": "not connected; the sandboxed runner gates execution over MCP"
  },
  "surface_note": "analysis.py is only partly decomposed. fetch, bh_holm, rank_biserial_mwu and boot_ci are called directly; T1, T2, T3a and T3b exist only inside analysis.main() and are re-implemented in tools.py, with the published_pointer acceptance calls as the proof that the re-implementation reproduces results.json. Two properties of the pinned source are reported, not repaired: the Family column files Achillea collina and A. pannonica under Rosaceae although Achillea is an Asteraceae genus, and Plantago media has two shed bags and two PLFA samples that all resolve to replicate 3.",
  "tools": [
    {
      "name": "dataset_summary",
      "summary": "Provenance of the pinned workbook and the number of paired species.",
      "unit": "analysis.fetch plus the species pairing in analysis.main",
      "parameters": [],
      "returns": "figshare_id, md5, n_species_paired",
      "supports_claims": [1, 2, 3, 4],
      "deterministic": true
    },
    {
      "name": "paired_decomposition_test",
      "summary": "Paired Wilcoxon, marcescent vs shed mass loss across species, with bootstrap CIs (T1).",
      "unit": "analysis.main T1 block (re-implemented: species pairing, scipy.stats.wilcoxon) with analysis.boot_ci",
      "parameters": [
        {
          "name": "aggregate",
          "type": "string",
          "default": "mean",
          "range": "mean | median (of up to three replicate bags per species and litter type)",
          "published_values": ["mean"],
          "notes": "The median is the robustness check on a mean of at most three bags."
        },
        {
          "name": "method",
          "type": "string",
          "default": "approx",
          "range": "approx (normal approximation, as published) | exact (exact null distribution)",
          "published_values": ["approx"],
          "notes": "Changes only the p-value. z, and the effect size derived from it, always come from the normal approximation, as in analysis.main."
        },
        {
          "name": "exclude_species",
          "type": "array of string | null",
          "default": null,
          "range": "species names as spelled in the source Decomposition sheet (e.g. Jacea.pratensis); 34 of its 39 species have both litter types",
          "published_values": [null],
          "notes": "Use it with exclude_families to drop Achillea collina and A. pannonica, which the source files under Rosaceae."
        },
        {
          "name": "exclude_families",
          "type": "array of string | null",
          "default": null,
          "range": "family labels as given in the source: Asparagaceae, Asteraceae, Cistaceae, Fabaceae, Hypericaceae, Iridaceae, Lamiaceae, Linaceae, Onagraceae, Plantaginaceae, Poaceae, Ranunculaceae, Rosaceae (Apocynaceae and Dipsacaceae hold only unpaired species)",
          "published_values": [null],
          "notes": "Directly probes the phylogenetic-independence caveat the object states in its T1 note."
        },
        {
          "name": "n_boot",
          "type": "integer",
          "default": 5000,
          "range": ">= 100",
          "published_values": [5000]
        },
        {
          "name": "boot_seed",
          "type": "integer",
          "default": 0,
          "range": "any non-negative integer",
          "published_values": [0],
          "notes": "Changing the seed measures the Monte Carlo error in the reported bootstrap CIs."
        }
      ],
      "returns": "test, W, z, p, rank_biserial_r (|z|/sqrt(n), as analysis.main computes it), median and mean mass loss per litter type, median and mean paired difference with 95% percentile-bootstrap CIs, n_species, n_marcescent_slower, n_marcescent_faster, note",
      "supports_claims": [1],
      "deterministic": true
    },
    {
      "name": "functional_group_contrast",
      "summary": "Mann-Whitney U on the per-species (marcescent - shed) difference, Forb vs Grass (T2).",
      "unit": "analysis.main T2 block (re-implemented: scipy.stats.mannwhitneyu) with analysis.rank_biserial_mwu",
      "parameters": [
        {
          "name": "legumes",
          "type": "string",
          "default": "excluded",
          "range": "excluded (as published) | with_forbs",
          "published_values": ["excluded"],
          "notes": "The two legume species are herbaceous dicots, i.e. forbs in a two-way growth-form split."
        },
        {
          "name": "aggregate",
          "type": "string",
          "default": "mean",
          "range": "mean | median (of replicate bags)",
          "published_values": ["mean"]
        },
        {
          "name": "exclude_species",
          "type": "array of string | null",
          "default": null,
          "range": "species names as spelled in the source Decomposition sheet",
          "published_values": [null]
        },
        {
          "name": "exclude_families",
          "type": "array of string | null",
          "default": null,
          "range": "family labels as given in the source (see paired_decomposition_test)",
          "published_values": [null],
          "notes": "Every grass is Poaceae, so this contrast is also a family contrast. Dropping families from the forb side asks how much of it is forb against grass."
        }
      ],
      "returns": "test, U, p, rank_biserial_r, mean_diff_forb, mean_diff_grass, n_forb, n_grass, note",
      "supports_claims": [2],
      "deterministic": true
    },
    {
      "name": "within_group_tests",
      "summary": "Paired Wilcoxon, marcescent vs shed, within each named functional group (T3a).",
      "unit": "analysis.main T3a loop (re-implemented: scipy.stats.wilcoxon per functional group)",
      "parameters": [
        {
          "name": "fgroups",
          "type": "array of string",
          "default": ["Forb", "Grass"],
          "range": "one or more of Forb, Grass, Legume (Legume has 2 paired species, too few for the test to reach p < 0.05)",
          "published_values": [["Forb", "Grass"]]
        },
        {
          "name": "method",
          "type": "string",
          "default": "approx",
          "range": "approx (as published) | exact",
          "published_values": ["approx"],
          "notes": "With seven grass species the exact null distribution is the appropriate one."
        },
        {
          "name": "aggregate",
          "type": "string",
          "default": "mean",
          "range": "mean | median (of replicate bags)",
          "published_values": ["mean"]
        },
        {
          "name": "exclude_species",
          "type": "array of string | null",
          "default": null,
          "range": "species names as spelled in the source Decomposition sheet",
          "published_values": [null]
        },
        {
          "name": "exclude_families",
          "type": "array of string | null",
          "default": null,
          "range": "family labels as given in the source (see paired_decomposition_test)",
          "published_values": [null]
        }
      ],
      "returns": "per functional group: W, p, n, median_M, median_S",
      "supports_claims": [3],
      "deterministic": true
    },
    {
      "name": "microbial_correlation",
      "summary": "Spearman correlation of microbial biomass (Cmic) with mass loss, per bag (T3b).",
      "unit": "analysis.main T3b block (re-implemented: Decomposition-PLFA join on Species, Littertype, Replication; scipy.stats.spearmanr)",
      "parameters": [
        {
          "name": "littertypes",
          "type": "array of string",
          "default": ["M", "S"],
          "range": "M and/or S (marcescent, shed)",
          "published_values": [["M", "S"]],
          "notes": "The published run pools both litter types, which differ in both Cmic and mass loss. A single litter type gives the within-type association."
        },
        {
          "name": "duplicate_keys",
          "type": "string",
          "default": "cross",
          "range": "cross (as published: many-to-many inner join) | drop (remove keys not unique on both sides)",
          "published_values": ["cross"],
          "notes": "Plantago media shed replicate 3 is duplicated in both sheets, so the published join yields four rows from two physical samples."
        }
      ],
      "returns": "test, rho, p, n",
      "supports_claims": [4],
      "deterministic": true
    },
    {
      "name": "multiplicity",
      "summary": "Benjamini-Hochberg and Holm correction over a family of p-values.",
      "unit": "analysis.bh_holm",
      "parameters": [
        {
          "name": "p_values",
          "type": "array of number | null",
          "default": null,
          "range": "any non-empty list of p-values in [0, 1]; null uses the declared family {T2, T3a-Forb, T3a-Grass, T3b}",
          "published_values": [null]
        }
      ],
      "returns": "raw_p, bh_p and holm_p per member of the family",
      "supports_claims": [2, 3, 4],
      "deterministic": true
    }
  ]
}