update docs and tests

Author: nebfield

docs/how-to/guides/match.rst

@@ -0,0 +1,61 @@
+How to match scoring file variants against target genomes
+=========================================================
+
+``pgscatalog-match`` is a CLI application that makes it easy to match genetic variants in a normalised scoring file against target variant information files. The application:
+
+* identifies match candidates using genomic coordinates and allele information
+* creates a summary log and calculates match rates using the best match candidates
+* writes scoring files in plink2 --score format using the best match candidates
+* creates a log that describes all possible match candidate and match status
+
+The application will error if not enough variants in the scoring file are present in the target variant information files. This is because it's important to match variants well to faithfully reproduce published scoring files.
+
+
+Installation
+-------------
+
+::
+
+    $ pip install pgscatalog-matchapp
+
+Usage
+-----
+
+Match variants
+~~~~~~~~~~~~~~
+
+::
+
+    $ mkdir matchout
+    $ pgscatalog-match --dataset test --scorefiles normalised_scorefile.txt --target variants.pvar --outdir matchout --min_overlap 0.75
+    
+.. note::
+
+    Variant information files in both plink2 pvar and plink1 bim format are supported
+
+Matching very large datasets
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you're matching many millions of variants it can be a good idea to split work by matching each chromosome separately:
+
+::
+
+    $ mkdir matchout
+    $ pgscatalog-match --dataset test --scorefiles normalised_scorefile.txt --target variants_chrom1.pvar --outdir matchout --chrom 1 --only_match
+
+This will generate match files in Arrow IPC format in matchout/matchtmp. This process can be run in parallel to distribute work.
+
+You can then merge these matches with a different CLI tool:
+
+::
+   
+   $ pgscatalog-matchmerge --dataset test --scorefiles normalised_scorefile.txt --matches path/to/matchfile --outdir matchmergeout --min_overlap 0.75
+
+The PGS Catalog Calculator does this automatically when working with target genomes split to have one file per chromosome.   
+    
+Help
+----
+
+::
+
+    $ pgscatalog-match --help

docs/how-to/index.rst

@@ -8,4 +8,5 @@ These guides describe how to use pygscatalog CLI applications.
    :caption: Contents:
 
    guides/download
-   guides/combine
+   guides/combine
+   guides/match

pgscatalog.matchapp/src/pgscatalog/matchapp/match_cli.py

@@ -154,7 +154,6 @@ def parse_args(args=None):
         dest="min_overlap",
         required=False,
         type=float,
-        default=0.75,
         help="<Optional> Minimum proportion of variants to match before error",
     )
     parser.add_argument(

pgscatalog.matchapp/tests/test_match_cli.py

@@ -1,4 +1,5 @@
 import itertools
+import os
 from unittest.mock import patch
 import pytest
 
@@ -36,6 +37,8 @@ def test_match(tmp_path_factory, good_scorefile, good_variants):
             str(good_variants),
             "--outdir",
             str(outdir),
+            "--min_overlap",
+            "0.75",
         )
     ]
     flargs = list(itertools.chain(*args))
@@ -50,6 +53,34 @@ def test_match(tmp_path_factory, good_scorefile, good_variants):
     assert (outdir / "test_ALL_additive_0.scorefile.gz").exists()
 
 
+def test_only_match(tmp_path_factory, good_scorefile, good_variants):
+    """Test just matching (for big data)"""
+    outdir = tmp_path_factory.mktemp("outdir")
+
+    args = [
+        (
+            "pgscatalog-match",
+            "-d",
+            "test",
+            "-s",
+            str(good_scorefile),
+            "-t",
+            str(good_variants),
+            "--outdir",
+            str(outdir),
+            "--only_match",
+        )
+    ]
+    flargs = list(itertools.chain(*args))
+
+    with pytest.raises(SystemExit):
+        with patch("sys.argv", flargs):
+            run_match()
+
+    # arrow IPC files have been written
+    assert len(os.listdir(outdir / "matchtmp")) == 1
+
+
 def test_strict_match(tmp_path_factory, good_scorefile, good_variants):
     """Test matching well with extremely strict overlap to trigger a MatchRateError"""
     outdir = tmp_path_factory.mktemp("outdir")
@@ -91,6 +122,8 @@ def test_match_fail(tmp_path_factory, bad_scorefile, good_variants):
             str(good_variants),
             "--outdir",
             str(outdir),
+            "--min_overlap",
+            "0.75",
         )
     ]
     flargs = list(itertools.chain(*args))