PyPop is a framework for processing genotype and allele data and running population genetic analyses, including conformity to Hardy-Weinberg expectations; tests for balancing or directional selection; estimates of haplotype frequencies and measures and tests of significance for linkage disequilibrium (LD). See the PyPop User Guide for a more detailed description.
How to cite PyPop
When citing PyPop, please cite the (2007) paper from Tissue Antigens:
- A. K. Lancaster, R. M. Single, O. D. Solberg, M. P. Nelson and G. Thomson (2007) "PyPop update - a software pipeline for large-scale multilocus population genomics" Tissue Antigens 69 (s1), 192-197. [journal page, preprint PDF (112 kB)].
In addition, you can also cite our 2003 Pacific Symposium on Biocomputing paper:
- Alex Lancaster, Mark P. Nelson, Richard M. Single, Diogo Meyer, and Glenys Thomson (2003) "PyPop: a software framework for population genomics: analyzing large-scale multi-locus genotype data", in Pacific Symposium on Biocomputing vol. 8:514-525 (edited by R B Altman. et al., World Scientific, Singapore, 2003) [PubMed Central, PDF (344 kB)].
Attention!
The package name for installation purposes is pypop-genomics - to avoid
conflicting with an unrelated package with the name pypop
already on PyPI. This is a working name and
may change and is not yet the final package name until the package
is released to PyPI.
Installing pypop-genomics
If you already have Python and pip installed, install a test pre-releases using the following:
pip install pypop-genomics --extra-index-url https://test.pypi.org/simple/Warning
These pre-release versions are being made available for initial testing, they are not intended to be used for production applications or analysis, and are not yet included in the main pypi.org index
Once pypop-genomics is installed, depending on your platform, you may also
need to adjust your PATH
environment variable.
Upgrading pypop-genomics
pip install -U pypop-genomics --extra-index-url https://test.pypi.org/simple/Uninstalling pypop-genomics
pip uninstall pypop-genomicsFor more, including handling common installation issues, see the detailed installation instructions .
Once you have installed pypop-genomics, you can move on to try some
example runs.
These are examples of how to check that the program is installed and some minimal use cases.
pypop --versionThis simply reports the version number and other information about PyPop, and indirectly checks that the program is installed. If all is well, you should see something like:
pypop 1.0.0a23
Copyright (C) 2003-2006 Regents of the University of California.
Copyright (C) 2007-2023 PyPop team.
This is free software. There is NO warranty; not even for
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
You can also run pypop --help to see a full list and explanation
of all the options available.
Download test .ini and .pop files: minimal.ini
and USAFEL-UchiTelle-small.pop.
You can then run them
pypop -c minimal.ini USAFEL-UchiTelle-small.popIf you have already cloned the git repository and it is your working directory, you can simply run
pypop -c tests/data/minimal.ini tests/data/USAFEL-UchiTelle-small.popThis will generate the following two files, an XML output file and a plain text version:
USAFEL-UchiTelle-small-out.xml USAFEL-UchiTelle-small-out.txt
There are three main steps:
- install Python and
pip - install package from Test PyPI
- adjusting your
PATHvariable after installation
A full description of installing Python and pip on your system is
beyond the scope of this guide, we recommend starting here:
https://wiki.python.org/moin/BeginnersGuide/Download
Here are some additional platform-specific notes that may be helpful:
- Most Linux distributions come with Python 3 preinstalled. On most
modern systems,
pipandpythonwill default to Python 3. - MacOS 10.9 (Jaguar) up until 12.3 (Catalina), used to ship with
Python 2 pre-installed, but it now has to be manually installed.
See the MacOS quick-start guide in the official
documentation for how to install Python 3. (Note that if Python is
installed on Mac via the MacOS developer tools, it may include the
version
3suffix on commands, e.g.python3andpip3, so modify the below, accordingly). - For Windows, see also the Windows quick-start guide in the official
documentation. Running
pythonin the Windows command terminal in Windows 11 and later will launch the installer for the Microsoft-maintained Windows package of Python 3.
Once you have both python and pip installed, you can use pip
to install pre-compiled binary "wheels" of pypop-genomics
pre-releases, test packages for PyPop available directly on the Test
PyPI.
Warning
These pre-release versions are being made available for initial testing, they are not intended to be used for production applications or analysis, and are not yet included in the main pypi.org index
pip install pypop-genomics --extra-index-url https://test.pypi.org/simple/Note
If, for whatever reason, you cannot use the these binaries (e.g. the pre-compiled binaries are not available for your platform), you may need to follow the developer installation instructions in the contributors guide.
Upgrade an existing PyPop installation
To update an existing installation to a newer version, use the same
command as above, but add the --upgrade (short version: -U)
flag, i.e.
pip install -U pypop-genomics --extra-index-url https://test.pypi.org/simple/Issues with installation permission
By default, pip will attempt to install the pypop-genomics
package wherever the current Python installation is installed. This
location may be a user-specific virtual environment (like conda,
see below), or a system-wide installation. On many Unix-based systems,
Python will generally already be pre-installed in a "system-wide"
location (e.g. under /usr/lib) which is read-only for regular
users. (This can also be true for system-installed versions of Python
on Windows and MacOS.)
When pip install cannot install in a read-only system-wide
location , pip will gracefully "fall-back" to installing just for
you in your home directory (typically ~/.local/lib/python<VER>
where <VER> is the version number of your current Python). In
general, this is what is wanted, so the above instructions are
normally sufficient.
However, you can also explicitly set installation to be in the user
directory, by adding the --user command-line option to the pip
install command, i.e.:
pip install pypop-genomics --user --extra-index-url https://test.pypi.org/simple/This may be necessary in certain cases where pip install doesn't
install into the expected user directory.
Installing within a conda environment
In the special case that you installing from within an activated
user-specific conda virtual environment that provides Python,
then you should not add the --user because it will install
it in ~/.local/lib/ rather than under the user-specific conda
virtual environment in ~/.conda/envs/.
We also sometimes make binary packages also available from the GitHub release page:
https://github.com/alexlancaster/pypop/releases
To install these is similar to installing via PyPI above, except that you need to explicitly provide a URL to the release page.
First, visit the release page, and choose the release version you wish to install (usually the most recent), and note the release tag (e.g.
v1.0.0-a23).Release version numbers
Note that version of the release is slightly different to the
gittag. This is because thegittag follows Semantic Versioning, which Python internally normalizes and abbreviates. So the release with thegittagv1.0.0-a23is actually version1.0.0a23of thepypop-genomicspackage, and the version thatpip"sees".Next, use
pipto install the package by running a command of the form (this will select and install the correct wheel for your Python version and operating system automatically):pip install pypop-genomics -f https://github.com/alexlancaster/pypop/releases/expanded_assets/<TAG_NAME>
where <TAG_NAME> is replaced with a specific tag, e.g. for the example given above, you would run:
pip install pypop-genomics -f https://github.com/alexlancaster/pypop/releases/expanded_assets/v1.0.0-a23
You can also manually download the specific wheel from the github release webpage and install directly, e.g.:
pip install pypop-genomics-1.0.0a23-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
You may need to adjust the PATH settings (especially on Windows)
for the pypop scripts to be visible when run from your console
application, without having to supply the full path to the pypop
executable file.
Warning
Pay close attention to the "WARNINGS" that are shown during the
pip installation, they will often note which directories need to
be added to the PATH.
- On Linux and MacOS, systems this is normally fairly simple and only
requires edit of the shell
.profile, or similar and addition of the$HOME/.local/binto thePATHvariable, followed by a restart of the terminal. - For Windows, however, as noted in most online instructions, this may need additional help from your system administrator if your user doesn't have the right permissions, and also require a system reboot.
To uninstall the current version of pypop-genomics:
pip uninstall pypop-genomicsPlease submit any bug reports, feature requests or questions, via our GitHub issue tracker (see our bug reporting guidelines for more details on how to file a good bug report):
https://github.com/alexlancaster/pypop/issues
Please do not report bugs via private email to developers.
The development of the code for PyPop is via our GitHub project:
https://github.com/alexlancaster/pypop
For a detailed description on bug reporting as well as how to contribute to PyPop, please consult our CONTRIBUTING.rst guide. We also have additional notes and background relevant for developers in DEV_NOTES.md. Source for the website and the documentation is located in the website subdirectory.
PyPop is Copyright (C) 2003-2006. The Regents of the University of California (Regents)
Copyright (C) 2007-2023 PyPop team.
PyPop is distributed under the terms of GPLv2