- """A numeric population with some statistics such as median, mean, pN,
- stdev, etc...
+ """This object *store* a numerical population in a way that enables relatively
+ fast addition of new numbers (:math:`O(2log_2 n)`) and instant access to the
+ median value in the population (:math:`O(1)`). It also provides other population
+ summary statistics such as the :meth:`mode`, :meth:`get_percentile` and
+ :meth:`stdev`.
+
+ .. note::
+
+ Because this class stores a copy of all numbers added to it, it shouldn't
+ be used for very large populations. Consider sampling.