.. index:: single: statisticsp
.. _statisticsp/0:

.. rst-class:: right

**protocol**

``statisticsp``
===============

Statistical calculations over a list of numbers protocol.

| **Availability:** 
|    ``logtalk_load(statistics(loader))``

| **Author:** Paulo Moura
| **Version:** 1:4:0
| **Date:** 2026-02-20

| **Compilation flags:**
|    ``static``


| **Dependencies:**
|   (none)


| **Remarks:**
|    (none)

| **Inherited public predicates:**
|    (none)

.. contents::
   :local:
   :backlinks: top

Public predicates
-----------------

.. index:: product/2
.. _statisticsp/0::product/2:

``product/2``
^^^^^^^^^^^^^

Calculates the product of all list numbers. Fails if the list is empty.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``product(List,Product)``
| **Mode and number of proofs:**
|    ``product(+list(number),-number)`` - ``zero_or_one``


------------

.. index:: sum/2
.. _statisticsp/0::sum/2:

``sum/2``
^^^^^^^^^

Calculates the sum of all list numbers. Fails if the list is empty.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``sum(List,Sum)``
| **Mode and number of proofs:**
|    ``sum(+list(number),-number)`` - ``zero_or_one``


------------

.. index:: min/2
.. _statisticsp/0::min/2:

``min/2``
^^^^^^^^^

Determines the minimum value in a list of numbers. Fails if the list is empty.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``min(List,Minimum)``
| **Mode and number of proofs:**
|    ``min(+list,-number)`` - ``zero_or_one``


------------

.. index:: max/2
.. _statisticsp/0::max/2:

``max/2``
^^^^^^^^^

Determines the list maximum value in a list of numbers. Fails if the list is empty.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``max(List,Maximum)``
| **Mode and number of proofs:**
|    ``max(+list,-number)`` - ``zero_or_one``


------------

.. index:: min_max/3
.. _statisticsp/0::min_max/3:

``min_max/3``
^^^^^^^^^^^^^

Determines the minimum and maximum values in a list of numbers. Fails if the list is empty.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``min_max(List,Minimum,Maximum)``
| **Mode and number of proofs:**
|    ``min_max(+list(number),-number,-number)`` - ``zero_or_one``


------------

.. index:: range/2
.. _statisticsp/0::range/2:

``range/2``
^^^^^^^^^^^

Range is the length of the smallest interval which contains all the numbers in List. Fails if the list is empty.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``range(List,Range)``
| **Mode and number of proofs:**
|    ``range(+list,-number)`` - ``zero_or_one``


------------

.. index:: arithmetic_mean/2
.. _statisticsp/0::arithmetic_mean/2:

``arithmetic_mean/2``
^^^^^^^^^^^^^^^^^^^^^

Calculates the arithmetic mean of a list of numbers. Fails if the list is empty.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``arithmetic_mean(List,Mean)``
| **Mode and number of proofs:**
|    ``arithmetic_mean(+list(number),-float)`` - ``zero_or_one``


------------

.. index:: geometric_mean/2
.. _statisticsp/0::geometric_mean/2:

``geometric_mean/2``
^^^^^^^^^^^^^^^^^^^^

Calculates the geometric mean of a list of numbers. Fails if the list is empty.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``geometric_mean(List,Mean)``
| **Mode and number of proofs:**
|    ``geometric_mean(+list(number),-float)`` - ``zero_or_one``


------------

.. index:: harmonic_mean/2
.. _statisticsp/0::harmonic_mean/2:

``harmonic_mean/2``
^^^^^^^^^^^^^^^^^^^

Calculates the harmonic mean of a list of numbers. Fails if the list is empty.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``harmonic_mean(List,Mean)``
| **Mode and number of proofs:**
|    ``harmonic_mean(+list(number),-float)`` - ``zero_or_one``


------------

.. index:: weighted_mean/3
.. _statisticsp/0::weighted_mean/3:

``weighted_mean/3``
^^^^^^^^^^^^^^^^^^^

Calculates the weighted mean of a list of numbers. Fails if the list is empty or if the two lists have different lengths. Weights are assumed to be non-negative.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``weighted_mean(Weights,List,Mean)``
| **Mode and number of proofs:**
|    ``weighted_mean(+list(number),+list(number),-float)`` - ``zero_or_one``


------------

.. index:: median/2
.. _statisticsp/0::median/2:

``median/2``
^^^^^^^^^^^^

Calculates the median of a list of numbers. Fails if the list is empty.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``median(List,Median)``
| **Mode and number of proofs:**
|    ``median(+list(number),-float)`` - ``zero_or_one``


------------

.. index:: modes/2
.. _statisticsp/0::modes/2:

``modes/2``
^^^^^^^^^^^

Returns the list of modes of a list of numbers in ascending order. Fails if the list is empty.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``modes(List,Modes)``
| **Mode and number of proofs:**
|    ``modes(+list(number),-list(number))`` - ``zero_or_one``


------------

.. index:: average_deviation/3
.. _statisticsp/0::average_deviation/3:

``average_deviation/3``
^^^^^^^^^^^^^^^^^^^^^^^

Calculates the average absolute deviation of a list of numbers given a central tendency (e.g., mean, median, or mode). Fails if the list is empty.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``average_deviation(List,CentralTendency,Deviation)``
| **Mode and number of proofs:**
|    ``average_deviation(+list(number),+float,-float)`` - ``zero_or_one``


------------

.. index:: mean_deviation/2
.. _statisticsp/0::mean_deviation/2:

``mean_deviation/2``
^^^^^^^^^^^^^^^^^^^^

Calculates the mean absolute deviation of a list of numbers. Fails if the list is empty.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``mean_deviation(List,Deviation)``
| **Mode and number of proofs:**
|    ``mean_deviation(+list(number),-float)`` - ``zero_or_one``


------------

.. index:: median_deviation/2
.. _statisticsp/0::median_deviation/2:

``median_deviation/2``
^^^^^^^^^^^^^^^^^^^^^^

Calculates the median absolute deviation of a list of numbers. Fails if the list is empty.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``median_deviation(List,Deviation)``
| **Mode and number of proofs:**
|    ``median_deviation(+list(number),-float)`` - ``zero_or_one``


------------

.. index:: standard_deviation/2
.. _statisticsp/0::standard_deviation/2:

``standard_deviation/2``
^^^^^^^^^^^^^^^^^^^^^^^^

Calculates the standard deviation of a list of numbers. Fails if the list is empty.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``standard_deviation(List,Deviation)``
| **Mode and number of proofs:**
|    ``standard_deviation(+list(number),-float)`` - ``zero_or_one``


------------

.. index:: coefficient_of_variation/2
.. _statisticsp/0::coefficient_of_variation/2:

``coefficient_of_variation/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Calculates the coefficient of variation of a list of numbers. Fails if the list is empty.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``coefficient_of_variation(List,Coefficient)``
| **Mode and number of proofs:**
|    ``coefficient_of_variation(+list(number),-float)`` - ``zero_or_one``


------------

.. index:: relative_standard_deviation/2
.. _statisticsp/0::relative_standard_deviation/2:

``relative_standard_deviation/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Calculates the relative standard deviation of a list of numbers. Fails if the list is empty.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``relative_standard_deviation(List,Percentage)``
| **Mode and number of proofs:**
|    ``relative_standard_deviation(+list(number),-float)`` - ``zero_or_one``


------------

.. index:: skewness/2
.. _statisticsp/0::skewness/2:

``skewness/2``
^^^^^^^^^^^^^^

Calculates the (moment) skewness of a list of numbers. Fails if the list is empty.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``skewness(List,Skewness)``
| **Mode and number of proofs:**
|    ``skewness(+list(number),-float)`` - ``zero_or_one``


------------

.. index:: kurtosis/2
.. _statisticsp/0::kurtosis/2:

``kurtosis/2``
^^^^^^^^^^^^^^

Calculates the (excess) kurtosis of a list of numbers. Fails if the list is empty.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``kurtosis(List,Kurtosis)``
| **Mode and number of proofs:**
|    ``kurtosis(+list(number),-float)`` - ``zero_or_one``


------------

.. index:: variance/2
.. _statisticsp/0::variance/2:

``variance/2``
^^^^^^^^^^^^^^

Calculates the unbiased variance of a list of numbers. Fails if the list is empty.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``variance(List,Variance)``
| **Mode and number of proofs:**
|    ``variance(+list(number),-float)`` - ``zero_or_one``


------------

.. index:: z_normalization/2
.. _statisticsp/0::z_normalization/2:

``z_normalization/2``
^^^^^^^^^^^^^^^^^^^^^

Normalizes a list of number such that for the resulting list the mean of is close to zero and the standard deviation is close to 1. Fails if the list is empty.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``z_normalization(List,NormalizedList)``
| **Mode and number of proofs:**
|    ``z_normalization(+list(number),-list(float))`` - ``zero_or_one``


------------

.. index:: fractile/3
.. _statisticsp/0::fractile/3:

``fractile/3``
^^^^^^^^^^^^^^

Calculates the smallest value in a list of numbers such that the list elements in its fraction ``P`` are less or equal to that value (with ``P`` in the open interval ``(0.0, 1.0)``). Fails if the list is empty.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``fractile(P,List,Fractile)``
| **Mode and number of proofs:**
|    ``fractile(+float,+list(integer),-integer)`` - ``zero_or_one``
|    ``fractile(+float,+list(float),-float)`` - ``zero_or_one``


------------

.. index:: percentile/3
.. _statisticsp/0::percentile/3:

``percentile/3``
^^^^^^^^^^^^^^^^

Calculates the P-th percentile of a list of numbers (with ``P`` in the open interval ``(0, 100)``). Fails if the list is empty.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``percentile(P,List,Percentile)``
| **Mode and number of proofs:**
|    ``percentile(+number,+list(number),-number)`` - ``zero_or_one``


------------

.. index:: quartiles/4
.. _statisticsp/0::quartiles/4:

``quartiles/4``
^^^^^^^^^^^^^^^

Calculates the quartiles (Q1, Q2, Q3) of a list of numbers. Q2 is the median. Q1 and Q3 are the medians of the lower and upper halves, respectively. Fails if the list has fewer than two elements.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``quartiles(List,Q1,Q2,Q3)``
| **Mode and number of proofs:**
|    ``quartiles(+list(number),-number,-number,-number)`` - ``zero_or_one``


------------

.. index:: interquartile_range/2
.. _statisticsp/0::interquartile_range/2:

``interquartile_range/2``
^^^^^^^^^^^^^^^^^^^^^^^^^

Calculates the interquartile range (Q3 - Q1) of a list of numbers. Fails if the list has fewer than two elements.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``interquartile_range(List,IQR)``
| **Mode and number of proofs:**
|    ``interquartile_range(+list(number),-number)`` - ``zero_or_one``


------------

.. index:: covariance/3
.. _statisticsp/0::covariance/3:

``covariance/3``
^^^^^^^^^^^^^^^^

Calculates the covariance of two lists of numbers. Fails if the lists are empty or have different lengths.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``covariance(List1,List2,Covariance)``
| **Mode and number of proofs:**
|    ``covariance(+list(number),+list(number),-float)`` - ``zero_or_one``


------------

.. index:: correlation/3
.. _statisticsp/0::correlation/3:

``correlation/3``
^^^^^^^^^^^^^^^^^

Calculates the Pearson correlation coefficient of two lists of numbers. Fails if the lists are empty or have different lengths.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``correlation(List1,List2,Correlation)``
| **Mode and number of proofs:**
|    ``correlation(+list(number),+list(number),-float)`` - ``zero_or_one``


------------

.. index:: rank_correlation/3
.. _statisticsp/0::rank_correlation/3:

``rank_correlation/3``
^^^^^^^^^^^^^^^^^^^^^^

Calculates the Spearman rank correlation coefficient of two lists of numbers. Handles ties using average ranks. Fails if the lists are empty or have different lengths.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``rank_correlation(List1,List2,Correlation)``
| **Mode and number of proofs:**
|    ``rank_correlation(+list(number),+list(number),-float)`` - ``zero_or_one``


------------

.. index:: trimmed_mean/3
.. _statisticsp/0::trimmed_mean/3:

``trimmed_mean/3``
^^^^^^^^^^^^^^^^^^

Calculates the trimmed mean of a list of numbers by removing a fraction of extreme values from both ends (with the fraction in the half-open interval ``[0.0, 0.5)``). Fails if the list is empty or if too many elements would be trimmed.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``trimmed_mean(Fraction,List,Mean)``
| **Mode and number of proofs:**
|    ``trimmed_mean(+float,+list(number),-float)`` - ``zero_or_one``


------------

.. index:: sum_of_squares/2
.. _statisticsp/0::sum_of_squares/2:

``sum_of_squares/2``
^^^^^^^^^^^^^^^^^^^^

Calculates the sum of squared deviations from the arithmetic mean of a list of numbers. Fails if the list is empty.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``sum_of_squares(List,Sum)``
| **Mode and number of proofs:**
|    ``sum_of_squares(+list(number),-float)`` - ``zero_or_one``


------------

.. index:: central_moment/3
.. _statisticsp/0::central_moment/3:

``central_moment/3``
^^^^^^^^^^^^^^^^^^^^

Calculates the K-th central moment of a list of numbers. The K-th central moment is the mean of the deviations from the mean raised to the power K (with ``K > 0``). Fails if the list is empty.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``central_moment(K,List,Moment)``
| **Mode and number of proofs:**
|    ``central_moment(+positive_integer,+list(number),-float)`` - ``zero_or_one``


------------

.. index:: min_max_normalization/2
.. _statisticsp/0::min_max_normalization/2:

``min_max_normalization/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Normalizes a list of numbers to the interval ``[0.0, 1.0]`` using min-max normalization. Fails if the list is empty or if all values are equal.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``min_max_normalization(List,NormalizedList)``
| **Mode and number of proofs:**
|    ``min_max_normalization(+list(number),-list(float))`` - ``zero_or_one``


------------

.. index:: frequency_distribution/2
.. _statisticsp/0::frequency_distribution/2:

``frequency_distribution/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Computes the frequency distribution of a list of numbers, returning a list of ``Value-Count`` pairs in ascending order of value. Fails if the list is empty.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``frequency_distribution(List,Distribution)``
| **Mode and number of proofs:**
|    ``frequency_distribution(+list(number),-list(pair(number,integer)))`` - ``zero_or_one``


------------

.. index:: standard_error/2
.. _statisticsp/0::standard_error/2:

``standard_error/2``
^^^^^^^^^^^^^^^^^^^^

Calculates the standard error of the mean of a list of numbers. Fails if the list is empty.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``standard_error(List,Error)``
| **Mode and number of proofs:**
|    ``standard_error(+list(number),-float)`` - ``zero_or_one``


------------

.. index:: mean_squared_error/3
.. _statisticsp/0::mean_squared_error/3:

``mean_squared_error/3``
^^^^^^^^^^^^^^^^^^^^^^^^

Calculates the mean squared error between two lists of numbers. Fails if the lists are empty or have different lengths.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``mean_squared_error(List1,List2,Error)``
| **Mode and number of proofs:**
|    ``mean_squared_error(+list(number),+list(number),-float)`` - ``zero_or_one``


------------

.. index:: root_mean_squared_error/3
.. _statisticsp/0::root_mean_squared_error/3:

``root_mean_squared_error/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Calculates the root mean squared error between two lists of numbers. Fails if the lists are empty or have different lengths.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``root_mean_squared_error(List1,List2,Error)``
| **Mode and number of proofs:**
|    ``root_mean_squared_error(+list(number),+list(number),-float)`` - ``zero_or_one``


------------

.. index:: valid/1
.. _statisticsp/0::valid/1:

``valid/1``
^^^^^^^^^^^

Term is a closed list of numbers.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``valid(Term)``
| **Mode and number of proofs:**
|    ``valid(@nonvar)`` - ``zero_or_one``


------------

Protected predicates
--------------------

(none)

Private predicates
------------------

(none)

Operators
---------

(none)

.. seealso::

   :ref:`statistics <statistics/0>`, :ref:`sample <sample/0>`, :ref:`population <population/0>`

