pg-sui 1.6.14.dev9__py3-none-any.whl → 1.7.0__py3-none-any.whl

pg_sui-1.6.14.dev9.dist-info/METADATA

@@ -1,344 +0,0 @@
-Metadata-Version: 2.4
-Name: pg-sui
-Version: 1.6.14.dev9
-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
-
-
-<img src="https://github.com/btmartin721/PG-SUI/blob/master/img/pgsui-logo-faded.png" alt="PG-SUI Logo" width="50%" height="50%">
-
-
-# PG-SUI
-
-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/).
-
-### Supervised Imputation Methods
-
-Supervised methods utilze the scikit-learn's IterativeImputer, which is based on the MICE (Multivariate Imputation by Chained Equations) algorithm ([1](#1)), 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 any of the following scikit-learn classifiers:
-
-+ K-Nearest Neighbors
-+ Random Forest
-+ XGBoost
-
-See the scikit-learn documentation (https://scikit-learn.org) for more information on IterativeImputer and each of the classifiers.
-
-### Unsupervised Imputation Methods
-
-Unsupervised imputers include three custom neural network models:
-
-+ Variational Autoencoder (VAE) ([2](#2))
-+ Standard Autoencoder (SAE) ([3](#3))
-+ Non-linear Principal Component Analysis (NLPCA) ([4](#4))
-+ Unsupervised Backpropagation (UBP) ([5](#5))
-
-VAE models train themselves to reconstruct their input (i.e., the genotypes). 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.
-
-SAE is a standard autoencoder that trains the input to predict itself. As with VAE, missing values are masked and the model gets trained only on known values. Predictions are then made on the missing values.
-
-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. The trained model can then predict the missing values.
-
-UBP is an extension of NLPCA that runs over three phases. 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.
-
-### Non-Machine Learning Methods
-
-We also include several non-machine learning options for imputing missing data, including:
-
-+ Per-population mode per SNP site
-+ Global mode per SNP site
-+ Using a phylogeny as input to inform the imputation
-+ Matrix Factorization
-
-These four "simple" imputation methods can be used as standalone imputers, as the initial imputation strategy for IterativeImputer (at least one method is required to be chosen), and to validate the accuracy of both IterativeImputer and the neural network models.
-
-## Installing PG-SUI
-
-The easiest way to install PG-SUI is to use pip:
-
-```
-pip install pg-sui
-```
-
-If you have an Intel CPU and want to use the sklearn-genetic-intelex package to speed up scikit-learn computations, you can do:
-
-```
-pip install pg-sui[intel]
-```
-
-### Optional GUI (Electron)
-
-PG-SUI ships an Electron GUI wrapper around the Python CLI.
-
-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 once:  
-   `pgsui-gui-setup`
-3. Launch the GUI:  
-   `pgsui-gui`
-
-The GUI shells out to the same CLI underneath, so presets/overrides and YAML configs behave identically.
-
-## Manual Installation
-
-### Dependencies
-
-+ python >= 3.11
-+ pandas
-+ numpy
-+ scipy
-+ matplotlib
-+ seaborn
-+ plotly
-+ kaleido
-+ tqdm
-+ toytree
-+ scikit-learn
-+ xgboost
-+ snpio
-+ optuna
-
-#### Installation troubleshooting
-
-##### "use_2to3 is invalid" error
-
-Users running setuptools v58 may encounter this error during the last step of installation, using pip to install sklearn-genetic-opt:
-
-```
-ERROR: Command errored out with exit status 1:
-   command: /Users/tyler/miniforge3/envs/pg-sui/bin/python3.8 -c 'import io, os, sys, setuptools, tokenize; sys.argv[0] = '"'"'/private/var/folders/6x/t6g4kn711z5cxmc2_tvq0mlw0000gn/T/pip-install-6y5g_mhs/deap_1d32f65d60a44056bd7031f3aad44571/setup.py'"'"'; __file__='"'"'/private/var/folders/6x/t6g4kn711z5cxmc2_tvq0mlw0000gn/T/pip-install-6y5g_mhs/deap_1d32f65d60a44056bd7031f3aad44571/setup.py'"'"';f = getattr(tokenize, '"'"'open'"'"', open)(__file__) if os.path.exists(__file__) else io.StringIO('"'"'from setuptools import setup; setup()'"'"');code = f.read().replace('"'"'\r\n'"'"', '"'"'\n'"'"');f.close();exec(compile(code, __file__, '"'"'exec'"'"'))' egg_info --egg-base /private/var/folders/6x/t6g4kn711z5cxmc2_tvq0mlw0000gn/T/pip-pip-egg-info-7hg3hcq2
-       cwd: /private/var/folders/6x/t6g4kn711z5cxmc2_tvq0mlw0000gn/T/pip-install-6y5g_mhs/deap_1d32f65d60a44056bd7031f3aad44571/
-  Complete output (1 lines):
-  error in deap setup command: use_2to3 is invalid.
-```
-
-This occurs during the installation of DEAP, one of the dependencies for sklearn-genetic-opt. As a workaround, first downgrade setuptools, and then proceed with the installation as normal:
-```
-pip install setuptools==57
-pip install sklearn-genetic-opt[all]
-
-```
-
-##### Mac ARM architecture
-
-PG-SUI has been tested on the new Mac M1 chips and is working fine, but some changes to the installation process were necessary as of 9-December-21. Installation was successful using the following:
-
-```
-### Install Miniforge3 instead of Miniconda3
-### Download: https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-MacOSX-arm64.sh
-bash ~/Downloads/Miniforge3-MacOSX-arm64.sh
-
-# Close and re-open terminal #
-
-#create and activate conda environment
-conda create -n pg-sui python
-
-#activate environment
-conda activate pg-sui
-
-#install packages
-conda install -c conda-forge matplotlib seaborn jupyterlab scikit-learn tqdm pandas numpy scipy xgboost lightgbm tensorflow keras sklearn-genetic-opt toytree
-conda install -c bioconda pyvolve
-
-#downgrade setuptools (may or may not be necessary)
-pip install setuptools==57
-
-#install sklearn-genetic-opt and mlflow
-pip install sklearn-genetic-opt mlflow
-
-```
-
-Any other problems we run into testing on the Mac ARM architecture will be adjusted here. Note that the step installing scikit-learn-intelex was skipped here. PG-SUI will automatically detect the CPU architecture you are running, and forgo importing this package (which will only work on Intel processors)
-
-## Input Data
-
-You can read your input files as a GenotypeData object from the [SNPio](https://snpio.readthedocs.io/en/latest/) package:
-
-```
-
-# Import snpio. Automatically installed with pgsui when using pip.
-from snpio import GenotypeData
-
-# Read in PHYLIP, VCF, or STRUCTURE-formatted alignments.
-data = GenotypeData(
-    filename="example_data/phylip_files/phylogen_nomx.u.snps.phy",
-    popmapfile="example_data/popmaps/phylogen_nomx.popmap",
-    force_popmap=True,
-    filetype="auto",
-    qmatrix_iqtree="example_data/trees/test.qmat",
-    siterates_iqtree="example_data/trees/test.rate",
-    guidetree="example_data/trees/test.tre",
-    include_pops=["EA", "TT", "GU"], # Only include these populations. There's also an exclude_pops option that will exclude the provided populations.
-)
-```
-
-## Supported Imputation Methods
-
-There are numerous supported algorithms 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:
-
-```
-from pgsui import *
-```
-
-Or you can import them one at a time.
-
-```
-from pgsui import ImputeVAE
-```
-
-### Supervised Imputers
-
-Various supervised imputation options are supported:
-
-```
-# Supervised IterativeImputer classifiers
-knn = ImputeKNN(data) # K-Nearest Neighbors
-rf = ImputeRandomForest(data) # Random Forest or Extra Trees
-xgb = ImputeXGBoost(data) # XGBoost
-```
-
-### Non-machine learning methods
-
-Use phylogeny to inform imputation:
-
-```
-phylo = ImputePhylo(data)
-```
-
-Use by-population or global allele frequency to inform imputation
-
-```
-pop_af = ImputeAlleleFreq(data, by_populations=True)
-global_af = ImputeAlleleFreq(data, by_populations=False)
-ref_af = ImputeRefAllele(data)
-```
-
-Non-matrix factorization:
-
-```
-mf = ImputeMF(*args) # Matrix factorization
-```
-
-### Unsupervised Neural Networks
-
-``` python
-vae = ImputeVAE(data) # Variational autoencoder
-nlpca = ImputeNLPCA(data) # Nonlinear PCA
-ubp = ImputeUBP(data) # Unsupervised backpropagation
-sae = ImputeStandardAutoEncoder(data) # standard autoencoder
-```
-
-## 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:
-
-```
-pg-sui \
-  --vcf data.vcf.gz \
-  --popmap pops.popmap \
-  --models ImputeUBP ImputeVAE \
-  --preset balanced \
-  --sim-strategy random_weighted_inv \
-  --sim-prop 0.25 \
-  --set io.prefix=vae_vs_ubp
-```
-
-CLI overrides cascade into every selected model, so a single invocation can evaluate multiple imputers with a consistent simulation strategy and output prefix.
-
-## To-Dos
-
-- simulations
-- Documentation
-
-## References:
-
-<a name="1">1. </a>Stef van Buuren, Karin Groothuis-Oudshoorn (2011). mice: Multivariate Imputation by Chained Equations in R. Journal of Statistical Software 45: 1-67.
-
-<a name="2">2. </a>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].
-
-<a name="3">3. </a>Hinton, G.E., & Salakhutdinov, R.R. (2006). Reducing the dimensionality of data with neural networks. Science, 313(5786), 504-507.
-
-<a name="4">4. </a>Scholz, M., Kaplan, F., Guy, C. L., Kopka, J., & Selbig, J. (2005). Non-linear PCA: a missing data approach. Bioinformatics, 21(20), 3887-3895.
-
-<a name="5">5. </a>Gashler, M. S., Smith, M. R., Morris, R., & Martinez, T. (2016). Missing value imputation with unsupervised backpropagation. Computational Intelligence, 32(2), 196-215.