Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 39 ยท Projects and Practice

Project: A Statistics Module

Build a reusable Fortran statistics module with mean, variance, standard deviation, median, correlation and histogram, then test it against known values.

In this project you will write a small statistics library as a Fortran module, the way you would for real work: clear interfaces, elemental or array-based functions, careful handling of edge cases, and a test program that checks every function against numbers you can verify by hand. It uses ideas from this chapter: modules, intent, pure functions, optional arguments and generic interfaces.

The Fortran compiler is not available on this site, so the module is shown read-only. Runnable Python stand-ins compute the same quantities, so you can check the expected values.

Requirements

The module stats_mod provides, for a real array x:

  1. mean(x)
  2. variance(x, sample): population by default, sample (n minus 1) when asked
  3. std_dev(x, sample)
  4. median(x)
  5. correlation(x, y): Pearson's r
  6. histogram(x, lo, hi, counts): counts per equal-width bin

Edge cases: empty arrays, a single value for the sample variance, and constant data for the correlation must not divide by zero silently.

The kind and the module header

FORTRAN
module stats_mod
  use, intrinsic :: iso_fortran_env, only: real64
  implicit none
  private

  integer, parameter, public :: dp = real64

  public :: mean, variance, std_dev, median, correlation, histogram

contains

Using real64 (a double precision real) from iso_fortran_env is the portable way to ask for 8-byte reals. Everything is private except what is listed.

Mean, variance and standard deviation

FORTRAN
  pure function mean(x) result(m)
    real(dp), intent(in) :: x(:)
    real(dp) :: m
    if (size(x) == 0) then
      m = 0.0_dp
    else
      m = sum(x) / real(size(x), dp)
    end if
  end function mean

  pure function variance(x, sample) result(v)
    real(dp), intent(in) :: x(:)
    logical, intent(in), optional :: sample
    real(dp) :: v
    integer :: n, denom
    n = size(x)
    denom = n
    if (present(sample)) then
      if (sample) denom = n - 1
    end if
    if (denom < 1) then
      v = 0.0_dp
    else
      v = sum((x - mean(x))**2) / real(denom, dp)
    end if
  end function variance

  pure function std_dev(x, sample) result(s)
    real(dp), intent(in) :: x(:)
    logical, intent(in), optional :: sample
    real(dp) :: s
    s = sqrt(variance(x, sample))
  end function std_dev

Points to notice:

  • x(:) is assumed-shape, so any length works and size(x) supplies it.
  • An absent optional can be passed on: variance(x, sample) inside std_dev forwards it correctly even if absent.
  • The nested if for present(sample) avoids the unsafe present(sample) .and. sample, because Fortran does not guarantee short-circuit evaluation.
  • The two-pass formula (mean first, then squared deviations) is numerically safer than mean(x**2) - mean(x)**2, which can lose all its digits for large offsets.

Median

FORTRAN
  function median(x) result(med)
    real(dp), intent(in) :: x(:)
    real(dp) :: med
    real(dp), allocatable :: s(:)
    integer :: n

    n = size(x)
    if (n == 0) then
      med = 0.0_dp
      return
    end if

    s = x                       ! automatic allocation: a sorted copy
    call insertion_sort(s)
    if (mod(n, 2) == 1) then
      med = s((n + 1) / 2)
    else
      med = 0.5_dp * (s(n / 2) + s(n / 2 + 1))
    end if
  end function median

  subroutine insertion_sort(a)
    real(dp), intent(inout) :: a(:)
    real(dp) :: key
    integer :: i, j
    do i = 2, size(a)
      key = a(i)
      j = i - 1
      do while (j >= 1)
        if (a(j) <= key) exit
        a(j + 1) = a(j)
        j = j - 1
      end do
      a(j + 1) = key
    end do
  end subroutine insertion_sort

The function is not pure only because it allocates a work array, which is fine in practice but a real library might call a pure sort. The input is never modified: s = x is a copy.

Correlation

FORTRAN
  function correlation(x, y) result(r)
    real(dp), intent(in) :: x(:), y(:)
    real(dp) :: r
    real(dp) :: dx(size(x)), dy(size(y)), denom
    if (size(x) /= size(y) .or. size(x) < 2) then
      r = 0.0_dp
      return
    end if
    dx = x - mean(x)
    dy = y - mean(y)
    denom = sqrt(sum(dx**2) * sum(dy**2))
    if (denom == 0.0_dp) then
      r = 0.0_dp                ! constant data: correlation undefined
    else
      r = sum(dx * dy) / denom
    end if
  end function correlation

Histogram

FORTRAN
  subroutine histogram(x, lo, hi, counts)
    real(dp), intent(in) :: x(:), lo, hi
    integer, intent(out) :: counts(:)
    integer :: i, b, nb
    real(dp) :: width
    nb = size(counts)
    counts = 0
    width = (hi - lo) / real(nb, dp)
    do i = 1, size(x)
      if (x(i) < lo .or. x(i) > hi) cycle
      b = int((x(i) - lo) / width) + 1
      if (b > nb) b = nb         ! x == hi goes in the last bin
      counts(b) = counts(b) + 1
    end do
  end subroutine histogram

end module stats_mod

counts is intent(out), so it must be set before use: the line counts = 0 does that. The caller chooses the number of bins by the size of the array it passes.

flowchart TD
    A["x(:) data"] --> B["mean"]
    B --> C["variance"]
    C --> D["std_dev"]
    A --> E["median<br/>sorted copy"]
    A --> F["correlation<br/>(with y)"]
    A --> G["histogram<br/>counts(:)"]

variance depends on mean, std_dev on variance; the others stand alone.

The test program

FORTRAN
program test_stats
  use stats_mod
  implicit none
  real(dp) :: x(8) = [2, 4, 4, 4, 5, 5, 7, 9]
  real(dp) :: y(8) = [1, 3, 3, 3, 4, 4, 6, 8]
  integer :: counts(4)

  call check("mean", mean(x), 5.0_dp)
  call check("pop variance", variance(x), 4.0_dp)
  call check("pop std", std_dev(x), 2.0_dp)
  call check("median", median(x), 4.5_dp)
  call check("correlation", correlation(x, y), 1.0_dp)

  call histogram(x, 2.0_dp, 10.0_dp, counts)
  print *, "histogram:", counts

contains

  subroutine check(label, got, want)
    character(*), intent(in) :: label
    real(dp), intent(in) :: got, want
    if (abs(got - want) < 1.0e-12_dp) then
      print "(a, a)", "PASS ", label
    else
      print "(a, a, 2f12.6)", "FAIL ", label, got, want
    end if
  end subroutine check

end program test_stats

The data y is x shifted by 1, so the correlation is exactly 1 (up to rounding, hence the tolerance). The histogram with 4 bins on 2 to 10 (width 2) uses the bins [2,4), [4,6), [6,8) and [8,10]. By hand: the value 2 is alone in the first bin, the three 4s and two 5s fill the second, 7 is in the third and 9 in the last, so the program must print counts 1, 5, 1, 1. The Python stand-in below confirms every expected value.

Python Stand-in: reference values for the module

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Extensions

  1. Add percentile(x, p) with linear interpolation.
  2. Make the functions generic for real32 and real64 with an interface block (see interfaces and generic procedures).
  3. Read the data from a file with file I/O and print a formatted report (formatted output).
  4. Replace the insertion sort with a quicksort for big arrays.
  5. Add sample_variance using the Welford one-pass algorithm.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why use the two-pass variance formula?

    Subtracting the mean first keeps the squared deviations small and accurate.
  2. 2. Why test present(sample) in a nested if instead of using .and. in one condition?

    Both operands of .and. may be evaluated, so reading an absent optional could happen.
  3. 3. Why does histogram set counts = 0 first?

    intent(out) arguments carry no usable value on entry, so initialize before accumulating.
  4. 4. The correlation of x with x shifted by a constant is:

    A constant shift keeps the data perfectly linearly related, so r = 1.

Summary

  • A module with private default and a public list is the unit of a library.
  • Assumed-shape arrays, optional arguments and pure functions give a clean, safe interface.
  • Handle edge cases explicitly; prefer numerically stable formulas.
  • Test against values you computed independently.

Next: Project: 1D heat diffusion