From 7953597a122c2fb2da043b3bfeceff9c75fcafeb Mon Sep 17 00:00:00 2001 From: Alex Lancaster Date: Sun, 31 Dec 2023 01:41:38 -0500 Subject: [PATCH 01/13] replace NEWS.rst with NEWS.md * use https://keepachangelog.com format * use myst_parser to include as markdown --- NEWS.md | 334 +++++++++++++++++++++++++ NEWS.rst | 331 ------------------------ website/docs/guide-chapter-changes.rst | 9 +- 3 files changed, 341 insertions(+), 333 deletions(-) create mode 100644 NEWS.md delete mode 100644 NEWS.rst diff --git a/NEWS.md b/NEWS.md new file mode 100644 index 000000000..14ceb315b --- /dev/null +++ b/NEWS.md @@ -0,0 +1,334 @@ +# Changelog + +## [1.0.0] - 2023-11-07 + +PyPop 1.0.0 is the first official release of PyPop using Python 3, and +the first release to be included on [PyPI](https://pypi.org/project/pypop-genomics/). In addition to using +modern libraries, there are some new features, such as the new +asymmetric LD measures, and better handling of TSV files, along with +the typical slew of bug fixes. Many more changes are of an "under the +hood" nature, such as a new unit testing and documentation framework, +and are detailed below. Many people contributed to this latest +release, which has been a while in coming. Thanks especially to all +new contributors including Vanessa Sochat, Gordon Webster, +Jurriaan H. Spaaks, Karl Kornel and Michael Mariani. Thanks also to +all of our bug reporters, and ongoing contributors, especially Richard +Single, Owen Solberg and Steve Mack. + +### New features + +- PyPop now fully ported to run under Python 3 (thanks to Vanessa + Sochat for major patch) + +- Added new asymmetric linkage disequilibrium (ALD) calculations + (thanks to Richard Single), see [^cite_thomson:single:2014] for more + details. Added in both the plain text (`.txt`) as well as the + `2-locus-summary.tsv` TSV file outputs. + +- Improved tab-separated values (TSV) output file handling: + + - old IHWG headers are disabled by default, so the `-disable-ihwg` + option has been replaced by the `--enable-ihwg` option, which + will re-enable them. + - `popmeta`: allow TSV files to be put in separate directory with + `-o`/ `--outputdir` command-lineoption for saving generated + files. + - `pypop`: renamed `--generate-tsv` to `--enable-tsv` + - dynamic generation of TSV files based on XML input, so the list of + files is no longer hard-coded (thanks to Steve Mack for + suggestion), this also adds support for haplotypes involving more + than 4 loci + +- Preliminary support for Genotype List (GL) String + () + +- Added unit-tests using `pytest` testing framework. + +- New documentation system using `sphinx`, replacing the old DocBook + XML, to generate both the website and the *PyPop User Guide* (HTML + and PDF): + + - sphinx-based documentation is now written in ReStructuredText + (`.rst`) + - improve `popmeta` and other documentation for command-line + programs + - documentation additions and improvements from Richard Single, + Michael Mariani, Gordon Webster and Steve Mack + - overhaul release process and add a contribution-guide to the + *PyPop User Guide*. + - update documentation to use new HLA nomenclature throughout + +- PyPop now uses `numpy` in place of the old `Numeric` library + `Numpy`, and `lxml` in place of `libxml_mod` + +### Bug fixes + +- TSV file fixes: + + - fix missing columns in TSV files (thanks to Steve Mack for report) + + - fix headers in 3 and 4 locus TSV files + + - output 2 locus haplotypes in TSV if they are explicitly specified + (thanks to Steve Mack) + + - `2-locus-haplo.tsv`: fixed missing output in `ld.d`, + `ld.dprime`, `ld.chisq`, and `exp` columns (thanks to Nabil + M for the report) + + - rename, remove and add some columns headers, including the new + `ALD` measures: + + - `2-locus-haplo.tsv`: rename columns: `allele` -> + `haplotype`, `exp` -> `haplotype.no-ld.count` + - `2-locus-haplo.tsv`: remove `obs` and `obs.freq` columns + which were duplicative of `haplotype.count` and + `haplotype.freq`, respectively + - `2-locus-summary.tsv`: add two new ALD measure columns: + `ald.1_2` and `ald.2_1` + - `*-locus-summary.tsv`: rename columns for multilocus + haplotypes for 3 or more loci, `allele` -> `haplotype` and + `locus` -> `loci` + +- Fix `DigitBinning` and `CustomBinning` filters `[Filters]` + (report from Steve Mack) + +- Fix issues with using colons in alleles, and other separation + isssues (thanks to Steve Mack) + +- Use `~` as the genotype terminator rather than `|` (fixes some + haplotype estimation bugs) + +- Round all haplotype frequencies to 5 decimal places to avoid + truncation issues (thanks to Steve Mack for report) + +- Restore semi-GUI interactive mode by using built-in `TkInter` file + dialog, and use more informative default "placeholder" file names + +- Fix warnings generated by `numpy` and `re` libraries. + +- Windows fixes: + + - `Emhaplofreq` will now give identical results on Windows as all + other platform (needed to port POSIX-version of `drand48()` to + Windows). + - Fixed `CustomBinning` filters that were failing on Windows. + - Enable all unit tests for Windows. + +### Internal + +- Replace old `getopt` with `argparse` library +- Major code refactoring, including moving code into `src` + directory, and using packages in `setup.py` +- Added continuous integration via GitHub Actions for releases and + website updates +- Prepare package for inclusion in `PyPI` +- Add code examples used in documentation as unit tests +- Create GitHub action for upload to Zenodo (thanks to + Jurriaan H. Spaaks) +- Support for arm64 builds on MacOS, e.g. M1-based Macs (thanks to + Owen Solberg for report and extensive testing). +- Remove dependency on `psutil`, rarely needed. +- Only build wheels on platforms for which binary wheels are available + for all dependencies. + +## [0.7.0] - 2008-09-09 + +### New features + +- `makeNewPopFile` option has been changed. This option allows user to + generate intermediate output of filtered files. Now option should + be of the format: `type:order` where `type` is one of + `separate-loci` or `all-loci` so that the user can specify whether + a separate file should be generated for each locus + (`separate-loci`) or a single file with all loci (`all-loci`). + `order` should be the order in the filtering chain where the + matrix is generated, there is no default, for example, for + generating files after the first filter operation use `1`. + +- New command-line option `--generate-tsv`, will generate the `.dat` + tab-separated values (TSV) files on the the generated -out.xml + files (aka "popmeta") directly from pypop without needing to run + additional script. Now output from pypop can be directly read + into spreadsheet. + +- New feature: add individual genotype tests to Hardy-Weinberg module + (gthwe), now computes statistics based on individual genotypes in + the HWP table. The `[HardyWeinbergGuoThompson]` or + `[HardyWeinbergGuoThompsonMonteCarlo]` options must be enabled in the + configuration ".ini" file in order for these tests to be carried out. + +- Major improvements to custom and random binning filters (Owen Solberg). + +- New feature: generate homozygosity values using the Ewens-Watterson test for + all pairwise loci, or all sites within a gene for sequence data + (`[homozygosityEWSlatkinExactPairwise]` in .ini file). Note: this + really only works for sequence data where the phase for sites + within an allele are known. + +- Haplotype and LD estimation module `emhaplofreq` improvements + + - improved memory usage and speed for emhaplofreq module. + - maximum sample size for emhaplofreq module increased from 1023 to + 5000 individuals. + - maximum length of allele names increased to 20 + +### Bug fixes + +- Support Python 2.4 on GCC 4.0 platforms. +- Add missing initialisation for non-sequence data when processing + haplotypes. Thanks to Jill Hollenbach for the report. +- Fix memory leak in xslt translation. +- Various fixes relating to parsing XML output. +- Fixed an incorrect parameter name. +- Handle some missing sections in .ini better. Thanks to + Owen Solberg for report. +- Various build and installation fixes (SWIG, compilation flags) +- Make name of source package be lowercase "pypop". +- Change data directory: /usr/share/pypop/ to /usr/share/PyPop/ +- Print out warning when maximum length of allele exceeded, rather than + crashing. Thanks to Steve Mack for report. + +### Other issues + +- Sequence filter + + - In the Sequence filter, add special case for Anthony Nolan HLA data: + mark null alleles ending in "N" (e.g. HLA-B\*5127N) as "missing + data" (`****`). + - Also in Sequence, keep track of unsequenced sites separately + (via unsequencedSites variable) from "untyped" (aka "missing + data"). Treat unsequencedSite as a unique allele to make sure that + those sites don't get treated as having a consensus sequence if + only one of the sequences in the the set of matches is typed. + - If no matching sequence is found in the MSF files, then return a + sequence of * symbols (ie, will be treated as truly missing data, + not untyped alleles. + - Add another special case for HLA data: test for 7 digits in allele names + (e.g. if 2402101 is not found insert a zero after the first 4 + digits to form 24020101, and check for that). This is to cope + with yet-another HLA nomenclature change. + +- Change semantics of batchsize, make "0" (default) process files separately + if only R dat files is enabled. If batchsize not set explicitly + (and therefore 0) set batchsize to `1` is PHYLIP mode is enabled. + +## [0.6.0] - 2005-04-13 + +### New features + +- Allow for odd allele counts when processing an allele count data + (i.e "semi"-typing). When PyPop is dealing with data that is + originally genotyped, the current default is preserved i.e. we + dis-allow individuals that are typed at only allele, and set + allowSemiTyped to false. +- New command-line option `-f` (long version `--filelist`) which + accepts a file containing a list of files (one per line) to + process (note that this is mutually exclusive with supplying + INPUTFILEs, and will abort with an error message if you supply + both simultaneously). +- In batch version, handle multiple INPUTFILEs supplied as command-line + arguments and support Unix shell-globbing syntax (e.g. `pypop.py + -c config.ini *.pop`). (NOTE: This is supported *only* in + batch version, not in the interactive version, which expects one + and only one file supplied by user. +- Allele count files can now be filtered through the filter apparatus + (particularly the Sequence and AnthonyNolan) in the same was as + genotype files transparently. \[This has been enabled via a code + refactor that treats allele count files as pseudo-genotype files + for the purpose of filtering\]. This change also resulted in the + removal of the obsolete lookup-table-based homozygosity test. +- Add `--disable-ihwg` option to popmeta script to disable hardcoded + generation of the IHWG header output, and use the output as + defined in the header in the original .pop input text file. This + is disabled by default to preserve backwards compatibility. +- Add `--batchsize` (`-b` short version) option for popmeta. Does the + processing in "batches". If set and greater than one, list of XML + files is split into batchsize group. For example, if there are 20 + XML files and option is via using ("-b 2" or "--batchsize=2") then + the files will be processed in two batches, each consisting of 10 + files. If the number does not divide evenly, the last list will + contain all the "left-over" files. This option is particularly + useful with large XML files that may not fit in memory all at + once. Note this option is mutually exclusive with the + `--enable-PHYLIP` option because the PHYLIP output needs to + calculate allele frequencies across all populations before + generating files. +- New .ini file option: `[HardyWeinbergGuoThompsonMonteCarlo]`: add a plain + Monte-Carlo (randomization, without the Markov chain test) test + for the HardyWeinberg "exact test". Add code for Guo & Thompson + test to distribution (now under GNU GPL). + +### Bug fixes + +- HardyWeinbergGuoThompson overall p-value test was numerically unstable + because it attempted to check for equality in greater than or + equal to constructs ("\<=") which is not reliable in C. Replaced + this with a GNU Scientific Library (GSL) function gsl_fcmp() which + compares floats to within an EPSILON (defaults to 1e-6). +- Allow `HardyWeinbergGuoThompson` test to be run if at least two alleles + present (test was originally failing with a `too-few-alleles` + message if there were not at least 3 alleles). Thanks to Kristie + Mather for the report. +- Checks to see if a locus is monomorphic, if it is, it generates an + allele summary report, but skips the rest of the single locus + analyses which do not make sense for monomorphic locus. Thanks to + Steve Mack and Owen Solberg for the bug report(s). +- Now builds against recent versions of SWIG (no longer stuck at version + 1.3.9), should be compatible with versions of SWIG > 1.3.10. + (Tested against SWIG 1.3.21). +- Homozygosity module: Prevent math errors by in Slatkin's exact test by + forcing the homozygosity to be positive (only a problem for rare + cases, when the result is so close to zero that the floating point + algorithms cause a negative result.) + +## [0.5.2] (public beta) - 2004-03-09 + +### Bug fixes + +- Add missing RandomBinning.py file to source distribution + Thanks to Hazael Maldonado Torres for the bug report. +- Fixed line endings for .bat scripts for Win32 so they work under + Windows 98 thanks to Wendy Hartogensis for the bug report. + +## [0.5.1] (public beta) - 2004-02-26 + +### Changes + +- New parameter `numInitCond`, number of initial conditions by the + haplotype estimation and LD algorithm used before performing + permutations. Defaults to 50. +- Remove some LOG messages/diagnostics that were erroneously implying + an error to the user (if nothing is wrong, don't say anything). Add + some more useful messages for what is being done in haplo/LD + estimation step. +- Add popmeta.py to the distribution: this is undocumented and unsupported + as yet, it is at alpha stage only, use at your own risk! + +### Bug fixes + +- Remember to output plaintext version of LD for specified loci. + +## [0.5] (public beta) - 2003-12-31 + +### Changes + +- All Linux wrapper scripts no longer have .sh file suffixes for + consistency with DOS (all DOS bat files can be executed without + specifying the .bat extension). + +### Bug fixes + +- Add wrapper scripts for interactive and batch mode for + both DOS and Linux so that correct shared libraries are called. +- Pause and wait for user to press a key at end of DOS .bat file + so that output can be viewed before window close. +- Set PYTHONHOME in wrapper scripts to prevent messages about + missing \ being displayed. + +## [0.4.3beta] + +### Bug fixes + +- Fixed bug in processing of `popname` field. + Thanks to Richard Single for the report. diff --git a/NEWS.rst b/NEWS.rst deleted file mode 100644 index bc3a0efbb..000000000 --- a/NEWS.rst +++ /dev/null @@ -1,331 +0,0 @@ -PyPop Release History -===================== - -.. _news-start: - -Release Notes for PyPop 1.0.0 ------------------------------ -(2023-11-07) - -PyPop 1.0.0 is the first official release of PyPop using Python 3, and -the first release to be included on `PyPI -`__. In addition to using -modern libraries, there are some new features, such as the new -asymmetric LD measures, and better handling of TSV files, along with -the typical slew of bug fixes. Many more changes are of an "under the -hood" nature, such as a new unit testing and documentation framework, -and are detailed below. Many people contributed to this latest -release, which has been a while in coming. Thanks especially to all -new contributors including Vanessa Sochat, Gordon Webster, -Jurriaan H. Spaaks, Karl Kornel and Michael Mariani. Thanks also to -all of our bug reporters, and ongoing contributors, especially Richard -Single, Owen Solberg and Steve Mack. - - -New features -^^^^^^^^^^^^ -* PyPop now fully ported to run under Python 3 (thanks to Vanessa - Sochat for major patch) -* Added new asymmetric linkage disequilibrium (ALD) calculations - (thanks to Richard Single), see [Thomson:Single:2014]_ for more - details. Added in both the plain text (``.txt``) as well as the - ``2-locus-summary.tsv`` TSV file outputs. -* Improved tab-separated values (TSV) output file handling: - - * old IHWG headers are disabled by default, so the ``-disable-ihwg`` - option has been replaced by the ``--enable-ihwg`` option, which - will re-enable them. - * ``popmeta``: allow TSV files to be put in separate directory with - ``-o``/ ``--outputdir`` command-lineoption for saving generated - files. - * ``pypop``: renamed ``--generate-tsv`` to ``--enable-tsv`` - * dynamic generation of TSV files based on XML input, so the list of - files is no longer hard-coded (thanks to Steve Mack for - suggestion), this also adds support for haplotypes involving more - than 4 loci - -* Preliminary support for Genotype List (GL) String - (https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3715123/) -* Added unit-tests using ``pytest`` testing framework. -* New documentation system using ``sphinx``, replacing the old DocBook - XML, to generate both the website and the *PyPop User Guide* (HTML - and PDF): - - * sphinx-based documentation is now written in ReStructuredText - (``.rst``) - * improve ``popmeta`` and other documentation for command-line - programs - * documentation additions and improvements from Richard Single, - Michael Mariani, Gordon Webster and Steve Mack - * overhaul release process and add a contribution-guide to the - *PyPop User Guide*. - * update documentation to use new HLA nomenclature throughout - -* PyPop now uses ``numpy`` in place of the old ``Numeric`` library - ``Numpy``, and ``lxml`` in place of ``libxml_mod`` - -Bug fixes -^^^^^^^^^ -* TSV file fixes: - - * fix missing columns in TSV files (thanks to Steve Mack for report) - * fix headers in 3 and 4 locus TSV files - * output 2 locus haplotypes in TSV if they are explicitly specified - (thanks to Steve Mack) - * ``2-locus-haplo.tsv``: fixed missing output in ``ld.d``, - ``ld.dprime``, ``ld.chisq``, and ``exp`` columns (thanks to Nabil - M for the report) - * rename, remove and add some columns headers, including the new - ``ALD`` measures: - - * ``2-locus-haplo.tsv``: rename columns: ``allele`` -> - ``haplotype``, ``exp`` -> ``haplotype.no-ld.count`` - * ``2-locus-haplo.tsv``: remove ``obs`` and ``obs.freq`` columns - which were duplicative of ``haplotype.count`` and - ``haplotype.freq``, respectively - * ``2-locus-summary.tsv``: add two new ALD measure columns: - ``ald.1_2`` and ``ald.2_1`` - * ``*-locus-summary.tsv``: rename columns for multilocus - haplotypes for 3 or more loci, ``allele`` -> ``haplotype`` and - ``locus`` -> ``loci`` - -* Fix ``DigitBinning`` and ``CustomBinning`` filters ``[Filters]`` - (report from Steve Mack) -* Fix issues with using colons in alleles, and other separation - isssues (thanks to Steve Mack) -* Use ``~`` as the genotype terminator rather than ``|`` (fixes some - haplotype estimation bugs) -* Round all haplotype frequencies to 5 decimal places to avoid - truncation issues (thanks to Steve Mack for report) -* Restore semi-GUI interactive mode by using built-in ``TkInter`` file - dialog, and use more informative default "placeholder" file names -* Fix warnings generated by ``numpy`` and ``re`` libraries. -* Windows fixes: - - * ``Emhaplofreq`` will now give identical results on Windows as all - other platform (needed to port POSIX-version of ``drand48()`` to - Windows). - * Fixed ``CustomBinning`` filters that were failing on Windows. - * Enable all unit tests for Windows. - -Internal -^^^^^^^^ -* Replace old ``getopt`` with ``argparse`` library -* Major code refactoring, including moving code into ``src`` - directory, and using packages in ``setup.py`` -* Added continuous integration via GitHub Actions for releases and - website updates -* Prepare package for inclusion in ``PyPI`` -* Add code examples used in documentation as unit tests -* Create GitHub action for upload to Zenodo (thanks to - Jurriaan H. Spaaks) -* Support for arm64 builds on MacOS, e.g. M1-based Macs (thanks to - Owen Solberg for report and extensive testing). -* Remove dependency on ``psutil``, rarely needed. -* Only build wheels on platforms for which binary wheels are available - for all dependencies. - -Release Notes for PyPop 0.7.0 ------------------------------ -(2008-09-09) - -New features -^^^^^^^^^^^^ -* ``makeNewPopFile`` option has been changed. This option allows user to - generate intermediate output of filtered files. Now option should - be of the format: ``type:order`` where ``type`` is one of - ``separate-loci`` or ``all-loci`` so that the user can specify whether - a separate file should be generated for each locus - (``separate-loci``) or a single file with all loci (``all-loci``). - ``order`` should be the order in the filtering chain where the - matrix is generated, there is no default, for example, for - generating files after the first filter operation use ``1``. -* New command-line option ``--generate-tsv``, will generate the ``.dat`` - tab-separated values (TSV) files on the the generated -out.xml - files (aka "popmeta") directly from pypop without needing to run - additional script. Now output from pypop can be directly read - into spreadsheet. -* New feature: add individual genotype tests to Hardy-Weinberg module - (gthwe), now computes statistics based on individual genotypes in - the HWP table. The ``[HardyWeinbergGuoThompson]`` or - ``[HardyWeinbergGuoThompsonMonteCarlo]`` options must be enabled in the - configuration ".ini" file in order for these tests to be carried out. -* Major improvements to custom and random binning filters (Owen Solberg). -* New feature: generate homozygosity values using the Ewens-Watterson test for - all pairwise loci, or all sites within a gene for sequence data - (``[homozygosityEWSlatkinExactPairwise]`` in .ini file). Note: this - really only works for sequence data where the phase for sites - within an allele are known. -* Haplotype and LD estimation module ``emhaplofreq`` improvements - - * improved memory usage and speed for emhaplofreq module. - * maximum sample size for emhaplofreq module increased from 1023 to - 5000 individuals. - * maximum length of allele names increased to 20 - -Bug fixes -^^^^^^^^^ -* Support Python 2.4 on GCC 4.0 platforms. -* Add missing initialisation for non-sequence data when processing - haplotypes. Thanks to Jill Hollenbach for the report. -* Fix memory leak in xslt translation. -* Various fixes relating to parsing XML output. -* Fixed an incorrect parameter name. -* Handle some missing sections in .ini better. Thanks to - Owen Solberg for report. -* Various build and installation fixes (SWIG, compilation flags) -* Make name of source package be lowercase "pypop". -* Change data directory: /usr/share/pypop/ to /usr/share/PyPop/ -* Print out warning when maximum length of allele exceeded, rather than - crashing. Thanks to Steve Mack for report. - -Other issues -^^^^^^^^^^^^ -* Sequence filter - - * In the Sequence filter, add special case for Anthony Nolan HLA data: - mark null alleles ending in "N" (e.g. HLA-B*5127N) as "missing - data" (``****``). - * Also in Sequence, keep track of unsequenced sites separately - (via unsequencedSites variable) from "untyped" (aka "missing - data"). Treat unsequencedSite as a unique allele to make sure that - those sites don't get treated as having a consensus sequence if - only one of the sequences in the the set of matches is typed. - * If no matching sequence is found in the MSF files, then return a - sequence of * symbols (ie, will be treated as truly missing data, - not untyped alleles. - * Add another special case for HLA data: test for 7 digits in allele names - (e.g. if 2402101 is not found insert a zero after the first 4 - digits to form 24020101, and check for that). This is to cope - with yet-another HLA nomenclature change. -* Change semantics of batchsize, make "0" (default) process files separately - if only R dat files is enabled. If batchsize not set explicitly - (and therefore 0) set batchsize to ``1`` is PHYLIP mode is enabled. - -Release Notes for PyPop 0.6.0 ------------------------------ -(2005-04-13) - -New features -^^^^^^^^^^^^ -* Allow for odd allele counts when processing an allele count data - (i.e "semi"-typing). When PyPop is dealing with data that is - originally genotyped, the current default is preserved i.e. we - dis-allow individuals that are typed at only allele, and set - allowSemiTyped to false. -* New command-line option ``-f`` (long version ``--filelist``) which - accepts a file containing a list of files (one per line) to - process (note that this is mutually exclusive with supplying - INPUTFILEs, and will abort with an error message if you supply - both simultaneously). -* In batch version, handle multiple INPUTFILEs supplied as command-line - arguments and support Unix shell-globbing syntax (e.g. ``pypop.py - -c config.ini *.pop``). (NOTE: This is supported *only* in - batch version, not in the interactive version, which expects one - and only one file supplied by user. -* Allele count files can now be filtered through the filter apparatus - (particularly the Sequence and AnthonyNolan) in the same was as - genotype files transparently. [This has been enabled via a code - refactor that treats allele count files as pseudo-genotype files - for the purpose of filtering]. This change also resulted in the - removal of the obsolete lookup-table-based homozygosity test. -* Add ``--disable-ihwg`` option to popmeta script to disable hardcoded - generation of the IHWG header output, and use the output as - defined in the header in the original .pop input text file. This - is disabled by default to preserve backwards compatibility. -* Add ``--batchsize`` (``-b`` short version) option for popmeta. Does the - processing in "batches". If set and greater than one, list of XML - files is split into batchsize group. For example, if there are 20 - XML files and option is via using ("-b 2" or "--batchsize=2") then - the files will be processed in two batches, each consisting of 10 - files. If the number does not divide evenly, the last list will - contain all the "left-over" files. This option is particularly - useful with large XML files that may not fit in memory all at - once. Note this option is mutually exclusive with the - ``--enable-PHYLIP`` option because the PHYLIP output needs to - calculate allele frequencies across all populations before - generating files. -* New .ini file option: ``[HardyWeinbergGuoThompsonMonteCarlo]``: add a plain - Monte-Carlo (randomization, without the Markov chain test) test - for the HardyWeinberg "exact test". Add code for Guo & Thompson - test to distribution (now under GNU GPL). - -Bug fixes -^^^^^^^^^ -* HardyWeinbergGuoThompson overall p-value test was numerically unstable - because it attempted to check for equality in greater than or - equal to constructs ("<=") which is not reliable in C. Replaced - this with a GNU Scientific Library (GSL) function gsl_fcmp() which - compares floats to within an EPSILON (defaults to 1e-6). -* Allow ``HardyWeinbergGuoThompson`` test to be run if at least two alleles - present (test was originally failing with a ``too-few-alleles`` - message if there were not at least 3 alleles). Thanks to Kristie - Mather for the report. -* Checks to see if a locus is monomorphic, if it is, it generates an - allele summary report, but skips the rest of the single locus - analyses which do not make sense for monomorphic locus. Thanks to - Steve Mack and Owen Solberg for the bug report(s). -* Now builds against recent versions of SWIG (no longer stuck at version - 1.3.9), should be compatible with versions of SWIG > 1.3.10. - (Tested against SWIG 1.3.21). -* Homozygosity module: Prevent math errors by in Slatkin's exact test by - forcing the homozygosity to be positive (only a problem for rare - cases, when the result is so close to zero that the floating point - algorithms cause a negative result.) - -Release Notes for PyPop 0.5.2 (public beta) -------------------------------------------- -(2004-03-09) - -Bug fixes -^^^^^^^^^ -* Add missing RandomBinning.py file to source distribution - Thanks to Hazael Maldonado Torres for the bug report. -* Fixed line endings for .bat scripts for Win32 so they work under - Windows 98 thanks to Wendy Hartogensis for the bug report. - -Release Notes for PyPop 0.5.1 (public beta) -------------------------------------------- -(2004-02-26) - -Changes -^^^^^^^ -* New parameter ``numInitCond``, number of initial conditions by the - haplotype estimation and LD algorithm used before performing - permutations. Defaults to 50. -* Remove some LOG messages/diagnostics that were erroneously implying - an error to the user (if nothing is wrong, don't say anything). Add - some more useful messages for what is being done in haplo/LD - estimation step. -* Add popmeta.py to the distribution: this is undocumented and unsupported - as yet, it is at alpha stage only, use at your own risk! - -Bug fixes -^^^^^^^^^ -* Remember to output plaintext version of LD for specified loci. - -Release Notes for PyPop 0.5 (public beta) ------------------------------------------ -(2003-12-31) - -Changes -^^^^^^^ -* All Linux wrapper scripts no longer have .sh file suffixes for - consistency with DOS (all DOS bat files can be executed without - specifying the .bat extension). - -Bug fixes -^^^^^^^^^ -* Add wrapper scripts for interactive and batch mode for - both DOS and Linux so that correct shared libraries are called. -* Pause and wait for user to press a key at end of DOS .bat file - so that output can be viewed before window close. -* Set PYTHONHOME in wrapper scripts to prevent messages about - missing being displayed. - -Release Notes for PyPop 0.4.3beta ---------------------------------- -Bug fixes -^^^^^^^^^ -* Fixed bug in processing of ``popname`` field. - Thanks to Richard Single for the report. diff --git a/website/docs/guide-chapter-changes.rst b/website/docs/guide-chapter-changes.rst index afacf48b7..de8c3e075 100644 --- a/website/docs/guide-chapter-changes.rst +++ b/website/docs/guide-chapter-changes.rst @@ -5,8 +5,13 @@ Authors and history ******************* .. include:: ../../AUTHORS.rst - -.. include:: ../../NEWS.rst + +PyPop Release History +===================== + +.. include:: ../../NEWS.md + :parser: myst_parser.sphinx_ + :start-after: Changelog From 40808b3795aa03124f6f6e5c1f7645ae041d8fd1 Mon Sep 17 00:00:00 2001 From: Alex Lancaster Date: Sun, 31 Dec 2023 01:48:48 -0500 Subject: [PATCH 02/13] note format --- NEWS.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/NEWS.md b/NEWS.md index 14ceb315b..7aa216636 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,10 @@ # Changelog +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + ## [1.0.0] - 2023-11-07 PyPop 1.0.0 is the first official release of PyPop using Python 3, and From 6cd1db53b7019f4c7316279fdac5b890bb3bb75a Mon Sep 17 00:00:00 2001 From: Alex Lancaster Date: Sun, 31 Dec 2023 02:23:48 -0500 Subject: [PATCH 03/13] numbering two levels, not three --- NEWS.md | 2 +- website/docs/guide-chapter-changes.rst | 2 +- website/docs/index.rst | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/NEWS.md b/NEWS.md index 7aa216636..9812f158f 100644 --- a/NEWS.md +++ b/NEWS.md @@ -3,7 +3,7 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +and this project adheres to [Semantic Versioning](https://semver.org). ## [1.0.0] - 2023-11-07 diff --git a/website/docs/guide-chapter-changes.rst b/website/docs/guide-chapter-changes.rst index de8c3e075..5b83407df 100644 --- a/website/docs/guide-chapter-changes.rst +++ b/website/docs/guide-chapter-changes.rst @@ -11,7 +11,7 @@ PyPop Release History .. include:: ../../NEWS.md :parser: myst_parser.sphinx_ - :start-after: Changelog + :start-after: https://semver.org). diff --git a/website/docs/index.rst b/website/docs/index.rst index 4ea37f870..dbaa7de63 100644 --- a/website/docs/index.rst +++ b/website/docs/index.rst @@ -63,7 +63,7 @@ This guide to PyPop contains four main parts: .. _user-guide-toc: .. toctree:: - :numbered: 3 + :numbered: 2 :maxdepth: 3 guide-chapter-install From 0a8d0433d51b1e4982c372a3a3b4b9c41ceadc6e Mon Sep 17 00:00:00 2001 From: Alex Lancaster Date: Sun, 31 Dec 2023 02:34:27 -0500 Subject: [PATCH 04/13] only first-level sections also for LaTeX --- website/conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/website/conf.py b/website/conf.py index b37661b16..1c20fec98 100644 --- a/website/conf.py +++ b/website/conf.py @@ -186,7 +186,8 @@ def __init__(self, **options): # 'preamble': r'''\DeclareRobustCommand{\and}{% \end{tabular}\kern-\tabcolsep\\\begin{tabular}[t]{c}% -}%''', +}% +\setcounter{secnumdepth}{1}%''', # Latex figure (float) alignment # From d300204501f76d36e325acae6fdd1a9b6f5e4765 Mon Sep 17 00:00:00 2001 From: Alex Lancaster Date: Sun, 31 Dec 2023 02:53:26 -0500 Subject: [PATCH 05/13] add links to recent tags only --- NEWS.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/NEWS.md b/NEWS.md index 9812f158f..fbb445c6e 100644 --- a/NEWS.md +++ b/NEWS.md @@ -218,7 +218,7 @@ Single, Owen Solberg and Steve Mack. if only R dat files is enabled. If batchsize not set explicitly (and therefore 0) set batchsize to `1` is PHYLIP mode is enabled. -## [0.6.0] - 2005-04-13 +## 0.6.0 - 2005-04-13 ### New features @@ -287,7 +287,7 @@ Single, Owen Solberg and Steve Mack. cases, when the result is so close to zero that the floating point algorithms cause a negative result.) -## [0.5.2] (public beta) - 2004-03-09 +## 0.5.2 (public beta) - 2004-03-09 ### Bug fixes @@ -296,7 +296,7 @@ Single, Owen Solberg and Steve Mack. - Fixed line endings for .bat scripts for Win32 so they work under Windows 98 thanks to Wendy Hartogensis for the bug report. -## [0.5.1] (public beta) - 2004-02-26 +## 0.5.1 (public beta) - 2004-02-26 ### Changes @@ -314,7 +314,7 @@ Single, Owen Solberg and Steve Mack. - Remember to output plaintext version of LD for specified loci. -## [0.5] (public beta) - 2003-12-31 +## 0.5 (public beta) - 2003-12-31 ### Changes @@ -331,9 +331,12 @@ Single, Owen Solberg and Steve Mack. - Set PYTHONHOME in wrapper scripts to prevent messages about missing \ being displayed. -## [0.4.3beta] +## 0.4.3beta ### Bug fixes - Fixed bug in processing of `popname` field. Thanks to Richard Single for the report. + +[1.0.0]: https://github.com/alexlancaster/pypop/releases/tag/v1.0.0 +[0.7.0]: https://github.com/alexlancaster/pypop/releases/tag/PYPOP_SRC-0_7_0 \ No newline at end of file From 8b2d0a0232010a82cceb5583f7e30876e422ea66 Mon Sep 17 00:00:00 2001 From: Alex Lancaster Date: Sun, 31 Dec 2023 17:15:44 -0500 Subject: [PATCH 06/13] convert AUTHORS to a table suppress the links to release pages in PDF backend fix citation in NEWS.md --- AUTHORS.rst | 117 +++++++++++++++---------- NEWS.md | 6 +- website/docs/guide-chapter-changes.rst | 16 +++- 3 files changed, 85 insertions(+), 54 deletions(-) diff --git a/AUTHORS.rst b/AUTHORS.rst index a035bee61..d86888a65 100644 --- a/AUTHORS.rst +++ b/AUTHORS.rst @@ -5,53 +5,76 @@ PyPop contributors (Listed in alphabetical order) -Karl Kornel | `0000-0001-5847-5330 `__ | Stanford Research Computing Center - Contributed containerization - -Alex Lancaster | `0000-0002-0002-9263 `_ | Amber Biology LLC, Ronin Institute - Lead developer. Co-designer of Python framework: author of main engine, text file - parser, Python extension module framework using SWIG, XML output and - XSLT post-processing framework (to generate plain text and HTML - output). - -Steven J. Mack | `0000-0001-9820-9547 `__ | University of California, San Francisco - Contributed bug reports, documentation, reviewed PRs. - -Michael P. Mariani | `0000-0001-5852-0517 `__ | Mariani Systems LLC and University of Vermont - Contributed bug reports, documentation, reviewed PRs. - -Diogo Meyer | `0000-0002-7155-5674 `__ | University of São Paulo - Reviewed and tested PyPop, contributed some statistical analysis code. - -Mark P. Nelson | University of California, Berkeley - Co-designer of Python framework: implemented and maintained Python - modules, particularly the module for Hardy-Weinberg analysis. Updated - and maintained XSLT code. - -Richard M. Single | `0000-0001-6054-6505 `__ | University of Vermont - Author of haplotype frequency and linkage disequilibrium analysis - module ``emhaplofreq``. Contributed documentation and testing/reviewing PRs. - -Vanessa Sochat | `0000-0002-4387-3819 `__ | Lawrence Livermore National Laboratory - Contributed to the Python 3 port. - -Owen Solberg | `0000-0003-3060-9709 `__ - Implemented filter modules, including conversion to allele name - information to sequence data. - -Jurriaan H. Spaaks | `0000-0002-7064-4069 `__ | Netherlands eScience Center - Contributed to Zenodo upload GitHub action - -Glenys Thomson | `0000-0001-5235-4159 `__ | University of California, Berkeley - Principal investigator - -`Yingssu Tsai `__ | `0009-0006-0162-6066 `__ | University of California, Berkeley - Implemented prototype of the allele names to sequence conversion - filter module. - -Gordon Webster | `0009-0009-2862-0467 `__ | Amber Biology LLC - Contributed documentation and testing framework. - +.. list-table:: + :widths: 20 20 30 25 + :header-rows: 1 + :class: longtable + + * - Author + - ORCiD + - Affiliation + - Contribution + * - Karl Kornel + - `0000-0001-5847-5330 `__ + - Stanford Research Computing Center + - Contributed containerization + * - Alex Lancaster + - `0000-0002-0002-9263 `_ + - Amber Biology LLC, Ronin Institute + - Lead developer. Co-designer of Python framework: author of main + engine, text file parser, Python extension module framework + using SWIG, XML output and XSLT post-processing framework (to + generate plain text and HTML output). + * - Steven J. Mack + - `0000-0001-9820-9547 `__ + - University of California, San Francisco + - Contributed bug reports, documentation, reviewed PRs. + * - Michael P. Mariani + - `0000-0001-5852-0517 `__ + - Mariani Systems LLC and University of Vermont + - Contributed bug reports, documentation, reviewed PRs. + * - Diogo Meyer + - `0000-0002-7155-5674 `__ + - University of São Paulo + - Reviewed and tested PyPop, contributed some statistical analysis code. + * - Mark P. Nelson + - + - University of California, Berkeley + - Co-designer of Python framework: implemented and maintained + Python modules, particularly the module for Hardy-Weinberg + analysis. Updated and maintained XSLT code. + * - Richard M. Single + - `0000-0001-6054-6505 `__ + - University of Vermont + - Author of haplotype frequency and linkage disequilibrium + analysis module ``emhaplofreq``. Contributed documentation and + testing/reviewing PRs. + * - Vanessa Sochat + - `0000-0002-4387-3819 `__ + - Lawrence Livermore National Laboratory + - Contributed to the Python 3 port. + * - Owen Solberg + - `0000-0003-3060-9709 `__ + - + - Implemented filter modules, including conversion to allele name + information to sequence data. + * - Jurriaan H. Spaaks + - `0000-0002-7064-4069 `__ + - Netherlands eScience Center + - Contributed to Zenodo upload GitHub action + * - Glenys Thomson + - `0000-0001-5235-4159 `__ + - University of California, Berkeley + - Principal investigator + * - `Yingssu Tsai `__ + - `0009-0006-0162-6066 `__ + - University of California, Berkeley + - Implemented prototype of the allele names to sequence conversion + filter module. + * - Gordon Webster + - `0009-0009-2862-0467 `__ + - Amber Biology LLC + - Contributed documentation and testing framework. Third-party modules ------------------- diff --git a/NEWS.md b/NEWS.md index fbb445c6e..2d553b2c0 100644 --- a/NEWS.md +++ b/NEWS.md @@ -26,9 +26,9 @@ Single, Owen Solberg and Steve Mack. Sochat for major patch) - Added new asymmetric linkage disequilibrium (ALD) calculations - (thanks to Richard Single), see [^cite_thomson:single:2014] for more - details. Added in both the plain text (`.txt`) as well as the - `2-locus-summary.tsv` TSV file outputs. + (thanks to Richard Single), see [Thomson & Single, 2014](https://doi.org/10.1534/genetics.114.165266) + for more details. Added in both the plain text (`.txt`) as well as + the `2-locus-summary.tsv` TSV file outputs. - Improved tab-separated values (TSV) output file handling: diff --git a/website/docs/guide-chapter-changes.rst b/website/docs/guide-chapter-changes.rst index 5b83407df..5e1d4317a 100644 --- a/website/docs/guide-chapter-changes.rst +++ b/website/docs/guide-chapter-changes.rst @@ -8,11 +8,19 @@ Authors and history PyPop Release History ===================== - -.. include:: ../../NEWS.md - :parser: myst_parser.sphinx_ - :start-after: https://semver.org). +.. only:: html + .. include:: ../../NEWS.md + :parser: myst_parser.sphinx_ + :start-after: https://semver.org). +.. only:: latex or pdf + + .. include:: ../../NEWS.md + :parser: myst_parser.sphinx_ + :start-after: https://semver.org). + :end-before: [1.0.0]: https://github.com/alexlancaster/pypop/releases/tag/v1.0.0 +.. + the above `end-before` ensures that the links don't get passed into the PDF end, which clutters titles From 0c74d6531c90b9fff40126016fb72eabb101adb8 Mon Sep 17 00:00:00 2001 From: Alex Lancaster Date: Sun, 31 Dec 2023 18:43:15 -0500 Subject: [PATCH 07/13] missing a sphinx extension --- CONTRIBUTING.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 0d539bff8..d19baab7a 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -728,7 +728,7 @@ documentation locally. Here’s an overview of how to do that: .. code-block:: shell - pip install setuptools_scm sphinx piccolo-theme sphinx_rtd_theme myst_parser rst2pdf sphinx_togglebutton sphinx-argparse + pip install setuptools_scm sphinx piccolo-theme sphinx_rtd_theme myst_parser rst2pdf sphinx_togglebutton sphinx-argparse sphinx_copybutton 2. make a fork of pypop if you haven't already (see `previous section `_) From 69b922752fb9fd5865e625f3328c7013de101696 Mon Sep 17 00:00:00 2001 From: Alex Lancaster Date: Mon, 1 Jan 2024 13:07:57 -0500 Subject: [PATCH 08/13] update template to use NEWS.md --- .github/release-drafter.yml | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/.github/release-drafter.yml b/.github/release-drafter.yml index 518849f43..3aec7d101 100644 --- a/.github/release-drafter.yml +++ b/.github/release-drafter.yml @@ -44,11 +44,17 @@ template: | ``` pip install -U pypop-genomics ``` - - ## Changes - A full history of changes is available in [`NEWS.rst`](https://github.com/alexlancaster/pypop/blob/main/NEWS.rst). + + + ## $NEXT_PATCH_VERSION - YYYY-MM-DD $CHANGES + [$NEXT_PATCH_VERSION]: https://github.com/alexlancaster/pypop/releases/tag/v$NEXT_PATCH_VERSION + + + + A full history of changes is available in [`NEWS.md`](https://github.com/alexlancaster/pypop/blob/main/NEWS.md). + **Full Changelog:** https://github.com/alexlancaster/pypop/compare/$PREVIOUS_TAG...v$NEXT_PATCH_VERSION From c82b0424ec10151cfe978cd5ebf5a76e181b9bb0 Mon Sep 17 00:00:00 2001 From: Alex Lancaster Date: Mon, 1 Jan 2024 13:13:20 -0500 Subject: [PATCH 09/13] move links inline in NEWS.md --- .github/release-drafter.yml | 1 + NEWS.md | 7 +++++-- website/docs/guide-chapter-changes.rst | 2 +- 3 files changed, 7 insertions(+), 3 deletions(-) diff --git a/.github/release-drafter.yml b/.github/release-drafter.yml index 3aec7d101..bb85ee3d1 100644 --- a/.github/release-drafter.yml +++ b/.github/release-drafter.yml @@ -44,6 +44,7 @@ template: | ``` pip install -U pypop-genomics ``` + Repository: $REPOSITORY diff --git a/NEWS.md b/NEWS.md index 2d553b2c0..5361c9c50 100644 --- a/NEWS.md +++ b/NEWS.md @@ -137,6 +137,8 @@ Single, Owen Solberg and Steve Mack. - Only build wheels on platforms for which binary wheels are available for all dependencies. +[1.0.0]: https://github.com/alexlancaster/pypop/releases/tag/v1.0.0 + ## [0.7.0] - 2008-09-09 ### New features @@ -218,6 +220,8 @@ Single, Owen Solberg and Steve Mack. if only R dat files is enabled. If batchsize not set explicitly (and therefore 0) set batchsize to `1` is PHYLIP mode is enabled. +[0.7.0]: https://github.com/alexlancaster/pypop/releases/tag/PYPOP_SRC-0_7_0 + ## 0.6.0 - 2005-04-13 ### New features @@ -338,5 +342,4 @@ Single, Owen Solberg and Steve Mack. - Fixed bug in processing of `popname` field. Thanks to Richard Single for the report. -[1.0.0]: https://github.com/alexlancaster/pypop/releases/tag/v1.0.0 -[0.7.0]: https://github.com/alexlancaster/pypop/releases/tag/PYPOP_SRC-0_7_0 \ No newline at end of file + \ No newline at end of file diff --git a/website/docs/guide-chapter-changes.rst b/website/docs/guide-chapter-changes.rst index 5e1d4317a..488275cb6 100644 --- a/website/docs/guide-chapter-changes.rst +++ b/website/docs/guide-chapter-changes.rst @@ -20,7 +20,7 @@ PyPop Release History .. include:: ../../NEWS.md :parser: myst_parser.sphinx_ :start-after: https://semver.org). - :end-before: [1.0.0]: https://github.com/alexlancaster/pypop/releases/tag/v1.0.0 + :end-before: .. the above `end-before` ensures that the links don't get passed into the PDF end, which clutters titles From 7c85aec98e3618e3c95616bf57d80686bebb9a78 Mon Sep 17 00:00:00 2001 From: Alex Lancaster Date: Mon, 1 Jan 2024 13:19:09 -0500 Subject: [PATCH 10/13] update NEWS.md metadata --- NEWS.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/NEWS.md b/NEWS.md index 5361c9c50..e11d8fafe 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,6 +1,8 @@ -# Changelog +# NEWS -All notable changes to this project will be documented in this file. +All notable changes to this project (especially user-visible ones) +will be documented in this file. It mostly consists of the +concatenated release notes. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org). From 9fe34be0cd1ca93a424b8fe8aaaa6d80f1fe0238 Mon Sep 17 00:00:00 2001 From: Alex Lancaster Date: Tue, 2 Jan 2024 00:16:36 -0500 Subject: [PATCH 11/13] use endnotes for URLs in LaTeX backend update spacing for author table don't output footnotetext links for releases - rendering is off --- AUTHORS.rst | 7 ++++--- NEWS.md | 2 -- website/conf.py | 24 ++++++++++++++++++++++-- website/docs/guide-chapter-changes.rst | 18 +++--------------- website/docs/index.rst | 21 ++++++++++++++++++++- 5 files changed, 49 insertions(+), 23 deletions(-) diff --git a/AUTHORS.rst b/AUTHORS.rst index d86888a65..a3ed19a44 100644 --- a/AUTHORS.rst +++ b/AUTHORS.rst @@ -6,7 +6,7 @@ PyPop contributors (Listed in alphabetical order) .. list-table:: - :widths: 20 20 30 25 + :widths: 18 22 28 30 :header-rows: 1 :class: longtable @@ -15,12 +15,13 @@ PyPop contributors - Affiliation - Contribution * - Karl Kornel - - `0000-0001-5847-5330 `__ + - `0000-0001-5847-5330 `_ - Stanford Research Computing Center - Contributed containerization * - Alex Lancaster - `0000-0002-0002-9263 `_ - - Amber Biology LLC, Ronin Institute + - Amber Biology LLC, + Ronin Institute - Lead developer. Co-designer of Python framework: author of main engine, text file parser, Python extension module framework using SWIG, XML output and XSLT post-processing framework (to diff --git a/NEWS.md b/NEWS.md index e11d8fafe..7a9b0af39 100644 --- a/NEWS.md +++ b/NEWS.md @@ -343,5 +343,3 @@ Single, Owen Solberg and Steve Mack. - Fixed bug in processing of `popname` field. Thanks to Richard Single for the report. - - \ No newline at end of file diff --git a/website/conf.py b/website/conf.py index 1c20fec98..3c3a2844c 100644 --- a/website/conf.py +++ b/website/conf.py @@ -169,7 +169,8 @@ def __init__(self, **options): PygmentsBridge.latex_formatter = CustomLatexFormatter -latex_show_urls = 'inline' +#latex_show_urls = 'inline' +latex_show_urls = 'footnote' latex_elements = { # The paper size ('letterpaper' or 'a4paper'). @@ -187,7 +188,26 @@ def __init__(self, **options): 'preamble': r'''\DeclareRobustCommand{\and}{% \end{tabular}\kern-\tabcolsep\\\begin{tabular}[t]{c}% }% -\setcounter{secnumdepth}{1}%''', +\setcounter{secnumdepth}{1}% + +\usepackage{pagenote} +\makepagenote +\renewcommand*{\notesname}{End Notes} +% \renewcommand*{\notedivision}{\chapter*{\notesname}} + +\DeclareRobustCommand{\pagenotesubhead}[2]{% + \subparagraph*{\chaptername\ #1 #2}} + +\usepackage{environ}% http://ctan.org/pkg/environ + +\newcommand{\OverwriteEnviron}[1]{% + \expandafter\let\csname #1\endcsname\relax% + \expandafter\let\csname end#1\endcsname\relax% + \expandafter\let\csname env@#1@parse\endcsname\relax% + \expandafter\let\csname env@#1@save@env\endcsname\relax% + \expandafter\let\csname env@#1@process\endcsname\relax% + \NewEnviron{#1}% +}''', # Latex figure (float) alignment # diff --git a/website/docs/guide-chapter-changes.rst b/website/docs/guide-chapter-changes.rst index 488275cb6..74c66b556 100644 --- a/website/docs/guide-chapter-changes.rst +++ b/website/docs/guide-chapter-changes.rst @@ -9,18 +9,6 @@ Authors and history PyPop Release History ===================== -.. only:: html - - .. include:: ../../NEWS.md - :parser: myst_parser.sphinx_ - :start-after: https://semver.org). - -.. only:: latex or pdf - - .. include:: ../../NEWS.md - :parser: myst_parser.sphinx_ - :start-after: https://semver.org). - :end-before: - -.. - the above `end-before` ensures that the links don't get passed into the PDF end, which clutters titles +.. include:: ../../NEWS.md + :parser: myst_parser.sphinx_ + :start-after: https://semver.org). diff --git a/website/docs/index.rst b/website/docs/index.rst index dbaa7de63..e0c9a40bf 100644 --- a/website/docs/index.rst +++ b/website/docs/index.rst @@ -15,6 +15,14 @@ PyPop User Guide .. only:: latex or pdf + .. raw:: latex + + % Place contents of footnote in a \pagenote + \OverwriteEnviron{footnote}[4]{\pagenote{\BODY}} + % FIXME: disable footnotetext, don't play nice with pagenote + \OverwriteEnviron{footnotetext}[4]{\relax} + \renewcommand{\sphinxfootnotemark}[4]{\relax} + .. include:: ../index.rst :start-after: guide-preface-1-start: :end-before: guide-preface-1-end: @@ -72,8 +80,19 @@ This guide to PyPop contains four main parts: guide-chapter-contributing guide-chapter-changes licenses - biblio +.. raw:: latex + + \begingroup + \footnotesize + \linespread{0.5} %regulate line spacing + \printnotes + \vfill + \endgroup + +.. toctree:: + + biblio .. |br| raw:: html From 76df436c6798be2ff9b5481ad365958d767df411 Mon Sep 17 00:00:00 2001 From: Alex Lancaster Date: Tue, 2 Jan 2024 00:50:00 -0500 Subject: [PATCH 12/13] update with new workflow for modifying NEWS * NEWS.rst -> NEWS.md throughout --- CONTRIBUTING.rst | 67 +++++++++++++++++++++++++---------------------- website/index.rst | 4 +-- 2 files changed, 38 insertions(+), 33 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index d19baab7a..2c454d49b 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -144,9 +144,10 @@ steps are: 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`` +6. updating ``AUTHORS.rst`` 7. checking unit tests pass -8. making a pull request +8. making a pull request (including a description of your changes + suitable for inclusion in ``NEWS.md``) Fork this repository @@ -232,29 +233,13 @@ You can push to your fork now if you wish: 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) +Update ``AUTHORS.rst`` +---------------------- - New features - ^^^^^^^^^^^^ - - * here goes my new additions - * explain them shortly and well - -Also add your name to the authors list at :code:`AUTHORS.rst`, so you +Also add your name to the author table at :code:`AUTHORS.rst`, so you will also be included in the periodic Zenodo software releases (see -also the section on `Crediting contributors`_) +also the section on `Crediting contributors`_). + Run unit tests with ``pytest`` ------------------------------ @@ -309,10 +294,29 @@ 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. +Once you are finished, create a pull request to the main repository +and engage with the developers. + +When you create the pull request in the initial submission box, you +should create a description of your changes with an explanatory bullet +list of the contributions. Please note if any of your changes will +break existing behaviour or anything else that would be important for +an end-user to know. This description should be in Markdown format. +Here is an example: + +.. code-block:: markdown + + ### New features + + - here goes my new additions, explain them shortly and well + - this feature will require an an update to your `.ini` file + +This will be used to populate the Release Notes and eventually be +included in the :code:`NEWS.md` file. + +If you need some code review or feedback while you're developing the +code, you can also make a pull request, even if you're not fully +finished. **However, before submitting a Pull Request, verify your development branch passes all tests as** `described above `_ **. If you are @@ -325,7 +329,8 @@ 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. +4. In the submission for the PR, include a description of the changes, + in markdown format, suitable for eventual inclusion in ``NEWS.md``. 5. Add yourself to ``website/docs/AUTHORS.rst``. @@ -651,7 +656,7 @@ outside ``website`` like ``README.rst`` and ``CONTRIBUTING.rst``: - ``guide-chapter-instructions.rst`` - ``guide-chapter-contributing.rst`` (pulls in top-level ``CONTRIBUTING.rst`` that contains the source of the text that you are reading right now) - - ``guide-chapter-changes.rst`` (pulls in top-level ``NEWS.rst`` and ``AUTHORS.rst``, which is local to ``website``) + - ``guide-chapter-changes.rst`` (pulls in top-level ``NEWS.md`` and ``AUTHORS.rst``, which is local to ``website``) - ``AUTHORS.rst`` - ``licenses.rst`` (pulls in top-level ``LICENSE``) - ``biblio.rst`` @@ -786,7 +791,7 @@ We define *contributions* in a broad way: including both writing code as well as documentation, and reviewing issues and PRs etc. Here are some ways we credit contributors: -``AUTHORS.rst``, ``NEWS.rst`` and GitHub Release Notes +``AUTHORS.rst``, ``NEWS.md`` and GitHub Release Notes ------------------------------------------------------ Anyone who has contributed a pull request to the project is welcome to @@ -795,7 +800,7 @@ part of the repository and included with with distributions. Every time we make a release, everyone who has made a commit to the repository since the previous release will be mentioned in either the -``NEWS.rst`` or in the GitHub Release Notes. +``NEWS.md`` or in the GitHub Release Notes. Authorship on Zenodo archives of releases ----------------------------------------- diff --git a/website/index.rst b/website/index.rst index 535091f7d..765d5ac58 100644 --- a/website/index.rst +++ b/website/index.rst @@ -37,8 +37,8 @@ large-scale population genetic analyses including: - Unit tests, new documentation system, continuous integration framework and PyPI package - and even more minor features and bug fixes... (see - `NEWS.rst - `__). + `NEWS.md + `__). * Recent previous releases: .. toggle:: From f84b0587d2f1f1c434b4953e7bf02ddb4ce172f7 Mon Sep 17 00:00:00 2001 From: Alex Lancaster Date: Tue, 2 Jan 2024 03:09:28 -0500 Subject: [PATCH 13/13] make endnotes even smaller --- website/docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/index.rst b/website/docs/index.rst index e0c9a40bf..3827e920b 100644 --- a/website/docs/index.rst +++ b/website/docs/index.rst @@ -84,7 +84,7 @@ This guide to PyPop contains four main parts: .. raw:: latex \begingroup - \footnotesize + \scriptsize \linespread{0.5} %regulate line spacing \printnotes \vfill