addressing reviews: applying suggestion about variable name change and mentioning in docs that the history matching done here is a single run but not performed in waves

Author: marjanfamili

autoemulate/history_matching.py

@@ -1,13 +1,22 @@
 import numpy as np
 
 
-def history_matching(obs, expectations, threshold=3.0, discrepancy=0.0, rank=1):
+def history_matching(obs, predictions, threshold=3.0, discrepancy=0.0, rank=1):
     """
     Perform history matching to compute implausibility and identify NROY and RO points.
-
+    This implementation performs history matching as a single run, completing the process
+    in one execution without iterative refinement or staged waves.
+
+    The implausibility is calculated as the absolute difference between the observed and
+    predicted values, normalized by the square root of the sum of the variances of the
+    observed and predicted values. The implausibility is then compared to a threshold to
+    classify the points as NROY or RO. The discrepancy value(s) can be provided as a
+    scalar or an array to account for model discrepancy.
+    The rank parameter is used to select the number of observations to consider for implausibility calculation.
+    The default value is 1, which corresponds to the most recent observation.
     Parameters:
         obs (tuple): Observations as (mean, variance).
-        expectations (tuple): Predicted (mean, variance).
+        predictions (tuple): Predicted (mean, variance).
         threshold (float): Implausibility threshold for NROY classification.
         discrepancy (float or ndarray): Discrepancy value(s).
         rank (int): Rank for implausibility calculation.
@@ -16,7 +25,7 @@ def history_matching(obs, expectations, threshold=3.0, discrepancy=0.0, rank=1):
         dict: Contains implausibility (I), NROY indices, and RO indices.
     """
     obs_mean, obs_var = np.atleast_1d(obs[0]), np.atleast_1d(obs[1])
-    pred_mean, pred_var = np.atleast_1d(expectations[0]), np.atleast_1d(expectations[1])
+    pred_mean, pred_var = np.atleast_1d(predictions[0]), np.atleast_1d(predictions[1])
 
     discrepancy = np.atleast_1d(discrepancy)
     n_obs = len(obs_mean)