Overview

This is the API documentation for all population and sample statistics procedures.

Mean

fsml_mean

Description

The procedure computes the arithmetic mean. $$\bar{x} = \frac{1}{n} \cdot \sum_{i=1}^{n} x_i$$ where $n$ is the size of (or number of observations in) vector x, $x_i$ are individual elements in x, and $\bar{x}$ is the arithmetic mean of x.

Syntax

result = fsml_mean(x)

Parameters

x: A rank-1 array of type real. Must have a length of at least 2.

Invalid argument values will result in the return of a sentinel value.

Returns

The result is a scalar and the same type as x.

Median

fsml_median

Description

The procedure computes median of vector x and handles tied ranks.

Syntax

result = fsml_median(x)

Parameters

x: A rank-1 array of type real. Must have a length of at least 2.

Invalid argument values will result in the return of a sentinel value.

Returns

The result is a scalar and the same type as x.

Variance

fsml_var

Description

The procedure computes the population or sample variance (depending on passed arguments). $$\operatorname{var}(x) = \frac{1}{n - \nu} \cdot \sum_{i=1}^{n} (x_i - \bar{x})^2$$ where $n$ is the size of (or number of observations in) vector x, $x_i$ are individual elements in x, $\nu$ (ddf) is a degrees of freedom adjustment (ddf = 0.0 for population variance, ddf = 1.0 for sample variance), and $\bar{x}$ is the arithmetic mean of x.

Syntax

result = fsml_var(x [,ddf])

Parameters

x: A rank-1 array of type real.

ddf: An optional argument and scalar of type real. If passed, it must be either 0.0 or 1.0. It will default to 0.0 if not passed.

Invalid argument values will result in the return of a sentinel value.

Returns

The result is a scalar and the same type as x.

Standard Deviation

fsml_std

Description

The procedure computes the population or sample standard deviation (depending on passed arguments). $$\sigma = \sqrt{\operatorname{var}(x)} = \sqrt{ \frac{1}{n - \nu} \cdot \sum_{i=1}^{n} (x_i - \bar{x})^2 }$$ where $\operatorname{var}(x)$ is the variance of vector x, $n$ is the size of (or number of observations in) vector x, $x_i$ are individual elements in x, and $\nu$ (ddf) is a degrees of freedom adjustment (ddf = 0.0 for population variance, ddf = 1.0 for sample variance).

Syntax

result = fsml_std(x [,ddf])

Parameters

x: A rank-1 array of type real.

ddf: An optional argument and scalar of type real. If passed, it must be either 0.0 or 1.0. It will default to 0.0 if not passed.

Invalid argument values will result in the return of a sentinel value.

Returns

The result is a scalar and the same type as x.

Covariance

fsml_cov

Description

The procedure computes the population or sample covariance (depending on passed arguments). $$\operatorname{cov}(x, y) = \frac{1}{n - \nu} \cdot \sum_{i=1}^{n} (x_i - \bar{x}) \cdot (y_i - \bar{y})$$ where $n$ is the size of (or number of observations in) vectors x and y, $x_i$ and $y_i$ are individual elements in x and y, $\nu$ (ddf) is a degrees of freedom adjustment (ddf = 0.0 for population variance, ddf = 1.0 for sample variance), and $\bar{x}$ and $\bar{y}$ are the arithmetic means of x and y.

Vectors x and y must be the same size.

Syntax

result = fsml_cov(x, y [,ddf])

Parameters

x: A rank-1 array of type real. It must be the same size as y.

y: A rank-1 array of type real. It must be the same size as x.

ddf: An optional argument and scalar of type real. If passed, it must be either 0.0 or 1.0. It will default to 0.0 if not passed.

Invalid argument values will result in the return of a sentinel value.

Returns

The result is a scalar and the same type as x and y.

Linear Trend

fsml_trend

Description

The procedure computes the regression coefficient/trend. $$m = \frac{\operatorname{cov}(x, y)}{\operatorname{var}(x)}$$ where $m$ is the slope of the regression line (linear trend), $\operatorname{cov}(x, y)$ is the covariance of x and y, and $\operatorname{var}(x)$ is the variance of x.

Vectors x and y must be the same size.

Syntax

result = fsml_trend(x, y)

Parameters

x: A rank-1 array of type real. It must be the same size as y.

y: A rank-1 array of type real. It must be the same size as x.

Invalid argument values will result in the return of a sentinel value.

Returns

The result is a scalar and the same type as x and y.

Pearson Correlation Coefficient

fsml_pcc

Description

The procedure computes the Pearson correlation coefficient (PCC). $$\rho_{x,y} = \frac{\operatorname{cov}(x, y)}{\sigma_x \cdot \sigma_y}$$ where $\rho_{x,y}$ is the Pearson correlation coefficient for vectors x and y, $\operatorname{cov}(x, y)$ is the covariance of x and y, and $\sigma_{x}$ and $\sigma_{y}$ are the standard deviations of x and y.

Vectors x and y must be the same size.

Syntax

result = fsml_pcc(x, y)

Parameters

x: A rank-1 array of type real. It must be the same size as y.

y: A rank-1 array of type real. It must be the same size as x.

Invalid argument values will result in the return of a sentinel value.

Returns

The result is a scalar and the same type as x and y.

Spearman Rank Correlation Coefficient

fsml_scc

Description

The procedure computes the Spearman rank correlation coefficient (SCC). The procedure gets the ranks of cectors x and y, then calculates the Pearson correlation coefficient on these ranks.

Vectors x and y must be the same size.

Syntax

result = fsml_scc(x, y)

Parameters

x: A rank-1 array of type real. It must be the same size as y.

y: A rank-1 array of type real. It must be the same size as x.

Invalid argument values will result in the return of a sentinel value.

Returns

The result is a scalar and the same type as x and y.

Examples

program example_sts

! |--------------------------------------------------------------------|
! | fsml - fortran statistics and machine learning library             |
! |                                                                    |
! | about                                                              |
! | -----                                                              |
! | Examples for basic statistics (sts module).                        |
! |                                                                    |
! | license : MIT                                                      |
! | author  : Sebastian G. Mutz (sebastian@sebastianmutz.com)          |
! |--------------------------------------------------------------------|

  use :: fsml
  use :: fsml_ini ! import wp; alternatively: iso_fortran_env, wp => real64

  implicit none

! ==== Description
!! The programme demonstrates the use of several statistics procedures based on
!! the same few data vectors.

! ==== Declarations
  integer(i4), parameter :: n1 = 10
  real(wp)   , parameter :: x1(n1) =        &
                                  [1.10_wp, &
                                   1.22_wp, &
                                   0.11_wp, &
                                   2.31_wp, &
                                   1.72_wp, &
                                   2.21_wp, &
                                   3.10_wp, &
                                   2.27_wp, &
                                   1.21_wp, &
                                   1.01_wp]
  real(wp)   , parameter :: x2(n1) =        &
                                  [2.10_wp, &
                                   1.10_wp, &
                                   0.23_wp, &
                                   1.25_wp, &
                                   1.95_wp, &
                                   1.52_wp, &
                                   1.00_wp, &
                                   1.05_wp, &
                                   2.32_wp, &
                                   1.40_wp]

! ==== Instructions

  ! mean of vector x1
  print*, "mean (x1): ", fsml_mean(x1)
  ! 1.6260000000000001

  ! median of vector x1
  print*, "median (x1): ", fsml_median(x1)
  ! 1.4700000000000000

  ! variance of vector x1
  print*, "variance (x1): ", fsml_var(x1)
  ! 0.66974399999999989

  ! sample variance of vector x1
  print*, "sample variance (x1): ", fsml_var(x1, ddf=1.0_wp)
  ! 0.74415999999999993

  ! standard deviation of vector x1
  print*, "standard deviation (x1): ", fsml_std(x1)
  ! 0.81837888535812064

  ! sample standard deviation of vector x1
  print*, "sample standard deviation (x1): ", fsml_std(x1, ddf=1.0_wp)
  ! 0.86264708890716135

  ! covariance of x1 and x2
  print*, "covariance (x1, x2): ", fsml_cov(x1, x2)
  ! 3.4878000000000006E-002

  ! sample covariance of x1 and x2
  print*, "sample covariance (x1, x2): ", fsml_cov(x1, x2, ddf=1.0_wp)
  ! 3.8753333333333341E-002

  ! linear regression slope for x1 and x2
  print*, "trend (x1, x2): ", fsml_trend(x1, x2)
  ! 5.2076614348168869E-002

  ! Pearson correlation coefficient for x1 and x2
  print*, "Pearson R (x1, x2): ", fsml_pcc(x1, x2)
  ! 7.2912607800353288E-002

  ! Spearman rank correlation coefficient for x1 and x2
  print*, "Spearman R (x1, x2): ", fsml_scc(x1, x2)
  ! -0.19999999999999998

end program example_sts