Statistical correctness audit: post-hoc FWER, Firth CI, ANCOVA EMM, Box-Cox guard + UI

.github/workflows/tests.yml

@@ -0,0 +1,42 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  pytest:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    env:
+      # conftest.py already forces this; set here too so CI logs are explicit.
+      QT_QPA_PLATFORM: offscreen
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install headless-Qt system libraries
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libegl1 libgl1 libxkbcommon0 libdbus-1-3
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install pytest
+
+      # Runs the tests/ suite (testpaths in pyproject.toml). The validation/
+      # suite is skipped in CI because several scripts shell out to R.
+      - name: Run unit tests
+        run: pytest

.gitignore

@@ -0,0 +1,52 @@
+.DS_Store
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+.venv*_backup_*/
+
+# Claude Code internal files
+.claude/
+
+# R output artifacts
+Rplots.pdf
+
+# Dead-code audit report (generated artifact)
+tools/audit_report.md
+
+# Generated report outputs (auto-generated by the application)
+docs/test_report_preview.html
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+
+# Test & coverage
+.coverage
+htmlcov/
+
+# Logs & temp files
+*.log
+*.tmp
+*.bak
+
+# PyInstaller build log
+build_log.txt
+
+# Editor & personal tool configs (not relevant for end users or contributors)
+.cursorrules
+.vscode/
+.continue/
+pyrefly.toml
+
+# AI assistant instruction files (personal workflow)
+AGENTS.md
+CLAUDE.md
+
+# One-off dev scripts
+refactor_imports.py
+
+# Local example images / scratch assets
+decision_tree_example.png
+

BUILD.md

@@ -0,0 +1,229 @@
+# BioMedStatX — Build & Release Guide
+
+Step-by-step instructions for producing the Windows `.exe` and macOS `.app`
+distributions and publishing them on the GitHub Releases page.
+
+---
+
+## Prerequisites (one-time setup)
+
+### Common
+* Python 3.10+ with all `requirements`-style deps installed (the venv used for
+  development is enough).
+* `PyInstaller >= 6.0` (`pip install pyinstaller`).
+* GitHub CLI (`gh`) for uploading releases (optional — can also use the
+  web UI). Portable Windows install:
+  ```powershell
+  $asset = (Invoke-RestMethod 'https://api.github.com/repos/cli/cli/releases/latest' `
+            -Headers @{'User-Agent'='installer'}).assets |
+           Where-Object name -match 'windows_amd64\.zip$' | Select-Object -First 1
+  Invoke-WebRequest $asset.browser_download_url -OutFile $env:TEMP\gh.zip
+  Expand-Archive $env:TEMP\gh.zip "$env:LOCALAPPDATA\gh-cli" -Force
+  ```
+  Add `%LOCALAPPDATA%\gh-cli\bin` to your user PATH, then `gh auth login`.
+
+### Windows-specific
+Nothing extra. The `.spec` already references
+`tools/win_version_info.txt` and uses the `.ico` icon.
+
+### macOS-specific
+* **Python from python.org**, not Homebrew — required for `universal2`
+  wheels. Verify:
+  ```bash
+  python3 -c "import platform; print(platform.python_implementation(), platform.processor())"
+  ```
+  Reinstall scientific deps as `universal2` so the resulting `.app` runs on
+  both Intel and Apple Silicon:
+  ```bash
+  pip install --upgrade --force-reinstall scipy numpy PyQt5 pingouin statsmodels
+  ```
+* **Apple Developer ID** (Apple Developer Program, $99/year). Without signing,
+  users have to right-click → Open the first time and dismiss a Gatekeeper
+  warning. Notarisation removes the warning entirely.
+* `iconutil` (built-in on macOS) for high-quality `.icns` generation.
+
+---
+
+## Build steps
+
+### 1. Generate the icons
+
+The repo only ships `assets/Institutslogo.png`. Convert it once per platform:
+
+```bash
+python tools/convert_icon.py
+```
+
+Produces `assets/Institutslogo.ico` (Windows) and a basic
+`assets/Institutslogo.icns` (macOS, single-resolution via Pillow).
+
+**Better `.icns` on macOS** (Retina-quality, multi-resolution):
+
+```bash
+SRC=assets/Institutslogo.png
+ICONSET=/tmp/biomed.iconset
+mkdir -p "$ICONSET"
+for size in 16 32 64 128 256 512; do
+  sips -z $size $size       "$SRC" --out "$ICONSET/icon_${size}x${size}.png"
+  sips -z $((size*2)) $((size*2)) "$SRC" --out "$ICONSET/icon_${size}x${size}@2x.png"
+done
+iconutil -c icns "$ICONSET" -o assets/Institutslogo.icns
+rm -rf "$ICONSET"
+```
+
+### 2. Clean any previous build
+
+```powershell
+# Windows
+Remove-Item -Recurse -Force dist, build -ErrorAction SilentlyContinue
+```
+```bash
+# macOS / Linux
+rm -rf dist build
+```
+
+### 3. Run PyInstaller
+
+**Windows with Anaconda Python** — `Library\bin` must be on PATH so PyInstaller
+can resolve Anaconda-managed DLLs (`ffi-8.dll`, `libexpat.dll`, etc.).
+Build from a clean venv at a short path (`C:\bmx_venv`) to avoid MAX_PATH issues:
+
+```powershell
+# One-time venv setup (only needed once per machine)
+C:\Users\pkrumm\AppData\Local\anaconda3\python.exe -m venv C:\bmx_venv
+C:\bmx_venv\Scripts\pip install -r requirements.txt pyinstaller
+
+# Build
+$env:PATH = "C:\Users\pkrumm\AppData\Local\anaconda3\Library\bin;C:\Users\pkrumm\AppData\Local\anaconda3\DLLs;$env:PATH"
+C:\bmx_venv\Scripts\pyinstaller.exe BioMedStatX.spec --noconfirm
+```
+
+**macOS / Linux:**
+```bash
+pyinstaller BioMedStatX.spec --noconfirm
+```
+
+* Output (Windows): `dist/BioMedStatX/` — onefolder build, ~400 MB.
+* Output (macOS):   `dist/BioMedStatX.app/` — application bundle, ~100 MB.
+
+Build time: 5–10 minutes depending on the machine. Watch `build_log.txt` if
+you tee'd the output. Hidden imports for `pingouin`, `statsmodels`, `scipy`,
+`sklearn`, `networkx` are handled automatically by `collect_all` in the spec.
+
+### 4. Smoke test
+
+Launch the resulting binary once and verify the main window comes up:
+
+```powershell
+# Windows
+.\dist\BioMedStatX\BioMedStatX.exe
+```
+```bash
+# macOS
+open dist/BioMedStatX.app
+```
+
+If anything is missing at runtime, PyInstaller usually reports
+`ModuleNotFoundError`. Add the offending module to `hiddenimports` in
+`BioMedStatX.spec` and rebuild.
+
+### 5. macOS: sign and notarise (release builds only)
+
+```bash
+codesign --deep --force --options runtime \
+  --entitlements assets/entitlements.plist \
+  --sign "Developer ID Application: Philipp Krumm (TEAMID)" \
+  dist/BioMedStatX.app
+
+xcrun notarytool submit dist/BioMedStatX.app \
+  --apple-id "philipp-krumm123@outlook.de" \
+  --password "<app-specific-password>" \
+  --team-id "TEAMID" --wait
+
+xcrun stapler staple dist/BioMedStatX.app
+```
+
+Without these steps the user sees a Gatekeeper warning. With them, the app
+opens cleanly on any Mac. Replace `TEAMID` with your Apple Developer Team ID.
+
+### 6. Package for distribution
+
+Match the naming used in `v1.0.1` so users can compare versions easily.
+
+```powershell
+# Windows
+Compress-Archive -Path dist\BioMedStatX\* `
+                 -DestinationPath BioMedStatX_windows.zip -Force
+```
+```bash
+# macOS — preserves symlinks + signature
+ditto -c -k --sequesterRsrc --keepParent dist/BioMedStatX.app BioMedStatX_macOS.zip
+```
+
+The Excel template is shipped separately as
+`BioMedStatX_Excel_Template.xlsx` (lives under `assets/templates/` or a path
+you decide; not produced by PyInstaller).
+
+---
+
+## Publishing on GitHub
+
+### Option A — `gh` CLI (recommended)
+
+```bash
+gh release create v2.0 \
+  BioMedStatX_windows.zip \
+  --title "BioMedStatX V2.0" \
+  --generate-notes \
+  --target feature/advanced-stats-automation
+```
+
+Add the macOS build later:
+
+```bash
+gh release upload v2.0 BioMedStatX_macOS.zip
+```
+
+(Drop the `--target` argument once the release branch is `main`.)
+
+### Option B — Web UI
+
+1. Browse to `https://github.com/philippkrumm/BioMedStatX/releases/new`.
+2. **Choose a tag**: type `v2.0` and pick "Create new tag: v2.0 on publish".
+3. **Target**: select the branch you want to tag (currently
+   `feature/advanced-stats-automation`).
+4. **Generate release notes** (button) — fills the description from commit
+   history.
+5. **Attach files**: drag `BioMedStatX_windows.zip` (and later
+   `BioMedStatX_macOS.zip` + the Excel template) into the assets area.
+6. Publish.
+
+---
+
+## Versioning conventions
+
+The Windows `.exe` version resource and the `.app` bundle version both live
+in two files:
+
+| File | Field |
+|---|---|
+| `tools/win_version_info.txt` | `filevers`, `prodvers`, `FileVersion`, `ProductVersion` |
+| `BioMedStatX.spec` (`BUNDLE` block) | `CFBundleShortVersionString`, `CFBundleVersion` |
+
+Bump **both** when cutting a new release. Keep them in sync with the Git tag
+(`v2.0` → `2.0.0`).
+
+---
+
+## Troubleshooting
+
+* **`ModuleNotFoundError` at runtime** → add to `hiddenimports` in the spec.
+* **`Qt platform plugin "windows" could not be initialised`** → the `assets/`
+  directory wasn't copied into the bundle. Check the `datas=[...]` entry in
+  the spec.
+* **macOS "App is damaged and can't be opened"** → bundle wasn't notarised
+  *or* the user downloaded the zip via a quarantined browser. Notarising +
+  stapling fixes this; manually clearing the attribute also works:
+  `xattr -dr com.apple.quarantine /Applications/BioMedStatX.app`.
+* **Excel export missing** → `src/export_dispatcher.py` currently has the
+  Excel calls commented out (HTML-only mode). Uncomment to restore.