Update median doc to note return value of even-sized input

heitorschueroff · heitorschueroff · commit bcfd7d8d2a89 · 2020-09-14T06:46:44.000-07:00
ghstack-source-id: d7825cd Pull Request resolved: #44562
diff --git a/torch/_torch_docs.py b/torch/_torch_docs.py
@@ -4577,6 +4577,12 @@ def merge_dicts(*dicts):
 
 Returns the median value of all elements in the :attr:`input` tensor.
 
+.. note::
+    The median is not unique for :attr:`input` tensors with an even number
+    of elements. In this case the lower of the two medians is returned. To
+    compute the mean of both medians in :attr:`input`, use :func:`torch.quantile`
+    with ``q=0.5`` instead.
+
 .. warning::
     This function produces deterministic (sub)gradients unlike ``median(dim=0)``
 
@@ -4604,6 +4610,12 @@ def merge_dicts(*dicts):
 Otherwise, :attr:`dim` is squeezed (see :func:`torch.squeeze`), resulting in
 the outputs tensor having 1 fewer dimension than :attr:`input`.
 
+.. note::
+    The median is not unique for :attr:`input` tensors with an even number
+    of elements in the dimension :attr:`dim`. In this case the lower of the
+    two medians is returned. To compute the mean of both medians in
+    :attr:`input`, use :func:`torch.quantile` with ``q=0.5`` instead.
+
 .. warning::
     ``indices`` does not necessarily contain the first occurrence of each
     median value found, unless it is unique.
