Update

dadi_cli/parsers/argument_validation.py

@@ -150,7 +150,34 @@ def existed_file(value: str) -> str:
 
 
 # helper functions for reading, parsing, and validating parameters from command line or files
-def check_params(params, model, option, misid):
+def check_params(params: list[str], model: str, 
+                 option: str, misid: bool) -> list[str]:
+    """
+    Validates the number of demographic parameters against the expected number for a given model.
+
+    Parameters
+    ----------
+    params : list[str]
+        A list containing the demographic parameters to be used with the model.
+    model : str
+        The name of the demographic model to be validated against the parameters.
+    option : str
+        Describes the scenario or method using these parameters (for debugging or error messages).
+    misid : bool
+        A flag indicating whether misidentification of alleles has been considered.
+        If True, one parameter is ignored in the count.
+
+    Returns
+    -------
+    list[str]
+        The validated list of parameters.
+
+    Raises
+    ------
+    Exception
+        If the number of input parameters does not match the required number for the specified model.
+
+    """
     input_params_len = len(params)
     _, model_params_len = get_model(model, None)
     model_params_len = len(model_params_len)
@@ -169,10 +196,38 @@ def check_params(params, model, option, misid):
             + " model"
             + "\nYou might be using the wrong model or need to add --nomisid if you did not use ancestral allele information to polarize the fs."
         )
+
     return params
 
 
-def check_pdf_params(params, pdf, option, misid):
+def check_pdf_params(params: list[str], pdf: str, 
+                     option: str, misid: bool) -> list[str]:
+    """
+    Validates the number of PDF (Probability Density Function) parameters against the expected number for a given PDF model.
+
+    Parameters
+    ----------
+    params : list[str]
+        A list of parameters to be used for the PDF.
+    pdf : str
+        The name of the PDF to be validated against the parameters.
+    option : str
+        Describes the scenario or method using these parameters (for debugging or error messages).
+    misid : bool
+        A flag indicating whether misidentification of alleles has been considered.
+        If True, one parameter is ignored in the count.
+
+    Returns
+    -------
+    tuple[list[str], list[str]]
+        A tuple containing the validated list of parameters and the list of parameter names from the PDF model.
+
+    Raises
+    ------
+    Exception
+        If the number of input parameters does not match the required number for the specified PDF model.
+
+    """
     input_params_len = len(params)
     if misid:
         input_params_len = input_params_len - 1
@@ -196,4 +251,5 @@ def check_pdf_params(params, pdf, option, misid):
             + pdf
             + " pdf"
         )
+
     return params, param_names

dadi_cli/parsers/common_arguments.py

@@ -3,13 +3,31 @@
 from dadi_cli.parsers.argument_validation import *
 
 
-def add_output_argument(parser) -> None:
+def add_output_argument(parser: argparse.ArgumentParser) -> None:
+    """
+    Adds an output file argument to a parser.
+
+    Parameters
+    ----------
+    parser : argparse.ArgumentParser
+        The argparse.ArgumentParser object to which the output file argument will be added.
+
+    """
     parser.add_argument(
         "--output", type=str, required=True, help="Name of the output file."
     )
 
 
-def add_bounds_argument(parser) -> None:
+def add_bounds_argument(parser: argparse.ArgumentParser) -> None:
+    """
+    Adds lower and upper bounds arguments to a parser, conditional on the model type and options.
+
+    Parameters
+    ----------
+    parser : argparse.ArgumentParser
+        The parser object to which the bounds arguments will be added.
+
+    """
     # Check that the model is not a standard neutral model
     if 'snm_1d' not in sys.argv and 'snm_2d' not in sys.argv:
         boundary_req = True
@@ -36,7 +54,16 @@ def add_bounds_argument(parser) -> None:
     )
 
 
-def add_demo_popt_argument(parser) -> None:
+def add_demo_popt_argument(parser: argparse.ArgumentParser) -> None:
+    """
+    Adds a demographic optimization parameter file argument to a parser, conditional on the model type.
+
+    Parameters
+    ----------
+    parser : argparse.ArgumentParser
+        The parser object to which the demographic optimization parameter file argument will be added.
+
+    """
     # Check that the model is not a standard neutral model
     bestfit_req = False
     if 'equil' not in sys.argv:
@@ -51,7 +78,16 @@ def add_demo_popt_argument(parser) -> None:
     )
 
 
-def add_grids_argument(parser) -> None:
+def add_grids_argument(parser: argparse.ArgumentParser) -> None:
+    """
+    Adds a grids argument to a parser to specify the sizes of grids used in computations.
+
+    Parameters
+    ----------
+    parser : argparse.ArgumentParser
+        The parser object to which the grid sizes argument will be added.
+
+    """
     parser.add_argument(
         "--grids",
         type=positive_int,
@@ -60,7 +96,16 @@ def add_grids_argument(parser) -> None:
     )
 
 
-def add_misid_argument(parser) -> None:
+def add_misid_argument(parser: argparse.ArgumentParser) -> None:
+    """
+    Adds an argument to the parser to control the inclusion of a parameter for modeling ancestral state misidentification.
+
+    Parameters
+    ----------
+    parser : argparse.ArgumentParser
+        The parser object to which the misidentification control argument will be added.
+
+    """
     # Note that the code previously had a --misid function that did the opposite, but this ia more sensible default.
     parser.add_argument(
         "--nomisid",
@@ -70,7 +115,16 @@ def add_misid_argument(parser) -> None:
     )
 
 
-def add_model_argument(parser) -> None:
+def add_model_argument(parser: argparse.ArgumentParser) -> None:
+    """
+    Adds model-related arguments to a parser for specifying demographic models in a command-line interface.
+
+    Parameters
+    ----------
+    parser : argparse.ArgumentParser
+        The parser object to which the model name and model file arguments will be added.
+
+    """
     # Because most of the functions for Plot
     # do not require a model, we make it
     # conditionally required.
@@ -93,7 +147,16 @@ def add_model_argument(parser) -> None:
     )
 
 
-def add_fs_argument(parser) -> None:
+def add_fs_argument(parser: argparse.ArgumentParser) -> None:
+    """
+    Adds an argument to a parser to specify the frequency spectrum file used for demographic inference.
+
+    Parameters
+    ----------
+    parser : argparse.ArgumentParser
+        The parser object to which the frequency spectrum file argument will be added.
+
+    """
     parser.add_argument(
         "--fs",
         type=existed_file,
@@ -102,11 +165,29 @@ def add_fs_argument(parser) -> None:
     )
 
 
-def add_seed_argument(parser) -> None:
+def add_seed_argument(parser: argparse.ArgumentParser) -> None:
+    """
+    Adds an argument to a parser to specify a random seed for ensuring reproducibility.
+
+    Parameters
+    ----------
+    parser : argparse.ArgumentParser
+        The parser object to which the random seed argument will be added.
+
+    """
     parser.add_argument("--seed", type=positive_int, help="Random seed.")
 
 
-def add_constant_argument(parser) -> None:
+def add_constant_argument(parser: argparse.ArgumentParser) -> None:
+    """
+    Adds an argument to a parser to specify constant parameters for inference or Godambe analysis.
+
+    Parameters
+    ----------
+    parser : argparse.ArgumentParser
+        The parser object to which the constants argument will be added.
+
+    """
     parser.add_argument(
         "--constants",
         default=-1,
@@ -116,7 +197,16 @@ def add_constant_argument(parser) -> None:
     )
 
 
-def add_delta_ll_argument(parser) -> None:
+def add_delta_ll_argument(parser: argparse.ArgumentParser) -> None:
+    """
+    Adds an argument to a parser to specify the maximum permissible percentage difference in log-likelihoods for convergence checks.
+
+    Parameters
+    ----------
+    parser : argparse.ArgumentParser
+        The parser object to which the delta log-likelihood argument will be added.
+
+    """
     parser.add_argument(
         "--delta-ll",
         type=positive_num,
@@ -127,7 +217,16 @@ def add_delta_ll_argument(parser) -> None:
     )
 
 
-def add_sample_sizes_argument(parser) -> None:
+def add_sample_sizes_argument(parser: argparse.ArgumentParser) -> None:
+    """
+    Adds an argument to a parser to specify the sample sizes of populations for demographic analysis.
+
+    Parameters
+    ----------
+    parser : argparse.ArgumentParser
+        The parser object to which the sample sizes argument will be added.
+
+    """
     parser.add_argument(
         "--sample-sizes",
         type=positive_int,
@@ -138,7 +237,16 @@ def add_sample_sizes_argument(parser) -> None:
     )
 
 
-def add_eps_argument(parser) -> None:
+def add_eps_argument(parser: argparse.ArgumentParser) -> None:
+    """
+    Adds an argument to a parser to specify the step sizes for Godambe analysis.
+
+    Parameters
+    ----------
+    parser : argparse.ArgumentParser
+        The parser object to which the epsilon (step sizes) argument will be added.
+
+    """
     parser.add_argument(
         "--eps",
         default=[0.1, 0.01, 0.001],
@@ -149,7 +257,16 @@ def add_eps_argument(parser) -> None:
     )
 
 
-def add_popt_argument(parser) -> None:
+def add_popt_argument(parser: argparse.ArgumentParser) -> None:
+    """
+    Adds arguments to a parser for specifying files containing best-fit parameters for demographic and DFE models.
+
+    Parameters
+    ----------
+    parser : argparse.ArgumentParser
+        The parser object to which the best-fit parameter file arguments will be added.
+
+    """
     parser.add_argument(
         "--demo-popt",
         type=existed_file,
@@ -165,7 +282,16 @@ def add_popt_argument(parser) -> None:
     )
 
 
-def add_dfe_argument(parser) -> None:
+def add_dfe_argument(parser: argparse.ArgumentParser) -> None:
+    """
+    Adds arguments to a parser for specifying cache files and probability density functions used in DFE (Distribution of Fitness Effects) analysis.
+
+    Parameters
+    ----------
+    parser : argparse.ArgumentParser
+        The parser object to which the DFE cache and PDF arguments will be added.
+
+    """
     parser.add_argument(
         "--cache1d",
         type=existed_file,
@@ -192,7 +318,16 @@ def add_dfe_argument(parser) -> None:
 
 
 # Currently this command is only needed for param_names.
-def add_mix_pdf_argument(parser) -> None:
+def add_mix_pdf_argument(parser: argparse.ArgumentParser) -> None:
+    """
+    Adds an argument to a parser for specifying a mixed probability density function (PDF) model name used in joint DFE inference.
+
+    Parameters
+    ----------
+    parser : argparse.ArgumentParser
+        The parser object to which the mixed PDF model name argument will be added.
+
+    """
     parser.add_argument(
         "--mix-pdf",
         dest="mix_pdf",
@@ -202,7 +337,17 @@ def add_mix_pdf_argument(parser) -> None:
     )
 
 
-def add_inference_argument(parser) -> None:
+def add_inference_argument(parser: argparse.ArgumentParser) -> None:
+    """
+    Adds a series of arguments to a parser related to inference configurations for demographic models,
+    including initial parameters, output file naming, convergence criteria, and computational settings.
+
+    Parameters
+    ----------
+    parser : argparse.ArgumentParser
+        The parser object to which all inference-related arguments will be added.
+
+    """
     parser.add_argument(
         "--p0",
         default=-1,
@@ -304,7 +449,9 @@ def add_inference_argument(parser) -> None:
     )
 
 
-def add_p0_argument(parser) -> None:
+def add_p0_argument(parser: argparse.ArgumentParser) -> None:
+    """
+    """
     p0_req = False
     if 'snm_1d' not in sys.argv and 'snm_2d' not in sys.argv:
         p0_req = True
@@ -321,7 +468,9 @@ def add_p0_argument(parser) -> None:
     )
 
 
-def make_dir(path) -> None:
+def make_dir(path: str) -> None:
+    """
+    """
     parent_dir = os.path.dirname(path)
     if parent_dir != '':
         os.makedirs(parent_dir, exist_ok=True)