tmp

Author: microslaw

pandas/core/generic.py

@@ -5816,7 +5816,7 @@ def sample(
             Missing values in the weights column will be treated as zero.
             Infinite values not allowed.
             When replace = False will not allow ``(n * max(weights) / sum(weights)) > 1``,
-            in order to avoid biased results.
+            in order to avoid biased results. See the Notes below for more details.
         random_state : int, array-like, BitGenerator, np.random.RandomState, np.random.Generator, optional
             If int, array-like, or BitGenerator, seed for random number generator.
             If np.random.RandomState or np.random.Generator, use as given.
@@ -5853,6 +5853,10 @@ def sample(
         -----
         If `frac` > 1, `replacement` should be set to `True`.
 
+        When replace = False will not allow ``(n * max(weights) / sum(weights)) > 1``,
+        since that would cause results to be biased. E.g. sampling 2 items without replacement,
+        with weights [100, 1, 1] would yield two last items in 1/2 of cases, instead of 1/102
+
         Examples
         --------
         >>> df = pd.DataFrame(

pandas/core/sample.py

@@ -150,12 +150,12 @@ def sample(
         else:
             raise ValueError("Invalid weights: weights sum to zero")
 
-    if weights is not None:
-        is_max_weight_dominating = size * weights.max() > 1
-        if is_max_weight_dominating and not replace:
+        assert weights is not None  # for mypy
+        if not replace and size * weights.max() > 1:
             raise ValueError(
-                "Invalid weights: If `replace`=False, "
-                "total unit probabilities have to be less than 1"
+                "Weighted sampling cannot be achieved with replace=False. Either "
+                "set replace=True or use smaller weights. See the docstring of "
+                "sample for details."
             )
 
     return random_state.choice(obj_len, size=size, replace=replace, p=weights).astype(

pandas/tests/frame/methods/test_sample.py

@@ -139,18 +139,23 @@ def test_sample_unit_probabilities_raises(self, obj):
         high_variance_weights = [1] * 10
         high_variance_weights[0] = 100
         msg = (
-            "Invalid weights: If `replace`=False, "
-            "total unit probabilities have to be less than 1"
+            "Weighted sampling cannot be achieved with replace=False. Either "
+            "set replace=True or use smaller weights. See the docstring of "
+            "sample for details."
         )
         with pytest.raises(ValueError, match=msg):
             obj.sample(n=2, weights=high_variance_weights, replace=False)
 
+    def test_sample_unit_probabilities_edge_case_do_not_raise(self, obj):
+        # GH#61516
         # edge case, n*max(weights)/sum(weights) == 1
         edge_variance_weights = [1] * 10
         edge_variance_weights[0] = 9
         # should not raise
         obj.sample(n=2, weights=edge_variance_weights, replace=False)
 
+    def test_sample_unit_normal_probabilities_do_not_raise(self, obj):
+        # GH#61516
         low_variance_weights = [1] * 10
         low_variance_weights[0] = 8
         # should not raise