From 0d34a863102bd0ae10b32dd63cd2be5bb66ed2ae Mon Sep 17 00:00:00 2001
From: Hagen Wierstorf <hwierstorf@audeering.com>
Date: Fri, 23 Aug 2024 09:43:42 +0200
Subject: [PATCH] Add docstring examples

---
 audpsychometric/core/gold_standard.py | 39 ++++++++++++++++++++++++---
 1 file changed, 35 insertions(+), 4 deletions(-)

diff --git a/audpsychometric/core/gold_standard.py b/audpsychometric/core/gold_standard.py
index 292f389..2361593 100644
--- a/audpsychometric/core/gold_standard.py
+++ b/audpsychometric/core/gold_standard.py
@@ -82,6 +82,16 @@ def confidence_numerical(
     Returns:
         numerical confidence score(s)
 
+    Examples:
+        >>> confidence_numerical([0, 1], 0, 1)
+        0.0
+        >>> confidence_numerical([0, 1], 0, 2)
+        0.5
+        >>> confidence_numerical([0, 0], 0, 1)
+        1.0
+        >>> confidence_numerical([0, np.nan], 0, 1)
+        nan
+
     """
     ratings = np.atleast_2d(np.array(ratings))
     cutoff_max = maximum - 1 / 2 * (minimum + maximum)
@@ -115,8 +125,8 @@ def evaluator_weighted_estimator(
 
     Args:
         ratings: ratings.
-            When given as a 1-dimensional array,
-            it is treated as a row vector
+            Has to contain more than one rater
+            and more than one stimuli
         axis: axis along which the EWE is computed.
             A value of ``1``
             assumes stimuli as rows
@@ -125,6 +135,10 @@ def evaluator_weighted_estimator(
     Returns:
         EWE over raters
 
+    Examples:
+        >>> evaluator_weighted_estimator([[1, 1, 0], [2, 2, 1]])
+        array([0.66666667, 1.66666667])
+
     """
     ratings = np.array(ratings)
     confidences = rater_confidence_pearson(ratings, axis=axis)
@@ -155,6 +169,18 @@ def mode(
     Returns:
         mode over raters
 
+    Examples:
+        >>> mode([0, 0, 1])
+        0
+        >>> mode(["a", "a", "b"])
+        'a'
+        >>> mode([0, 2])
+        1
+        >>> mode(["a", "c"])
+        'a'
+        >>> mode([None, None, "a"])
+        'a'
+
     """
     ratings = np.atleast_2d(np.array(ratings))
     return _value_or_array(
@@ -180,8 +206,7 @@ def rater_confidence_pearson(
     Args:
         ratings: ratings.
             Has to contain more than one rater
-            When given as a 1-dimensional array,
-            it is treated as a row vector
+            and more than one stimuli
         axis: axis along which the rater confidence is computed.
             A value of ``1``
             assumes stimuli as rows
@@ -190,6 +215,12 @@ def rater_confidence_pearson(
     Returns:
         rater confidences
 
+    Examples:
+        >>> rater_confidence_pearson([[1, 1, 0], [2, 2, 1]])
+        array([1., 1., 1.])
+        >>> rater_confidence_pearson([[1, 1, 0], [2, 2, 1], [2, 2, 2]])
+        array([0.94491118, 0.94491118, 0.8660254 ])
+
     """
     ratings = np.array(ratings)