feat: implement a new validate command

docs/commands/validate.rst

@@ -0,0 +1,125 @@
+.. _commands-validate:
+
+
+validate
+========
+
+Validate the structure of a ``.hap`` file.
+
+When a ``.hap`` file contains any errors, they will be logged accordingly.
+
+Optionally, the haplotypes present in the ``.hap`` file can be compared against a ``.pgen`` file.
+
+Usage
+~~~~~
+.. code-block:: bash
+
+  haptools validate \
+  --sort \
+  --genotypes PATH \
+  --verbosity [CRITICAL|ERROR|WARNING|INFO|DEBUG|NOTSET] \
+  HAPFILE
+
+Examples
+~~~~~~~~
+.. code-block:: bash
+
+  haptools validate tests/data/hapfiles/basic.hap
+
+Outputs a message specifying the amount of errors and warnings.
+
+.. code-block::
+
+  [    INFO] Completed HapFile validation with 0 errors and 0 warnings.
+
+All warnings and errors will be logged if there are any.
+
+.. code-block:: bash
+
+  haptools validate tests/data/hapfiles/valhap_with_no_version.hap
+
+.. code-block::
+
+  [ WARNING] No version declaration found. Assuming to use the latest version.
+  [    INFO] Completed HapFile validation with 0 errors and 1 warnings.
+  [ WARNING] Found several warnings and / or errors in the hapfile
+
+One can use ``--no-sort`` to avoid sorting the file.
+This will make it so that all unordered files will get removed, such as out-of-header lines with meta information.
+
+.. code-block:: bash
+
+  haptools validate --no-sort tests/data/hapfiles/valhap_with_out_of_header_metas.hap
+
+Will turn:
+
+.. code-block::
+
+  #   orderH	ancestry	beta
+  #	version	0.2.0
+  #H	ancestry	s	Local ancestry
+  #H	beta	.2f	Effect size in linear model
+  #R	beta	.2f	Effect size in linear model
+  H	21	26928472	26941960	chr21.q.3365*1	ASW	0.73
+  R	21	26938353	26938400	21_26938353_STR	0.45
+  H	21	26938989	26941960	chr21.q.3365*10	CEU	0.30
+  H	21	26938353	26938989	chr21.q.3365*11	MXL	0.49
+  # This should cause an error if the file is sorted
+  #V	test_field	s	A field to test with
+  V	chr21.q.3365*1	26928472	26928472	21_26928472_C_A	C
+  V	chr21.q.3365*1	26938353	26938353	21_26938353_T_C	T
+  V	chr21.q.3365*1	26940815	26940815	21_26940815_T_C	C
+  V	chr21.q.3365*1	26941960	26941960	21_26941960_A_G	G
+  V	chr21.q.3365*10	26938989	26938989	21_26938989_G_A	A
+  V	chr21.q.3365*10	26940815	26940815	21_26940815_T_C	T
+  V	chr21.q.3365*10	26941960	26941960	21_26941960_A_G	A
+  V	chr21.q.3365*11	26938353	26938353	21_26938353_T_C	T
+  V	chr21.q.3365*11	26938989	26938989	21_26938989_G_A	A
+
+Into
+
+.. code-block::
+
+  #	orderH	ancestry	beta
+  #	version	0.2.0
+  #H	ancestry	s	Local ancestry
+  #H	beta	.2f	Effect size in linear model
+  #R	beta	.2f	Effect size in linear model
+  H	21	26928472	26941960	chr21.q.3365*1	ASW	0.73
+  R	21	26938353	26938400	21_26938353_STR	0.45
+  H	21	26938989	26941960	chr21.q.3365*10	CEU	0.30
+  H	21	26938353	26938989	chr21.q.3365*11	MXL	0.49
+  V	chr21.q.3365*1	26928472	26928472	21_26928472_C_A	C
+  V	chr21.q.3365*1	26938353	26938353	21_26938353_T_C	T
+  V	chr21.q.3365*1	26940815	26940815	21_26940815_T_C	C
+  V	chr21.q.3365*1	26941960	26941960	21_26941960_A_G	G
+  V	chr21.q.3365*10	26938989	26938989	21_26938989_G_A	A
+  V	chr21.q.3365*10	26940815	26940815	21_26940815_T_C	T
+  V	chr21.q.3365*10	26941960	26941960	21_26941960_A_G	A
+  V	chr21.q.3365*11	26938353	26938353	21_26938353_T_C	T
+  V	chr21.q.3365*11	26938989	26938989	21_26938989_G_A	A
+
+
+If the previous example were to be sorted then there would be several errors in the ``.hap`` file.
+All sorted files parse the meta information lines first, thus the ``V`` lines would be incomplete.
+
+As mentioned before, one can use the ``--genotypes`` flag to provide a ``.pgen`` file with which to compare the existence of variant IDs.
+The following will check if all of the variant IDs in the ``.hap`` appear in the ``.pvar`` associated to the ``.pgen``.
+
+.. code-block:: bash
+
+  haptools validate --genotypes tests/data/hapfiles/valhap_test_data.pgen tests/data/hapfiles/valhap_test_data.hap
+
+.. warning::
+
+  You must generate a ``.pvar`` from your ``.pgen`` file.
+  This is done in order to avoid reading heavy amounts of
+  information which is not relevant to the validation process.
+
+Detailed Usage
+~~~~~~~~~~~~~~
+
+.. click:: haptools.__main__:main
+  :prog: haptools
+  :show-nested:
+  :commands: validate

docs/index.rst

@@ -20,6 +20,8 @@ Commands
 
 * :doc:`haptools transform </commands/transform>`: Transform a set of genotypes via a list of haplotypes. Create a new VCF containing haplotypes instead of variants.
 
+* :doc:`haptools validate </commands/validate>`: Validate the formatting of a haplotype file.
+
 * :doc:`haptools index </commands/index>`: Sort, compress, and index our custom file format for haplotypes.
 
 * :doc:`haptools clump </commands/clump>`: Convert variants in LD with one another into clumps.
@@ -95,6 +97,7 @@ There is an option to *Cite this repository* on the right sidebar of `the reposi
    commands/simphenotype.rst
    commands/karyogram.rst
    commands/transform.rst
+   commands/validate.rst
    commands/index.rst
    commands/clump.rst
    commands/ld.rst

haptools/__main__.py

@@ -1,6 +1,7 @@
 #!/usr/bin/env python
 
 from __future__ import annotations
+from enum import Flag
 import sys
 from pathlib import Path
 
@@ -1025,6 +1026,49 @@ def clump(
     )
 
 
+@main.command(short_help="Validate the structure of a .hap file")
+@click.argument("filename", type=click.Path(exists=True, path_type=Path))
+@click.option(
+    "--sort/--no-sort",
+    is_flag=True,
+    default=True,
+    show_default=True,
+    help="Sorting of the file will not be performed",
+)
+@click.option(
+    "--genotypes",
+    type=click.Path(path_type=Path),
+    default=None,
+    show_default="optional .pvar file to compare against",
+    help=(
+        "A .pvar file containing variant IDs in order to compare them to the .hap file"
+    ),
+)
+@click.option(
+    "-v",
+    "--verbosity",
+    type=click.Choice(["CRITICAL", "ERROR", "WARNING", "INFO", "DEBUG", "NOTSET"]),
+    default="INFO",
+    show_default=True,
+    help="The level of verbosity desired",
+)
+def validate(
+    filename: Path,
+    sort: bool,
+    genotypes: Path | None = None,
+    verbosity: str = "DEBUG",
+):
+    from .logging import getLogger
+    from .validate import is_hapfile_valid
+
+    log = getLogger(name="validate", level=verbosity)
+
+    is_valid = is_hapfile_valid(filename, sorted=sort, logger=log, pgen=genotypes)
+
+    if not is_valid:
+        log.warn("Found several warnings and / or errors in the hapfile")
+
+
 if __name__ == "__main__":
     # run the CLI if someone tries 'python -m haptools' on the command line
     main(prog_name="haptools")