feat: implement a new validate command

docs/commands/validate.rst

@@ -0,0 +1,76 @@
+.. _commands-validate:
+
+
+validate
+========
+
+Validate the formatting of a :doc:`.hap file </formats/haplotypes>`. Output warnings/errors explaining how the formatting of your ``.hap`` file may be improved.
+
+If a :ref:`.pvar file <formats-genotypesplink>` file is provided, the SNPs and TRs present in the ``.hap`` file will be checked for existence in the ``.pvar`` file.
+
+.. note::
+
+  This command will not check that your ``.hap`` file is properly sorted. It only checks formatting.
+
+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/validate/basic.hap
+
+Outputs a message specifying the amount of errors and warnings.
+
+.. code-block::
+
+  [    INFO] Completed .hap file 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/validate/no_version.hap
+
+.. code-block::
+
+  [ WARNING] No version declaration found. Assuming to use the latest version.
+  [    INFO] Completed .hap file validation with 0 errors and 1 warnings.
+  Error: Found several warnings and / or errors in the .hap file
+
+All ``.hap`` files must be sorted before they can be validated, so we try our best to sort your ``.hap`` file internally before performing any validation checks.
+If your ``.hap`` file is already sorted, you should use the ``--sorted`` parameter. It will speed things up a bit by skipping the sorting step. If your ``.hap`` file is indexed, it will be assumed to be sorted regardless.
+
+.. code-block:: bash
+
+  haptools validate --sorted tests/data/simple.hap
+
+As mentioned before, one can use the ``--genotypes`` flag to provide a ``.pvar`` file with which to compare the existence of variant IDs.
+The following will check if all of the variant IDs in the ``.hap`` file appear in the ``.pvar`` file.
+
+.. code-block:: bash
+
+  haptools validate --genotypes tests/data/simple.pvar tests/data/simple.hap
+
+.. note::
+
+  We accept a PVAR file instead of a VCF in order to avoid reading lots of information
+  which is not relevant to the validation process. However, any VCF subsetted to just
+  its first 8 fields is a valid PVAR file. So you can easily create a PVAR file from a
+  VCF using ``cut -f -8`` or ``plink2 --make-just-pvar``.
+
+Detailed Usage
+~~~~~~~~~~~~~~
+
+.. click:: haptools.__main__:main
+  :prog: haptools
+  :show-nested:
+  :commands: validate

docs/formats/genotypes.rst

@@ -18,7 +18,7 @@ Genotype files must be specified as VCF or BCF files. They can be bgzip-compress
 PLINK2 PGEN
 ~~~~~~~~~~~
 
-There is also experimental support for `PLINK2 PGEN <https://github.com/chrchang/plink-ng/blob/master/pgen_spec/pgen_spec.pdf>`_ files in some commands. These files can be loaded and created much more quickly than VCFs, so we highly recommend using them if you're working with large datasets. See the documentation for the :class:`GenotypesPLINK` class in :ref:`the API docs <api-data-genotypesplink>` for more information.
+There is also experimental support for `PLINK2 PGEN <https://github.com/chrchang/plink-ng/blob/master/pgen_spec/pgen_spec.pdf>`_ files (accomponied by PVAR and PSAM files) in some commands. These files can be loaded and created much more quickly than VCFs, so we highly recommend using them if you're working with large datasets. See the documentation for the :class:`GenotypesPLINK` class in :ref:`the API docs <api-data-genotypesplink>` for more information.
 
 If you run out memory when using PGEN files, consider reading/writing variants from the file in chunks via the ``--chunk-size`` parameter.
 

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

@@ -1025,6 +1025,61 @@ 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(
+    "--sorted/--not-sorted",
+    is_flag=True,
+    default=False,
+    show_default=True,
+    help="Has the file been sorted already?",
+)
+@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,
+    sorted: bool = False,
+    genotypes: Path | None = None,
+    verbosity: str = "INFO",
+):
+    """
+    Validate the formatting of a .hap file
+
+    Output warnings/errors explaining how the formatting of your .hap file may
+    be improved.
+    """
+    from .logging import getLogger
+    from .validate import is_hapfile_valid
+
+    log = getLogger(name="validate", level=verbosity)
+
+    # if the hap file is compressed and a .tbi index exists for it, assume it is sorted
+    if filename.suffix == ".gz" and filename.with_suffix(".gz.tbi").exists():
+        sorted = True
+
+    is_valid = is_hapfile_valid(filename, sorted=sorted, log=log, pvar=genotypes)
+
+    if not is_valid:
+        raise click.ClickException(
+            "Found several warnings and / or errors in the .hap file"
+        )
+
+
 if __name__ == "__main__":
     # run the CLI if someone tries 'python -m haptools' on the command line
     main(prog_name="haptools")

haptools/transform.py

@@ -175,7 +175,7 @@ class GenotypesAncestry(data.GenotypesVCF):
         See documentation for :py:attr:`~.Genotypes.log`
     """
 
-    def __init__(self, fname: Path | str, log: Logger = None):
+    def __init__(self, fname: Path | str, log: logging.Logger = None):
         super().__init__(fname, log)
         self.ancestry = None
         self.valid_labels = None