From bd952b92fbcd3dba6c817444248e394c98fcecdd Mon Sep 17 00:00:00 2001 From: Alex Lancaster Date: Tue, 18 Jul 2023 13:40:33 -0400 Subject: [PATCH] adding pypi upload, contribution guide, quickstart (#94) * add `test_pypi` upload feature * rename package again: `pypopgenomics` -> `pypop-genomics` * add CONTRIBUTING.rst: top-level and in `User Guide` * move most of the developer installation instructions to `CONTRIBUTING.rst` and add notes on bug reporting * remove obsolete 0.7.0 instructions * make test.pypi.org the default installation method * move citation to README.rst * use full URLs for cross-referencing to other docs in README.rst * add a quickstart guide section for simplest case, move detailed installation instructions to later --- .github/workflows/build_wheels.yml | 21 + CONTRIBUTING.rst | 520 ++++++++++++++ README.rst | 660 ++++++------------ setup.py | 0 src/PyPop/__init__.py | 2 +- website/conf.py | 2 +- website/docs/guide-chapter-contributing.rst | 7 + .../docs/guide-chapter-install-obsolete.rst | 266 ------- website/docs/index.rst | 22 +- website/index.rst | 33 +- 10 files changed, 798 insertions(+), 735 deletions(-) create mode 100644 CONTRIBUTING.rst mode change 100644 => 100755 setup.py create mode 100644 website/docs/guide-chapter-contributing.rst delete mode 100644 website/docs/guide-chapter-install-obsolete.rst diff --git a/.github/workflows/build_wheels.yml b/.github/workflows/build_wheels.yml index 2cf39a337..fba16f3f3 100644 --- a/.github/workflows/build_wheels.yml +++ b/.github/workflows/build_wheels.yml @@ -1,6 +1,7 @@ name: Build PyPop on: + workflow_dispatch: pull_request: paths-ignore: - '**.md' @@ -75,3 +76,23 @@ jobs: name: Uploading binaries to release page with: files: dist/* + + upload_test_pypi: + name: Upload to test_pypi + needs: [build_wheels, build_sdist] + runs-on: ubuntu-latest + environment: test_pypi + permissions: + id-token: write + if: github.event_name == 'release' && github.event.action == 'published' + steps: + - uses: actions/download-artifact@v3 + with: + # unpacks default artifact into dist/ + # if `name: artifact` is omitted, the action will create extra parent dir + name: artifact + path: dist + + - uses: pypa/gh-action-pypi-publish@release/v1 + with: + repository_url: https://test.pypi.org/legacy/ diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 000000000..f5bf9fabc --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,520 @@ +============ +Contributing +============ + +.. _guide-contributing-start: + +Contributions to PyPop are welcome, and they are greatly appreciated! +Every little bit helps, and credit will always be given. + +Reporting and requesting +======================== + +.. _guide-contributing-bug-report: + +Did you find a bug? +------------------- + +When `reporting a bug +`_ please use one of +the provided issue templates if applicable, otherwise just start a +blank issue and describe your situation. + +* Ensure the bug was not already reported by searching on GitHub under + `Issues `_. + +* If you're unable to find an open issue addressing the problem, open + a new one. Be sure to include a title and clear description, as much + relevant information as possible, and a code sample or an executable + test case demonstrating the expected behavior that is not occurring. + +* If possible, use the relevant bug report templates to create the issue. + +* When reporting bugs, especially during installation, please run the + following and include the output: + + .. code:: shell + + echo $CPATH + echo $LIBRARY_PATH + echo $PATH + which python + + If you are running on MacOS, and you used the MacPorts installation + method, please also run and include the output of: + + :: + + port installed + + +Documentation improvements +-------------------------- + +**pypop** could always use more documentation, whether as part of the +official docs, in docstrings, or even on the web in blog posts, +articles, and such. Write us a `documentation issue `_ describing what you +would like to see improved in here, and, if you can do +it, just `Pull Request `_ your proposed updates ``:-)``. + +Feature requests and feedback +----------------------------- + +The best way to send feedback is to file an issue using the `feature +template +`_. + +If you are proposing a feature: + +* Explain in detail how it would work. +* Keep the scope as narrow as possible, to make it easier to implement. +* Remember that this is a volunteer-driven project, and that code contributions are welcome + +Making a code contribution +========================== + +To contribute new code that implement a feature, or fix a bug, this +section provides a step-by-step guide to getting you set-up. The main +steps are: + +1. forking the repository (or "repo") +2. cloning the main repo on to your local machine +3. making a new branch +4. `installing a development version `_ on your machine +5. updating your branch when "upstream" (the main repository) has changes to include those changes in your local branch +6. updating the changelog in ``NEWS.rst`` +7. checking unit tests pass +8. making a pull request + + +Fork this repository +-------------------- + +`Fork this repository before contributing`_. Forks creates a cleaner representation of the `contributions to the +project`_. + +Clone the main repository +------------------------- + +Next, clone the main repository to your local machine: + +:: + + git clone https://github.com/alexlancaster/pypop.git + cd pypop + +Add your fork as an upstream repository: + +:: + + git remote add myfork git://github.com/YOUR-USERNAME/pypop.git + git fetch myfork + +Make a new branch +----------------- + +From the ``main`` branch create a new branch where to develop the new code. + +:: + + git checkout main + git checkout -b new_branch + + +**Note** the ``main`` branch is from the main repository. + +Build locally +------------- + +Now you are ready to make your changes. First, you need to build +``pypop`` locally on your machine, and ensure it works, see the +separate section on `building and installing a development version +`_. + +Once you have done the installation and have verified that it works +you can start to develop the feature, or make the bug fix, and keep +regular pushes to your fork with comprehensible commit messages. + +:: + + git status + git add # (the files you want) + git commit # (add a nice commit message) + git push myfork new_branch + +While you are developing, you can execute ``pytest`` as needed to run +your unit tests. See `run unit tests with pytest`_. + +Keep your branch in sync with upstream +-------------------------------------- + +You should keep your branch in sync with the upstream ``main`` +branch. For that: + +:: + + git checkout main # return to the main branch + git pull # retrieve the latest source from the main repository + git checkout new_branch # return to your devel branch + git merge --no-ff main # merge the new code to your branch + +At this point you may need to solve merge conflicts if they exist. If you don't +know how to do this, I suggest you start by reading the `official docs +`_ + +You can push to your fork now if you wish: + +:: + + git push myfork new_branch + +And, continue doing your developments are previously discussed. + +Update NEWS.rst +--------------- + +Update the changelog file under :code:`NEWS.rst` with an explanatory +bullet list of your contribution. Add that list under the "Notes +towards the next release" under the appropriate category, e.g. for a +new feature you would add something like: + +.. code-block:: text + + Notes towards next release + -------------------------- + (unreleased) + + New features + ^^^^^^^^^^^^ + + * here goes my new additions + * explain them shortly and well + + +Also add your name to the authors list at :code:`website/docs/AUTHORS.rst`. + +Run unit tests with ``pytest`` +------------------------------ + +Once you have done your initial installation, you should first check +that the build worked, by running the test suite, via ``pytest``: + +:: + + pytest tests + +If ``pytest`` is not already installed, you can install via: + +:: + + pip install pytest + +If you run into errors during your initial installationg, please first +carefully repeat and/or check your installation. If you still get +errors, file a bug, and include the output of ``pytest`` run in +verbose mode and capturing the output + +:: + + pytest -s -v tests + + +You should also continuously run ``pytest`` as you are developing your +code, to ensure that you don't inadvertently break anything. + +Also before creating a Pull Request from your branch, check that all +the tests pass correctly, using the above. + +These are exactly the same tests that will be performed online via +Github Actions continuous integration (CI). This project follows CI +good practices (let us know if something can be improved). + +Make a Pull Request +------------------- + +Once you are finished, you can create a pull request to the main +repository and engage with the developers. If you need some code +review or feedback while you're developing the code just make a pull +request. + +**However, before submitting a Pull Request, verify your development branch passes all +tests as** `described above `_ **. If you are +developing new code you should also implement new test cases.** + +**Pull Request checklist** + +Before requesting a finale merge, you should: + +1. Make sure your PR passes all ``pytest`` tests. +2. Add unit tests if you are developing new features +3. Update documentation when there's new API, functionality etc. +4. Add a note to ``NEWS.rst`` about the changes. +5. Add yourself to ``website/docs/AUTHORS.rst``. + + +Installation for developers +=========================== + +Once you have setup your branch as described in `making a code +contribution`_, above, you are ready for the four main steps of the +developer installation: + +1. install a build environment +2. build +3. run tests + +.. note:: + + Note that you if you need to install PyPop from source, but do not + intend to contribute code, you can skip creating your own forking + and making an additional branch, and clone the main upstream + repository directly: + + .. code:: shell + + git clone https://github.com/alexlancaster/pypop.git + cd pypop + +For most developers, we recommend using the miniconda approach +described below. + +Install the build environment +----------------------------- + +To install the build environment, you should choose either ``conda`` or +system packages. Once you have chosen and installed the build +environment, you should follow the instructions related to the option +you chose here in all subsequent steps. + +Install build environment via miniconda (recommended) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Visit https://docs.conda.io/en/latest/miniconda.html to download the + miniconda installer for your platform, and follow the instructions to + install. + + In principle, the rest of the PyPop miniconda installation process + should work on any platform that is supported by miniconda, but + only Linux and MacOS have been tested in standalone mode, at this + time. + +2. Once miniconda is installed, create a new conda environment, using + the following commands: + + .. code-block:: shell + + conda create -n pypop3 gsl swig python=3 + + This will download and create a self-contained build-environment that + uses of Python to the system-installed one, along with other + requirements. You will need to use this this environment for the + build, installation and running of PyPop. The conda environment name, + above, ``pypop3``, can be replaced with your own name. + + When installing on MacOS, before installing ``conda``, you should + first to ensure that the Apple Command Line Developer Tools + (XCode) are + `installed `__, + so you have the compiler (``clang``, the drop-in replacement for + ``gcc``), ``git`` etc. ``conda`` is unable to include the full + development environment for ``clang`` as a conda package for legal + reasons. + +3. Activate the environment, and set environments variables needed for + compilation: + + .. code-block:: shell + + conda activate pypop3 + conda env config vars set CPATH=${CONDA_PREFIX}/include:${CPATH} + conda env config vars set LIBRARY_PATH=${CONDA_PREFIX}/lib:${LIBRARY_PATH} + conda env config vars set LD_LIBRARY_PATH=${CONDA_PREFIX}/lib:${LD_LIBRARY_PATH} + +4. To ensure that the environment variables are saved, reactivate the + environment: + + .. code-block:: shell + + conda activate pypop3 + +5. Skip ahead to `Build PyPop`_. + +Install build environment via system packages (advanced) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Unix/Linux: +^^^^^^^^^^^ + +1. Ensure Python 3 version of ``pip`` is installed: + + :: + + python3 -m ensurepip --user --no-default-pip + + .. + + Note the use of the ``python3`` - you may find this to be + necessary on systems which parallel-install both Python 2 and 3, + which is typically the case. On newer systems you may find that + ``python`` and ``pip`` are, by default, the Python 3 version of + those tools. + +2. Install packages system-wide: + + 1. Fedora/Centos/RHEL + + :: + + sudo dnf install git swig gsl-devel python3-devel + + 2. Ubuntu + + :: + + sudo apt install git swig libgsl-dev python-setuptools + +MacOS X +^^^^^^^ + +1. Install developer command-line tools: + https://developer.apple.com/downloads/ (includes ``git``, ``gcc``) + +2. Visit http://macports.org and follow the instructions there to + install the latest version of MacPorts for your version of MacOS X. + +3. Set environment variables to use macports version of Python and other + packages, packages add the following to ``~/.bash_profile`` + + .. code:: shell + + export PATH=/opt/local/bin:$PATH + export LIBRARY_PATH=/opt/local/lib/:$LIBRARY_PATH + export CPATH=/opt/local/include:$CPATH + +4. Rerun your bash shell login in order to make these new exports active + in your environment. At the command line type: + + .. code:: shell + + exec bash -login + +5. Install dependencies via MacPorts and set Python version to use + (FIXME: currently untested!) + + .. code:: shell + + sudo port install swig-python gsl py39-numpy py39-lxml py39-setuptools py39-pip py39-pytest + sudo port select --set python python39 + sudo port select --set pip pip39 + +6. Check that the MacPorts version of Python is active by typing: + ``which python``, if it is working correctly you should see + ``/opt/local/bin/python``. + +Windows +~~~~~~~ + +(Currently untested in standalone-mode) + + +Build PyPop +----------- + +You should choose *either* of the following two approaches. Don’t try +to mix-and-match the two. The build-and-install approach is only +recommended if don’t plan to make any modifications to the code +locally. + +Build-and-install (not recommended for developers) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Once you have setup your environment and cloned the repo, you can use +the following one-liner to examine the ``setup.py`` and pull all the +required dependencies from ``pypi.org`` and build and install the +package. + + Note that if you use this method and install the package, it will be + available to run anywhere on your system, by running ``pypop``. + +.. + + If you use this installation method, changes you make to the code, + locally, or via subsequent ``git pull`` requests will not be + available in the installed version until you repeat the + ``pip install`` command. + +1. if you installed the conda development environment, use: + + :: + + pip install .[test] + + .. + + (the ``[test]`` keyword is included to make sure that any package + requirements for the test suite are installed as well). + +2. if you installed a system-wide environment, the process is slightly + different, because we install into the user’s ``$HOME/.local`` rather + than the conda environment: + + :: + + pip install --user .[test] + +3. PyPop is ready-to-use, you should `run unit tests with pytest`_. + +4. if you later decide you want to switch to using the developer + approach, below, follow the `cleaning up build`_ before + starting. + +Build-and-run-from-checkout (recommended for developers) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. First manually install the dependencies via ``pip``, note that if you + are running on Python <= 3.8, you will need to also add + ``importlib-resources`` to the list of packages, below. + + 1. conda + + :: + + pip install numpy lxml psutil pytest + + 2. system-wide + + :: + + pip install --user numpy lxml psutil pytest + +2. Run the build + + :: + + ./setup.py build + +3. You will be runnning PyPop, directly out of the ``src/PyPop`` + subdirectory (e.g. ``./src/PyPop/pypop.py`` and + ``./src/PyPop/popmeta.py``). Note that you have to include the + ``.py`` extension when you run from an uninstalled checkout, + because the script is not installed. + +Cleaning up build +~~~~~~~~~~~~~~~~~ + +If you installed using the approach in `Build-and-install (not recommended +for developers)`_, above, follow the end-user instructions on +:ref:`uninstalling PyPop`. In addition, to clean-up any compiled +files and force a recompilation from scratch, run the ``clean`` +command: + +:: + + ./setup clean --all + + +.. _Fork this repository before contributing: https://github.com/alexlancaster/pypop/network/members +.. _up to date with the upstream: https://gist.github.com/CristinaSolana/1885435 +.. _contributions to the project: https://github.com/alexlancaster/pypop/network +.. _Gitflow Workflow: https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow +.. _Pull Request: https://github.com/alexlancaster/pypop/pulls diff --git a/README.rst b/README.rst index fb4814f70..01802f879 100644 --- a/README.rst +++ b/README.rst @@ -2,28 +2,157 @@ Python for Population Genomics (PyPop) ====================================== PyPop is a framework for processing genotype and allele data and -running population genetic analyses. See the `PyPop User Guide -`__ for a more detailed description. +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. -.. |pkgname| replace:: ``pypopgenomics`` +.. |pkgname| replace:: ``pypop-genomics`` + +.. _guide-include-pypop-cite-start: + +**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) `__]. + +.. _guide-include-pypop-cite-end: .. _guide-include-start: .. ATTENTION:: - The working package name for installation purposes is - ``pypopgenomics`` - to avoid conflicting with an unrelated package with - the name ``pypop`` already on `PyPI `__. This may - change and is not yet the final package name until the package is - released to PyPI. + The package name for installation purposes is |pkgname| - 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. -Installation (end user) -======================= +Quickstart +========== + +**Installing** |pkgname| + +If you already have Python and ``pip`` `installed `_, install a test pre-releases using the following: + +.. code-block:: shell + + 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 |pkgname| is installed, depending on your platform, you may also +need to `adjust `_ your ``PATH`` +environment variable. + +**Upgrading** |pkgname| + +.. code-block:: shell + + pip install -U pypop-genomics --extra-index-url https://test.pypi.org/simple/ + +**Uninstalling** |pkgname| + +.. code-block:: shell + + pip uninstall pypop-genomics + +**For more, including handling common installation issues, see the** `full installation instructions`_ **.** + +Once you have installed |pkgname|, you can move on to try some +`example runs `__. + + +.. _guide_readme_examples: + +Examples +======== + +These are examples of how to check that the program is installed and +some minimal use cases. + +Checking version and installation +--------------------------------- + +.. code-block:: shell + + pypop --version + +This 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: + +.. code-block:: text + + 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. + +Run a minimal dataset: +---------------------- + +Download test ``.ini`` and ``.pop`` files: `minimal.ini +`_ +and `USAFEL-UchiTelle-small.pop +`_. +You can then run them + +.. code-block:: shell + + pypop -c minimal.ini USAFEL-UchiTelle-small.pop + +If you have already cloned the git repository and it is your working +directory, you can simply run + +.. code-block:: shell + + pypop -c tests/data/minimal.ini tests/data/USAFEL-UchiTelle-small.pop + + +This 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 + + +Full installation instructions +============================== -There are two steps to the end-user installation: +There are three main steps: 1. install Python and ``pip`` -2. install package from Github release +2. install package from Test PyPI +3. adjusting your ``PATH`` variable after installation Install Python 3 and ``pip`` @@ -54,61 +183,32 @@ Here are some additional platform-specific notes that may be helpful: in Windows 11 and later will launch the installer for the Microsoft-maintained Windows package of Python 3. -Install package from GitHub Releases ------------------------------------- +Install package from PyPI +------------------------- Once you have both python and ``pip`` installed, you can use ``pip`` -to install pre-compiled binary "wheels" of ``pypopgenomics`` pre-releases, -available from the GitHub release page: - - https://github.com/alexlancaster/pypop/releases +to install pre-compiled binary "wheels" of |pkgname| +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** + applications or analysis, and are not yet included in the main + pypi.org index** + +.. code-block:: shell + + 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 `_, below. - -1. 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``). - - .. admonition:: Release version numbers - - Note that version of the release is slightly different to the - ``git`` tag. This is because the ``git`` tag follows `Semantic - Versioning `__, which Python internally - normalizes and abbreviates. So the release with the ``git`` tag - ``v1.0.0-a23`` is actually version ``1.0.0a23`` of the - ``pypopgenomics`` package, and the version that ``pip`` "sees". - -2. Next, use ``pip`` to 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): - - .. code-block:: shell - - pip install pypopgenomics -f https://github.com/alexlancaster/pypop/releases/expanded_assets/ - - where ** is replaced with a specific tag, e.g. for the example given above, you would run: - - .. code-block:: shell - - pip install pypopgenomics -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.: - - .. code-block:: shell - - pip install pypopgenomics-1.0.0a23-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl + instructions `_ in the contributors + guide. **Upgrade an existing PyPop installation** @@ -118,14 +218,14 @@ flag, i.e. .. code-block:: shell - pip install -U pypopgenomics -f ... + 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 ``pypopgenomics`` 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, +By default, ``pip`` will attempt to install the |pkgname| +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 @@ -144,7 +244,7 @@ install`` command, i.e.: .. code-block:: shell - pip install pypopgenomics --user ... + 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. @@ -156,13 +256,52 @@ install into the expected user directory. 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/``. - -Install package from PyPI [not yet available] ---------------------------------------------- + +Install package from GitHub Releases (advanced) +----------------------------------------------- + +We also sometimes make binary packages also available from the GitHub +release page: -TBA. Eventually, we will be making PyPop available directly on `PyPI -`__. + 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. + +1. 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``). + + .. admonition:: Release version numbers + + Note that version of the release is slightly different to the + ``git`` tag. This is because the ``git`` tag follows `Semantic + Versioning `__, which Python internally + normalizes and abbreviates. So the release with the ``git`` tag + ``v1.0.0-a23`` is actually version ``1.0.0a23`` of the + |pkgname| package, and the version that ``pip`` "sees". + +2. Next, use ``pip`` to 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): + + .. code-block:: shell + + pip install pypop-genomics -f https://github.com/alexlancaster/pypop/releases/expanded_assets/ + + where ** is replaced with a specific tag, e.g. for the example given above, you would run: + + .. code-block:: shell + + 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.: + + .. code-block:: shell + + pip install pypop-genomics-1.0.0a23-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl + Post-install ``PATH`` adjustments --------------------------------- @@ -187,382 +326,28 @@ executable file. additional help from your system administrator if your user doesn't have the right permissions, and also require a system reboot. -Once you have installed the package, you can skip ahead to the -`section on Examples `_ - -Installation (developer) -======================== - -There are four main steps to the developer installation: - -1. install a build environment -2. clone the repository -3. build -4. run tests - -For most casual users and developers, we recommend using the miniconda -approach described below. - -Install the build environment ------------------------------ - -To install the build environment, you should choose either ``conda`` or -system packages. Once you have chosen and installed the build -environment, you should follow the instructions related to the option -you chose here in all subsequent steps. - -Install build environment via miniconda (recommended) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -1. Visit https://docs.conda.io/en/latest/miniconda.html to download the - miniconda installer for your platform, and follow the instructions to - install. - - In principle, the rest of the PyPop miniconda installation process - should work on any platform that is supported by miniconda, but - only Linux and MacOS have been tested in standalone mode, at this - time. - -2. Once miniconda is installed, create a new conda environment, using - the following commands: - - .. code-block:: shell - - conda create -n pypop3 gsl swig python=3 - - This will download and create a self-contained build-environment that - uses of Python to the system-installed one, along with other - requirements. You will need to use this this environment for the - build, installation and running of PyPop. The conda environment name, - above, ``pypop3``, can be replaced with your own name. - - When installing on MacOS, before installing ``conda``, you should - first to ensure that the Apple Command Line Developer Tools - (XCode) are - `installed `__, - so you have the compiler (``clang``, the drop-in replacement for - ``gcc``), ``git`` etc. ``conda`` is unable to include the full - development environment for ``clang`` as a conda package for legal - reasons. - -3. Activate the environment, and set environments variables needed for - compilation: - - .. code-block:: shell - - conda activate pypop3 - conda env config vars set CPATH=${CONDA_PREFIX}/include:${CPATH} - conda env config vars set LIBRARY_PATH=${CONDA_PREFIX}/lib:${LIBRARY_PATH} - conda env config vars set LD_LIBRARY_PATH=${CONDA_PREFIX}/lib:${LD_LIBRARY_PATH} - -4. To ensure that the environment variables are saved, reactivate the - environment: - - .. code-block:: shell - - conda activate pypop3 - -5. Skip ahead to `Clone the repository `_ - -Install build environment via system packages (advanced) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Unix/Linux: -^^^^^^^^^^^ - -1. Ensure Python 3 version of ``pip`` is installed: - - :: - - python3 -m ensurepip --user --no-default-pip - - .. - - Note the use of the ``python3`` - you may find this to be - necessary on systems which parallel-install both Python 2 and 3, - which is typically the case. On newer systems you may find that - ``python`` and ``pip`` are, by default, the Python 3 version of - those tools. - -2. Install packages system-wide: - - 1. Fedora/Centos/RHEL - - :: - - sudo dnf install git swig gsl-devel python3-devel - - 2. Ubuntu - - :: - - sudo apt install git swig libgsl-dev python-setuptools - -MacOS X -^^^^^^^ - -1. Install developer command-line tools: - https://developer.apple.com/downloads/ (includes ``git``, ``gcc``) - -2. Visit http://macports.org and follow the instructions there to - install the latest version of MacPorts for your version of MacOS X. - -3. Set environment variables to use macports version of Python and other - packages, packages add the following to ``~/.bash_profile`` - - .. code:: shell - - export PATH=/opt/local/bin:$PATH - export LIBRARY_PATH=/opt/local/lib/:$LIBRARY_PATH - export CPATH=/opt/local/include:$CPATH - -4. Rerun your bash shell login in order to make these new exports active - in your environment. At the command line type: - - .. code:: shell - - exec bash -login - -5. Install dependencies via MacPorts and set Python version to use - (FIXME: currently untested!) - - .. code:: shell - - sudo port install swig-python gsl py39-numpy py39-lxml py39-setuptools py39-pip py39-pytest - sudo port select --set python python39 - sudo port select --set pip pip39 - -6. Check that the MacPorts version of Python is active by typing: - ``which python``, if it is working correctly you should see - ``/opt/local/bin/python``. - -Windows -~~~~~~~ - -(Currently untested in standalone-mode) - -Clone the repository --------------------- - -.. code:: shell - - git clone https://github.com/alexlancaster/pypop.git - cd pypop - -Build PyPop ------------ - -You should choose *either* of the following two approaches. Don’t try to -mix-and-match the two. The build-and-install approach is recommended for -end-users, or you if don’t plan to make any modifications to the code -locally. - -Build-and-install (recommended for end-users) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Once you have setup your environment and cloned the repo, you can use -the following one-liner to examine the ``setup.py`` and pull all the -required dependencies from ``pypi.org`` and build and install the -package. - - Note that if you use this method and install the package, it will be - available to run anywhere on your system, by running ``pypop``. - -.. - - If you use this installation method, changes you make to the code, - locally, or via subsequent ``git pull`` requests will not be - available in the installed version until you repeat the - ``pip install`` command. - -1. if you installed the conda development environment, use: - - :: - - pip install .[test] - - .. - - (the ``[test]`` keyword is included to make sure that any package - requirements for the test suite are installed as well). - -2. if you installed a system-wide environment, the process is slightly - different, because we install into the user’s ``$HOME/.local`` rather - than the conda environment: - - :: - - pip install --user .[test] - -3. PyPop is ready-to-use, skip to `Run the test suite`_. - -4. if you later decide you want to switch to using the developer - approach, below, follow the `Uninstalling PyPop and cleaning up`_ before - starting. - -Build-and-run-from-checkout (recommended for developers) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -1. First manually install the dependencies via ``pip``, note that if you - are running on Python <= 3.8, you will need to also add - ``importlib-resources`` to the list of packages, below. - - 1. conda - - :: - - pip install numpy lxml psutil pytest - - 2. system-wide - - :: - - pip install --user numpy lxml psutil pytest - -2. Run the build - - :: - - ./setup.py build - -3. You will run PyPop, directly out of the ``src/PyPop`` subdirectory - (e.g. ``./src/PyPop/pypop.py``). Note that you have to include the - ``.py`` extension when you run from an uninstalled checkout, - because the script is not installed. - -Run the test suite +Uninstalling PyPop ------------------ -You should first check that the build worked, by running the test suite, -via ``pytest``: - -:: - - pytest tests - -If you run into errors, please first carefully repeat and/or check your -installation steps above. If you still get errors, file a bug (as per -Support, below), and include the output of ``pytest`` run in verbose -mode and capturing the output - -:: - - pytest -s -v tests - -Uninstalling PyPop and cleaning up ----------------------------------- - -If you installed using the end-user approach in `Build-and-install (recommended for end-users)`_, above, you -can remove the installed version: - -:: - - pip uninstall pypopgenomics - -To clean-up any compiled files and force a recompilation from scratch, -run the ``clean`` command: - -:: - - ./setup clean --all - -.. _guide_readme_examples: - -Examples -======== - -These are examples of how to check that the program is installed and -some minimal use cases. - -Checking version and installation ---------------------------------- - -.. code-block:: shell - - pypop --version - -This 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: - -.. code-block:: text - - 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. - -Run a minimal dataset: ----------------------- - -Download test ``.ini`` and ``.pop`` files: `minimal.ini -`_ -and `USAFEL-UchiTelle-small.pop -`_. -You can then run them +To uninstall the current version of |pkgname|: .. code-block:: shell - pypop -c minimal.ini USAFEL-UchiTelle-small.pop - -If you installed from source and your working directory is already the -git repository as described in `clone the repository `_, you can simply run - -.. code-block:: shell - - pypop -c tests/data/minimal.ini tests/data/USAFEL-UchiTelle-small.pop - -.. - - replace ``pypop``, by ``./src/PyPop/pypop.py`` if you installed - using `Build-and-run-from-checkout (recommended for developers)`_, - i.e running locally from within the uninstalled checkout of the repository + pip uninstall pypop-genomics -This 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 - -Support -======= - -Please submit any bug reports,feature requests or questions, via our GitHub issue tracker: + + +Support and development +======================= +Please 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 via private email to developers. - -Bug reporting -------------- - -When reporting bugs, especially during installation, please run the -following and include the output: - -.. code:: shell - - echo $CPATH - echo $LIBRARY_PATH - echo $PATH - which python - -If you are running on MacOS, and you used the MacPorts installation -method, please also run and include the output of: - -:: - - port installed - -Development ------------ + +**Please do not report bugs via private email to developers.** The development of the code for PyPop is via our GitHub project: @@ -570,13 +355,18 @@ The development of the code for PyPop is via our GitHub project: .. _guide-include-end: -More detailed notes and background relevant for maintainers, packagers -and developers are maintained in `DEV_NOTES.md `__. Source for website and the documentation is located in the `website `__ subdirectory. +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. Copyright and License ===================== -PyPop is Copyright (C) 2003-2015. The Regents of the University of +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 diff --git a/setup.py b/setup.py old mode 100644 new mode 100755 diff --git a/src/PyPop/__init__.py b/src/PyPop/__init__.py index de00864b5..59afe927a 100644 --- a/src/PyPop/__init__.py +++ b/src/PyPop/__init__.py @@ -33,7 +33,7 @@ # IS". REGENTS HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, # UPDATES, ENHANCEMENTS, OR MODIFICATIONS. -__pkgname__ = 'pypopgenomics' +__pkgname__ = 'pypop-genomics' __version_scheme__ = 'post-release' try: diff --git a/website/conf.py b/website/conf.py index c8c0fd68e..0459c6f31 100644 --- a/website/conf.py +++ b/website/conf.py @@ -84,7 +84,7 @@ rst_epilog = """ .. |pkgname| replace:: %s .. |htmlauthor| replace:: %s -""" % ("pypopgenomics", htmlauthor) +""" % ("``pypop-genomics``", htmlauthor) # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/website/docs/guide-chapter-contributing.rst b/website/docs/guide-chapter-contributing.rst new file mode 100644 index 000000000..f96a6dbc5 --- /dev/null +++ b/website/docs/guide-chapter-contributing.rst @@ -0,0 +1,7 @@ +********************* +Contributing to PyPop +********************* + +.. include:: ../../CONTRIBUTING.rst + :start-after: guide-contributing-start: + diff --git a/website/docs/guide-chapter-install-obsolete.rst b/website/docs/guide-chapter-install-obsolete.rst deleted file mode 100644 index 3887145c7..000000000 --- a/website/docs/guide-chapter-install-obsolete.rst +++ /dev/null @@ -1,266 +0,0 @@ -************************************************ -Installation instructions for old 0.7.0 binaries -************************************************ - -.. danger:: - - These instructions refer to the now out-of-date 0.7.0 binaries for - the Python 2 version of PyPop and will likely not work on newer - systems. They are provided only for historical purposes, and will - soon be removed once 1.0.0 binaries for the new Python 3-based - version are available via `PyPI `__. Please - refer to the newer instructions in :doc:`guide-chapter-install` for - how to compile and install pre-release version(s). - -.. _install-standalone: - -Installing standalone binary -============================ - -Standalone binary versions are provided for PyPop that make minimal -assumptions about external software installed on your system, and for -the majority of users, will be the simplest way to install PyPop. We -have only tested them on a subset of the possible operating systems and -have noted them in the relevant section below. - -.. note:: - - * GNU/Linux (the Linux binary needs a recent distribution that a - recent glibc (2.8 has been tested): Fedora Core 9 is known to - work, earlier versions of Red Hat such as the 7.x series and 8.0 - are known to not work). - * Windows (originally tested on Windows 98, 2000 and XP) - - -.. _install-standalone-linux: - -Installing on GNU/Linux ------------------------ - -**System requirements.** - -Your GNU/Linux system should contain at least 2.6 version of ``glibc`` -(the GNU C library). - -**Systems tested.** - -Fedora 8 (may work on other distributions but untested at present, -earlier versions were tested on Red Hat 9 Fedora Core 2, 3, 7, Slackware -9.1 but may now have out of date versions of glibc) - -1. Download the latest stable release and save it somewhere in your home - directory: - - - `PyPopLinux-0.7.0.tar.gz <../PyPopLinux-0.7.0.tar.gz>`__ - -2. From the command-line terminal untar and uncompress the package - (typically using the GNU ``tar`` program): - - :: - - $ tar zxf PyPopLinux-0.7.0.tar.gz - -At this point PyPop should be successfully installed. To test your -installation, run the program and use the sample test files with the -following steps: - -1. Change directory into the extracted directory - - :: - - $ cd PyPopLinux-0.7.0 - -2. Now you can run the interactive version of the program, by typing - ``./pypop``, at the command line. - - A short message describing PyPop will be displayed, followed by - prompts to supply the name of the configuration file and then the - population file. Select the file, ``sample.ini`` and ``sample.pop``, - respectively (noted in the sample screen output below, in **bold**). - - :: - - PyPop: Python for Population Genomics (0.4.3) - Copyright (C) 2003 Regents of the University of California - This is free software. There is NO warranty; not even for - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - - You may redistribute copies of PyPop under the terms of the - GNU General Public License. For more information about these - matters, see the file named COPYING. - - To accept the default in brackets for each filename, simply press - return for each prompt. - Please enter config filename [config.ini]: sample.ini - Please enter population filename [no default]: sample.pop - PyPop is processing sample.pop - - (Note: some messages with the prefix "LOG:" may appear here. - They are informational only and do not indicate improper operation - of the program) - - PyPop run complete! - XML output can be found in: sample-out.xml - Plain text output can be found in: sample-out.txt - - PyPop will remember the names of the configuration and population - files you used last, and will provide those as defaults in subsequent - runs. - -.. _install-standalone-windows: - -Installing on Windows ---------------------- - -**System requirements.** - -At least Windows 98 - -**Systems tested.** - -Windows 2000, Windows XP (may work on other platforms but untested at -present) - -1. Before starting an install on Windows, you must first make sure you - have a copy of a zip file extractor such as PowerArchiver or WinZip. - -2. Download the latest stable Windows release of PyPop and save it in - one of your directories or on the Desktop: - - - `PyPopWin32-0.7.0.zip <../PyPopWin32-0.7.0.zip>`__ - -3. Once you have downloaded the file, you should double-click it. If you - have correctly installed one of the zip compression utilities, it - should open using that zip program. Extract the contents of the zip - file to your desktop, or wherever you normally save your programs and - data. Consult the documentation for your archiving utility for - details on how to do this (it should be reasonably self-explanatory). - -To test your installation: - -1. Once you have the ``PyPopWin32-0.7.0`` directory extracted, open the - directory and double-click on the ``pypop.bat`` file. - -2. A DOS shell should then open running the program inside it. - - A short message describing PyPop will be displayed, followed by - prompts to supply the name of the configuration file and then the - population file. Select the file, ``sample.ini`` and ``sample.pop``, - respectively (noted in the sample screen output below, in **bold**). - - :: - - PyPop: Python for Population Genomics (0.4.3) - Copyright (C) 2003 Regents of the University of California - This is free software. There is NO warranty; not even for - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - - You may redistribute copies of PyPop under the terms of the - GNU General Public License. For more information about these - matters, see the file named COPYING. - - To accept the default in brackets for each filename, simply press - return for each prompt. - Please enter config filename [config.ini]: sample.ini - Please enter population filename [no default]: sample.pop - PyPop is processing sample.pop - - (Note: some messages with the prefix "LOG:" may appear here. - They are informational only and do not indicate improper operation - of the program) - - PyPop run complete! - XML output can be found in: sample-out.xml - Plain text output can be found in: sample-out.txt - -.. _install-from-source: - -Installing from source -====================== - -The source code for PyPop can be obtained here: - -- http://www.pypop.org/pypop-0.7.0.tar.gz - -- In addition, because the Windows binary distributes a copy of the - ``cygwin1.dll``, we are required under the terms of the GNU GPL to - provide a copy of the Cygwin source which we compiled the binary - from: ` `__. - - .. note:: - - Note that this only required for Windows and is *not* required for - compilation even under Windows if you install within the Cygwin - environment (because it already contains a copy ``cygwin1.dll``) - and is only provided for legal reasons. - -.. _install-from-source-sysreq: - -System requirements -------------------- - -- `Python 2.4 `__ or later. - -- `Numerical Python (Numpy) (Numpy) - 24.0 `__ - -- `Simple Wrapper Interface Generator (SWIG) `__: - uses "development" version (should now be compatible with all recent - SWIG versions: last tested against SWIG 1.3.31). - -- `libxml2/libxslt `__ including - `libxml2-python `__, a Python - interface to the GNOME XML/XSLT parser (This is a fast C - library-based parser. Most recent GNU/Linux distributions will - install libxml2/libxslt as part of the base distribution, but you may - need to install libxml2-python and libxslt-python separately). - - (Untested recently: `4Suite `__ a pure Python - XML/XSLT parsing engine.) - -- The GNU Scientific Library - (`GSL `__) On Fedora you will want - to install the gsl-devel package. - -.. _install-from-source-install: - -Installation ------------- - -*Before starting, you must ensure you have installed all the system -requirements listed above. In particular, make sure Python is installed -correctly.* - -Unzip and untar the above tar ball. Build and install PyPop by changing -into the ``PyPop-0.7.0`` directory, and type: - -:: - - python setup.py build - python setup.py install - -If you need to do additional configuration (e.g. changing the base -directory) please type ``python setup.py``, or see the documentation for -Distutils. - -.. _install-from-source-distribution: - -Distribution structure ----------------------- - -:: - - AUTHORS -- A list of people who have contributed. - emhaplofreq/ -- LD and haplotype estimation extension module - pval/ -- Modified code from R project for p-value calculation - slatkin-exact/ Slatkin's code for Ewens-Watterson exact test - gthwe/ Modified Guo and Thompson Hardy-Weinberg code - SWIG/ -- Helper code for SWIG for generating C-Python wrappers - xslt/ -- XSLT for generating text and other output from XML - COPYING -- License information for this package - MANIFEST.in -- Tells distutils what files to distribute - NEWS -- Release notes and news - README -- Information and TODO list. - INSTALL -- This file - setup.py -- Installation file. - diff --git a/website/docs/index.rst b/website/docs/index.rst index 1d3c4cb48..dff4b15c5 100644 --- a/website/docs/index.rst +++ b/website/docs/index.rst @@ -16,7 +16,11 @@ PyPop User Guide .. include:: ../index.rst :start-after: guide-preface-1-start: :end-before: guide-preface-1-end: - + + .. include:: ../../README.rst + :start-after: guide-include-pypop-cite-start: + :end-before: guide-include-pypop-cite-end: + .. include:: ../index.rst :start-after: guide-preface-2-start: :end-before: guide-preface-2-end: @@ -24,16 +28,18 @@ PyPop User Guide **How to use this guide** -This guide to PyPop contains three parts: +This guide to PyPop contains four main parts: - :doc:`guide-chapter-install` describes how to install PyPop, - including pre-release binaries. (:doc:`guide-chapter-install-obsolete` - are included on temporary basis, and will be removed soon.) + including pre-release binaries. + +- :doc:`guide-chapter-usage` describes how to run PyPop. -- :doc:`guide-chapter-usage` describes how to run PyPop. +- :doc:`guide-chapter-instructions` details the population genetic + methods and statistics that PyPop computes. -- :doc:`guide-chapter-instructions` details the - population genetic methods and statistics that PyPop computes. +- :doc:`guide-chapter-contributing` details how to contribute to + ongoing PyPop code and documentation. .. only:: html @@ -57,7 +63,7 @@ This guide to PyPop contains three parts: guide-chapter-install guide-chapter-usage guide-chapter-instructions - guide-chapter-install-obsolete + guide-chapter-contributing guide-chapter-changes licenses biblio diff --git a/website/index.rst b/website/index.rst index e82ac97c0..15a8d1cc4 100644 --- a/website/index.rst +++ b/website/index.rst @@ -10,8 +10,8 @@ PyPop: Python for Population Genomics and will no install or work on many platforms. Please follow the instructions on the GitHub `README.rst `__ for how to - build PyPop from source on a modern Python 3 system, or install - one of the pre-releases when they become available. + install one of the Python 3-based pre-releases, or build PyPop + from source on a modern Python 3 system. .. _news: @@ -73,7 +73,9 @@ PyPop, is contained in the :ref:`PyPop User Guide Please file all questions, support requests, and bug reports via our `GitHub issue tracker - `__. + `__. More details on + how to file bug reports can be found in our :ref:`contributors + chapter ` of the *User Guide*. .. _source-code: @@ -89,27 +91,11 @@ source code is available and maintained on our `GitHub website .. _citing-pypop: -.. _guide-preface-2-start: - -**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) `__]. +.. include:: ../README.rst + :start-after: guide-include-pypop-cite-start: + :end-before: guide-include-pypop-cite-end: -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) `__]. +.. _guide-preface-2-start: PyPop was originally developed for the analysis of data for the 13th `International Histocompatiblity Workshop and @@ -129,7 +115,6 @@ Marsh, Mark Grote and Leslie Louie for helpful comments and testing. .. _guide-preface-2-end: - .. _popdata-files: **Supplementary data files**