FedGWAS 0.0.1__tar.gz

fedgwas-0.0.1/.flwr/.gitignore

@@ -0,0 +1 @@
+.credentials

fedgwas-0.0.1/.github/workflows/deploy-docs.yml

@@ -0,0 +1,61 @@
+name: Deploy documentation
+
+on:
+  push:
+    tags:
+      - '*'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: github-pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build Docusaurus site
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: docs/website/package-lock.json
+
+      - name: Install dependencies
+        working-directory: docs/website
+        run: npm ci
+
+      - name: Build documentation
+        working-directory: docs/website
+        run: npm run build
+
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/website/build
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v4

fedgwas-0.0.1/.github/workflows/publish-pypi.yml

@@ -0,0 +1,57 @@
+name: Publish Python package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: python -m pip install --upgrade build twine
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Check distributions
+        run: python -m twine check dist/*
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/FedGWAS/
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

fedgwas-0.0.1/.gitignore

@@ -0,0 +1,145 @@
+.venv
+dist/
+sdist/
+**/__pycache__/
+.pytest_cache/
+*.pyc
+.mypy_cache/
+docs/website/.docusaurus/
+
+# Local-only docs (not shipped)
+docs/paper/
+docs/old_docs/
+docs/prd/
+docs/README_old.md
+
+# Data
+user_data/
+
+# Logs
+logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+dev-debug.log
+
+# Dependency directories
+docs/website/node_modules/
+docs/website/build/
+
+# Environment variables
+.env
+
+# Editor directories and files
+.idea
+.vscode
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# OS specific
+.DS_Store
+**/.DS_Store
+
+# Legacy/archived directories
+archived/
+bin/
+centers/
+data/
+
+# Unused / local-only pipeline paths
+pipeline/exerpiements.md
+pipeline/experiments.md
+pipeline/visualization_archived/
+pipeline/server/strategy.py
+pipeline/server/strategy_new.py
+pipeline/server/aggregator_qc.py
+pipeline/utils/bloom_filter.py
+
+# Redundant/outdated documentation
+Readme_pipeline.md
+EXPERIMENT_RUNNER_README.md
+.pre-commit-config.yaml
+!cluster_deployment/docs/
+!cluster_deployment/docs/**
+
+# Docker (local workflow only; cluster deployment is under cluster_deployment/)
+docker/
+.dockerignore
+
+# Performance manuscript drafts (local only; configs stay in repo)
+experiments/performance/README.md
+experiments/performance/appendix_sections.md
+experiments/performance/appendix_table.md
+experiments/performance/appendix_table.tex
+experiments/performance/manuscript_sections.md
+
+# Local notes, reports, and archives (not shipped)
+experiments/real_world/1000genomes/EXPERIMENT_STATUS.md
+ISSUES_REPORT.md
+ISSUES_REPORT_UPDATED.md
+plan.md
+experiments.docx
+InfoSummit_kinship.pdf
+mkdocs.yml
+pipeline.pdf
+pipeline.zip
+plink.zip
+results/
+
+# Experiment run outputs and synthetic data artifacts
+experiments/**/results/
+experiments/**/results_*/
+experiments/*/*/results/
+experiments/**/data/**/*.bed
+experiments/**/data/**/*.bim
+experiments/**/data/**/*.fam
+experiments/**/data/**/*.log
+experiments/**/data/**/*.kin0
+experiments/**/data/**/*.assoc*
+experiments/**/data/**/*.genome
+experiments/**/data/**/*.hwe
+experiments/**/data/**/*.imiss
+experiments/**/data/**/*.lmiss
+experiments/**/data/**/*.frq
+experiments/**/intermediate/
+**/__pycache__/
+
+# Task / cluster bundles
+fedgwas-cluster.tar.gz
+cluster_deployment/wheels/
+
+# Log files
+*.log
+**/*.log
+
+# PLINK output files
+*.bed
+*.bim
+*.fam
+*.kin0
+*.assoc*
+*.genome
+*.hwe
+*.imiss
+*.lmiss
+*.frq
+
+# Large data files (duplicate patterns for safety)
+*.bed
+*.bim
+*.fam
+
+# claude
+.claude/
+.venv/
+claude.md
+.windsurfrules
+README-task-manager.md
+.env.example
+/scripts/
+.cursor/*
+.test_scenario_a.py
+my_study/

fedgwas-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 idsla
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fedgwas-0.0.1/PKG-INFO

@@ -0,0 +1,287 @@
+Metadata-Version: 2.5
+Name: FedGWAS
+Version: 0.0.1
+Summary: Federated genome-wide association study pipeline built with Flower and PLINK
+Project-URL: Homepage, https://github.com/idsla/Fed-GWAS
+Project-URL: Repository, https://github.com/idsla/Fed-GWAS
+Project-URL: Issues, https://github.com/idsla/Fed-GWAS/issues
+Project-URL: Documentation, https://idsla.github.io/Fed-GWAS/
+Author: idsla
+License: MIT
+License-File: LICENSE
+Keywords: bioinformatics,federated-learning,flower,gwas,plink
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.11
+Requires-Dist: flwr[simulation]<1.20,>=1.19.0
+Requires-Dist: matplotlib>=3.10.9
+Requires-Dist: mkdocs>=1.6.1
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: pandas-plink>=2.3.1
+Requires-Dist: pandas>=2.2.2
+Requires-Dist: phe>=1.5.0
+Requires-Dist: pycryptodomex>=3.19.0
+Requires-Dist: pyplink>=1.3.7
+Requires-Dist: pysnptools>=0.5.13
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: quarto-cli>=1.9.38
+Requires-Dist: rich>=13.0.0
+Requires-Dist: scipy>=1.9.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: flake8-docstrings>=1.7.0; extra == 'dev'
+Requires-Dist: flake8>=7.1.0; extra == 'dev'
+Requires-Dist: isort>=5.13.2; extra == 'dev'
+Requires-Dist: mypy>=1.10.1; extra == 'dev'
+Requires-Dist: pre-commit>=3.7.1; extra == 'dev'
+Requires-Dist: pylint>=3.2.5; extra == 'dev'
+Requires-Dist: pytest>=8.2.2; extra == 'dev'
+Requires-Dist: tox>=4.16.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/idsla/Fed-GWAS/main/docs/website/images/logo-readme.png" alt="FedGWAS logo" width="640">
+</p>
+
+# FedGWAS: a lightweight federated pipeline for privacy-preserving GWAS screening
+
+[![PyPI](https://img.shields.io/pypi/v/FedGWAS.svg)](https://pypi.org/project/FedGWAS/)
+[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-2f8f83)](https://idsla.github.io/Fed-GWAS/)
+[![Deploy documentation](https://github.com/idsla/Fed-GWAS/actions/workflows/deploy-docs.yml/badge.svg)](https://github.com/idsla/Fed-GWAS/actions/workflows/deploy-docs.yml)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+## Overview
+
+FedGWAS is a lightweight federated pipeline for privacy-preserving GWAS screening across distributed genomic datasets. It coordinates federated quality control, KING-based relatedness screening, and logistic-regression association screening under a client–server architecture, while keeping genotype-level computations local to participating clients. FedGWAS uses Flower for federated coordination, PLINK for genetics operations, and encryption, shuffling, anonymization, and lightweight secret-sharing so that the server can relay selected protocol messages without decrypting them.
+
+Use FedGWAS when multiple participating institutions need a shared GWAS screening lifecycle and cannot pool individual-level genotype data.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/idsla/Fed-GWAS/main/docs/website/images/current_overview.png" alt="FedGWAS workflow illustration" width="100%">
+</p>
+
+To get started and learn how to use FedGWAS, use the following resources:
+
+- Documentation site: [Documentation](https://idsla.github.io/Fed-GWAS/)
+- Examples gallery: [Examples](https://idsla.github.io/Fed-GWAS/examples/overview)
+- API reference: [API Reference](https://idsla.github.io/Fed-GWAS/api-reference/api)
+- Technical details: [Technical Details](https://idsla.github.io/Fed-GWAS/user-guide/design/workflow)
+
+## Prerequisites
+
+FedGWAS requires Python 3.11 or later, Flower, and PLINK. Input genotypes use [PLINK 1.9](https://www.cog-genomics.org/plink/1.9/) binary format (`plink` on `PATH` or configured per client). KING-based relatedness screening also needs [PLINK 2](https://www.cog-genomics.org/plink/2.0/) available as `plink2`. VCF input is supported via conversion to PLINK-compatible representations where configured.
+
+```bash
+plink --version
+plink2 --version
+```
+
+For repository-based runs, you can also set the PLINK path in each client config if your environment does not expose `plink` globally.
+
+## FedGWAS Local Simulation Guide
+
+Local simulation mode runs the full FedGWAS screening workflow on one machine by launching multiple simulated clients and a federated server through Flower. Use it to validate an installation, create simulation experiments from preset settings and generated data, prototype client (center) configs, and compare federated outputs against a centralized baseline without setting up a real federated deployment.
+
+You can start local simulation in either of two ways:
+
+1. Recommended: install from PyPI and use `fedgwas-sim` command line interface (CLI)
+2. Repository/local workflow: clone this repository and run the old scripts directly
+
+Both workflows require:
+
+- Python 3.11 or later
+- PLINK 1.9 (`plink`) and PLINK 2 (`plink2`) available on `PATH` or configured locally
+- Flower installed through the package or local environment
+
+### Recommended: PyPI CLI Workflow
+
+Install the package:
+
+```bash
+python -m pip install FedGWAS
+```
+
+Verify that the simulation CLI is available:
+
+```bash
+fedgwas-sim --help
+```
+
+Create a standalone study directory and run the tiny two-client simulation:
+
+```bash
+mkdir my_study
+cd my_study
+
+# initialize study project directory
+fedgwas-sim init
+# setup data and configurations
+fedgwas-sim setup-experiment syn-tiny --seed 42
+# validation and run simulation
+fedgwas-sim check
+fedgwas-sim run --rounds 100
+# evaluation and results collection
+fedgwas-sim baseline generate --output data/centralized_baseline
+fedgwas-sim evaluate results --baseline data/centralized_baseline --king
+fedgwas-sim results collect --label tiny_run
+```
+
+The usage of the CLI can be found in the [documentation site](https://idsla.github.io/Fed-GWAS/user-guide/cli-simulation).
+
+### Repository/Local Script Workflow
+
+Clone the repository if you want the old direct script workflow, bundled experiment files, cluster deployment scripts, documentation source, or developer tooling:
+
+```bash
+git clone https://github.com/idsla/Fed-GWAS.git
+cd Fed-GWAS
+python -m pip install -e .
+```
+
+With `uv`, you can install the local environment with:
+
+```bash
+git clone https://github.com/idsla/Fed-GWAS.git
+cd Fed-GWAS
+uv sync --python 3.11
+```
+
+Generate synthetic data:
+
+```bash
+python pipeline/simulation/simulated_data/generate_synthetic_data.py \
+  --scale tiny \
+  --partition-strategy even \
+  --seed 42 \
+  --output-dir experiments/correctness/tiny_even/data
+```
+
+Generate the centralized baseline:
+
+```bash
+python experiments/tools/generate_baseline.py \
+  experiments/correctness/tiny_even/config.yaml
+```
+
+Run the federated simulation:
+
+```bash
+flwr run . local-simulation --stream
+```
+
+Or run with explicit release-smoke settings:
+
+```bash
+flwr run . local-simulation --stream --run-config \
+  'simulation=true num-server-rounds=100 config_path="experiments/correctness/tiny_even/configs"'
+```
+
+Evaluate the run:
+
+```bash
+python experiments/tools/evaluation/evaluate_all.py \
+  experiments/correctness/tiny_even/results_2 \
+  --baseline experiments/correctness/tiny_even/data/tiny/centralized_baseline \
+  --king
+```
+
+If you changed the active config output paths, pass the results directory from those config files instead.
+
+### Example Simulation Experiments
+
+We have a few preset experiments with generated data and configs in the repository for testing and demonstration. You can find the details of these example experiments in the documentation and the experiment directories:
+
+- Tiny experiment details: [experiments/correctness/tiny_even/README.md](experiments/correctness/tiny_even/README.md)
+
+- Small experiment details: [experiments/performance/small_even/README.md](experiments/performance/small_even/README.md)
+
+- Real-world data experiment details: [experiments/real_world/1000genomes/README.md](experiments/real_world/1000genomes/README.md)
+
+## FedGWAS Cluster Deployment Guide
+
+Use federated deployment when the server and clients should run as separate Flower processes, usually on separate machines. One coordinating **server** runs SuperLink and submits the app. Each participating **client** runs a SuperNode with its own center config and local PLINK data.
+
+FedGWAS provides two equivalent deployment modes. Both wrap `flower-superlink`, `flower-supernode`, and `flwr run . local-deployment`. Use Flower 1.19.x on every node. Pick one mode for a given run; do not mix them.
+
+### CLI
+
+```bash
+fedgwas-deploy server start --host 0.0.0.0 --daemon --log-file /tmp/superlink.log
+
+fedgwas-deploy client start \
+  --server <server-ip> \
+  --center-id <k> \
+  --config configs/center_k.yaml \
+  --daemon
+
+fedgwas-deploy server run --server <server-ip> --rounds 20 --scale tiny
+```
+
+Stop on each node separately: `fedgwas-deploy server stop` on the server, `fedgwas-deploy client stop` on each client.
+
+### Script deployment
+
+Clone this repository on each node and run the wrappers from the repository root:
+
+```bash
+nohup cluster_deployment/scripts/cluster-start-server.sh --server-ip 0.0.0.0 \
+  > /tmp/superlink.log 2>&1 &
+
+cluster_deployment/scripts/cluster-start-client.sh \
+  --server-ip <server-ip> \
+  --client-id <k> \
+  --config configs/center_k.yaml
+
+cluster_deployment/scripts/cluster-run-app.sh \
+  --server-ip <server-ip> \
+  --rounds 20 \
+  --scale tiny
+```
+
+Stop on each node separately: `cluster_deployment/scripts/cluster-stop-all.sh`.
+
+Guides:
+
+- Get Started: [Federated Deployment](https://idsla.github.io/Fed-GWAS/get-started/federated-deployment)
+- [CLI Deployment](https://idsla.github.io/Fed-GWAS/user-guide/federated-deployment/cli-deployment)
+- [Script Deployment](https://idsla.github.io/Fed-GWAS/user-guide/federated-deployment/script-deployment)
+- Worked example: [examples/04three-node-deployment](examples/04three-node-deployment/README.md)
+
+## Federated Protocol Summary
+
+FedGWAS implements a four-stage GWAS screening lifecycle. These conceptual stages are realized as coordinated federated rounds (including initialization, chunking, and aggregation):
+
+1. Privacy-preserving initialization: clients exchange encrypted seed shares via the server, which acts only as a message relay, and derive a shared global seed
+2. Federated quality control: local sample-level missingness filtering, then encrypted variant-level summaries for harmonized MAF, missingness, and Hardy–Weinberg filters
+3. KING-based relatedness screening: chunked, anonymized kinship estimation
+4. Federated association screening: privacy-preserving tokens for local logistic-regression filtering, then federated logistic regression
+
+The current implementation uses encryption, shuffling, anonymization, and lightweight secret-sharing. The server relays encrypted client-to-client payloads for selected stages and does not decrypt those payloads. Logging, metrics, and production- versus research-oriented output retention are configured separately and are not screening stages. See [CURRENT_VERSION.md](docs/CURRENT_VERSION.md) for the current privacy model, stage contracts, and limitations.
+
+Population stratification handling, continuous traits, and association models other than case–control logistic regression are not part of the current screening protocol.
+
+## Troubleshooting (Common Issues)
+
+- `plink` or `plink2` not found: install PLINK 1.9 and PLINK 2, and make sure both are on `PATH` or set in the client config.
+- Flower uses the wrong config: pass `--run-config 'config_path="..."'`.
+- Empty or missing results: generate the tiny synthetic data and baseline before running.
+- TestPyPI or PyPI install fails for a new release: check that the version in `pyproject.toml` has been published and that dependency resolution can reach normal PyPI.
+
+## License
+
+FedGWAS is distributed under the MIT License. See [LICENSE](LICENSE).
+
+## Contributors and Creator
+
+Software development is hosted at the [Rutgers Institute in Data Science, Learning, and Application](https://sites.rutgers.edu/idsla/). The accompanying paper authors are Xinyue Wang (Renmin University of China), Sitao Min, and Jaideep Vaidya (Rutgers University).
+
+**Contributors**:
+
+- Dr. Xinyue Wang <a href="mailto:xinyue.wang@ruc.edu.cn" aria-label="Email Dr. Xinyue Wang">&#9993;</a>
+- Dr. Sitao Min <a href="mailto:sitaomin1994@gmail.com" aria-label="Email Dr. Sitao Min">&#9993;</a>
+- Dr. Jaideep Vaidya <a href="mailto:jsvaidya@business.rutgers.edu" aria-label="Email Dr. Jaideep Vaidya">&#9993;</a>