Refactor argument parsers to avoid duplication

docs/cli.md

@@ -3,12 +3,12 @@
 `matchmaps` is built to be used from the command-line. See the following utilities below. You can also print these messages in the command-line via the `--help` option.
 
 ```{eval-rst}
-.. autoprogram:: matchmaps._compute_realspace_diff:parse_arguments()
+.. autoprogram:: matchmaps._parsers:matchmaps_parser
    :prog: matchmaps
 
-.. autoprogram:: matchmaps._compute_ncs_diff:parse_arguments()
-   :prog: matchmaps.ncs
-
-.. autoprogram:: matchmaps._compute_mr_diff:parse_arguments()
+.. autoprogram:: matchmaps._parsers:matchmaps_mr_parser
    :prog: matchmaps.mr
+
+.. autoprogram:: matchmaps._parsers:matchmaps_ncs_parser
+   :prog: matchmaps.ncs
 ```

src/matchmaps/_args.py

@@ -0,0 +1,244 @@
+"""
+Dictionaries for arguments parsed by one or more matchmaps utilities
+"""
+
+matchmaps_description = (
+            "Compute a real-space difference map. "
+            "You will need two MTZ files, which will be referred to throughout as 'on' and 'off', "
+            "though they could also be light/dark, bound/apo, mutant/WT, hot/cold, etc. "
+            "Each mtz will need to contain structure factor amplitudes and uncertainties; you will not need any phases. "
+            "You will, however, need an input model (assumed to correspond with the 'off' state) which will be used to determine phases. "
+            "The input file may be in .pdb or .cif format. "
+            "Please note that both ccp4 and phenix must be installed and active in your environment for this function to run. "
+            ""
+            "More information can be found online at https://rs-station.github.io/matchmaps/index.html"
+        )
+
+matchmaps_mr_description = (
+            "Compute a real-space difference map between inputs in different space groups / crystal packings. "
+            "You will need two MTZ files, which will be referred to throughout as 'on' and 'off', "
+            "though they could also be light/dark, bound/apo, mutant/WT, hot/cold, etc. "
+            "Each mtz will need to contain structure factor amplitudes and uncertainties; you will not need any phases. "
+            "You will, however, need an input model (assumed to correspond with the 'off' state) which will be used to determine phases. "
+            "The input file may be in .pdb or .cif format. "
+            "Please note that phenix must be installed and active in your environment for this function to run. "
+            ""
+            "If your mtzoff and mtzon are in the same spacegroup and crystal packing, see the basic matchmaps utility. "
+            "More information can be found online at https://rs-station.github.io/matchmaps/index.html"
+        )
+
+matchmaps_ncs_description = (
+            "Compute an 'internal' real-space difference map between NCS-related molecules. "
+            "You will need an MTZ file with structure factor amplitudes and optionally containing phases, and a PDB/CIF file."
+            ""
+            "Please note that phenix must be installed and active in your environment for this function to run. "
+            ""
+            "More information can be found online at https://rs-station.github.io/matchmaps/index.html"
+        )
+
+base_and_mr_args = (
+    (("--mtzoff", "-f"), {
+        "nargs": 3,
+        "metavar": ("mtzfileoff", "Foff", "SigFoff"),
+        "required": True,
+        "help": (
+            "MTZ or sfCIF containing off/apo/ground/dark state data. "
+            "Specified as [filename F SigF]"
+        ),
+    }),
+
+    (("--mtzon", "-n"), {
+        "nargs": 3,
+        "metavar": ("mtzfileon", "Fon", "SigFon"),
+        "required": True,
+        "help": (
+            "MTZ or sfCIF containing on/bound/excited/bright state data. "
+            "Specified as [filename F SigF]"
+        ),
+    }),
+
+    (("--pdboff", "-p"), {
+        "required": True,
+        "help": (
+            "Reference PDB or mmCIF corresponding to the off/apo/ground/dark state. "
+            "Used for rigid-body refinement of both input MTZs to generate phases."
+        ),
+    }),
+    (("--on-as-stationary",), {
+        "required": False,
+        "action": "store_true",
+        "default": False,
+        "help": (
+            "Include this flag to align 'off' data onto 'on' data. By default, 'off' data is stationary and 'on' data is moved."
+        ),
+    }),
+
+    (("--alpha",), {
+        "required": False,
+        "type": float,
+        "default": 0,
+        "help": (
+            "Alpha to use for error weighting of F-obs prior to Fourier Transform. "
+            "Weights are computed as: 1 / ((1+(alpha*(SigF^2)) / <SigF>^2). "
+            "Default value is alpha=0, e.g., no weighting is performed. "
+        )
+    }),
+
+    (("--unmasked-radius",), {
+        "required": False,
+        "type": float,
+        "default": 5,
+        "help": (
+            "Maximum distance (in Anstroms) away from protein model to include voxels. Only applies to the 'unmasked' difference map output. "
+            "Defaults to 5. "
+            "Note that the regular difference map (e.g. the 'masked' version) is not affected by this parameter and maintains a solvent mask radius of 2 Angstroms."
+        ),
+    }),
+
+    (("--rbr-selections", "-r"), {
+        "required": False,
+        "default": None,
+        "nargs": "*",
+        "help": (
+            "Specification of multiple rigid-body groups for refinement. By default, everything is refined as one rigid-body group. "
+        ),
+    }),
+)
+
+ncs_args = (
+    (("--mtz", "-m"), {
+        "nargs": "*",
+        "required": True,
+        "help": (
+            "MTZ or sfCIF file containing structure factor amplitudes. "
+            "Specified as [filename F SigF] or [filename F]. "
+            "SigF is not necessary if phases are also provided"
+        ),
+    }),
+
+    (("--phases",), {
+        "required": False,
+        "default": None,
+        "help": (
+            "Optional. Column in MTZ/sfCIF file containing phases. "
+            "If phases are not provided, phases will be computed via rigid-body refinement of "
+            "the provided model and structure factor amplitudes."
+        ),
+    }),
+
+    (("--pdb", "-p"), {
+        "required": True,
+        "help": (
+            "Reference PDB or mmCIF. "
+            "If phases are not provided, used for rigid-body refinement of input MTZ/sfCIF to generate phases."
+        ),
+    }),
+
+    (("--ncs-chains", "-n"), {
+        "required": True,
+        "metavar": ("fixed_chain", "moving_chain"),
+        "default": None,
+        "nargs": 2,
+        "help": (
+            "NCS chains to overlay and subtract, specified as [fixed_chain, moving_chain]."
+            "E.g. to overlay chain C onto chain B, specify: --ncs-chains B C"
+        ),
+    }),
+
+    (("--mapname",), {
+        "required": False,
+        "default": "matchmaps_ncs",
+        "help": "Base filename for the output map files. "
+    })
+)
+
+common_args = (
+    # args used by all three utilities
+    (("--ligands", "-l"), {
+        "help": "Any .cif restraint files needed for refinement",
+        "required": False,
+        "default": None,
+        "nargs": "*",
+    }),
+
+    (("--input-dir", "-i"), {
+        "help": "Path to input files. Optional, defaults to './' (current directory)",
+        "required": False,
+        "default": "./",
+    }),
+
+    (("--output-dir", "-o"), {
+        "help": "Path to which output files should be written. Optional, defaults to './' (current directory)",
+        "required": False,
+        "default": "./",
+    }),
+
+    (("--spacing", "-s"), {
+        "help": (
+            "Approximate voxel size in Angstroms for real-space maps. Defaults to 0.5 A. "
+            "Value is approximate because there must be an integer number of voxels along each unit cell dimension"
+        ),
+        "required": False,
+        "default": 0.5,
+        "type": float,
+    }),
+
+    (("--dmin",), {
+        "help": (
+            "Highest-resolution (in Angstroms) reflections to include in Fourier transform for FloatGrid creation. "
+            "By default, cutoff is the resolution limit of the lower-resolution input MTZ. "
+        ),
+        "required": False,
+        "type": float,
+        "default": None,
+    }),
+
+    (("--no-bss",), {
+        "help": (
+            "Include this flag to skip bulk solvent scaling in phenix.refine. By default, BSS is included."
+        ),
+        "required": False,
+        "action": "store_true",
+        "default": False,
+    }),
+
+    (("--verbose", "-v"), {
+        "help": "Include this flag to print out scaleit and phenix.refine outputs to the terminal. Useful for troubleshooting, but annoying; defaults to False.",
+        "required": False,
+        "action": "store_true",
+        "default": False,
+    }),
+
+    (("--eff",), {
+        "help": "Custom .eff template for running phenix.refine. ",
+        "required": False,
+        "default": None,
+    }),
+
+    (("--keep-temp-files", "-k"), {
+        "required": False,
+        "default": None,
+        "help": (
+            "Do not delete intermediate matchmaps files, but rather place them in the supplied directory. "
+            "This directory is created as a subdirectory of the supplied output-dir."
+        )}),
+
+    (("--script",), {
+        "required": False,
+        "default": "run_matchmaps",
+        "help": (
+            "Name for a file {script}.sh which can be run to repeat this command. "
+            "By default, this file is called `run_matchmaps.sh`. "
+            "Note that this file is written out in the current working directory, NOT the input or output directories"
+        )
+    }),
+
+    (("--phenix-version",), {
+        "required": False,
+        "help": (
+            "Specify phenix version as a string, e.g. '1.20'. "
+            "If omitted, matchmaps will attempt to automatically detect the version in use "
+            "by analyzing the output of phenix.version"
+        )
+    }),
+)