pg-sui 1.6.14.dev9__py3-none-any.whl → 1.6.16a3__py3-none-any.whl

pg_sui-1.6.16a3.dist-info/METADATA

@@ -0,0 +1,292 @@
+Metadata-Version: 2.4
+Name: pg-sui
+Version: 1.6.16a3
+Summary: Python machine and deep learning API to impute missing genotypes
+Author-email: "Drs. Bradley T. Martin and Tyler K. Chafin" <evobio721@gmail.com>
+Maintainer-email: "Dr. Bradley T. Martin" <evobio721@gmail.com>
+License: GNU General Public License v3 (GPLv3)
+Project-URL: Homepage, https://github.com/btmartin721/PG-SUI
+Project-URL: Documentation, https://pg-sui.readthedocs.io/en/latest/
+Project-URL: Source, https://github.com/btmartin721/PG-SUI.git
+Project-URL: BugTracker, https://github.com/btmartin721/PG-SUI/issues
+Keywords: impute,imputation,AI,deep learning,machine learning,neural network,vae,autoencoder,ubp,nlpca,population genetics,unsupervised,supervised,bioinformatics,snp,genomics,genotype,missing data,data analysis,data science,statistics,data visualization,python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Unix
+Classifier: Operating System :: POSIX
+Classifier: Natural Language :: English
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib
+Requires-Dist: numpy>=2.1
+Requires-Dist: pandas>=2.2.2
+Requires-Dist: scikit-learn>=1.4
+Requires-Dist: scipy
+Requires-Dist: seaborn
+Requires-Dist: torch
+Requires-Dist: tqdm
+Requires-Dist: toytree
+Requires-Dist: optuna
+Requires-Dist: rich
+Requires-Dist: rich[jupyter]
+Requires-Dist: snpio
+Provides-Extra: intel
+Requires-Dist: scikit-learn-intelex; extra == "intel"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx-rtd-theme; extra == "docs"
+Requires-Dist: sphinx_autodoc_typehints; extra == "docs"
+Requires-Dist: sphinxcontrib-napoleon; extra == "docs"
+Requires-Dist: sphinxcontrib-programoutput; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: wheel; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: sphinx; extra == "dev"
+Requires-Dist: sphinx-rtd-theme; extra == "dev"
+Requires-Dist: sphinx-autodoc-typehints; extra == "dev"
+Requires-Dist: sphinxcontrib-napoleon; extra == "dev"
+Requires-Dist: sphinxcontrib-programoutput; extra == "dev"
+Requires-Dist: requests; extra == "dev"
+Provides-Extra: optional
+Requires-Dist: PyObjC; extra == "optional"
+Provides-Extra: gui
+Requires-Dist: fastapi>=0.110; extra == "gui"
+Requires-Dist: uvicorn[standard]>=0.23; extra == "gui"
+Dynamic: license-file
+
+# PG-SUI
+
+![PG-SUI Logo](https://github.com/btmartin721/PG-SUI/blob/master/img/pgsui-logo-faded.png)
+
+Population Genomic Supervised and Unsupervised Imputation.
+
+## About PG-SUI
+
+PG-SUI is a Python 3 API that uses machine learning to impute missing values from population genomic SNP data. There are several supervised and unsupervised machine learning algorithms available to impute missing data, as well as some non-machine learning imputers that are useful.
+
+Below is some general information and a basic tutorial. For more detailed information, see our [API Documentation](https://pg-sui.readthedocs.io/en/latest/).
+
+### Unsupervised Imputation Methods
+
+Unsupervised imputers include three custom neural network models:
+
++ Variational Autoencoder (VAE) [1](#1)
+  + VAE models train themselves to reconstruct their input (i.e., the genotypes) [1](#1). To use VAE for imputation, the missing values are masked and the VAE model gets trained to reconstruct only on known values. Once the model is trained, it is then used to predict the missing values.
++ Autoencoder [2](#2)
+  + A standard autoencoder that trains the input to predict itself [2](#2). As with VAE, missing values are masked and the model gets trained only on known values. Predictions are then made on the missing values.
++ Non-linear Principal Component Analysis (NLPCA) [3](#3)
+  + NLPCA initializes random, reduced-dimensional input, then trains itself by using the known values (i.e., genotypes) as targets and refining the random input until it accurately predicts the genotype output [3](#3). The trained model can then predict the missing values.
++ Unsupervised Backpropagation (UBP) [4](#4)
+  + UBP is an extension of NLPCA that runs over three phases [4](#4). Phase 1 refines the randomly generated, reduced-dimensional input in a single layer perceptron neural network to obtain good initial input values. Phase 2 uses the refined reduced-dimensional input from phase 1 as input into a multi-layer perceptron (MLP), but in Phase 2 only the neural network weights are refined. Phase three uses an MLP to refine both the weights and the reduced-dimensional input. Once the model is trained, it can be used to predict the missing values.
+
+### Supervised Imputation Methods
+
+Supervised methods utilze the scikit-learn's ``IterativeImputer``, which is based on the MICE (Multivariate Imputation by Chained Equations) algorithm [5](#5), and iterates over each SNP site (i.e., feature) while uses the N nearest neighbor features to inform the imputation. The number of nearest features can be adjusted by users. IterativeImputer currently works with the following scikit-learn classifiers:
+
++ ImputeRandomForest
++ ImputeHistGradientBoosting
+
+See the [scikit-learn documentation](https://scikit-learn.org) for more information on IterativeImputer and each of the classifiers.
+
+### Non-Machine Learning (Deterministic) Methods
+
+We also include several deterministic options for imputing missing data, including:
+
++ Per-population mode per SNP site
++ Overall mode per SNP site
+
+## Installing PG-SUI
+
+PG-SUI supports both pip and conda distributions. Both are kept current with up-to-date releases.
+
+### Installation with Pip
+
+To install PG-SUI with pip, do the following. It is strongly recommended to install pg-sui in a virtual environment.
+
+``` shell
+python3 -m venv .pgsui-venv
+source .pgsui-venv/bin/activate
+pip install pg-sui
+```
+
+### Installation with Anaconda
+
+To install PG-SUI with Anaconda, do the following:
+
+``` shell
+conda create -n pgsui-env python=3.12
+conda activate pgsui-env
+conda install -c btmartin721 pg-sui
+```
+
+### Docker Container
+
+We also maintains a Docker image that comes with PG-SUI preinstalled. This can be useful for automated worklows such as Nextflow or Snakemake.
+
+``` shell
+docker pull pg-sui:latest
+```
+
+### Optional MacOS GUI
+
+PG-SUI ships an optional Electron GUI (Graphical User Interface) wrapper around the Python CLI. Currently for the GUI, only MacOS is supported.
+
+1. Install the Python-side extras (FastAPI/ uvicorn helper) if you want to serve from Python:
+   `pip install pg-sui[gui]`
+2. Install [Node.js](https://nodejs.org) and fetch the app dependencies:
+   `pgsui-gui-setup`
+3. Launch the graphical interface:
+   `pgsui-gui`
+
+The GUI shells out to the same CLI underneath, so presets, overrides, and YAML configs behave identically.
+
+## Input Data
+
+You can read your input files as a GenotypeData object from the [SNPio](https://snpio.readthedocs.io/en/latest/) package. SNPio supports the VCF, PHYLIP, STRUCTURE, and GENEPOP input file formats.
+
+``` python
+# Import snpio. Automatically installed with pg-sui.
+from snpio import VCFReader
+
+# Read in VCF alignment.
+# SNPio also supports PHYLIP, STRUCTURE, and GENEPOP input file formats.
+data = VCFReader(
+    filename="pgsui/example_data/phylogen_subset14K.vcf.gz,
+    popmapfile="pgsui/example_data/popmaps/phylogen_nomx.popmap", # optional
+    force_popmap=True, # optional
+)
+```
+
+## Supported Imputation Methods
+
+There are several supported algorithms PG-SUI uses to impute missing data. Each one can be run by calling the corresponding class. You must provide a GenotypeData instance as the first positional argument.
+
+You can import all the supported methods with the following:
+
+``` python
+from pgsui import ImputeUBP, ImputeVAE, ImputeNLPCA, ImputeAutoencoder, ImputeRefAllele, ImputeMostFrequent, ImputeRandomForest, ImputeHistGradientBoosting
+```
+
+### Unsupervised Imputers
+
+The four unsupervised imputers can be run by initializing them with the SNPio ``GenotypeData`` object and then calling ``fit()`` and ``transform()``.
+
+``` python
+# Initialize the models, then fit and impute
+vae = ImputeVAE(data) # Variational autoencoder
+vae.fit()
+vae_imputed = vae.transform()
+
+nlpca = ImputeNLPCA(data) # Nonlinear PCA
+nlpca.fit()
+nlpca_imputed = nlpca.transform()
+
+ubp = ImputeUBP(data) # Unsupervised backpropagation
+ubp.fit()
+ubp_imputed = ubp.transform()
+
+ae = ImputeAutoencoder(data) # standard autoencoder
+ae.fit()
+ae_imputed = ae.transform()
+```
+
+The ``*_imputed`` objects will be NumPy arrays that are compatible with SNPio's ``GenotypeData`` objects.
+
+### Supervised Imputers
+
+Various supervised imputation options are supported, and these use the same API design.
+
+``` python
+# Supervised IterativeImputer classifiers
+
+# Random Forest
+rf = ImputeRandomForest(data)
+rf.fit()
+imputed_rf = rf.transform()
+
+# HistGradientBoosting
+hgb = ImputeHistGradientBoosting(data)
+hgb.fit()
+imputed_hgb = hgb.transform()
+```
+
+### Non-machine learning methods
+
+The following deterministic methods are supported. ``ImputeMostFrequent`` supports the mode-per-population or overall (global) mode options to inform imputation.
+
+``` python
+# Per-population, per-locus mode
+pop_mode = ImputeMostFrequent(data, by_populations=True)
+pop_mode.fit()
+imputed_pop_mode = pop_mode.transform()
+
+# Per-locus mode
+mode = ImputeMostFrequent(data, by_populations=False)
+mode.fit()
+imputed_mode = mode.transform()
+```
+
+Or, always replace missing values with the reference allele.
+
+``` python
+ref = ImputeRefAllele(data)
+ref.fit()
+imputed_ref = ref.transform()
+```
+
+## Command-Line Interface
+
+Run the PG-SUI CLI with ``pg-sui`` (installed alongside the library). The CLI follows the same precedence model as the Python API:
+
+``code defaults  <  preset (--preset)  <  YAML (--config)  <  explicit CLI flags  <  --set key=value``.
+
+Recent releases add explicit switches for the simulated-missingness workflow shared by the neural and supervised models:
+
++ ``--sim-strategy`` selects one of ``random``, ``random_weighted``, ``random_weighted_inv``, ``nonrandom``, ``nonrandom_weighted``.
++ ``--sim-prop`` sets the proportion of observed calls to temporarily mask when building the evaluation set.
++ ``--simulate-missing`` disables simulated masking entirely (store-false flag); omit it to inherit preset/YAML defaults or re-enable via ``--set sim.simulate_missing=True``.
+
+Example:
+
+``` shell
+pg-sui \
+  --vcf data.vcf.gz \
+  --popmap pops.popmap \
+  --models ImputeUBP ImputeVAE \
+  --preset balanced \
+  --sim-strategy random_weighted_inv \
+  --sim-prop 0.25 \
+  --prefix ubp_and_vae \
+  --n-jobs 4 \
+  --tune-n-trials 100 \
+  --set tune.enabled=True
+```
+
+CLI overrides cascade into every selected model, so a single invocation can evaluate multiple imputers with a consistent simulation strategy and output prefix.
+
+## References
+
+1. Kingma, D.P. & Welling, M. (2013). Auto-encoding variational bayes. In: Proceedings  of  the  International Conference on Learning Representations (ICLR). arXiv:1312.6114 [stat.ML].
+
+2. Hinton, G.E., & Salakhutdinov, R.R. (2006). Reducing the dimensionality of data with neural networks. Science, 313(5786), 504-507.
+
+3. Scholz, M., Kaplan, F., Guy, C. L., Kopka, J., & Selbig, J. (2005). Non-linear PCA: a missing data approach. Bioinformatics, 21(20), 3887-3895.
+
+4. Gashler, M. S., Smith, M. R., Morris, R., & Martinez, T. (2016). Missing value imputation with unsupervised backpropagation. Computational Intelligence, 32(2), 196-215.
+
+5. Stef van Buuren, Karin Groothuis-Oudshoorn (2011). mice: Multivariate Imputation by Chained Equations in R. Journal of Statistical Software 45: 1-67.

{pg_sui-1.6.14.dev9.dist-info → pg_sui-1.6.16a3.dist-info}/RECORD

@@ -1,10 +1,10 @@
-pg_sui-1.6.14.dev9.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+pg_sui-1.6.16a3.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
 pgsui/__init__.py,sha256=wQFzVX6vh8aUva1LCvP42jS7rcKCpkaU52YfZIy61q8,1493
-pgsui/_version.py,sha256=wKIKHCX5SmsO-4sA-OpkKAHVYuXeZ-aL_K4jO6bGQPU,719
-pgsui/cli.py,sha256=tYSXK_BvBv_8rpDEFGcqrV1OCwN48vMervVV-C-6H_A,29675
+pgsui/_version.py,sha256=Ob9Wzde013P9zPCsc2eaS--ZJQaRFPqutqIvBNJDnP4,714
+pgsui/cli.py,sha256=F6v7Bv073NgH3Ku_Lb6DSciTCLzM_o49ktrKnjkiHJg,30229
 pgsui/data_processing/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pgsui/data_processing/config.py,sha256=g5G7pjWG4uU2BRvBu_DpO0J_4X1Foa11X69imBWjaKA,20483
-pgsui/data_processing/containers.py,sha256=5bGA_u3czuTr8TMq6ZmQ-Wc1l-4Qh8-O2siBi3h-owc,51558
+pgsui/data_processing/containers.py,sha256=mtVExBEQQXCID_TbngxY23I690d09WIzmJBdVa7HIo0,51513
 pgsui/data_processing/transformers.py,sha256=kdwOTmfDjgQ3RmiwQIK7LYL4vQUpgA4bob7NHYgnYRM,30998
 pgsui/electron/bootstrap.py,sha256=wnrXgX-hiqrMMFE9WGoD-UC8zeK2ZP6Kupu68PodVWI,1185
 pgsui/electron/launch.py,sha256=M60o_jub77kJL-B9d_sMB7LYuTzWlOnQXR09efmCX2o,1715
@@ -53,15 +53,15 @@ pgsui/impute/supervised/imputers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRk
 pgsui/impute/supervised/imputers/hist_gradient_boosting.py,sha256=5LZsee2R9tbshmgVvLDIjGDihiQPvp9XfbaGwzL35E8,11509
 pgsui/impute/supervised/imputers/random_forest.py,sha256=jpeaLjhzYrwRPc9nPasLgwOqBoHlBlymHMc3x5OkBWA,10393
 pgsui/impute/unsupervised/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pgsui/impute/unsupervised/base.py,sha256=ev9sWIMTB7WwKgkPW5MkSGrGr_BZaxvhkKiUUmvI5jo,46794
+pgsui/impute/unsupervised/base.py,sha256=DqgP8QNKmbUaljzx_lWC_zFuWTUO3iiRseYTQEWNG0Q,46945
 pgsui/impute/unsupervised/callbacks.py,sha256=jkxncpKNRdssImv4N5c-Hq8VcA07QvxLoct7EqDW9RE,5026
 pgsui/impute/unsupervised/loss_functions.py,sha256=f18uQnerj0KF9xcU2I1_Y2OCKKguXXaEDaYhJg0XElY,10089
 pgsui/impute/unsupervised/nn_scorers.py,sha256=-rl5MBJm2GN6E1wPBIe1wMgdrHEHhYooUUxVbfcf1Z8,9758
 pgsui/impute/unsupervised/imputers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pgsui/impute/unsupervised/imputers/autoencoder.py,sha256=fREEWDcmL4DEpFTXFDQjb84sdf2yHSDoCLNWMDhHqe8,54018
-pgsui/impute/unsupervised/imputers/nlpca.py,sha256=fboE4gLv6M-mq2PPHSejtpSfShrhUfUSsngAinHgzVw,63797
-pgsui/impute/unsupervised/imputers/ubp.py,sha256=ThJh8J-txNaP3JZENtJeQJQim18U3vc2kxOW3vvnyqA,67021
-pgsui/impute/unsupervised/imputers/vae.py,sha256=zoOc9yEvAyUPGAew0x3clRvBb7SflMN0LPFuVO0rTsU,50598
+pgsui/impute/unsupervised/imputers/autoencoder.py,sha256=k8GJ80hysAteT-QUmRRtWfPcvH-QjUFHrWBZGVuFH1c,57872
+pgsui/impute/unsupervised/imputers/nlpca.py,sha256=AChGz0Gp9Yt0qF8vtrDI4t5iIr70LQRb-8pFGQBYLZo,69086
+pgsui/impute/unsupervised/imputers/ubp.py,sha256=sBJ9VSW2tTzXVjnXogjhuj6GixRaH0HcQ2B7cK4y6tw,71361
+pgsui/impute/unsupervised/imputers/vae.py,sha256=hK3ZOxyLjQqm-3Hcq2BMUZOghsJiDGYNRQjqA7zoncs,54713
 pgsui/impute/unsupervised/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pgsui/impute/unsupervised/models/autoencoder_model.py,sha256=mHmfTkldJNpN7Dy7RTS2RnkE2L_K1rChNjpjDvzRlEQ,12333
 pgsui/impute/unsupervised/models/nlpca_model.py,sha256=1NathvhsirBtd9UcmeJzRoVf7oi7PfDmRpt18Di63Cg,8021
@@ -74,8 +74,8 @@ pgsui/utils/misc.py,sha256=Mw5CsspFJkDAcCRufk-lO7fKyVoYK7PRYXkLXKswUjI,3065
 pgsui/utils/plotting.py,sha256=d5CTzGIpanu3j6rEB6fq_F1g8w_A2Ti_XiedRjIFFII,42444
 pgsui/utils/pretty_metrics.py,sha256=dtN7Ohcx3qJYCw4JeJCXvthGDdSV7bgE8v6EGwHSAE0,9862
 pgsui/utils/scorers.py,sha256=sL2upL2ZZMFBTMM4DiGiWeXrqc_fp1RRbleYCnuRUhw,12564
-pg_sui-1.6.14.dev9.dist-info/METADATA,sha256=F_9XvBZpZqKvrMnmD9TnwRuOkjXPEtnsUyGnRQu9orE,14443
-pg_sui-1.6.14.dev9.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pg_sui-1.6.14.dev9.dist-info/entry_points.txt,sha256=xidyl6yqQv7oj3XSzZC6Vv9l7aNgbHi_pjv-dJjGJds,129
-pg_sui-1.6.14.dev9.dist-info/top_level.txt,sha256=87-oDpfY6sDY_uN-OM2lcnrgPesifhzwqFOajp9ukz0,6
-pg_sui-1.6.14.dev9.dist-info/RECORD,,
+pg_sui-1.6.16a3.dist-info/METADATA,sha256=G87-keKhu56QhKFiAeGQVSD36EH_W2uNf9u4wciAsmU,12320
+pg_sui-1.6.16a3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pg_sui-1.6.16a3.dist-info/entry_points.txt,sha256=xidyl6yqQv7oj3XSzZC6Vv9l7aNgbHi_pjv-dJjGJds,129
+pg_sui-1.6.16a3.dist-info/top_level.txt,sha256=87-oDpfY6sDY_uN-OM2lcnrgPesifhzwqFOajp9ukz0,6
+pg_sui-1.6.16a3.dist-info/RECORD,,

pgsui/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '1.6.14.dev9'
-__version_tuple__ = version_tuple = (1, 6, 14, 'dev9')
+__version__ = version = '1.6.16a3'
+__version_tuple__ = version_tuple = (1, 6, 16, 'a3')
 
 __commit_id__ = commit_id = None

pgsui/cli.py

@@ -185,6 +185,8 @@ def _args_to_cli_overrides(args: argparse.Namespace) -> dict:
         overrides["io.n_jobs"] = int(args.n_jobs)
     if hasattr(args, "seed"):
         overrides["io.seed"] = _parse_seed(args.seed)
+    if hasattr(args, "debug"):
+        overrides["io.debug"] = bool(args.debug)
 
     # Train
     if hasattr(args, "batch_size"):
@@ -589,6 +591,7 @@ def main(argv: Optional[List[str]] = None) -> int:
         help="Random seed: 'random', 'deterministic', or an integer.",
     )
     parser.add_argument("--verbose", action="store_true", help="Info-level logging.")
+    parser.add_argument("--debug", action="store_true", help="Debug-level logging.")
     parser.add_argument(
         "--log-file", default=argparse.SUPPRESS, help="Also write logs to a file."
     )
@@ -877,7 +880,17 @@ def main(argv: Optional[List[str]] = None) -> int:
         pth.mkdir(parents=True, exist_ok=True)
 
         logging.info(f"Writing imputed VCF for {name} to {pth} ...")
-        gd_imp.write_vcf(pth / f"{name.lower()}_imputed.vcf.gz")
+
+        if fmt_final == "vcf":
+            gd_imp.write_vcf(pth / f"{name.lower()}_imputed.vcf.gz")
+        elif fmt_final == "phylip":
+            gd_imp.write_phylip(pth / f"{name.lower()}_imputed.phy")
+        elif fmt_final == "genepop":
+            gd_imp.write_genepop(pth / f"{name.lower()}_imputed.gen")
+        else:
+            logging.warning(
+                f"Output format {fmt_final} not supported for imputed data export."
+            )
 
     logging.info("All requested models processed.")