# LigninQC 1.0.0

**Reproduce a numerical finding from a lignin paper, inspect its source, and apply the same analysis to your own table.** This release contains two completed published-data case studies, code, original source XML, structured data, readable reports and independent numerical verification. It is a secondary-analysis tool, not an automated scientific referee.

[Русский отчёт](reference/report.html) · [Public project and download](https://zack-dev-cm.github.io/projects/ligninqc-reproducible-scientific-research-workflows/) · [Data and reuse terms](DATA-LICENSE.md) · [Validation evidence](docs/VALIDATION.md)

## Run the complete examples

Unpack the archive, open a terminal in its `ligninqc-reanalysis-2026-09-05` directory, and run:

```sh
python3 -m ligninqc reproduce --out results
python3 -m ligninqc verify
python3 tools/check_independent.py
python3 -m unittest discover -s tests -v
```

Open `results/report.html` in any browser. `results/results.json` contains the input hashes, selected and missing compound IDs, ten predefined statistical variants plus a separately labelled post-hoc ABTS source-conflict sensitivity, all held-out predictions and all thermal comparison rows. On Windows, use `py -3` in place of `python3`; the file manager can unpack the ZIP. `reference/report.html` is already included and can be read without Python.

Python **3.10 or newer** is the only core runtime requirement. No pip install, paid program, API key, cloud account, Google connection or internet access is required by the numerical workflow. Actual tested runtimes and clean-archive outcomes are recorded in `docs/VALIDATION.md`; minimum-version compatibility is a code/API requirement, not a claim that every Python/OS combination has been tested. Commands work from any filesystem location, but run them from the unpacked directory so Python can find the `ligninqc` module.

An existing nonempty output directory is refused. Use a new directory, or add `--force` to replace the generated `results.json` and `report.html`. Do not use the source-data directory as an output directory. Verification reads the frozen package; it does not alter it or download newer sources.

## What the real cases show

- **Lauberte et al. (2019), DOI [10.3390/molecules24091794](https://doi.org/10.3390/molecules24091794).** Reanalysis of Table 1's rounded BDE and radical-deactivation-index values. DPPH neutral forms: 18 complete pairs, R² ≈ 0.636567; author-named exclusion of compounds 5/16 gives 0.898259 for 16 pairs. Same-fold leave-one-out linear MAE ≈ 0.322107 versus 0.632784 for the training-mean baseline on the full DPPH set. Reported state, missingness, assay and normalization alternatives are retained. Table 1 and §2.2 also disagree on ABTS values for compounds 5/6; a separate post-hoc substitution changes matched-state R² from 0.579906 to 0.747168 for the same 14 compounds. Neither source version is adjudicated. This is not external prediction validation or an exact reconstruction of undocumented raw-data regression choices.
- **Kazachenko et al. (2022), DOI [10.3390/polym14153000](https://doi.org/10.3390/polym14153000).** Table 2 assigns 61.9% and 76.6% mass loss at 800 °C to initial and sulfated lignin respectively; the prose reverses these assignments. An operational comparison over the paragraph's described range from 250 °C has one tabular counterexample among 12 temperatures. The package preserves both source representations and does not decide which one is experimentally correct.

The practical benefit over one correlation coefficient is visible selection/state sensitivity, an ordinary prediction baseline, source-linked input checks and explicit counterexamples. These two retrospectively selected cases do not establish general detection accuracy, a population error rate, novelty, a publishable discovery, or measured human time savings.

## Analyze your own CSV

```sh
python3 -m ligninqc analyze --csv examples/own-data.csv \
  --x bde_kcal_mol --y activity_rdi --id compound_id \
  --direction negative --x-unit kcal/mol --y-unit RDI --out my-results
```

`examples/own-data.csv` is an explicitly **synthetic format example**, separate from the two real studies. To use real data, supply your own file or one of the bundled tables. Every row needs a nonempty unique ID; selected x/y columns must be finite numbers or explicit missing entries (empty, `NA`, `N/A`, `n.d.`, `-`). Zero is a measurement, never a missing-value marker. The pairwise and leave-one-out diagnostics have quadratic runtime and are intended for small curated tables like these cases, not unbounded screening datasets. At least three complete pairs and variation in both columns are required. Duplicates, nonnumeric values, NaN, infinity and constant data are rejected.

Specify the expected direction and units. Use `dimensionless` where appropriate. This records your definitions; the tool cannot detect mixed units, wrong structures, incorrect protonation assignments, dependent observations or incompatible assays from arbitrary column names. Do not pool DPPH and ABTS or quantities with different normalization into one response column. Correlation cannot establish a reaction mechanism or replace activation free energies.

## Check a numerical table statement

```sh
python3 -m ligninqc compare --csv data/kazachenko2022/table2.csv \
  --index temperature_c --left initial_mass_loss_pct \
  --right sulfated_mass_loss_pct --expected greater --min 250 \
  --unit percent --out comparison-results
```

The condition means `right > left` at each selected index, inclusive of interval endpoints. Results include the complete selected denominator and every counterexample. Subtracting two percentages gives **percentage points**, not relative percentage change. Equal values fail a strict greater/less statement. Numeric index aliases such as `250` and `250.0` are rejected as duplicates. The command compares explicitly structured numbers; it does not automatically read and interpret a new paper's prose.

## Inspect and verify the evidence

- `data/lauberte2019/table1.csv`: all 19 compounds, raw cell strings, alternatives, confidence-interval half-widths, missingness and annotations.
- `data/kazachenko2022/table2.csv`: both samples at all 13 temperatures; `claims.json` preserves the textual assignments and comparison scope. `table1-gpc.csv` is contextual source data; no automated mechanistic verdict is derived from it.
- `data/*/provenance.json`: complete source citations, original URLs, licenses, locators, methods and transformation notes.
- `data/sources/`: original CC BY article XML and the original CC BY structural figure used to verify phenolic OH counts. The self-contained `data/sources/source-extracts.html` gives readable original tables and key paragraphs; XML preserves the broader context offline; rendering its referenced remote images is not needed for the supplied analyses.
- `reference/`: frozen results and reports; `figures/` includes shareable SVG, PNG and PDF plots.
- `tools/independent_source_analysis.py`: separate exact-rational calculations directly from source XML; no imports from the release's analysis code and no reading of its CSVs.

```sh
python3 tools/independent_source_analysis.py --out independent.json
```

Run `python3 tools/check_independent.py` for a fresh automated comparison of the CLI against that separate XML-based calculation (940 numerical/identity comparisons). Additional exploratory variants in the independent diagnostic output are labelled by their subset and are not substituted for the ten primary CLI variants.

The file manifest checks SHA-256 integrity, and `verify` recalculates results with a 1e-10 relative/absolute numerical tolerance. File hashes are not evidence of scientific correctness; source-level and independent numerical checks are reported separately. The extraction and review were AI-assisted; independent human peer review is not claimed. Optional figure-redrawing dependencies are isolated in [FIGURES.md](docs/FIGURES.md); all numerical reproduction and prebuilt figures work without them.

## Reuse in research

Cite each original paper for its experimental/DFT data and LigninQC version 1.0.0 for this reanalysis. Include the variant name, sample count, unit/state/normalization choices and input hashes when reporting results. Do not write that new experiments or DFT calculations were performed. `CITATION.cff` provides software metadata, and [USE-IN-A-PAPER.md](docs/USE-IN-A-PAPER.md) contains a ready-to-adapt methods/results paragraph with its limitations.

Code/tests: MIT. Original scientific documentation, new analysis and figures: CC BY 4.0. Bundled article material remains CC BY 4.0 with original authors and source attribution. Your own input data retain their existing rights; running the tool does not relicense them. See [DATA-LICENSE.md](DATA-LICENSE.md).
