Documentation fixes (#182)

* Fixed broken links in online documentation
Fixes #169

Author: espenhgn

CHANGELOG.md

@@ -7,11 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Note that CoMorMent containers are organized using several GitHub repositories:
 
-* <https://github.com/comorment/containers> - .sif files, public reference data, documentation, common scripts
-* <https://github.com/comorment/reference> - private reference data with access restricted to CoMorMent collaborator
+* [https://github.com/comorment/containers](https://github.com/comorment/containers) - .sif files, public reference data, documentation, common scripts
+* [https://github.com/comorment/reference](https://github.com/comorment/reference) - private reference data with access restricted to CoMorMent collaborator
 
 All of the above repositories are covered by this CHANGELOG. They will have the same version tags on github.
-In addition, we have repositories containing specific tools, e.g. <https://github.com/comorment/HDL>,
+In addition, we have repositories containing specific tools, e.g. [https://github.com/comorment/HDL](https://github.com/comorment/HDL),
 which will be covered by their own CHANGELOG.md file.
 
 To identify the version of a .sif file, run ``md5sum <container>.sif`` command and find the MD5 checksum in the list below.
@@ -35,10 +35,16 @@ If MD5 sum is not listed for a certain release then it means that the container
 
 * Removals goes here
 
-### Misc.
+### Misc
 
 * Miscellaneous goes here
 
+## [1.3.2] - 2023-06-12
+
+### Fixed
+
+* Fixed misc. issues with cross references in online documentation
+
 ## [1.3.1] - 2023-06-07
 
 ### Added
@@ -47,7 +53,7 @@ If MD5 sum is not listed for a certain release then it means that the container
 
 ### Fixed
 
-* Fixed issue with character encoding in sumstats files, in case chromosome column name is uppercase. 
+* Fixed issue with character encoding in sumstats files, in case chromosome column name is uppercase.
 
 ## [1.3.0] - 2023-05-19
 
@@ -66,18 +72,21 @@ If MD5 sum is not listed for a certain release then it means that the container
 * Added ``RELEASES.md`` file explaining steps needed to make releases.
 * Added ``PRSice_linux`` to ``r.sif``
 * Added tests for ``gwas.py``
-* Added package ``GWASTools`` to ``r.sif``. 
+* Added package ``GWASTools`` to ``r.sif``.
 * Added confidence intervals to qq plots created by ``gwas.py`` using ``GWASTools`` R package.
-* Added status badges and citation.cff file 
+* Added status badges and citation.cff file
 
 ### Updated
 
 * Updated file and folder layout, fixing minor documentation issues. Moving from ``m2r2`` to ``Myst-parser`` for Sphinx-generated online docs.
 * Rebuilt the R container
+
 * ````
   1d435af6003bbca95ef8cc062bf666fc  singularity/r.sif
   ```
+
 * Rebuilt the R container
+
   ```
   23d195a10b84603b15d0e8c42df40fbd  singularity/r.sif
   ```
@@ -102,7 +111,7 @@ If MD5 sum is not listed for a certain release then it means that the container
 
 ## [1.1] - 2022-12-01
 
-Maintenance/feature release with the following main software incorporated into each container: 
+Maintenance/feature release with the following main software incorporated into each container:
 
   | container         | OS/tool             | version                                   | license
   | ----------------- | ------------------- | ----------------------------------------- | -------------
@@ -151,24 +160,25 @@ Maintenance/feature release with the following main software incorporated into e
 Main changes since release version [1.0.0](https://github.com/comorment/containers/releases/tag/v1.0.0):
 
 ### Added
+
 * add option to append ``usecases/LDpred2/ldpred.R`` score output to an existing file
 * add script ``usecases/LDpred2/complementSumstats.R`` to append chromosome and position to summary statistics
 * add polygenic score output tests for ``usecases/LDpred2/ldpred.R``
 * add ``usecases/LDpred2/imputeGenotypes.R`` for imputing genotypes using R-package bigSNPR
 * add ``usecases/LDpred2/calculateLD.R`` for calculation LD using R-package bigSNPR.
-* add autobuilt online documentation from repository sources at https://comorment-containers.readthedocs.io/en/latest/
+* add autobuilt online documentation from repository sources at <https://comorment-containers.readthedocs.io/en/latest/>
 * add R libraries for LDpred2 analysis to `r.sif` + corresponding example.
 * add tests for ``metal`` and ``qctool`` in ``gwas.sif`` build
-* add basic GitHub actions from https://github.com/precimed/container_template.git
+* add basic GitHub actions from <https://github.com/precimed/container_template.git>
 * add ``FaST-LMM`` (version 0.6.3) to future ``python3.sif``, and corresponding test
 * add ``shapeit4.2`` binary (shapeit4 v.4.2.2) and HTSlib (1.11) to future ``gwas.sif`` builds, and corresponding test
 * added additional tests for software in ``gwas.sif``, ``python3.sif`` builds
-* add versions identifiers for all explicitly installed software across ``hello.sif``, ``gwas.sif``, ``python3.sif``, ``r.sif``, listed in [docker/README.md](https://github.com/comorment/containers/docker/README.md)
+* add versions identifiers for all explicitly installed software across ``hello.sif``, ``gwas.sif``, ``python3.sif``, ``r.sif``, listed in [docker/README.md](./docker/README.md)
 * replaced Ubuntu 18.04 with 20.04 (LTS) as base image for ``hello.sif``, ``gwas.sif``, ``python3.sif``
-* replaced ``src/scripts/install_miniconda3.sh`` by ``scr/scripts/install_mambaforge.sh`` which is now used in future  ``python3.sif`` builds 
+* replaced ``src/scripts/install_miniconda3.sh`` by ``scr/scripts/install_mambaforge.sh`` which is now used in future  ``python3.sif`` builds
 * add tests for bgenix and Minimac4 software in ``gwas.sif``, removing build-time dependencies for these from container
 * add basic test that KING software runs in ``gwas.sif``
-* add Dockerfiles and install scripts for `gwas.sif`, `hello.sif`, `python3.sif`, `r.sif`, `saige.sif` from [gwas](https://github.com/comorment/gwas). 
+* add Dockerfiles and install scripts for `gwas.sif`, `hello.sif`, `python3.sif`, `r.sif`, `saige.sif` from [gwas](https://github.com/comorment/gwas).
 * add CHANGELOG.md (this file)
 * add ``gwas.py --analysis saige`` option, allowing to run SAIGE analysis
 * add ``gwas.py --analysis figures`` option, using R qqman for QQ and manhattan plots
@@ -183,6 +193,7 @@ Main changes since release version [1.0.0](https://github.com/comorment/containe
 ### Updated
 
 * rebuilt the following containers following version pinning in Dockerfiles, install scripts, etc. (see above additions):
+
   ```
   bb7a8e0b977e29e03067d75d19803913  singularity/gwas.sif
   11ac9e8fe69df07d650bd5e1e7cdeee5  singularity/hello.sif
@@ -208,13 +219,13 @@ Main changes since release version [1.0.0](https://github.com/comorment/containe
 * ``gwas.py --analysis loci manh qq`` options as removed (fix #22)
 * ``--bed-fit``, ``--bed-test``, ``--bgen-fit``, ``--bgen-test`` options of ``gwas.py`` are removed; use new options ``--geno-fit-file`` and ``--geno-file`` instead
 * remove ``regenie.sif`` and ``regenie3.sif``, because regenie software is also included in ``gwas.sif``
-* remove MiXeR package from ``python3.sif`` container, because MiXeR is now available as a separate container (<https://github.com/comorment/mixer>). This is also where you will find MiXeR's use-cases.
-* MAGMA, LAVA and ldblock software is moved to https://github.com/comorment/magma.
+* remove MiXeR package from ``python3.sif`` container, because MiXeR is now available as a separate container ([https://github.com/comorment/mixer](https://github.com/comorment/mixer)). This is also where you will find MiXeR's use-cases.
+* MAGMA, LAVA and ldblock software is moved to <https://github.com/comorment/magma>.
   MAGMA reference files are also moved to this repository.
-* enigma-cnv.sif and enigma-cnv.sif is moved to https://github.com/comorment/iPsychCNV
-  enigma-cnv.sif is also available here: in https://github.com/ENIGMA-git/ENIGMA-CNV/tree/main/CNVCalling/containers
-* tryggve_query.sif  is moved to https://github.com/comorment/Tryggve_psych
-* ``matlabruntime.sif`` container is moved to https://github.com/comorment/matlabruntime.
+* enigma-cnv.sif and enigma-cnv.sif is moved to <https://github.com/comorment/iPsychCNV>
+  enigma-cnv.sif is also available here: in <https://github.com/ENIGMA-git/ENIGMA-CNV/tree/main/CNVCalling/containers>
+* tryggve_query.sif  is moved to <https://github.com/comorment/Tryggve_psych>
+* ``matlabruntime.sif`` container is moved to <https://github.com/comorment/matlabruntime>.
   pleioFDR reference files are also moved to this repository.
 
 ## [1.0.0] - 2020-10-20

CONTRIBUTING.md

@@ -100,7 +100,7 @@ When you're ready to contribute code to address an open issue, please follow the
     Our continuous integration (CI) testing runs [a number of checks](https://github.com/comorment/containers/actions) for each pull request on [GitHub Actions](https://github.com/features/actions). 
     You can run most of these tests locally, which is something you should do *before* opening a PR to help speed up the review process and make it easier for us.
 
-    And finally, please update the [CHANGELOG](https://github.com/comorment/containers/blob/main/CHANGELOG.md) with notes on your contribution in the "Unreleased" section at the top.
+    And finally, please update the [CHANGELOG](./CHANGELOG.md) with notes on your contribution in the "Unreleased" section at the top.
 
     After all of the above checks have passed, you can now open [a new GitHub pull request](https://github.com/comorment/containers/pulls).
     Make sure you have a clear description of the problem and the solution, and include a link to relevant issues.

README.md

@@ -4,15 +4,15 @@ The goal of the [CoMorMent](https://www.comorment.uio.no) containers repository
 
 Most of these tools are packaged into singularity containers (<https://sylabs.io/singularity/>) and shared in the [singularity](https://github.com/comorment/containers/tree/main/singularity) folder of this repository. You can download individual containers using github's ``Download`` button, or clone the entire repository from command line as described in the [Getting started](#getting-started) section below.
 
-Most of the tools require additional [reference](reference) data, provided in the [reference](https://github.com/comorment/containers/tree/main/reference) folder of this repository.
+Many of the tools require additional reference data provided in the [reference](https://github.com/comorment/containers/tree/main/reference) folder of this repository.
 Certain reference data can not be made publicly available, in which case we provide access instructions in a separate GitHub repository:
 <https://github.com/comorment/reference>. This repository is private - please approach your contact within CoMorMent project to enable your access.
 
-Description of containers and usage instructions are provided in the [docs](docs) folder.
+Description of containers and usage instructions are provided in the [docs](https://github.com/comorment/containers/tree/main/docs) folder.
 
-More extensive use cases of containers, focusing on real data analysis, are provided in the [usecases](usecases) folder.
+More extensive use cases of containers, focusing on real data analysis, are provided in the [usecases](https://github.com/comorment/containers/tree/main/usecases) folder.
 
-The history of changes is available in the [CHANGELOG.md](https://github.com/comorment/containers/blob/main/CHANGELOG.md) file.
+The history of changes is available in the [CHANGELOG.md](./CHANGELOG.md) file.
 
 Additional tools are available in separate repositories:
 
@@ -21,7 +21,7 @@ Additional tools are available in separate repositories:
 * <https://github.com/comorment/popcorn> - cross-ancestry genetic correlations
 * <https://github.com/comorment/magma> - MAGMA, LAVA, lava-partitioning tools
 * <https://github.com/comorment/HDL> - High-Definition Likelihood
-* <https://github.com/comorment/ldpred2_ref> - reference files for LDpred2. The tool itself is included in ``r.sif`` ([more info](scripts/pgs)).
+* <https://github.com/comorment/ldpred2_ref> - reference files for LDpred2. The tool itself is included in ``r.sif`` ([more info](https://github.com/comorment/containers/tree/main/scripts/pgs)).
 
 ## Project status
 
@@ -71,8 +71,8 @@ export COMORMENT=/cluster/projects/p33/github/comorment
 export COMORMENT=/ess/p697/data/durable/s3-api/github/comorment
 ```
 
-Once you have a clone of this repository on your system, you may proceed with [docs/singularity/hello.md](docs/singularity/hello.md) example.
-Take a look at other README files in the [docs/singularity](docs/singularity) folder, as well as detailed use cases in [usecases](usecases).
+Once you have a clone of this repository on your system, you may proceed with [docs/singularity/hello.md](./docs/singularity/hello.md) example.
+Take a look at the [README](./docs/singularity/README.md) file in the [docs/singularity](https://github.com/comorment/containers/tree/main/docs/singularity) folder, as well as detailed use cases in [usecases](https://github.com/comorment/containers/tree/main/usecases).
 
 To simplify instructions throughout this repository we use certain variables (it's a good idea to include them in your ``.bashrc`` or similar):
 
@@ -90,7 +90,7 @@ Earlier version (prior to April 2021) of all containers and refrence data was di
 ## Source files
 
 The source files for configuring and building the container files provided here are found in the [docker](https://github.com/comorment/containers/tree/main/docker) directory.
-See the corresponding [README](docker) file therein for details.
+See the corresponding [README](./docker/README.md) file therein for details.
 
 ## Online documentation
 

docker/README.md

@@ -8,11 +8,11 @@ For new users we recommend to go over introductory instructions in [docs/singula
 
 If you would like to contribute to developing these containers, please see the [CONTRIBUTING](./../CONTRIBUTING.md) file.
 
-For a tutorial on GWAS with synthetic data, see [docs/usecases/gwas_demo.md](./../docs/usecases/gwas_demo.md).
+For a tutorial on GWAS with synthetic data, see [usecases/gwas_demo.md](./../usecases/gwas_demo.md).
 
 ### Prerequisites (to running tutorials)
 
-NOTE: This is out of date. Confer [docs/usecases](./../docs/usecases).
+NOTE: This is out of date. Confer [usecases/README.md](./../usecases/README.md).
 
 * download container files shared on the [Google Drive](https://drive.google.com/drive/folders/1mfxZJ-7A-4lDlCkarUCxEf2hBIxQGO69?usp=sharing).
 * download ``comorment_ref.tar.gz`` file from the above Google Drive folder, extract it with ``tar -xzvf comorment_ref.tar.gz`` command,
@@ -25,7 +25,7 @@ NOTE: This is out of date. Confer [docs/usecases](./../docs/usecases).
 
 ## Description of available containers
 
-The detailed description of the available container [files](./../singularity) provided in this repository are found [here](./../docs/singularity).
+The detailed description of the available container [files](https://github.com/comorment/containers/tree/main/singularity) provided in this repository are found [here](./../docs/singularity/README.md).
 
 ## Software versions
 

docs/README.md

@@ -2,8 +2,8 @@
 
 ## Singularity
 
-Brief descriptions of the available software container builds are available at [singularity](singularity).
+Brief descriptions of the available software container builds are available at [singularity](./singularity/README.md).
 
 ## Specifications
 
-Specifications of the input data format for GWAS anslysis, recommended in CoMorMent projects are documentat at [specifications](specifications)
+Specifications of the input data format for GWAS analysis, recommended in CoMorMent projects are documented at [specifications](./specifications/README.md)

docs/singularity/README.md

@@ -1,6 +1,6 @@
 # Singularity
 
-Here is a brief overview of available container [files](./../../singularity) (more info in the links below):
+Here is a brief overview of available container [files](./../../singularity/README.md) (more info in the links below):
 
 * [hello.sif](hello.md) - a simple container for demo purpose, allowing to experiment with singularity features
 * [gwas.sif](gwas.md) - multiple tools (released as binaries/executables) for imputation and GWAS analysis

docs/singularity/gwas.md

@@ -1,6 +1,6 @@
 # ``gwas.sif`` container
 
-The ``gwas.sif`` container file has multiple tools related to imputation and GWAS analysis, as summarized in this [table](./../../docker#software-versions).
+The ``gwas.sif`` container file has multiple tools related to imputation and GWAS analysis, as summarized in this [table](./../../docker/README.md#software-versions).
 
 Note that some specific tools (e.g. ``bolt``) are added to the path directly from their ``/tools`` folder (e.g. ``/tools/bolt``) due to hard-linked dependencies.
 Either way, all tools can be invoked by their name, as listed above. For example:

docs/singularity/hello.md

@@ -81,7 +81,7 @@ Please [let us know](https://github.com/comorment/containers/issues/new) if you
 
 ## TSD-specific instructions
 
-The official documentation fro singularity on TSD  is available [here](https://www.uio.no/english/services/it/research/sensitive-data/use-tsd/hpc/software/singularity.html). Here are more important notes about singularity on TSD:
+The official documentation for singularity on TSD  is available [here](https://www.uio.no/english/services/it/research/sensitive-data/use-tsd/hpc/software/singularity.html). Here are more important notes about singularity on TSD:
 * ``module load singularity/2.6.1`` is going to be deprecated soon; instead, there will be a local installation of singularity on each Colossus node
 * Singularity might be unavailable on some of the interactive nodes. For example, in ``p33`` project it is recommended to run singularity on ``p33-appn-norment01`` node. You may also find it in ``p33-submit`` nodes. 
 * You may want to run ``module purge``, to make sure you use locally installed singularity. It is good idea to run ``which singularity`` to validate this.

docs/singularity/r.md

@@ -1,7 +1,7 @@
 # ``r.sif`` container
 
 The ``r.sif`` container has multiple genomics tools related based on R.
-Please confer this [table](./../../docker#software_versions) for the more complete list.
+Please confer this [table](./../../docker/README.md#software-versions) for the more complete list.
 
 In addition several standard R packages are also included (e.g. data.table, ggplot2, rmarkdown, etc.)
 

docs/specifications/sumstats_specification.md

@@ -16,7 +16,7 @@ The results of GWAS are represented as summary statistics, with the following co
 * ``L95``, ``U95`` - lower and upper 95% confidence interval of the ``BETA``.
 * ``P`` - p-value
 
-For ``SNP``, ``CHR``, ``BP``, ``A1`` and ``A2`` columns the [gwas.py](gwas.py) script will simply copy over the information from the genetic file, i.e. from ``.bgen`` or ``.bim`` files. This means that ``SNP`` is likely to be dbSNP rs#, or some other form of identifyied such as ``CHR:BP:A1:A2``. 
+For ``SNP``, ``CHR``, ``BP``, ``A1`` and ``A2`` columns the [scripts/gwas/gwas.py](https://github.com/comorment/containers/tree/main/scripts/gwas/gwas.py) script will simply copy over the information from the genetic file, i.e. from ``.bgen`` or ``.bim`` files. This means that ``SNP`` is likely to be dbSNP rs#, or some other form of identifyied such as ``CHR:BP:A1:A2``. 
 For ``CHR`` and ``BP``, there we don't enforce a specific genomic build - it all depends on what build was used by the genotype data.
 Finally, ``A1`` and ``A2`` are not guarantied to be minor or major alleles, but ``A1`` will be used as an effect allele for signed summary statistics (i.e. ``Z`` and ``BETA`` columns).