## Overview

`amalgkit finalize` exports final per-species expression tables from metadata and merged abundance data.

Tau uses linear arithmetic means computed after inverse-transforming each run. See [Tau and replicate aggregation](Tau-and-replicate-aggregation.md) for donor/project weights, fixed tissue panels, missing values and migration of earlier results.

It is also the current location for optional batch-effect correction. All current backends are Python implementations.

## Inputs

`finalize` expects:

- metadata, usually from `wsfilter/metadata.tsv` or `csfilter/metadata.tsv`
- abundance tables from `merge` or `cstmm`

If `--input_dir inferred` is used, AMALGKIT reads:

```text
out_dir/cstmm if it exists, otherwise out_dir/merge
```

With `--metadata inferred`, AMALGKIT uses the last successful filter recorded
in `filter_metadata_state.json`, then the selected input directory's metadata.
Legacy workspaces prefer `csfilter` over `wsfilter` with a warning, not by file
modification time. See [metadata and normalization](https://github.com/kfuku52/amalgkit/wiki/Metadata-and-normalization).

FPKM or CPM from CSTMM counts requires `cstmm/metadata.tsv` or a filtered descendant
with valid `tmm_library_size`. For Oarfish runs, add `--norm log2p1-cpm`;
the default FPKM transformation is undefined for their length model.

For reproducible runs, pass the metadata path explicitly:

```bash
amalgkit finalize \
    --out_dir ./ \
    --metadata ./csfilter/metadata.tsv \
    --batch_effect_alg no
```

## Batch-Correction Backends

`--batch_effect_alg` supports:

| Algorithm | Extra dependency |
| --- | --- |
| `no` | none |
| `sva` | none beyond AMALGKIT Python dependencies |
| `ruvseq` | none beyond AMALGKIT Python dependencies |
| `combatseq` | optional `inmoose` |
| `latent_loglinear` | none beyond AMALGKIT Python dependencies; experimental |
| `latent_glm` | historical alias for `latent_loglinear`, not a likelihood GLM |

Examples:

```bash
amalgkit finalize \
    --out_dir ./ \
    --metadata ./csfilter/metadata.tsv \
    --batch_effect_alg sva
```

```bash
amalgkit finalize \
    --out_dir ./ \
    --metadata ./csfilter/metadata.tsv \
    --batch_effect_alg latent_loglinear \
    --latent_weighting dispersion \
    --latent_k 1
```

The example fixes k for reproducibility; it does not establish that k=1 is
appropriate for a particular dataset. Latent and RUV automatic k selection is
uncalibrated and is skipped unless `--latent_k_selection legacy` or
`--ruvseq_k_selection legacy` is explicitly supplied. Prefer a scientifically
justified explicit k and compare against k=0.

Model failures default to **skip the whole species' batch correction**. Requested
expression normalization still runs. Metadata and summaries distinguish `skipped`
from a normal `not_needed` result (e.g. k=0). Use `--batch_failure_policy error` to
require successful fitting. Invalid inputs and missing dependencies always stop.
The correction never retries without protected covariates or with another model.

ComBat-seq requires integer raw counts from `merge`, not CSTMM-divided counts.
Singleton batches and confounded designs are skipped as a whole. Its default
protects `sample_group`; `--combatseq_group_model batch_only` explicitly omits
that protection. Additional covariates may be specified using
`--batch_categorical_covariates` and `--batch_continuous_covariates`.

See [batch correction models and diagnostics](Batch-correction-models) for
assumptions, failure reasons, method differences and migration details.

## Main Outputs

Top level:

- `finalize/metadata.tsv`
- `finalize/finalize_exclusion.pdf`

Per species, under `finalize/<Species>/`:

- `<Species>_metadata.tsv`
- `<Species>_expression.tsv`
- `<Species>_expression_uncorrected.tsv`
- `<Species>_sample_group_mean.tsv`
- `<Species>_sample_group_mean_uncorrected.tsv`
- `<Species>_tau.tsv`
- `<Species>_tau_linear_mean.tsv`: linear arithmetic means used by tau
- `<Species>_tau_coverage.tsv`: required groups, available runs/units and missing-group reasons
- `<Species>_tau_weights.tsv`: run contributions within each group
- `<Species>_tau_definition.json`: transformation, weighting and tissue panel identifier
- `<Species>_correlation_statistics.tsv`
- `<Species>_batch_effect_summary.tsv`
- `<Species>_batch_effect_diagnostics.json` (complete settings, design and diagnostics)
- `<Species>_batch_effect_design.tsv` (when a correction design was evaluated)
- `<Species>_batch_effect_factors.tsv` (estimated SV/W; empty on skipped fits)
- `<Species>_batch_effect_removal_basis.tsv` (actual design-orthogonal removal space)
- `<Species>_curation_round_summary.tsv`
- `<Species>_curation_final_summary.tsv`
- `<Species>_before_after_<alg>.pdf` (when a batch-correction algorithm is selected)
- `<Species>_tau_hist_<alg>.pdf`

Expression tables have target IDs as rows and runs as columns, on the scale
selected by `--norm` (by default, log2(FPKM + 1)), after any requested batch
correction and postprocessing. They are not raw read-count tables.
`sample_group_mean` tables average runs on that expression scale. They differ
from `tau_linear_mean`, whose inverse transformation and weighting are defined
in [Tau and replicate aggregation](Tau-and-replicate-aggregation.md).

## General Options

| Option | Default | Use |
| --- | --- | --- |
| `--norm` | `log2p1-fpkm` | expression transformation before optional batch correction |
| `--clip_negative` | `yes` | clip negative corrected values to zero |
| `--maintain_zero` | `yes` | preserve input zero values after correction |
| `--batch_failure_policy` | `skip` | skip the entire species' correction on model failure; `error` stops |
| `--seed` | `0` | random seed for stochastic steps; `auto` requests an unseeded run |

## Backend-Specific Options

SVA:

- `--sva_nsv`
- `--sva_B`
- `--sva_nsv_permutations` (alias of `--sva_B`; permutation count only)
- `--sva_B_auto_max`
- `--sva_irw_iterations` (5; independent of permutations)
- `--sva_estimation_method` (`be`; `leek` or explicit `be_then_leek` also supported)

RUVSeq:

- `--ruvseq_control_genes`
- `--ruvseq_k`
- `--ruvseq_k_max`
- `--ruvseq_control_top_n`
- `--ruvseq_min_controls`
- `--ruvseq_control_file` (one unique gene ID per line, no header; control mode `file`)
- `--ruvseq_k_selection` (`manual`; `legacy` explicitly enables the heuristic)

latent_loglinear (historical alias: latent_glm):

- `--latent_weighting uniform|dispersion` (historical `--latent_family poisson|nb` aliases)
- `--latent_k INT|auto`
- `--latent_k_max INT`
- `--latent_max_iter INT`
- `--latent_tol FLOAT`
- `--latent_k_selection manual|legacy`

The comparison plot's after panels use the final saved expression matrix,
including clipping and input-zero restoration. Detailed diagnostics record each
nonlinear postprocessing step and its scale. Factor-space protection does not
guarantee preservation of arithmetic means after these operations.

Backend selectors:

- `--sva_backend python`
- `--combatseq_backend python`
- `--ruvseq_backend python`

`combatseq` imports `inmoose.pycombat` at runtime. Install `inmoose` before using `--batch_effect_alg combatseq`.

## Next Steps

Check outputs after a full run:

```bash
amalgkit sanity --out_dir ./ --check finalize
```