English | 简体中文

PaperConan

A numerical detective for the source data behind published papers.

paperconan scans a paper's supplementary data files with a battery of numeric detectors — columns duplicated across sheets and files, constant offsets between supposedly independent replicates, row-wise scaled copies, reused decimal tails, and more — and pinpoints what deserves a human second look, down to the exact file, sheet, rows, columns, and rule that fired. It reads .xlsx, legacy .xls, .xlsm, .csv, and .tsv, extracts structured tables from supplementary .pdf / .docx, and can catalog local figure images when enabled with --images.

Two things to know up front:

• It reports statistical signals, not conclusions about author intent. Many raw hits have benign explanations. Final interpretation always requires the original tables, figure legends, Methods, the authors' response, and journal or institutional review.
• It is designed to be driven by an AI agent. The recommended setup pairs the CLI with the skill bundled in this repository, inside Claude Code, Codex, or a similar agent: you ask in plain language, and the agent runs the real detectors and interprets the output under explicit written rules instead of eyeballing numbers. This page follows that workflow; direct CLI and Python usage is covered in the CLI and library reference.

Who it's for:

• Graduate students and early-career researchers running a sanity check before citing or building on a paper
• Labs, research groups, and departments triaging publicly available source data
• PubPeer posters who want the exact table, rows, columns, and rule before deciding what to ask
• Batch audits — a journal, an author group, or a list of DOIs, prioritized by an agent afterwards

What it does not do:

• Judge author intent or responsibility, or replace statistical peer review
• Interpret Western blots, microscopy images, gels, or image splicing on its own; semantic image review is handled by an external multimodal agent that can open the local images
• Digitize data points from bar-chart or line-chart pixels
• Configure model APIs, credentials, or provider SDKs; the deterministic image_findings are optional hints, not a complete review checklist
• Bypass paywalls — and it never treats "no public data found" as evidence that a paper's data have no issues

---

See It in Action: A Real Adjudicated Report

The report below comes from a case that is already public and has been handled by the institution involved: the Nature paper Human HDAC6 senses valine abundancy to regulate DNA damage (Nature 637, 215–223, 2025; DOI 10.1038/s41586-024-08248-5). Inconsistencies in its source data were raised on PubPeer starting in 2025 and drew wider attention in 2026. The authors' university later announced personnel actions: the corresponding author was removed as dean and demoted, and the first author's employment was terminated.

Our part is deliberately narrow and reproducible: feed the paper's public Nature source data to paperconan, have an AI agent write verdict.json under the skill's adjudication protocol, and render the result with paperconan report.

PaperConan's constant_offset detector independently flagged the following pattern: in Source Data Fig.4 (labeled Fig.4c inside the sheet), the two shHDAC6 columns labeled VR (0 h) and VR (24 h) — which should be independent measurements of the same sample batch at 0 and 24 hours — differ by exactly 0.3 in every one of 35 rows (0.45/0.15, 0.60/0.30, 3.34/3.04, and so on). This is the same Figure 4c inconsistency previously raised in public. The tool did not guess it from the plotted figure; it located the numerical pattern in the source data itself and named the exact file, sheet, rows, columns, and rule.

The finding was marked confirmed only after an adversarial red-team review that started from "assume it's a false positive" and worked through ten benign mechanisms one by one. The same scan raised more than 700 signals; the report kept the one that withstood that challenge and downgraded the rest. That restraint is what signal-not-verdict looks like in practice.

Keep the boundary clear: PaperConan reports reproducible numerical patterns, not conclusions about author intent. The institutional actions above are publicly documented facts, not a PaperConan judgment. The tool's role ends at locating signals anyone can reproduce; interpretation still requires the original data, the authors' response, and journal or institutional review.

For the complete commands used to reproduce this report, see Reports and tuning › Adjudicated HTML reports.

---

Quick Start (Recommended: Agent + Skill)

1. Install the CLI (The Skill Calls It Behind the Scenes)

Python >= 3.10 is required.

pip install "paperconan[all]"   # [all] includes PDF / Word table extraction; recommended
pip install "paperconan[image]" # adds only image assets, PDF pages, and optional image hints
paperconan --version            # verify the installation

The base package includes the Rust-powered python-calamine reader: legacy .xls / .xlsm / .xlsb work out of the box, and .xlsx reads are faster. Other install variants: CLI and library reference › Installation.

Once the skill from Step 2 is installed, an agent with shell access and a Python environment (a local Claude Code or Codex session, for example) will detect a missing CLI and pip install it before its first scan — so you can skip this step and go straight to Step 2.

2. Connect the Skill to Your Agent

The simplest option is the cross-agent npx skills installer — one command covers Claude Code, Codex, Cursor, and other compatible agents:

npx skills add zixixr/paperconan                          # install for detected agents

# You can also select agents or installation scope:
npx skills add zixixr/paperconan -a claude-code -a codex  # install only for these two
npx skills add zixixr/paperconan -g                       # install globally for the user

The installer clones the repository, discovers the paperconan skill, and wires it up using each agent's own directory conventions — you never touch ~/.claude/skills or the other agent-specific paths.

Manual fallback: if you would rather not use npx, or want the skill to track git pull, symlink it into Claude Code's personal skill directory:

git clone https://github.com/zixixr/paperconan.git
mkdir -p ~/.claude/skills
ln -s "$(pwd)/paperconan/skills/paperconan" ~/.claude/skills/paperconan

If your agent does not discover skill directories yet, reference SKILL.md from your project's agent instructions instead:

echo '@'"$(pwd)"'/paperconan/skills/paperconan/SKILL.md' >> AGENTS.md

Restart the agent session after installing or updating the skill so it gets picked up.

skills/paperconan/SKILL.md is the agent entry point. It requires the agent to run the real detectors, interpret their output under the rules in references/, and preserve the signal-not-verdict boundary.

The skill ships a reusable, public adjudication protocol: adjudication-tiers.md defines Tier 1/2/3 and KEEP / DROP / NEEDS_HUMAN; report-templates.md defines the short report and the formal eight-section report; adversarial-review.md defines the red-team review process. Tiers express review priority and how hard a signal is to explain through benign mechanisms — they are not conclusions about author intent.

3. Ask in Plain Language

Once the skill is connected, you don't need to remember any commands. Just ask:

• "Check this paper's source data for statistical signals worth reviewing: 10.1038/sxxxxx"
• "Scan ~/Downloads/source_data/ and show me the few signals that most need human review"
• "Could this cross-sheet match be a false positive? Compare it with the original table"

The agent decides whether to fetch or scan directly, parses scan.json, loads the relevant reference material, and opens the original table when needed. Its answer comes with the evidence, the plausible benign explanations, and the scientific context a human still needs to supply.

Image review runs through the same flow. The agent first confirms it can open local images, then works through every item in image_assets — whole image first, original-pixel crops for small panels or unresolved details. image_findings are hints only, never a substitute for full asset coverage; every asset must end up recorded as reviewed, unresolved, unreadable, or deferred. Numeric and image assessments land in the same verdict.json findings[] array and produce a single adjudicated report.

The full command sequence behind all of this:

paperconan fetch "<DOI or title>" --auto --images --out data/
paperconan data/ --images
paperconan data/ --images --image-diagnostics
paperconan report data/audit/scan.json --verdict verdict.json --out adjudication.html

If the agent cannot open local images, it sets image_review.status to unavailable_no_multimodal, states explicitly that semantic image review is incomplete, and continues with the numeric review. PaperConan itself never calls or configures model services.

An agent without a usable Python environment should ask you to run the commands locally. It must never present an eyeballed guess as PaperConan output.

---

Reading the Reports: The Essentials

The audit/report.html generated directly by paperconan <dir> is a workbench of raw signals from deterministic detectors. By design it contains many false positives — shared controls, redrawn axes, unit conversions, derived columns, and other benign mechanisms account for most hits. It is not a conclusion and is not meant to be published as-is.

For a formal, interpreted report, use an agent together with the skill: the detectors produce reproducible raw signals and optional image hints; the agent checks each one against the original table, the full image, original-pixel crops, the figure legend, and Methods; only then are the numeric and image findings combined into an adjudicated report. The CLI alone never performs this semantic assessment.

How to read the raw signals, control false positives with --profile, and generate an adjudicated report: Reports and tuning.

---

⚠️ Important Notice

paperconan reports algorithmically identified statistical signals, not conclusions about author intent or responsibility. Final interpretation requires clarification from the original authors, verification by journal editors, or independent peer review.

Use established channels: post a specific, reproducible data inconsistency on PubPeer; contact the journal's ethics team; or, where appropriate, contact your institution's research integrity office.

Do not: publicly accuse individual authors on social media, present a PaperConan screenshot as a final conclusion, or skip author clarification and jump straight to a judgment.

The tool is neutral. Its use must be, too.

---

Documentation

This page covers the main workflow; details live under docs/:

• What it detects — an overview of every detector
• Reports and tuning — reading reports, controlling false positives with --profile, generating adjudicated HTML reports
• Recommended batch-scanning workflow — fetch → scan → filter → build dossiers → agent adjudication → tiering → adversarial review
• CLI and library reference — installation, scanning, fetch, PDF/Word support, the Python library, memory/output safeguards
• FAQ

For the deeper rules used by AI agents and the skill, see skills/paperconan/references/: detectors · output-schema · judgment-rubric · interpretation · adjudication-tiers · report-templates · adversarial-review · batch-workflow · case-patterns

---

Example

examples/ contains a complete synthetic demo: two synthetic source-data files, a generated audit/scan.json and report.html, screenshots, and a finding-by-finding walkthrough. Start with examples/README.md and examples/report-preview.png, or run it yourself:

cd examples
paperconan demo_paper
open demo_paper/audit/report.html

---

Roadmap

Done:

• Inputs: .xlsx / legacy .xls / .xlsm / .csv / .tsv, plus tables from PDF / Word
• paperconan fetch — supplement discovery and download from open sources
• Agent skill bundle
• Columnar engine (fast calamine reads, including legacy Excel) with memory/output safeguards
• review / forensic / triage profiles and a deterministic prefilter
• Reuse/transformation detectors: whole-column reuse across sheets and files, matrix decimal-place reuse, contiguous-segment offsets, shared decimals across integer-separated values, fixed row-vector recurrence across figures, row-wise ratios/equality (including scaled reuse across blocks), round-number gaps with preserved tails, high-precision tail clustering
• HTML reports with evidence highlighting
• Local image-asset registration from permitted sources, optional non-gating image hints, coverage accounting by an external multimodal agent, and a unified adjudicated report for numeric and image findings

Next:

• Cross-paper scanning — reuse across multiple papers from one lab or author group
• Chart-pixel digitization
• More comprehensive deterministic image-pattern hints
• PubPeer Public API integration

Pull requests are welcome — new detector patterns, documentation, and demos alike.

---

Why It Exists

PaperConan started as prep for a YouTube / Douyin / Bilibili video: scan publicly available source data from Nature-family papers and locate the numerical patterns that warrant explanation. It is open source so that people doing careful research can spend less time and attention on unreliable data.

License

MIT.

Acknowledgments

• Detective Conan © Gosho Aoyama / TMS Entertainment. The project takes its name — and its patience for small clues — from the series.
• PubPeer. PaperConan's output should ultimately support public questions that are specific, measured, and reproducible.