diff --git a/CHANGELOG.md b/CHANGELOG.md index 5081b5fc..73e8f319 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,20 @@ ## [0.2.2] - 2024-XX-XX +**Documentation** + +- Various fixes in documentation, including documenting returned fits. + +**Breaking changes** + +- The `return_posteriors` argument has been removed and replaced with `return_fit`. + An instance of one of two previously internal classes, `ExpectationPropagation` + and `BeliefPropagation`, are now returned when `return_fit=True`, and posteriors can + be obtained using `fit.node_posteriors()`. + +- Topology-only dating (setting `mutation_rate=None`) has been removed for tree sequences + of more than one tree, as tests have found that span-weighting the conditional coalescent + causes substantial bias. ## [0.2.1] - 2024-07-31 diff --git a/docs/Makefile b/docs/Makefile index 61dc187d..1b909c7d 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,7 +1,7 @@ # Need to set PYTHONPATH so that we pick up the local tsdate PYPATH=$(shell pwd)/../ TSDATE_VERSION:=$(shell PYTHONPATH=${PYPATH} \ - python3 -c 'import tsdate; print(tsdate.__version__.split("+")[0])') + python -c 'import tsdate; print(tsdate.__version__.split("+")[0])') BUILDDIR = _build @@ -16,4 +16,4 @@ dist: PYTHONPATH=${PYPATH} ./build.sh clean: - rm -fR $(BUILDDIR) \ No newline at end of file + rm -fR $(BUILDDIR) diff --git a/docs/_config.yml b/docs/_config.yml index 747e3b2a..4b39fcda 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -35,6 +35,7 @@ html: sphinx: extra_extensions: - sphinx.ext.autodoc + - sphinx.ext.mathjax - sphinx.ext.autosummary - sphinx.ext.todo - sphinx.ext.viewcode diff --git a/docs/python-api.md b/docs/python-api.md index 43b51c6b..847a95ec 100644 --- a/docs/python-api.md +++ b/docs/python-api.md @@ -32,13 +32,28 @@ This page provides formal documentation for the _tsdate_ Python API. .. autofunction:: tsdate.maximization ``` +## Underlying fit objects + +Instances of the classes below are returned by setting `return_fit=True` +when dating. The fits can be inspected to obtain more detailed results than +may be present in the returned tree sequence and its metadata. The classes +are not intended to be instantiated directly. + +```{eval-rst} +.. autoclass:: tsdate.discrete.BeliefPropagation() + :members: + +.. autoclass:: tsdate.variational.ExpectationPropagation() + :members: +``` + ## Prior and Time Discretisation Options ```{eval-rst} .. autofunction:: tsdate.build_prior_grid .. autofunction:: tsdate.build_parameter_grid -.. autoclass:: tsdate.base.NodeGridValues -.. autodata:: tsdate.base.DEFAULT_APPROX_PRIOR_SIZE +.. autoclass:: tsdate.node_time_class.NodeTimeValues +.. autodata:: tsdate.prior.DEFAULT_APPROX_PRIOR_SIZE ``` ## Variable population sizes diff --git a/docs/usage.md b/docs/usage.md index d89f2385..d51a14b1 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -175,23 +175,20 @@ running _tsdate_: The metadata values (currently saved as `mn` and `vr`) need not be constrained by the topology of the tree sequence, and should be used in preference e.g. to `nodes_time` and `mutations_time` when evaluating the accuracy of _tsdate_. -2. The `return_posteriors` parameter can be used when calling {func}`tsdate.date`, which - then returns both the dated tree sequence and a dictionary specifying the posterior - distributions. - -