Merge pull request #152 from smithlabcode/release-140-prep

Release 140 prep

MAINTAINERS.md

@@ -1,72 +1,72 @@
-## Docker images
-
-The docker images for `dnmtools` are hosted in GitHub Container registry.  The
-process of building and pushing the image to the registry is handled by the
-workflow specified in
-[docker-build.yml](https://github.com/smithlabcode/dnmtools/blob/master/.github/workflows/docker-build.yml).
-The build instruction is in
-[Dockerfile](https://github.com/smithlabcode/dnmtools/blob/master/Dockerfile).
-You can see the published images
-[here](https://github.com/smithlabcode/dnmtools/pkgs/container/dnmtools).
-
-The workflow is triggered either manually or automatically by a tag event of
-type `v*.*.*`, which is intended for new releases. Currently, publishing the
-images can happen only to commits tagged by a version number. This is intended
-to associate every docker image with a version number. This means that there is
-no option to push the image for the latest commit if it is not tagged by
-a version number.
-
-### Automatic build and publish in a tag event
-
-In a tag event of type `v*.*.*`, such as new release or retagging of versoin
-number, this work flow is triggered to build and publish the image for the
-tagged version number. The published image is tagged with SHA hash and the
-version number.  It is also taged with `latest` if the version number is the
-latest.
-
-### Manual build (and publish)
-
-Manual trigger is intedned to test the image build processes as well as publish
-an image for an existing version.  In
-[Actions](https://github.com/smithlabcode/dnmtools/actions), go to `Docker image
-build` under `All workflows` and click `Run workflow` and choose from the
-following options:
-
-1. `Build latest commit`: for testing for the latest commit
-2. `Build existing version`: for testing a particular version
-3. `Build + push existing version`: for publishing a particular version  
-
-For options 2 and 3, specify the version number in the form `v*.*.*`. If not
-specified, the workflow will assume the latest verion.
-
-### Use scenarios 
-
-**Before a new release**: It is a good idea to test image building before a new
-release. Manually trigger the workflow with opiton 1. If it builds with no
-issues, make a new release and the image will automatically be built and
-published. 
-
-**Publish an existing version**: It is possible to publish a docker image for an
-existing version by option 3 in the manual trigger. First, test build using
-option 2, and then publish using option 3.  The published image is tagged with
-SHA hash and the version number.  It is also taged with `latest` if the version
-number is the latest. If option 3 is deployed with a version number for which
-a docker image already exists, it will simply rebuild and update the existing
-image.
-
-**Deleting an image**: If you have owner access to `smithlabcode`, you can
-delete an image by going
-[here](https://github.com/smithlabcode/dnmtools/pkgs/container/dnmtools/versions)
-and manually delete a version.
-
-
-
-## Installation
-The image can be pulled by one of the following commands.
-
-```bash
-docker pull ghcr.io/smithlabcode/dnmtools:latest
-docker pull ghcr.io/smithlabcode/dnmtools:[7-DIGIT SHA]
-docker pull ghcr.io/smithlabcode/dnmtools:v[VERSION NUMBER] #(e.g. v1.3.0)
-```
-
+## Docker images
+
+The docker images for `dnmtools` are hosted in GitHub Container registry.  The
+process of building and pushing the image to the registry is handled by the
+workflow specified in
+[docker-build.yml](https://github.com/smithlabcode/dnmtools/blob/master/.github/workflows/docker-build.yml).
+The build instruction is in
+[Dockerfile](https://github.com/smithlabcode/dnmtools/blob/master/Dockerfile).
+You can see the published images
+[here](https://github.com/smithlabcode/dnmtools/pkgs/container/dnmtools).
+
+The workflow is triggered either manually or automatically by a tag event of
+type `v*.*.*`, which is intended for new releases. Currently, publishing the
+images can happen only to commits tagged by a version number. This is intended
+to associate every docker image with a version number. This means that there is
+no option to push the image for the latest commit if it is not tagged by
+a version number.
+
+### Automatic build and publish in a tag event
+
+In a tag event of type `v*.*.*`, such as new release or retagging of versoin
+number, this work flow is triggered to build and publish the image for the
+tagged version number. The published image is tagged with SHA hash and the
+version number.  It is also taged with `latest` if the version number is the
+latest.
+
+### Manual build (and publish)
+
+Manual trigger is intedned to test the image build processes as well as publish
+an image for an existing version.  In
+[Actions](https://github.com/smithlabcode/dnmtools/actions), go to `Docker image
+build` under `All workflows` and click `Run workflow` and choose from the
+following options:
+
+1. `Build latest commit`: for testing for the latest commit
+2. `Build existing version`: for testing a particular version
+3. `Build + push existing version`: for publishing a particular version  
+
+For options 2 and 3, specify the version number in the form `v*.*.*`. If not
+specified, the workflow will assume the latest verion.
+
+### Use scenarios 
+
+**Before a new release**: It is a good idea to test image building before a new
+release. Manually trigger the workflow with opiton 1. If it builds with no
+issues, make a new release and the image will automatically be built and
+published. 
+
+**Publish an existing version**: It is possible to publish a docker image for an
+existing version by option 3 in the manual trigger. First, test build using
+option 2, and then publish using option 3.  The published image is tagged with
+SHA hash and the version number.  It is also taged with `latest` if the version
+number is the latest. If option 3 is deployed with a version number for which
+a docker image already exists, it will simply rebuild and update the existing
+image.
+
+**Deleting an image**: If you have owner access to `smithlabcode`, you can
+delete an image by going
+[here](https://github.com/smithlabcode/dnmtools/pkgs/container/dnmtools/versions)
+and manually delete a version.
+
+
+
+## Installation
+The image can be pulled by one of the following commands.
+
+```bash
+docker pull ghcr.io/smithlabcode/dnmtools:latest
+docker pull ghcr.io/smithlabcode/dnmtools:[7-DIGIT SHA]
+docker pull ghcr.io/smithlabcode/dnmtools:v[VERSION NUMBER] #(e.g. v1.4.0)
+```
+

README.md

@@ -12,7 +12,7 @@ sequencing (RRBS). These tools focus on overcoming the computing
 challenges imposed by the scale of genome-wide DNA methylation data,
 which is usually the early parts of data analysis.
 
-## Installing release 1.3.0
+## Installing release 1.4.0
 
 The documentation for DNMTools can be found
 [here](https://dnmtools.readthedocs.io). But if you want to install
@@ -41,14 +41,14 @@ repo, it is easiest if all dependencies are available through conda.
 
 ### Configuration
 
-* Download [dnmtools-1.3.0.tar.gz](https://github.com/smithlabcode/dnmtools/releases/download/v1.3.0/dnmtools-1.3.0.tar.gz).
+* Download [dnmtools-1.4.0.tar.gz](https://github.com/smithlabcode/dnmtools/releases/download/v1.4.0/dnmtools-1.4.0.tar.gz).
 * Unpack the archive:
 ```console
-tar -zxvf dnmtools-1.3.0.tar.gz
+tar -zxvf dnmtools-1.4.0.tar.gz
 ```
 * Move into the dnmtools directory and create a build directory:
 ```console
-cd dnmtools-1.3.0 && mkdir build && cd build
+cd dnmtools-1.4.0 && mkdir build && cd build
 ```
 * Run the configuration script:
 ```console
@@ -137,7 +137,7 @@ docker tag ghcr.io/smithlabcode/dnmtools:latest dnmtools:latest
 
 You can also install the image for a particular vertion by running
 ```console
-docker pull ghcr.io/smithlabcode/dnmtools:v[VERSION NUMBER] #(e.g. v1.3.0)
+docker pull ghcr.io/smithlabcode/dnmtools:v[VERSION NUMBER] #(e.g. v1.4.0)
 ```
 Not all versions have corresponding images; you can find available images
 [here](https://github.com/smithlabcode/dnmtools/pkgs/container/dnmtools).

configure.ac

@@ -14,7 +14,7 @@ dnl but WITHOUT ANY WARRANTY; without even the implied warranty of
 dnl MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 dnl General Public License for more details.
 
-AC_INIT([dnmtools], [1.3.0], [andrewds@usc.edu],
+AC_INIT([dnmtools], [1.4.0], [andrewds@usc.edu],
         [dnmtools], [https://github.com/smithlabcode/dnmtools])
 dnl the config.h is #included in the sources for version info
 AC_CONFIG_HEADERS([config.h])

data/md5sum.txt

@@ -6,9 +6,7 @@ ae05a28de5643a512386e767b3aa963a  tests/araTha1_simulated.hypermr
 961b0671a349e2ad8041e0807393bf78  tests/reads.counts.select
 af22e5468fd6614c611646cbc675542f  tests/reads.counts.sym
 b38d571baaf2bc16646dbd14a7edb770  tests/reads.epiread
-6abb0e3e6571e221ec6f91ba52a358ea  tests/reads.fmt.sam
 8edab98b1be4411820e2f130aa6ba6b9  tests/reads.fmt.srt.sam
-3e57d7bde5f7be88b56cd92bbfc935ce  tests/reads.fmt.srt.uniq.sam
 af8b97ef25af8a16ced1537ca4a74d07  tests/reads.hmr
 52d44c4c1d6891b45741f573f51e67cd  tests/reads.levels
 916fe07a1d03449b65dfc1458d7c1c40  tests/reads.mstats
@@ -20,3 +18,5 @@ e7e9590475a7f9b1ae41701d81892e57  tests/two_epialleles.amr
 ec6a686617cad31e9f7a37a3d378e6ed  tests/two_epialleles.states
 93e38b20d162062a5d147c4290095a13  tests/mlml.out
 d947fe3d61ef7b1564558a69608f0e64  tests/methylome.pmd
+04c007d96bcaf975bdb09afc46216f72  tests/reads.fmt.sam
+03057e8c736ff1f07f7fb6e7f20d0cf3  tests/reads.fmt.srt.uniq.sam

docs/content/bsrate.md

@@ -171,7 +171,12 @@ This option will generate a histogram of conversion rate per read,
 printed to the terminal. This option is correct as of v1.4.0.
 
 ```txt
- -p, -per-read
+ -b, -bins
 ```
 Assming the `-p` option is used, this option determines the number of
 bins in the histogram. This option is correct as of v1.4.0.
+
+```txt
+ -S, -summary
+```
+Write a summary of information gathered during the run to this file.

docs/content/cleanhp.md

@@ -16,7 +16,7 @@ output filename prefix [required]
 ```txt
  -s, -stat
 ```
- stats output filename [required]
+stats output filename [required]
 ```txt
  -h, -hairpin
 ```
@@ -28,17 +28,20 @@ check for hairpin contamination
 ```txt
  -n, -nreads
 ```
- number of reads in initial check
+number of reads in initial check
 ```txt
  -c, -cutoff
 ```
- cutoff for calling an inverse duplication(default: 0.95)
+cutoff for calling an inverse duplication(default: 0.95)
 ```txt
  -i, -ignore
 ```
 length of read name suffix to ignore when matching
 ```txt
  -v, -verbose
 ```
-print more run info to STDERR while the program is running
-
+print more run info to the terminal while the program is running
+```txt
+ -h, -hist
+```
+write a histogram of hairpin matches to this file

docs/content/counts.md

@@ -171,3 +171,8 @@ merge data as symmetric CpGs.
 -v, -verbose
 ```
 Report more information while the program is running.
+
+```txt
+-progress
+```
+Show progress while the program is running.

docs/content/hmr.md

@@ -174,5 +174,5 @@ testing (default: 408).
 ```txt
  -S, -summary
 ```
-Write the analysis summary to this file. The summary is not
-reported unless a file is specified here. This option is correct as of v1.4.0.
+Write the analysis summary to this file. The summary is not reported
+unless a file is specified here. This option is correct as of v1.4.0.

docs/content/pmd.md

@@ -190,6 +190,5 @@ Specify a random seed value.
 ```txt
  -S, -summary
 ```
-Write the analysis summary to this file. The summary is not
-reported unless a file is specified here. This option is correct as of v1.4.0.
-
+Write the analysis summary to this file. The summary is not reported
+unless a file is specified here. This option is correct as of v1.4.0.

docs/content/quickstart.md

@@ -3,9 +3,19 @@ Installation
 
 ## Installation via conda
 
-Right now this is probably the easiest way. Dnmtools is among the
-bioconda recipes. If you know how to use conda and are setup to use
-bioconda, then you might simply be able to do:
+*Note (9/26/2023)* Although conda currently works, it seems that using
+`mamba` is more reliable. If you have `conda` installed, you can
+install mamba very easily by following instructions here:
+
+https://anaconda.org/conda-forge/mamba
+
+In the instructions below, replacing `conda` with `mamba` should work
+the same (and, in some cases, more reliably), but with mamba.
+
+Right now conda is probably the easiest way to install
+dnmtools. Dnmtools is among the bioconda recipes. If you know how to
+use conda and are setup to use bioconda, then you might simply be able
+to do:
 ```console
 $ conda install dnmtools
 ```
@@ -25,7 +35,6 @@ recommended by bioconda.
 * Bioconda: additional helpful setup instructions can be found
   [here](https://bioconda.github.io).
 
-
 If you encounter further problems, try creating a new environment for
 dnmtools within conda:
 ```console
@@ -42,32 +51,35 @@ would need to be activated when you want to use dnmtools.
 ### Required libraries
 
 * A recent compiler: most users will be building and installing this
-  software with GCC. We require a compiler that fully supports C++11,
-  so we recommend using at least GCC 5.8. There are still many systems
-  that install a very old version of GCC by default, so if you have
-  problems with building this software, that might be the first thing
-  to check.
+  software with GCC. We require a compiler that fully supports C++17,
+  so we recommend using at least GCC 8 (released in 2018). There are
+  still many systems that install a very old version of GCC by
+  default, so if you have problems with building this software, that
+  might be the first thing to check. On macOS and Ubuntu/Debian
+  systems, the brew and apt package managers can get you a recent
+  compiler easily. Any cluster or high-performance computing
+  environment should give you access to a recent compiler.
 * The GNU Scientific Library: this has always been required. It can be
   installed using apt on Linux (Ubuntu, Debian), using brew on macOS,
   or from source available [here](http://www.gnu.org/software/gsl).
+* The HTSlib library, which can be installed through brew on macOS,
+  through apt on Linux (Ubuntu, Debian), or from source downloadable
+  [here](https://github.com/samtools/htslib).
 * The Zlib compression library: Most likely you already have this
   installed on your system. If not, it can be installed using apt on
   Linux (Ubuntu, Debian) through the package `zlib1g-dev`. On macOS,
   Zlib can be installed with brew.
-* The HTSlib library, which can be installed through brew on macOS,
-  through apt on Linux (Ubuntu, Debian), or from source downloadable
-  [here](https://github.com/samtools/htslib).
 
 ### Configuration
 
-* Download [dnmtools-1.3.0.tar.gz](https://github.com/smithlabcode/dnmtools/releases/download/v1.3.0/dnmtools-1.3.0.tar.gz).
+* Download [dnmtools-1.4.0.tar.gz](https://github.com/smithlabcode/dnmtools/releases/download/v1.4.0/dnmtools-1.4.0.tar.gz).
 * Unpack the archive:
 ```console
-$ tar -zxvf dnmtools-1.3.0.tar.gz
+$ tar -zxvf dnmtools-1.4.0.tar.gz
 ```
 * Move into the dnmtools directory and create a build directory:
 ```console
-$ cd dnmtools-1.3.0
+$ cd dnmtools-1.4.0
 $ mkdir build && cd build
 ```
 * Run the configuration script:
@@ -109,16 +121,23 @@ any arguments and you should see the list of available commands:
 ```console
 $ dnmtools
 ```
+If you want to do more extensive tests, you can run:
+```console
+$ make check
+```
+from the directory where you run `make`. This will to several tests of
+various commands within `dnmtools`, and might take some time.
 
 ## Using a clone of the repo
 
-Not recommended, but if you want to do it this way, we assume you know
-what you are doing. We strongly recommend using dnmtools through the
-latest stable release under the releases section on GitHub. Developers
-who wish to work on the latest commits, which are unstable, can
-compile the source using the `Makefile` available in the root of the
-source tree. If HTSLib and other libraries are available system-wide,
-compile by running:
+*This option is deprecated; we are no longer maintaining a Makefile
+that is not generated by `./configure`.* Not recommended, but if you
+want to do it this way, we assume you know what you are doing. We
+strongly recommend using dnmtools through the latest stable release
+under the releases section on GitHub. Developers who wish to work on
+the latest commits, which are unstable, can compile the source using
+the `Makefile` available in the root of the source tree. If HTSLib and
+other libraries are available system-wide, compile by running:
 ```console
 $ make
 ```