From c5ae4bd61b0d9220e6817ebb98e3412bdc01f4ed Mon Sep 17 00:00:00 2001
From: jac16 <jennifer.clark@nist.gov>
Date: Wed, 16 Aug 2023 17:34:11 -0400
Subject: [PATCH] Updated SurvivalProbabilty docs

---
 package/CHANGELOG                            |  4 +++-
 package/MDAnalysis/analysis/waterdynamics.py | 19 ++++++++++++-------
 2 files changed, 15 insertions(+), 8 deletions(-)

diff --git a/package/CHANGELOG b/package/CHANGELOG
index 5c1d8902acf..be686888025 100644
--- a/package/CHANGELOG
+++ b/package/CHANGELOG
@@ -13,7 +13,7 @@ The rules for this file:
   * release numbers follow "Semantic Versioning" http://semver.org
 
 ------------------------------------------------------------------------------
-??/??/?? IAlibay, hmacdope, pillose
+??/??/?? IAlibay, hmacdope, pillose, jaclark5
 
  * 2.7.0
 
@@ -23,6 +23,8 @@ Fixes
 Enhancements
 
 Changes
+  * Update documentation for SurvivalProbabilty to be more clear
+    (Issue #4247)
   * Cython DEF statments have been replaced with compile time integer constants
     as DEF is deprecated as of Cython>=3.0 (Issue #4237, PR #4246)
 
diff --git a/package/MDAnalysis/analysis/waterdynamics.py b/package/MDAnalysis/analysis/waterdynamics.py
index f6d96d55634..81a6dfacfb9 100644
--- a/package/MDAnalysis/analysis/waterdynamics.py
+++ b/package/MDAnalysis/analysis/waterdynamics.py
@@ -885,15 +885,17 @@ def run(self, **kwargs):
 
 class SurvivalProbability(object):
     r"""
-    Survival Probability (SP) gives the probability for a group of particles to remain in a certain region.
-    The SP is given by:
+    Survival Probability (SP) gives the probability for a group of particles to remain
+    in a certain region. The SP is given by:
 
     .. math::
-        P(\tau) = \frac1T \sum_{t=1}^T \frac{N(t,t+\tau)}{N(t)}
+        P(\tau) = \langle \frac{ N(t, t + \tau )} { N(t) }\rangle
 
-    where :math:`T` is the maximum time of simulation, :math:`\tau` is the
-    timestep, :math:`N(t)` the number of particles at time :math:`t`, and
-    :math:`N(t, t+\tau)` is the number of particles at every frame from :math:`t` to `\tau`.
+    where :math:`\tau` is the timestep, :math:`N(t)` the number of particles at time 
+    :math:`t`, and :math:`N(t, t+\tau)` is the number of particles at every frame from 
+    :math:`t` to :math:`t + \tau`. The angular brackets represent an average over all time 
+    origins, :math:`t`. See :func:`MDAnalysis.lib.correlations.autocorrelation` for
+    technical details.
 
 
     Parameters
@@ -902,7 +904,8 @@ class SurvivalProbability(object):
       Universe object
     select : str
       Selection string; any selection is allowed. With this selection you
-      define the region/zone where to analyze, e.g.: "resname SOL and around 5 (resid 10)". See `SP-examples`_.
+      define the region/zone where to analyze, e.g.: "resname SOL and around 5 
+      (resid 10)". See `SP-examples`_.
     verbose : Boolean, optional
       When True, prints progress and comments to the console.
 
@@ -928,6 +931,8 @@ class SurvivalProbability(object):
        The `stop` keyword as passed to :meth:`SurvivalProbability.run` has now
        changed behaviour and will act in an `exclusive` manner (instead of it's
        previous `inclusive` behaviour),
+    .. versionchanged:: 2.7.0
+       Updated docs to align with discrete autocorrelation function.
     """
 
     def __init__(self, universe, select, verbose=False):