salmopredict 0.1.2__tar.gz → 0.3.0__tar.gz

salmopredict-0.3.0/LICENSE

@@ -0,0 +1,138 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+Required Notice: Copyright 2026 State Key Laboratory of Veterinary Public Health
+and Safety, China Agricultural University
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software.  Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.  For example, if the licensor provided the
+following notice in the software:
+
+    Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+You must ensure that any plain-text lines beginning with
+`Required Notice:` appear.
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization,
+or government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization.  **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.

{salmopredict-0.1.2 → salmopredict-0.3.0}/MANIFEST.in

@@ -6,3 +6,4 @@ recursive-include salmopredict/gui/assets *.png
 include LICENSE
 include environment.yml
 include examples/*.csv
+include examples/README.md

salmopredict-0.3.0/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: salmopredict
+Version: 0.3.0
+Summary: AutoGluon-based Incidence predictor for Salmonella virulence-factor gene-frequency features
+Author-email: Dongyan Shao <563608176@qq.com>
+License: PolyForm-Noncommercial-1.0.0
+Project-URL: Homepage, https://github.com/shaodongyan/SalmoPredict
+Project-URL: Repository, https://github.com/shaodongyan/SalmoPredict
+Project-URL: Issues, https://github.com/shaodongyan/SalmoPredict/issues
+Keywords: salmonella,incidence,autogluon,prediction,bioinformatics
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: <3.11,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: autogluon.tabular[fastai]==1.1.1
+Requires-Dist: setuptools<81
+Requires-Dist: pandas>=2.0
+Requires-Dist: openpyxl>=3.0
+Requires-Dist: rich-argparse>=1.4
+Requires-Dist: streamlit>=1.30
+Provides-Extra: gui
+Requires-Dist: streamlit>=1.30; extra == "gui"
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/shaodongyan/SalmoPredict/main/salmopredict/gui/assets/salmopredict_icon.png" alt="salmopredict" width="200">
+</p>
+
+# salmopredict
+
+AutoGluon-based **Incidence** predictor for *Salmonella* virulence-factor
+gene-frequency features, with a command-line interface and a Streamlit GUI.
+
+Given a feature table (rows = samples, columns = virulence-factor genes),
+salmopredict aligns the columns to the features a pre-trained AutoGluon
+`TabularPredictor` expects, runs the `WeightedEnsemble_L2` model, and writes a
+single prediction file. It reproduces the alignment used by the original
+`predict_autogluon.py`: column names are normalised R-`make.names`-style
+(`/` and `-` become `.`), genes the model expects but the input lacks are filled
+with `0` (a missing gene means frequency 0), and extra input columns are ignored.
+
+**Feature CSV input/output** — the output columns depend on whether the input
+has a `Sample` column:
+
+| Input | Output columns |
+|-------|----------------|
+| No `Sample` column (features only) | `Incidence(%)` |
+| Has a `Sample` column | `Sample`, `Incidence(%)` |
+| Has a `Sample` column **and** `--attach meta.csv` | `Sample`, `Incidence(%)`, + the metadata's other columns |
+
+Metadata is joined on the `Sample` key (the metadata CSV must also have a
+`Sample` column), so attaching metadata requires a `Sample` column in the input.
+
+## Install
+
+salmopredict runs on **Python 3.10** and loads its model with **AutoGluon
+1.1.1** — both are hard requirements, because the model is pickled with that
+exact stack.
+
+**New installation from this source directory.** Run these commands from the
+directory containing `pyproject.toml`:
+
+```bash
+conda create -n salmopredict python=3.10
+conda activate salmopredict
+python -m pip install .
+salmopredict check
+```
+
+This installs AutoGluon 1.1.1 with its **Torch and FastAI backends**, compatible
+`setuptools<81`, the Streamlit GUI, and the bundled prediction model. The
+backends are required by the bundled ensemble; base `autogluon.tabular` alone
+does not install them. AutoGluon 1.1.1 also needs `pkg_resources`, which newer
+setuptools releases no longer provide.
+
+Both interfaces are then available:
+
+```bash
+salmopredict run -i features.csv -o results/   # command line
+salmopredict gui                                # browser GUI
+```
+
+**Conda environment (alternative, from this source directory).** Pins Python 3.10 and installs
+AutoGluon via pip inside the env (conda-installed AutoGluon does not resolve
+cleanly for this project):
+
+```bash
+conda env create -f environment.yml
+conda activate salmopredict
+salmopredict check
+```
+
+**Editable / development install (from a clone).**
+
+```bash
+python -m pip install -e .          # installs the CLI and the Streamlit GUI
+```
+
+**Install the updated local wheel.** In a Python 3.10 environment:
+
+```bash
+python -m pip install --upgrade dist/salmopredict-0.3.0-py3-none-any.whl
+salmopredict check
+```
+
+**Update an existing source installation.** Stop a running GUI with `Ctrl+C`,
+then run from this source directory:
+
+```bash
+conda activate salmopredict
+python -m pip install --upgrade -e .
+salmopredict check
+salmopredict gui
+```
+
+**PyPI installation / upgrade.** In a Python 3.10 environment:
+
+```bash
+python -m pip install --upgrade "salmopredict>=0.3.0"
+salmopredict check
+```
+
+Version 0.3.0 includes two-table prediction and installs the required Torch,
+FastAI and compatible setuptools dependencies automatically.
+
+If the page opens but prediction reports `No module named 'pkg_resources'`,
+`torch`, or `fastai`, use the update/repair command above and restart the GUI.
+To verify actual prediction from a source checkout (use a new output folder):
+
+```bash
+salmopredict run -i examples/example_features.csv -o results_install_check/
+```
+
+## The model
+
+The prediction model is **already bundled** with salmopredict — both in this
+repository and inside the PyPI wheel — at `salmopredict/models/model_default`, a
+30 MB deployment. salmopredict uses it automatically, so the tool works out of
+the box with no extra download or build step.
+
+Model resolution order is `--model`, then `$SALMOPREDICT_MODEL`, then the single
+directory under the package `models/` folder; with nothing specified it uses the
+bundled `model_default`. Pass `--model /path/to/other` to run a different
+AutoGluon model.
+
+## Usage
+
+Ready-to-run inputs live in [`examples/`](examples/) (see its README):
+`example_features.csv` (Type 1, no `Sample`), `example_with_sample.csv`
+(Type 2, with `Sample`), and `example_meta.csv` (metadata to attach). Features
+are `gene_frequency × log10(CFU dose)`, matching how the model was trained. Try
+one immediately:
+
+```bash
+salmopredict run -i examples/example_features.csv -o results/
+```
+
+```bash
+# Features only  -> output has just Incidence(%)
+salmopredict run -i features.csv -o results/ --model /path/to/model
+
+# With a Sample column  -> output has Sample, Incidence(%)
+salmopredict run -i examples/example_with_sample.csv -o results/
+
+# Attach metadata joined on the Sample key -> Sample, Incidence(%), + meta columns
+salmopredict run -i examples/example_with_sample.csv -o results/ \
+  --attach examples/example_meta.csv
+
+# Launch the GUI, or check the environment/model
+salmopredict gui
+salmopredict check --model /path/to/model
+```
+
+Each feature-input run writes one `pred_<input-stem>.csv` to the output directory; the
+prediction column is `Incidence(%)`. Features filled with `0` (genes the model
+expects but the input lacks) are always reported, and a prominent warning
+appears when more than `--missing-warn-frac` (default 0.3) of the model's
+features are missing.
+
+## Predict from samples and gene frequencies
+
+Supply two CSV files instead of calculating features yourself:
+
+* **Samples**: `Sample,dose_cfu,serotype`. `dose_cfu` contains raw CFU, e.g.
+  `1000`, not `3`. Each Sample must be nonblank and unique.
+* **Gene frequencies**: `Serotype` plus one column per gene, one row per
+  serotype, with numeric frequencies from 0 to 1. This accepts the layout of
+  `02_gene_frequencies.csv` directly.
+
+```bash
+salmopredict run \
+  --samples examples/example_samples.csv \
+  --gene-frequencies examples/example_gene_frequencies.csv \
+  -o results_two_tables/
+```
+
+For each sample, the program looks up its serotype and calculates
+`gene_frequency × log10(dose_cfu)`, then predicts incidence. It writes:
+
+* `features_example_samples.csv`: `Sample` and the calculated gene features.
+* `pred_example_samples.csv`: `Sample,dose_cfu,serotype,Incidence(%)`.
+
+Sample order and identifier strings (including leading zeros) are preserved.
+Required header names are case-insensitive. Serotype values match exactly after
+trimming outer spaces; synonyms and spelling differences are not guessed.
+Missing serotypes stop the run and list affected samples. Duplicate sample IDs
+or serotypes, blank required values, nonfinite/nonpositive doses, and frequencies
+outside [0, 1] also stop the run. Additional sample columns are ignored. Missing
+model genes use the existing fill-and-warning behavior.
+
+`--samples` and `--gene-frequencies` must be used together and cannot be combined
+with `-i` or `--attach`. Use `--force` to replace existing output files.
+
+In the **GUI**, choose **Samples + gene frequencies** under **Input mode**,
+upload both CSVs, inspect their previews, choose an output folder and click
+**Run prediction**. The result table and both CSV download buttons appear after
+success. **Feature CSV** selects the existing single-table workflow.
+
+The two example inputs were reconstructed from the matching sample/dose metadata
+and dose-weighted features. See [examples/README.md](examples/README.md) for their
+provenance and rounding tolerance.
+
+## License
+
+Licensed under the [PolyForm Noncommercial License 1.0.0](LICENSE): free to use,
+modify, and share for any **noncommercial** purpose — including research,
+teaching, and personal use, and by academic, government, public-health, and
+other nonprofit organizations — but **commercial use is not permitted**.
+Developed at the State Key Laboratory of Veterinary Public Health and Safety,
+China Agricultural University, in collaboration with the China National Center
+for Food Safety Risk Assessment (CFSA).
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/shaodongyan/SalmoPredict/main/salmopredict/gui/assets/vphs_logo.png" alt="State Key Laboratory of Veterinary Public Health and Safety" height="80">
+  &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
+  <img src="https://raw.githubusercontent.com/shaodongyan/SalmoPredict/main/salmopredict/gui/assets/cfsa_logo.png" alt="China National Center for Food Safety Risk Assessment" height="80">
+</p>

salmopredict-0.3.0/README.md

@@ -0,0 +1,213 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/shaodongyan/SalmoPredict/main/salmopredict/gui/assets/salmopredict_icon.png" alt="salmopredict" width="200">
+</p>
+
+# salmopredict
+
+AutoGluon-based **Incidence** predictor for *Salmonella* virulence-factor
+gene-frequency features, with a command-line interface and a Streamlit GUI.
+
+Given a feature table (rows = samples, columns = virulence-factor genes),
+salmopredict aligns the columns to the features a pre-trained AutoGluon
+`TabularPredictor` expects, runs the `WeightedEnsemble_L2` model, and writes a
+single prediction file. It reproduces the alignment used by the original
+`predict_autogluon.py`: column names are normalised R-`make.names`-style
+(`/` and `-` become `.`), genes the model expects but the input lacks are filled
+with `0` (a missing gene means frequency 0), and extra input columns are ignored.
+
+**Feature CSV input/output** — the output columns depend on whether the input
+has a `Sample` column:
+
+| Input | Output columns |
+|-------|----------------|
+| No `Sample` column (features only) | `Incidence(%)` |
+| Has a `Sample` column | `Sample`, `Incidence(%)` |
+| Has a `Sample` column **and** `--attach meta.csv` | `Sample`, `Incidence(%)`, + the metadata's other columns |
+
+Metadata is joined on the `Sample` key (the metadata CSV must also have a
+`Sample` column), so attaching metadata requires a `Sample` column in the input.
+
+## Install
+
+salmopredict runs on **Python 3.10** and loads its model with **AutoGluon
+1.1.1** — both are hard requirements, because the model is pickled with that
+exact stack.
+
+**New installation from this source directory.** Run these commands from the
+directory containing `pyproject.toml`:
+
+```bash
+conda create -n salmopredict python=3.10
+conda activate salmopredict
+python -m pip install .
+salmopredict check
+```
+
+This installs AutoGluon 1.1.1 with its **Torch and FastAI backends**, compatible
+`setuptools<81`, the Streamlit GUI, and the bundled prediction model. The
+backends are required by the bundled ensemble; base `autogluon.tabular` alone
+does not install them. AutoGluon 1.1.1 also needs `pkg_resources`, which newer
+setuptools releases no longer provide.
+
+Both interfaces are then available:
+
+```bash
+salmopredict run -i features.csv -o results/   # command line
+salmopredict gui                                # browser GUI
+```
+
+**Conda environment (alternative, from this source directory).** Pins Python 3.10 and installs
+AutoGluon via pip inside the env (conda-installed AutoGluon does not resolve
+cleanly for this project):
+
+```bash
+conda env create -f environment.yml
+conda activate salmopredict
+salmopredict check
+```
+
+**Editable / development install (from a clone).**
+
+```bash
+python -m pip install -e .          # installs the CLI and the Streamlit GUI
+```
+
+**Install the updated local wheel.** In a Python 3.10 environment:
+
+```bash
+python -m pip install --upgrade dist/salmopredict-0.3.0-py3-none-any.whl
+salmopredict check
+```
+
+**Update an existing source installation.** Stop a running GUI with `Ctrl+C`,
+then run from this source directory:
+
+```bash
+conda activate salmopredict
+python -m pip install --upgrade -e .
+salmopredict check
+salmopredict gui
+```
+
+**PyPI installation / upgrade.** In a Python 3.10 environment:
+
+```bash
+python -m pip install --upgrade "salmopredict>=0.3.0"
+salmopredict check
+```
+
+Version 0.3.0 includes two-table prediction and installs the required Torch,
+FastAI and compatible setuptools dependencies automatically.
+
+If the page opens but prediction reports `No module named 'pkg_resources'`,
+`torch`, or `fastai`, use the update/repair command above and restart the GUI.
+To verify actual prediction from a source checkout (use a new output folder):
+
+```bash
+salmopredict run -i examples/example_features.csv -o results_install_check/
+```
+
+## The model
+
+The prediction model is **already bundled** with salmopredict — both in this
+repository and inside the PyPI wheel — at `salmopredict/models/model_default`, a
+30 MB deployment. salmopredict uses it automatically, so the tool works out of
+the box with no extra download or build step.
+
+Model resolution order is `--model`, then `$SALMOPREDICT_MODEL`, then the single
+directory under the package `models/` folder; with nothing specified it uses the
+bundled `model_default`. Pass `--model /path/to/other` to run a different
+AutoGluon model.
+
+## Usage
+
+Ready-to-run inputs live in [`examples/`](examples/) (see its README):
+`example_features.csv` (Type 1, no `Sample`), `example_with_sample.csv`
+(Type 2, with `Sample`), and `example_meta.csv` (metadata to attach). Features
+are `gene_frequency × log10(CFU dose)`, matching how the model was trained. Try
+one immediately:
+
+```bash
+salmopredict run -i examples/example_features.csv -o results/
+```
+
+```bash
+# Features only  -> output has just Incidence(%)
+salmopredict run -i features.csv -o results/ --model /path/to/model
+
+# With a Sample column  -> output has Sample, Incidence(%)
+salmopredict run -i examples/example_with_sample.csv -o results/
+
+# Attach metadata joined on the Sample key -> Sample, Incidence(%), + meta columns
+salmopredict run -i examples/example_with_sample.csv -o results/ \
+  --attach examples/example_meta.csv
+
+# Launch the GUI, or check the environment/model
+salmopredict gui
+salmopredict check --model /path/to/model
+```
+
+Each feature-input run writes one `pred_<input-stem>.csv` to the output directory; the
+prediction column is `Incidence(%)`. Features filled with `0` (genes the model
+expects but the input lacks) are always reported, and a prominent warning
+appears when more than `--missing-warn-frac` (default 0.3) of the model's
+features are missing.
+
+## Predict from samples and gene frequencies
+
+Supply two CSV files instead of calculating features yourself:
+
+* **Samples**: `Sample,dose_cfu,serotype`. `dose_cfu` contains raw CFU, e.g.
+  `1000`, not `3`. Each Sample must be nonblank and unique.
+* **Gene frequencies**: `Serotype` plus one column per gene, one row per
+  serotype, with numeric frequencies from 0 to 1. This accepts the layout of
+  `02_gene_frequencies.csv` directly.
+
+```bash
+salmopredict run \
+  --samples examples/example_samples.csv \
+  --gene-frequencies examples/example_gene_frequencies.csv \
+  -o results_two_tables/
+```
+
+For each sample, the program looks up its serotype and calculates
+`gene_frequency × log10(dose_cfu)`, then predicts incidence. It writes:
+
+* `features_example_samples.csv`: `Sample` and the calculated gene features.
+* `pred_example_samples.csv`: `Sample,dose_cfu,serotype,Incidence(%)`.
+
+Sample order and identifier strings (including leading zeros) are preserved.
+Required header names are case-insensitive. Serotype values match exactly after
+trimming outer spaces; synonyms and spelling differences are not guessed.
+Missing serotypes stop the run and list affected samples. Duplicate sample IDs
+or serotypes, blank required values, nonfinite/nonpositive doses, and frequencies
+outside [0, 1] also stop the run. Additional sample columns are ignored. Missing
+model genes use the existing fill-and-warning behavior.
+
+`--samples` and `--gene-frequencies` must be used together and cannot be combined
+with `-i` or `--attach`. Use `--force` to replace existing output files.
+
+In the **GUI**, choose **Samples + gene frequencies** under **Input mode**,
+upload both CSVs, inspect their previews, choose an output folder and click
+**Run prediction**. The result table and both CSV download buttons appear after
+success. **Feature CSV** selects the existing single-table workflow.
+
+The two example inputs were reconstructed from the matching sample/dose metadata
+and dose-weighted features. See [examples/README.md](examples/README.md) for their
+provenance and rounding tolerance.
+
+## License
+
+Licensed under the [PolyForm Noncommercial License 1.0.0](LICENSE): free to use,
+modify, and share for any **noncommercial** purpose — including research,
+teaching, and personal use, and by academic, government, public-health, and
+other nonprofit organizations — but **commercial use is not permitted**.
+Developed at the State Key Laboratory of Veterinary Public Health and Safety,
+China Agricultural University, in collaboration with the China National Center
+for Food Safety Risk Assessment (CFSA).
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/shaodongyan/SalmoPredict/main/salmopredict/gui/assets/vphs_logo.png" alt="State Key Laboratory of Veterinary Public Health and Safety" height="80">
+  &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
+  <img src="https://raw.githubusercontent.com/shaodongyan/SalmoPredict/main/salmopredict/gui/assets/cfsa_logo.png" alt="China National Center for Food Safety Risk Assessment" height="80">
+</p>

{salmopredict-0.1.2 → salmopredict-0.3.0}/environment.yml

@@ -8,9 +8,5 @@ dependencies:
   - python=3.10
   - pip
   - pip:
-      - autogluon.tabular==1.1.1
-      - pandas>=2.0
-      - openpyxl>=3.0
-      - rich-argparse>=1.4
-      - streamlit>=1.30
+      # pyproject.toml includes the Torch/FastAI backends and setuptools<81.
       - -e .

salmopredict-0.3.0/examples/README.md

@@ -0,0 +1,83 @@
+# Example inputs
+
+Three ready-to-run files that cover the two input types and the metadata attach.
+Feature values are built the way the model was trained:
+
+```
+feature = gene_frequency(serotype, gene)  ×  log10(CFU dose)
+```
+
+so the same serotype at a higher CFU has larger feature values and a higher
+predicted incidence. All files share the same 10 samples — two serotypes
+(Enteritidis, Typhimurium) each at CFU = 500 / 1 000 / 2 000 / 10 000 / 100 000.
+Gene column names keep the original biological form (`mig-5`, `spiC/ssaB`, …);
+salmopredict normalises them to the model's names (`mig-5` → `mig.5`).
+
+| File | Rows × cols | Type | Output when run |
+|------|-------------|------|-----------------|
+| `example_features.csv` | 10 × 123 | **Type 1** — features only, **no `Sample`** column (just the 123 genes the model uses) | `Incidence(%)` |
+| `example_with_sample.csv` | 10 × 348 | **Type 2** — a `Sample` column + all 347 genes (the ~224 extra genes are ignored) | `Sample`, `Incidence(%)` |
+| `example_meta.csv` | 10 × 5 | Metadata to **attach** — `Sample` + `serotype`, `dose_cfu`, `source`, `region` | joined onto a Type-2 run by the `Sample` key |
+
+## Run them
+
+```bash
+# Type 1: features only -> a single Incidence(%) column
+salmopredict run -i examples/example_features.csv -o results/
+
+# Type 2: a Sample column -> Sample, Incidence(%)
+salmopredict run -i examples/example_with_sample.csv -o results/
+
+# Type 2 + attach: metadata joined on Sample -> Sample, Incidence(%), + meta columns
+salmopredict run -i examples/example_with_sample.csv -o results/ \
+  --attach examples/example_meta.csv
+```
+
+The attached run shows the dose–response, since `example_meta.csv` carries the
+`dose_cfu` alongside each `Sample`:
+
+```
+Sample,Incidence(%),serotype,dose_cfu,source,region
+S001,12.39,Enteritidis,500,retail chicken,North
+S002,14.15,Enteritidis,1000,retail pork,East
+...
+S005,37.43,Enteritidis,100000,retail pork,West
+```
+
+Rules for attaching metadata:
+
+* the **input** must have a `Sample` column (Type 2), and so must the
+  **metadata** file — the two are joined on `Sample`;
+* the metadata's `Sample` values should be unique (duplicates are rejected);
+* every metadata column except `Sample` is appended to the output.
+
+In the GUI (`salmopredict gui`), the **Attach metadata** box only appears once
+the chosen input is detected to have a `Sample` column.
+
+## Rebuilding these files
+
+The values come from the per-serotype gene-frequency table used to train the
+model (`results/02_gene_frequencies.csv` in the assembly project) multiplied by
+`log10(dose)`, reproducing `multiply_CFU_geneFreq.R`. To change the serotypes or
+CFU values, edit that grid and recompute `gene_frequency × log10(CFU)` for every
+gene column — do not edit a dose value alone, or the features and the dose will
+disagree.
+
+## Two-table input examples
+
+`example_samples.csv` contains 10 samples with raw `dose_cfu` and `serotype`.
+`example_gene_frequencies.csv` has 2 serotypes and 123 model gene columns.
+Both are also saved in the sibling `../test/` folder requested for verification.
+
+These files were reconstructed from `../test/pred_example_with_sample.csv`
+(sample IDs, serotypes and doses only) and `../test/example_features.csv`
+(weighted features), pairing rows in their original order. The prediction column
+is not used to derive frequencies. For each serotype, the 1000-CFU row gives
+`frequency = feature / log10(1000) = feature / 3`. All five dose rows per serotype
+were checked against that frequency. The maximum reconstructed feature error
+is less than 5e-7, consistent with six-decimal rounding in the original features.
+
+```bash
+salmopredict run --samples examples/example_samples.csv \
+  --gene-frequencies examples/example_gene_frequencies.csv -o results_two_tables/
+```