From 1140f34ef2b667ae0c61bf609742c8a365901e09 Mon Sep 17 00:00:00 2001 From: Yan Wong Date: Fri, 17 Nov 2023 22:05:03 +0000 Subject: [PATCH] Document DEFAULT_APPROX_PRIOR_SIZE --- docs/python-api.md | 2 ++ tsdate/base.py | 6 +++++- tsdate/core.py | 4 ++-- tsdate/prior.py | 34 ++++++++++++++++++---------------- 4 files changed, 27 insertions(+), 19 deletions(-) diff --git a/docs/python-api.md b/docs/python-api.md index 61c74b61..4a786566 100644 --- a/docs/python-api.md +++ b/docs/python-api.md @@ -34,6 +34,8 @@ This page provides formal documentation for the `tsdate` Python API. .. autofunction:: tsdate.build_parameter_grid .. autoclass:: tsdate.base.NodeGridValues + +.. autodata:: tsdate.base.DEFAULT_APPROX_PRIOR_SIZE ``` ## Variable population sizes diff --git a/tsdate/base.py b/tsdate/base.py index 4880eec2..3aaef198 100644 --- a/tsdate/base.py +++ b/tsdate/base.py @@ -29,7 +29,11 @@ LIN = "linear" LOG = "logarithmic" GAMMA_PAR = "gamma_parameter" -NTIPS_DEFAULT_PRIOR_APPROX = 10000 # n_tips above which to use an approx for the prior + +#: The default value for `approx_prior_size` (see :func:`~tsdate.build_prior_grid` and +#: :func:`~tsdate.build_parameter_grid`) +DEFAULT_APPROX_PRIOR_SIZE = 10000 + # Bit 20 is set in node flags when they are samples not at time zero in the sampledata # file NODE_IS_HISTORIC_SAMPLE = 1 << 20 diff --git a/tsdate/core.py b/tsdate/core.py index 8db930ee..2cabeb1d 100644 --- a/tsdate/core.py +++ b/tsdate/core.py @@ -1603,9 +1603,9 @@ def variational_dates( ) # Default to not creating approximate priors unless ts has - # greater than NTIPS_DEFAULT_PRIOR_APPROX samples + # greater than DEFAULT_APPROX_PRIOR_SIZE samples approx_priors = False - if tree_sequence.num_samples > base.NTIPS_DEFAULT_PRIOR_APPROX: + if tree_sequence.num_samples > base.DEFAULT_APPROX_PRIOR_SIZE: approx_priors = True if priors is None: diff --git a/tsdate/prior.py b/tsdate/prior.py index cb69f02c..a79cdbe7 100644 --- a/tsdate/prior.py +++ b/tsdate/prior.py @@ -193,7 +193,7 @@ def add(self, total_tips, approximate=None): if approximate is not None: self.approximate = approximate else: - if total_tips >= base.NTIPS_DEFAULT_PRIOR_APPROX: + if total_tips >= base.DEFAULT_APPROX_PRIOR_SIZE: self.approximate = True else: self.approximate = False @@ -204,10 +204,10 @@ def add(self, total_tips, approximate=None): " the ConditionalCoalescentTimes object with a non-zero number" ) - if not self.approximate and total_tips >= base.NTIPS_DEFAULT_PRIOR_APPROX: + if not self.approximate and total_tips >= base.DEFAULT_APPROX_PRIOR_SIZE: logging.warning( "Calculating exact priors for more than " - f"{base.NTIPS_DEFAULT_PRIOR_APPROX} tips. Consider " + f"{base.DEFAULT_APPROX_PRIOR_SIZE} tips. Consider " "setting `approximate=True` for a faster calculation." ) @@ -1069,7 +1069,7 @@ def __init__( ): if approximate_priors: if not approx_prior_size: - approx_prior_size = base.NTIPS_DEFAULT_PRIOR_APPROX + approx_prior_size = base.DEFAULT_APPROX_PRIOR_SIZE else: if approx_prior_size is not None: raise ValueError( @@ -1215,12 +1215,13 @@ def build_grid( times are measured in generations. :param int or array_like timepoints: The number of quantiles used to create the time slices, or manually-specified time slices as a numpy array. Default: 20 - :param bool approximate_priors: Whether to use a precalculated approximate prior or - exactly calculate prior. If approximate prior has not been precalculated, tsdate - will do so and cache the result. Default: False - :param int approx_prior_size: Number of samples from which to precalculate prior. - Should only enter value if approximate_priors=True. If approximate_priors=True - and no value specified, defaults to 1000. Default: None + :param bool approximate_priors: Whether to use a precalculated approximation to the + treewise conditional coalescent prior if there are large numbers of sample tips. + If an approximate prior has not been precalculated, tsdate will do so and cache + the result. Default: False + :param int approx_prior_size: Number of samples above which a precalculated prior is + used. Only valid if ``approximate_priors`` is True. Default: ``None``, treated as + :data:`~tsdate.base.DEFAULT_APPROX_PRIOR_SIZE` if ``approximate_priors`` is True. :param string prior_distr: What distribution to use to approximate the conditional coalescent prior. Can be "lognorm" for the lognormal distribution (generally a better fit, but slightly slower to calculate) or "gamma" for the gamma @@ -1264,12 +1265,13 @@ def parameter_grid( epoch breakpoints and effective population sizes. Using standard (unscaled) values for ``population_size`` results in a prior where times are measured in generations. - :param bool approximate_priors: Whether to use a precalculated approximate prior or - exactly calculate prior. If approximate prior has not been precalculated, tsdate - will do so and cache the result. Default: False - :param int approx_prior_size: Number of samples from which to precalculate prior. - Should only enter value if approximate_priors=True. If approximate_priors=True - and no value specified, defaults to 1000. Default: None + :param bool approximate_priors: Whether to use a precalculated approximation to the + treewise conditional coalescent prior if there are large numbers of sample tips. + If an approximate prior has not been precalculated, tsdate will do so and cache + the result. Default: False + :param int approx_prior_size: Number of samples above which a precalculated prior is + used. Only valid if ``approximate_priors`` is True. Default: ``None``, treated as + :data:`~tsdate.base.DEFAULT_APPROX_PRIOR_SIZE` if ``approximate_priors`` is True. :rtype: base.NodeGridValues """