pal

Run repeated-model PAL (Post-hoc Attribution Loci) analysis: train many models on real labels and many on permuted labels, derive PAL_Common and PAL_AMAS discovery sets, and estimate PAL_AMAS p-values via null-distribution bootstrapping. This is PostHoc’s primary locus-discovery command — see Concepts and methodology for the full methodology.

posthoc pal

Usage

posthoc pal [OPTIONS]

Options

--pfile <pfile>: Required Prefix of PLINK2 .pgen/.pvar/.psam fileset.

--pheno <pheno>: Required Phenotype file.

--pheno-name <pheno_name>: Phenotype column name (default: first value column).

--covar <covar>: Covariate file.

--logistic: Binary phenotype (BCE loss).

--linear: Continuous phenotype (MSE loss).

--model <model_name>

Options:: mlp

--maf <min_maf>: Minimum minor allele frequency.

--geno <max_missing>: Max per-variant missingness.

--indep-pairwise <indep_pairwise>: LD pruning: WINDOW_SIZE STEP R2_THRESHOLD (requires plink2 on PATH).

--hidden-dims <hidden_dims>: Comma-separated MLP hidden layer sizes.

--dropout <dropout>: Dropout parameter of neural network

--epochs <max_epochs>

--patience <patience>

--lr <lr>

--activation <activation>

Options:: relu | tanh | gelu | lrelu

--weight-decay <weight_decay>

--data-dropout

--val-fraction <val_fraction>

--n-steps <n_steps>: Integrated Gradients interpolation steps.

--ig-baseline <ig_baseline>

Baseline reference input for Integrated Gradients.

Options:: zero | mean

--n-models <n_models>: Number of models trained with different seeds (real labels).

--n-null-models <n_null_models>: Number of models trained on permuted labels for the null distribution.

--theta-percentile <theta_percentile>: Percentile threshold for PAL detection (99.99=strict, 99.95=relaxed in the paper).

--ld-window <ld_window>: +/- SNP window checked for LD clumping.

--ld-r-threshold <ld_r_threshold>: Absolute Pearson r threshold for LD clumping.

--n-bootstrap <n_bootstrap>: Bootstrap iterations for PAL_AMAS P-values.

--seed <seed>: Base seed; model i uses seed+i.

--device <device>

--out <out_path>: Required Output PAL .tsv path.

Behavior notes

This command trains --n-models + --n-null-models MLPs sequentially — expect runtime roughly that multiple of a single attribute run. Consider --device cuda if available (see Installation).
Model attribution scores (MAS) for both real and null models are computed only on case samples (phenotype == 1); a click.UsageError is raised if a training split has no case samples at all. This means pal is only meaningful for --logistic in practice, even though --linear is accepted at the training-config level.
--seed is the base seed: real-label model i uses seed + i, and null-label model i uses seed + n_models + i, so every model in the run is trained with a distinct seed.
pal exposes additional MLP training knobs not present on attribute: --activation, --weight-decay, --data-dropout. These default to the same values attribute uses implicitly (relu, 1e-4, off), but are surfaced here because tuning them can matter more when training many models for aggregation.
--ld-window and --ld-r-threshold control the LD-clumping step used when computing PAL_AMAS occurrence counts — see Concepts and methodology.

Example

posthoc pal \
  --pfile datasets/data/processed/chr22_subset \
  --pheno outputs/simulated.pheno \
  --pheno-name PHENO1 \
  --logistic \
  --n-models 10 \
  --n-null-models 10 \
  --theta-percentile 99.99 \
  --n-bootstrap 100 \
  --out outputs/pal.tsv