diff --git a/README.md b/README.md index 69357d7..7b7923c 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,16 @@ Whalen, A, Ros-Freixedes, R, Wilson, DL, Gorjanc, G, Hickey, JM. (2018). Hybrid See https://alphapeel.readthedocs.io/en/latest +Quick links: + +- [Installation](https://alphapeel.readthedocs.io/en/latest/get_started.html#install-software) + +- [Simple example](https://alphapeel.readthedocs.io/en/latest/get_started.html#an-example) + +- [How to use](https://alphapeel.readthedocs.io/en/latest/usage.html) + +- [Algorithm](https://alphapeel.readthedocs.io/en/latest/algorithm.html) + ## Conditions of use AlphaPeel is fully and freely available for all use under the MIT License. diff --git a/docs/source/algorithm.rst b/docs/source/algorithm.rst index 24a4422..68eadda 100644 --- a/docs/source/algorithm.rst +++ b/docs/source/algorithm.rst @@ -1,3 +1,5 @@ +.. _algorithm: + ================== Algorithm Overview ================== diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst index 988a963..b428c25 100644 --- a/docs/source/changelog.rst +++ b/docs/source/changelog.rst @@ -1,14 +1,23 @@ ========= Changelog ========= -[1.3.1] - 2026-03-05 -==================== + +.. + If you are add a new entry to the changelog, please follow the format of the existing entries and + add your changes to the top of the file under the [Unreleased] section. + Please also include the pull request number and the GitHub username(s) of the contributor(s) who made the change. + +[Unreleased] - 2026-03-?? +========================= New features ------------ * Allow a founding individual to have two different metafounders, e.g., one for the paternal lineage and one for the maternal lineage (:pr:`222`, :user:`RosCraddock`, :user:`gregorgorjanc`, :user:`XingerTang`). +* Add a version option to the command line interface + (:pr:`237`, :user:`XingerTang`). + Maintenance ----------- @@ -25,16 +34,15 @@ Maintenance - Reformatted the ``alt_allele_prob_file`` input to match the outputted ``alt_allele_prob_file``. - -[Unreleased] - 2026-02-12 -========================= - -Maintenance ------------ - * Updated the documentation to clarify inputs, outputs, and parameters (:pr:`219`, :user:`gregorgorjanc`). +* Add collaboration guidelines to the documentation + (:pr:`224`, :user:`XingerTang`, :user:`RosCraddock`, :user:`AprilYuZhang`, :user:`gregorgorjanc`). + +* Updated the documentation to add more techincal instructions for developers and contributors + (:pr:`237`, :user:`XingerTang`). + [1.3.0] - 2026-02-05 ==================== diff --git a/docs/source/contribute.rst b/docs/source/contribute.rst index 91c410f..30b4efb 100644 --- a/docs/source/contribute.rst +++ b/docs/source/contribute.rst @@ -24,7 +24,7 @@ To efficiently manage our development process, we use tags to categorize issues. Following are two main issue tags that we use to label issues: -1. Discussion / Idea +1. Discussion/Idea * Label: ``discussion`` @@ -41,6 +41,8 @@ Following are two main issue tags that we use to label issues: **Rule**: Only task issues can have branches/PRs +.. _task-issue-template: + Task issue template ^^^^^^^^^^^^^^^^^^^ @@ -87,6 +89,8 @@ Rules * Version tag on ``main``: ``v1.2.0``, ``latest``, ``stable`` +.. _branch-naming: + Branch naming ^^^^^^^^^^^^^ @@ -107,6 +111,9 @@ A suggested branch naming convention for a task issue on your fork is as follows * ``fix``: bug fix * ``refactor``: code cleanup * ``doc``: documentation updates + * etc. + +.. _PR-practice: Pull request ------------ @@ -129,7 +136,7 @@ Template for PR of ``AlphaPeel`` .. code-block:: markdown ## Related Issue - Closes # + Closes AlphaGenes/AlphaPeel#GitHubIssueNumber ## What changed - Brief summary of changes @@ -149,8 +156,8 @@ Template for PR of ``AlphaPeel`` - Anything reviewers should pay attention to -Template for PR of``tinyhouse`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Template for PR of ``tinyhouse`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: markdown @@ -183,13 +190,13 @@ from defining the work to merging a pull request. * Create a **task issue** * Clearly define: - * goal - * scope - * “done when” + * Goal + * Scope + * “Done when” If ``tinyhouse`` changes are needed: - * create a **linked issue in ``tinyhouse``** + * Create a **linked issue in** ``tinyhouse`` 2. Create branches (both repos) @@ -209,6 +216,8 @@ from defining the work to merging a pull request. .. code-block:: bash feat/issue-15-support-analysis + + For instructions, see :ref:`branch-instructions`. 3. Implement ``tinyhouse`` changes first @@ -218,11 +227,11 @@ from defining the work to merging a pull request. * Implement changes in ``tinyhouse`` branch * Push to your fork - * Open **PR to ``devel`` branch of ``tinyhouse`` repository** + * Open **PR to** ``devel`` **branch of** ``tinyhouse`` **repository** 4. Use updated ``tinyhouse`` reference in ``AlphaPeel`` repository -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In your ``AlphaPeel`` repository branch: @@ -247,7 +256,11 @@ from defining the work to merging a pull request. 6. Development + syncing ^^^^^^^^^^^^^^^^^^^^^^^^ - During development, always keep your branch synced with upstream using ``rebase``. + During development, always keep your branch synced with upstream. + + * ``rebase`` to the latest ``devel`` branch of the AlphaGenes repository to keep up with the latest changes and avoid merge conflicts later on. + + * Instructions: :ref:`rebase_instructions` 7. Review phase ^^^^^^^^^^^^^^^ @@ -271,9 +284,17 @@ from defining the work to merging a pull request. * Before merge: - * final check the new changes by others and update with ``rebase`` if needed + * ``squash`` the commits to simplify the history if applicable + + * This is optional + + * Be careful when squashing the merged, rebased, or squashed commits, as it can cause issues with the commit history and may cause GitHub to not able to merge the PR + + * Instructions: :ref:`squash-commits-instructions` - * ``squash`` the commits to simplify the history + * Final check the new changes by others and update with ``rebase`` if needed + + * Instructions: :ref:`rebase_instructions` Developer meetings @@ -302,7 +323,7 @@ Technical Contribution Guide Fork the repository ------------------- -First, you should fork the `repository `_. +First, you should fork the `AlphaGenes repository `_. For more information, see the `GitHub Docs `_. @@ -316,6 +337,46 @@ initialise submodules at the same time by running the following command in your git clone --recurse-submodules URL_of_your_forked_repository +.. _use-correct-version-submodule: + +Use correct version of the submodule +------------------------------------ + +In the above command, the ``--recurse-submodules`` flag will automatically initialise and update the submodule ``tinyhouse`` +in the repository according to the ``.gitmodules`` file, it is expected to be the commit that is stable for the current version of ``AlphaPeel``, +but it might not be the latest version of the submodule. + +Usually the most up-to-date version of the code of the submodule ``tinyhouse`` is in the ``devel`` branch of its repository, +so if you need to use the lastest version, you can run the following command to checkout the ``devel`` branch of the submodules: + +.. code-block:: bash + + cd AlphaPeel + cd src/tinypeel/tinyhouse + git fetch origin + git checkout devel # checkout the devel branch of the submodule + cd ../../.. + +Here we are using the ``devel`` branch of the submodule as an example, +but you can checkout to any branch or commit of the submodule that +you want to use for your development in the ``AlphaPeel`` repository. +If you are working with a specific branch of commit of your fork of the submodule, +you can checkout to that branch or commit instead. + +.. code-block:: bash + + cd AlphaPeel + cd src/tinypeel/tinyhouse + git remote add fork URL_of_your_forked_submodule_repository + git fetch fork + git checkout commit_or_branch_of_your_forked_submodule + cd ../../.. + +.. _branch-instructions: + +Work with branches +------------------ + Depending on the type of code change, you should use different branches. First, check the available branches: @@ -331,12 +392,14 @@ which will be later merged into the ``devel`` branch by maintainers: .. code-block:: bash git checkout devel # start from the development branch - git branch issue_GitHubIssueNumber # work on issue with GitHub number GitHubIssueNumber - git checkout issue_GitHubIssueNumber + git branch # create a new branch for your issue + git checkout # now work on your code changes -It is a good practice that you first open an issue to document what you plan to do, -then follow the above process. +For branch naming convention, see :ref:`branch-naming`. + +It is a good practice that you first open a task issue to document what you plan to do, +then follow the above process. For the task issue template, see :ref:`task-issue-template`. Small code changes can go directly to the ``devel`` branch, which will eventually be merged into the main branch by maintainers, @@ -347,15 +410,30 @@ but check this with the maintainers when you open/discuss the issue: git checkout devel # now work on your code changes -Stable code for wider use will be published is in the ``main`` branch. -While most changes will be happening on the ``devel`` branch, -critical bugfixes, can go to the ``main`` branch, -but check this with the maintainers when you open/discuss the issue: +.. _rebase_instructions: + +Rebase to keep up with the latest changes +----------------------------------------- + +During development, always keep your branch synced with upstream. +You can do this by rebasing to the latest ``devel`` branch of the AlphaGenes repository to +keep up with the latest changes and avoid merge conflicts later on. + +To rebase to the AlphaGenes repository, you need to first add the AlphaGenes repository as an upstream remote: .. code-block:: bash - git checkout main - # now work on your code changes + git remote add AlphaGenes https://github.com/AlphaGenes/AlphaPeel + git fetch AlphaGenes + +Then, you can rebase your branch to the latest ``devel`` branch of the AlphaGenes repository: + +.. code-block:: bash + + git checkout + git rebase AlphaGenes/devel + +.. _changes_instructions: Make changes in your clone -------------------------- @@ -377,6 +455,13 @@ To install ``pytest`` and ``pytest-benchmark``: pip install pytest pip install pytest-benchmark +To build and reinstall the package on your modified code: + +.. code-block:: bash + + python -m build + python -m pip uninstall AlphaPeel -y + python -m pip install dist/*.whl To run ``pytest``: @@ -384,7 +469,19 @@ To run ``pytest``: pytest -If the tests run successfully, you are expected to see output similar to the following: +If you want to run a specific functional test, such as the ``test_files``, you can run like the following: + +.. code-block:: bash + + pytest tests/functional_tests/run_func_test.py::TestClass::test_files + +If some functioanl tests fail and you want to see the output of the tests, you can add the ``-s`` flag, note that the accuracy test report cannot be generated with the ``-s`` flag: + +.. code-block:: bash + + pytest -s tests/functional_tests/run_func_test.py + +If the tests run successfully, you are expected to see the head of the output similar to the following: .. code-block:: @@ -437,43 +534,94 @@ because this last command will add all changes files to your commit, including temporary files that might not belong in the repository. Are you aware of `.gitignore file `_? -In the `git add` line above, don't use `git add .` because this last command will add all changes files to your commit, including temporary files that might not belong in the repository. Are you aware of _? +In the ``git add`` line above, don't use ``git add .`` because this last command will add all changes files to your commit, +including temporary files that might not belong in the repository. Are you aware of ``_? -Update submodules? ------------------- +.. _documentation-changes: -Sometimes you have to update the submodules in line with -your code changes in the ``AlphaPeel`` or the submodules. +Documentation changes +--------------------- -First, check the current state of the submodule: +If you make documenation changes, you can build the documentation locally to check if the changes are correctly reflected in the documentation. .. code-block:: bash - git submodule status + cd docs + make html + +Then, you can open the generated HTML files in the ``build/html`` directory. + +.. _submodule-changes: + +Submodule consistency +--------------------- + +Before you push your changes to your fork, make sure the submodule pointer is updated to the commit +that you want to use for your development in the ``AlphaPeel`` repository. + +It is recommended to check if your code changes in the ``AlphaPeel`` is consistent with the latest version of the submodule +``tinyhouse`` in the ``devel`` branch of its repository. + +You can find the instruction to update the submodule pointer in the section :ref:`use-correct-version-submodule` above. + +After update the submodule pointer, make sure to test your code changes by running the tests on +the distribution built on your modified code to check if the code changes are consistent with the latest version of the submodule. -Next, check the latest commit in the submodule's remote repository: +Before open a pull request +-------------------------- + +Before you open a pull request, make sure you have: + + * Tested your code changes by running the tests on the distribution built on your modified code + + * Instructions: :ref:`changes_instructions` + + * Committed your changes with informative commit messages + + * Instructions: :ref:`changes_instructions` + + * Updated the submodule pointer to the commit that you want to use for your development in the ``AlphaPeel`` repository + + * Instructions: :ref:`submodule-changes` + + * If you have made documentation changes, built the documentation locally to check if the changes are correctly reflected in the documentation + + * Instructions: :ref:`documentation-changes` + + * You can add description of your change in the ``docs/changelog.rst`` file to keep track of the changes you have made, but this is optional and can be done later by maintainers when merging the PR + +Also, make sure you have the lastest code changes from the AlphaGenes repository by rebasing to the latest ``devel`` branch of the AlphaGenes repository (see :ref:`rebase_instructions`). + +.. _squash-commits-instructions: + +Squash commits +^^^^^^^^^^^^^^ + +An optional method for cleaning up the commit history is to squash the commits, +but be careful when squashing the merged, rebased, or squashed commits, +as it can cause issues with the commit history and may cause GitHub to not be able to merge the PR. +To squash the last N commits, you can run the following command: .. code-block:: bash - cd src/tinypeel/tinyhouse - git log --oneline --max-count=1 origin/main - cd ../../.. + git reset --soft HEAD~N + git commit -m "Informative short message AlphaGenes/AlphaPeel#GitHubIssueNumber" -If the commit hashes match, then the submodule reference is up to date. -If you want to use the old submodule version, then a mismatch is ok. -Otherwise, update the reference using: +If you have already pushed the commits to your fork, you can use the following command to force push the squashed commit: .. code-block:: bash - git submodule update --remote - git commit -m "Updated submodule reference to X.Y.Z AlphaGenes/AlphaPeel#GitHubIssueNumber" - # provide submodules version (X.Y.Z) or commit hash + git push --force-with-lease origin + Create a pull request --------------------- `Create a pull request (PR) `_ to propose your changes to the repository. Maintainers will review your PR. +Please follow the PR best practices outline in the section :ref:`PR-practice` above when you create a PR. + + Update the version of the package to publish the package -------------------------------------------------------- diff --git a/docs/source/get_started.rst b/docs/source/get_started.rst index 78d90ea..595b75d 100644 --- a/docs/source/get_started.rst +++ b/docs/source/get_started.rst @@ -2,6 +2,18 @@ Getting Started =============== +Quick links: + +* Installation: :ref:`install` + +* Simple example: :ref:`simple_example` + +* How to use: :ref:`usage` + +* Algorithm: :ref:`algorithm` + +.. _install: + Install |Software| ------------------ @@ -135,6 +147,9 @@ you may can try: git config core.fileMode false + +.. _simple_example: + An example ---------- @@ -233,7 +248,7 @@ And following output files: simple_output.dosage.txt simple_output.rec_prob.txt -TODO: Let's round up these thresholds to 0.3333333333333333 to 0.33, so 2 digits +.. TODO: Let's round up these thresholds to 0.3333333333333333 to 0.33, so 2 digits This should be enough, I reckon, but happy to discuss! simple_output.geno_0.3333333333333333.txt simple_output.seq_error_prob.txt @@ -256,9 +271,10 @@ in line with their fully homozygous genotypes. As such, the progeny could only inherit one kind of a haplotype from each of the parents, making this a very simple example. -TODO: Let's round up these thresholds to 0.3333333333333333 to 0.33, so 2 digits +.. + TODO: Let's round up these thresholds to 0.3333333333333333 to 0.33, so 2 digits This should be enough, I reckon, but happy to discuss! -The ``simple_output.geno_0.3333333333333333.txt`` provides the called genotypes: + The ``simple_output.geno_0.3333333333333333.txt`` provides the called genotypes: .. code-block:: bash diff --git a/docs/source/usage.rst b/docs/source/usage.rst index d9240ad..64d6388 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -12,7 +12,11 @@ Program options |Software| accepts several command-line options to control the program's behaviour. To view a list of all supported options, run |Software| like this: -``AlphaPeel`` or ``AlphaPeel -h``. +``AlphaPeel``, ``AlphaPeel -h``, ``AlphaPeel -help`` or ``AlphaPeel --help``. + +User can check the version of the program with ``AlphaPeel -version``. +Remember to use the correct version of the documentation for the version of the program you are using. +For example, the link to the documentation for version ``v1.3.0`` is https://alphapeel.readthedocs.io/en/v1.3.0/index.html. .. _input_options: diff --git a/src/tinypeel/Peeling/version.py b/src/tinypeel/Peeling/version.py new file mode 100644 index 0000000..fe47c6e --- /dev/null +++ b/src/tinypeel/Peeling/version.py @@ -0,0 +1,3 @@ +from importlib.metadata import version + +version = version("alphapeel") diff --git a/src/tinypeel/tinyhouse b/src/tinypeel/tinyhouse index 57652a6..34da21f 160000 --- a/src/tinypeel/tinyhouse +++ b/src/tinypeel/tinyhouse @@ -1 +1 @@ -Subproject commit 57652a6f3c910b5644d06a6f37a10cbe6fcee32b +Subproject commit 34da21feca3db71128dc0fcf2641ea0cda593e9f diff --git a/src/tinypeel/tinypeel.py b/src/tinypeel/tinypeel.py index de1519a..95b810b 100644 --- a/src/tinypeel/tinypeel.py +++ b/src/tinypeel/tinypeel.py @@ -16,6 +16,10 @@ from itertools import repeat import argparse +from .Peeling import version + +version_version = version.version + def runPeelingCycles(pedigree, peelingInfo, args, singleLocusMode=False): """Sets up and runs each of the peeling cycles (default is 5). @@ -826,6 +830,21 @@ def getArgs(): ) # singleLocus_parser.add_argument('-blocksize',default=100, required=False, type=int, help='The number of markers to impute at once. This changes the memory requirements of the program.') + # special handle for version argument to allow it to be called with just -version + parser.add_argument( + "-version", + default=None, + action="version", + version="%(prog)s " + version_version, + help="Show program's version number and exit.", + ) + + args = sys.argv[1:] + + if "-version" in args: + parser.parse_args(args) + sys.exit(0) + return InputOutput.parseArgs("AlphaPeel", parser)