Compute and return the memberships and minimum distances of a set of input points with respect to the an input set of cluster centers.
More...

Detailed Description

Compute and return the memberships and minimum distances of a set of input points with respect to the an input set of cluster centers.

The membership ID of the ith sample sample(:,i) is determined by computing the distance of the sample from each cluster and choosing the cluster ID j whose center(:,j) has the minimum distance from the sample among all clusters.
This minimum squared distance is output in disq(:,i).
The metric used within this generic interface is the Euclidean distance.

Parameters

[in,out]	membership	: The output (or input/output) scalar or vector of shape `(1:nsam)` of type `integer` of default kind IK, containing the membership of each input sample in `sample` from its nearest cluster `center`, such that `cluster(membership(i))` is the nearest cluster center to the `i`th sample `sample(:, i)` at a squared-distance of `disq(i)`. If the optional input argument `changed` is missing, then `membership` has `intent(out)`. If the optional input argument `changed` is present, then `membership` has `intent(inout)`. On input, `membership` must contain the old cluster membership of the input sample.
[out]	disq	: The output scalar or vector of shape `(1:nsam)` of the same type and kind as the input argument `sample`, containing the Euclidean squared distance of each input sample in `sample` from its nearest cluster `center`.
[in]	sample	: The input scalar, vector, or matrix of, type `real` of kind any supported by the processor (e.g., RK, RK32, RK64, or RK128), containing the sample of `nsam` points in a `ndim`-dimensional space whose memberships and minimum distances with respect to the input `center`s must be computed. If `sample` is a scalar and `center` is a vector of shape `(1 : ncls)`, then the input `sample` must be the coordinate of a single sample in (univariate space) whose distance from `ncls` cluster `center`s must be computed. If `sample` is a vector of shape `(1 : ndim)` and `center` is a matrix of shape `(1 : ndim, 1 : ncls)`, then the input `sample` must be a single sample (in `ndim`-dimensional space) whose distance from `ncls` cluster `center`s must be computed. If `sample` is a vector of shape `(1 : nsam)` and `center` is a vector of shape `(1 : ncls)`, then the input `sample` must be a collection of `nsam` points (in univariate space) whose distances from `ncls` cluster `center`s must be computed. If `sample` is a matrix of shape `(1 : ndim, 1 : nsam)` and `center` is a matrix of shape `(1 : ndim, 1 : ncls)`, then the input `sample` must be a collection of `nsam` points (in `ndim`-dimensional space) whose distances from `ncls` cluster `center`s must be computed.
[in]	center	: The input vector of shape `(1:ncls)` or matrix of shape `(1 : ndim, 1 : ncls)` of the same type and kind as the input argument `sample`, containing the set of `ncls` cluster centers (centroids) with respect to which the sample memberships and minimum distances must be computed.
[out]	changed	: The output scalar of type `logical` of default kind LK that is `.false.` if and only if the input values for `membership` and `disq` do not change for any* of the input `sample`. In other words, a single membership update is sufficient to set the value of `changed` to `.true.` on output. (optional. If missing, the arguments `membership` and `disq` have `intent(out)` and both will be computed afresh.)

Possible calling interfaces ⛓

: use pm_clusKmeans, only: setMember

! The arguments `membership` and `disq` have `intent(out)`.

call setMember(membership , disq , sample , center(1 : ncls))

call setMember(membership(1 : nsam) , disq(1 : nsam), sample(1 : nsam) , center(1 : ncls))

call setMember(membership , disq , sample(1 : ndim) , center(1 : ndim, 1 : ncls))

call setMember(membership(1 : nsam) , disq(1 : nsam), sample(1 : ndim, 1 : nsam), center(1 : ndim, 1 : ncls))

! The arguments `membership` and `disq` have `intent(inout)`.

call setMember(membership , disq , sample , center(1 : ncls), changed)

call setMember(membership(1 : nsam) , disq(1 : nsam), sample(1 : nsam) , center(1 : ncls), changed)

call setMember(membership , disq , sample(1 : ndim) , center(1 : ndim, 1 : ncls), changed)

call setMember(membership(1 : nsam) , disq(1 : nsam), sample(1 : ndim, 1 : nsam), center(1 : ndim, 1 : ncls), changed)

pm_clusKmeans::setMember
Compute and return the memberships and minimum distances of a set of input points with respect to the...
Definition: pm_clusKmeans.F90:249

pm_clusKmeans
This module contains procedures and routines for the computing the Kmeans clustering of a given set o...
Definition: pm_clusKmeans.F90:113

Warning: The condition ubound(center, rank(center)) > 0 must hold for the corresponding input arguments.
The condition ubound(sample, rank(sample)) == ubound(disq, 1) must hold for the corresponding input arguments.
The condition ubound(sample, rank(sample)) == ubound(membership, 1) must hold for the corresponding input arguments.
The condition ubound(sample, 1) == ubound(center, 1) .or. rank(sample) == 0 .or. rank(center) == 1 must hold for the corresponding input arguments.
These conditions are verified only if the library is built with the preprocessor macro CHECK_ENABLED=1.; The pure procedure(s) documented herein become impure when the ParaMonte library is compiled with preprocessor macro CHECK_ENABLED=1.
By default, these procedures are pure in release build and impure in debug and testing builds.

Remarks: This generic interface implements one of the two major steps involved in Kmeans clustering.

See also: setKmeans
setCenter
setMember
setKmeansPP

Example usage ⛓

: 1program example

2

3 use pm_kind, only: SK, IK, LK

4 use pm_kind, only: RKG => RKS ! all other real kinds are also supported.

5 use pm_io, only: display_type

6 use pm_distUnif, only: getUnifRand

7 use pm_arrayResize, only: setResized

8 use pm_clusKmeans, only: setMember

9 use pm_arrayRange, only: getRange

10

11 implicit none

12

13 logical(LK) :: changed

14 integer(IK) :: ndim, nsam, ncls

15 real(RKG) , allocatable :: sample(:,:), center(:,:), disq(:)

16 integer(IK) , allocatable :: membership(:)

17 type(display_type) :: disp

18

19 disp = display_type(file = "main.out.F90")

20

21 call disp%skip

22 call disp%show("!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")

23 call disp%show("! Compute memberships of a sample of points from arbitrary dimensional cluster centers.")

24 call disp%show("!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")

25 call disp%skip

26

27 call disp%skip()

28 call disp%show("ndim = getUnifRand(1, 5); nsam = getUnifRand(1, 5); ncls = getUnifRand(1, 5);")

29 ndim = getUnifRand(1, 5); nsam = getUnifRand(1, 5); ncls = getUnifRand(1, 5);

30 call disp%show("[ndim, nsam, ncls]")

31 call disp%show( [ndim, nsam, ncls] )

32 call disp%show("center = getUnifRand(0., 5., ndim, ncls) ! initialize random centers.")

33 center = getUnifRand(0., 5., ndim, ncls) ! initialize random centers.

34 call disp%show("center")

35 call disp%show( center )

36 call disp%show("sample = getUnifRand(0., 5., ndim, nsam) ! Create a random sample.")

37 sample = getUnifRand(0., 5., ndim, nsam) ! Create a random sample.

38 call disp%show("sample")

39 call disp%show( sample )

40 call disp%show("call setResized(disq, nsam)")

41 call setResized(disq, nsam)

42 call disp%show("call setResized(membership, nsam)")

43 call setResized(membership, nsam)

44 call disp%skip()

45

46 call disp%show("call setMember(membership, disq, sample, center) ! sample points memberships.")

47 call setMember(membership, disq, sample, center) ! sample points memberships.

48 call disp%show("membership")

49 call disp%show( membership )

50 call disp%show("disq")

51 call disp%show( disq )

52 call disp%skip()

53

54 call disp%show("call setMember(membership, disq, sample, center, changed) ! sample points memberships.")

55 call setMember(membership, disq, sample, center, changed) ! sample points memberships.

56 call disp%show("membership")

57 call disp%show( membership )

58 call disp%show("disq")

59 call disp%show( disq )

60 call disp%show("changed")

61 call disp%show( changed )

62 call disp%skip()

63

64 call disp%show("call setMember(membership(1), disq(1), sample(:,1), center) ! single point membership.")

65 call setMember(membership(1), disq(1), sample(:,1), center) ! single point membership.

66 call disp%show("membership")

67 call disp%show( membership )

68 call disp%show("disq")

69 call disp%show( disq )

70 call disp%skip()

71

72 call disp%show("call setMember(membership(1), disq(1), sample(:,1), center, changed) ! single point membership.")

73 call setMember(membership(1), disq(1), sample(:,1), center, changed) ! single point membership.

74 call disp%show("membership")

75 call disp%show( membership )

76 call disp%show("disq")

77 call disp%show( disq )

78 call disp%show("changed")

79 call disp%show( changed )

80 call disp%skip()

81

82 call disp%show("call setMember(membership, disq, sample(1,:), center(1,:)) ! sample points memberships in one-dimension.")

83 call setMember(membership, disq, sample(1,:), center(1,:)) ! sample points memberships in one-dimension.

84 call disp%show("membership")

85 call disp%show( membership )

86 call disp%show("disq")

87 call disp%show( disq )

88 call disp%skip()

89

90 call disp%show("call setMember(membership, disq, sample(1,:), center(1,:), changed) ! sample points memberships in one-dimension.")

91 call setMember(membership, disq, sample(1,:), center(1,:), changed) ! sample points memberships in one-dimension.

92 call disp%show("membership")

93 call disp%show( membership )

94 call disp%show("disq")

95 call disp%show( disq )

96 call disp%show("changed")

97 call disp%show( changed )

98 call disp%skip()

99

100 call disp%show("call setMember(membership(1), disq(1), sample(1,1), center(1,:)) ! single point membership in one-dimension.")

101 call setMember(membership(1), disq(1), sample(1,1), center(1,:)) ! single point membership in one-dimension.

102 call disp%show("membership")

103 call disp%show( membership )

104 call disp%show("disq")

105 call disp%show( disq )

106 call disp%skip()

107

108 call disp%show("call setMember(membership(1), disq(1), sample(1,1), center(1,:), changed) ! single point membership in one-dimension.")

109 call setMember(membership(1), disq(1), sample(1,1), center(1,:), changed) ! single point membership in one-dimension.

110 call disp%show("membership")

111 call disp%show( membership )

112 call disp%show("disq")

113 call disp%show( disq )

114 call disp%show("changed")

115 call disp%show( changed )

116 call disp%skip()

117

118 !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

119 ! Output an example for visualization.

120 !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

121

122 block

123 integer(IK) :: funit, i

124 ndim = 2

125 ncls = 5

126 nsam = 5000

127 center = getUnifRand(0., 1., ndim, ncls)

128 sample = getUnifRand(0., 1., ndim, nsam)

129 call setResized(disq, nsam)

130 call setResized(membership, nsam)

131 call setMember(membership, disq, sample, center)

132 call setMember(membership, disq, sample, center, changed)

133 open(newunit = funit, file = "setMember.center.txt")

134 do i = 1, ncls

135 write(funit, "(*(g0,:,','))") i, center(:,i)

136 end do

137 close(funit)

138 open(newunit = funit, file = "setMember.sample.txt")

139 do i = 1, nsam

140 write(funit, "(*(g0,:,','))") membership(i), sample(:,i)

141 end do

142 close(funit)

143 end block

144

145end program example

pm_arrayRange::getRange
Generate minimally-spaced character, integer, real sequences or sequences at fixed intervals of size ...
Definition: pm_arrayRange.F90:135

pm_arrayResize::setResized
Allocate or resize (shrink or expand) an input allocatable scalar string or array of rank 1....
Definition: pm_arrayResize.F90:249

pm_distUnif::getUnifRand
Generate and return a scalar or a contiguous array of rank 1 of length s1 of randomly uniformly distr...
Definition: pm_distUnif.F90:4150

pm_io::show
This is a generic method of the derived type display_type with pass attribute.
Definition: pm_io.F90:11726

pm_io::skip
This is a generic method of the derived type display_type with pass attribute.
Definition: pm_io.F90:11508

pm_arrayRange
This module contains procedures and generic interfaces for generating ranges of discrete character,...
Definition: pm_arrayRange.F90:36

pm_arrayResize
This module contains procedures and generic interfaces for resizing allocatable arrays of various typ...
Definition: pm_arrayResize.F90:81

pm_distUnif
This module contains classes and procedures for computing various statistical quantities related to t...
Definition: pm_distUnif.F90:274

pm_io
This module contains classes and procedures for input/output (IO) or generic display operations on st...
Definition: pm_io.F90:252

pm_io::disp
type(display_type) disp
This is a scalar module variable an object of type display_type for general display.
Definition: pm_io.F90:11393

pm_kind
This module defines the relevant Fortran kind type-parameters frequently used in the ParaMonte librar...
Definition: pm_kind.F90:268

pm_kind::LK
integer, parameter LK
The default logical kind in the ParaMonte library: kind(.true.) in Fortran, kind(....
Definition: pm_kind.F90:541

pm_kind::IK
integer, parameter IK
The default integer kind in the ParaMonte library: int32 in Fortran, c_int32_t in C-Fortran Interoper...
Definition: pm_kind.F90:540

pm_kind::SK
integer, parameter SK
The default character kind in the ParaMonte library: kind("a") in Fortran, c_char in C-Fortran Intero...
Definition: pm_kind.F90:539

pm_kind::RKS
integer, parameter RKS
The single-precision real kind in Fortran mode. On most platforms, this is an 32-bit real kind.
Definition: pm_kind.F90:567

pm_io::display_type
Generate and return an object of type display_type.
Definition: pm_io.F90:10282

Example Unix compile command via Intel ifort compiler ⛓
1#!/usr/bin/env sh

2rm main.exe

3ifort -fpp -standard-semantics -O3 -Wl,-rpath,../../../lib -I../../../inc main.F90 ../../../lib/libparamonte* -o main.exe

4./main.exe

Example Windows Batch compile command via Intel ifort compiler ⛓
1del main.exe

2set PATH=..\..\..\lib;%PATH%

3ifort /fpp /standard-semantics /O3 /I:..\..\..\include main.F90 ..\..\..\lib\libparamonte*.lib /exe:main.exe

4main.exe

Example Unix / MinGW compile command via GNU gfortran compiler ⛓
1#!/usr/bin/env sh

2rm main.exe

3gfortran -cpp -ffree-line-length-none -O3 -Wl,-rpath,../../../lib -I../../../inc main.F90 ../../../lib/libparamonte* -o main.exe

4./main.exe

Example output ⛓
1

2!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

3! Compute memberships of a sample of points from arbitrary dimensional cluster centers.

4!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

5

6

7ndim = getUnifRand(1, 5); nsam = getUnifRand(1, 5); ncls = getUnifRand(1, 5);

8[ndim, nsam, ncls]

9+3, +1, +5

10center = getUnifRand(0., 5., ndim, ncls) ! initialize random centers.

11center

12+3.13817549, +1.30127048, +3.22299910, +0.854633451, +3.42645597

13+4.34367943, +1.17531443, +1.18732572, +0.516248941, +1.45963287

14+3.43847895, +3.74144411, +2.26864052, +3.36472607, +3.09419990

15sample = getUnifRand(0., 5., ndim, nsam) ! Create a random sample.

16sample

17+4.94577074

18+4.77742815

19+3.28567791

20call setResized(disq, nsam)

21call setResized(membership, nsam)

22

23call setMember(membership, disq, sample, center) ! sample points memberships.

24membership

25+1

26disq

27+3.47888660

28

29call setMember(membership, disq, sample, center, changed) ! sample points memberships.

30membership

31+1

32disq

33+3.47888660

34changed

35F

36

37call setMember(membership(1), disq(1), sample(:,1), center) ! single point membership.

38membership

39+1

40disq

41+3.47888660

42

43call setMember(membership(1), disq(1), sample(:,1), center, changed) ! single point membership.

44membership

45+1

46disq

47+3.47888660

48changed

49F

50

51call setMember(membership, disq, sample(1,:), center(1,:)) ! sample points memberships in one-dimension.

52membership

53+5

54disq

55+2.30831742

56

57call setMember(membership, disq, sample(1,:), center(1,:), changed) ! sample points memberships in one-dimension.

58membership

59+5

60disq

61+2.30831742

62changed

63F

64

65call setMember(membership(1), disq(1), sample(1,1), center(1,:)) ! single point membership in one-dimension.

66membership

67+5

68disq

69+2.30831742

70

71call setMember(membership(1), disq(1), sample(1,1), center(1,:), changed) ! single point membership in one-dimension.

72membership

73+5

74disq

75+2.30831742

76changed

77F

78

79

Postprocessing of the example output ⛓
1#!/usr/bin/env python

2

3import matplotlib.pyplot as plt

4import pandas as pd

5import numpy as np

6import glob

7import sys

8import os

9

10fontsize = 17

11fig = plt.figure(figsize = 1.25 * np.array([6.4, 4.8]), dpi = 200)

12ax = plt.subplot()

13

14parent = os.path.basename(os.path.dirname(__file__))

15pattern = parent + "*.txt"

16

17fileList = glob.glob(pattern)

18legends = []

19if len(fileList) == 2:

20 for file in fileList:

21

22 kind = file.split(".")[1]

23 prefix = file.split(".")[0]

24 df = pd.read_csv(file, delimiter = ",", header = None)

25

26 if kind == "center":

27 ax.scatter ( df.values[:, 1]

28 , df.values[:,2]

29 , zorder = 100

30 , marker = "*"

31 , c = "red"

32 , s = 50

33 )

34 legends.append("center")

35 elif kind == "sample":

36 ax.scatter ( df.values[:, 1]

37 , df.values[:,2]

38 , c = df.values[:, 0]

39 , s = 10

40 )

41 legends.append("sample")

42 else:

43 sys.exit("Ambiguous file exists: {}".format(file))

44

45 ax.legend(legends, fontsize = fontsize)

46 plt.xticks(fontsize = fontsize - 2)

47 plt.yticks(fontsize = fontsize - 2)

48 ax.set_xlabel("X", fontsize = 17)

49 ax.set_ylabel("Y", fontsize = 17)

50 ax.set_title("Membership Scatter Plot", fontsize = fontsize)

51

52 plt.axis('equal')

53 plt.grid(visible = True, which = "both", axis = "both", color = "0.85", linestyle = "-")

54 ax.tick_params(axis = "y", which = "minor")

55 ax.tick_params(axis = "x", which = "minor")

56 ax.set_axisbelow(True)

57 plt.tight_layout()

58

59 plt.savefig(prefix + ".png")

60else:

61 sys.exit("Ambiguous file list exists.")

Visualization of the example output ⛓

Benchmarks:

Benchmark :: The runtime performance of setMember for external membership change verification vs. in place verification by the algorithm. ⛓

! Test the performance of Cholesky factorization computation using an assumed-shape interface vs. explicit-shape interface.
program benchmark
 
    use pm_kind, only: IK, LK, RKG => RKD, SK
    use pm_distUnif, only: setUnifRand
    use pm_bench, only: bench_type
 
    implicit none
 
    integer(IK)                         :: icls
    integer(IK)                         :: ibench
    integer(IK)                         :: fileUnit
    integer(IK)     , parameter         :: nsam = 1000
    integer(IK)     , parameter         :: ndim = 3_IK
    integer(IK)     , parameter         :: ncls = 20_IK
    integer(IK)                         :: membership(nsam)
    real(RKG)                           :: sample(ndim, nsam)
    real(RKG)                           :: center(ndim, ncls)
    real(RKG)                           :: disq(nsam)
    type(bench_type), allocatable       :: bench(:)
    real(RKG)                           :: mean(ndim)
    integer(IK)                         :: idum = 0
    logical(LK)                         :: mchanged
 
    bench = [ bench_type(name = SK_"default", exec = default, overhead = setOverhead) &
            , bench_type(name = SK_"changed", exec = changed, overhead = setOverhead) &
            ]
 
    write(*,"(*(g0,:,' '))")
    write(*,"(*(g0,:,' '))") "membership benchmarking..."
    write(*,"(*(g0,:,' '))")
 
    open(newunit = fileUnit, file = "main.out", status = "replace")
 
        write(fileUnit, "(*(g0,:,','))") "ClusterCount", (bench(ibench)%name, ibench = 1, size(bench))
 
        do icls = 1, 20
 
            write(*,"(*(g0,:,' '))") "Benchmarking default() vs. changed()", nsam
 
            call random_number(disq)
            call random_number(center)
            call random_number(sample)
            call setUnifRand(membership, 1, icls)
            do ibench = 1, size(bench)
                bench(ibench)%timing = bench(ibench)%getTiming()
            end do
 
            write(fileUnit,"(*(g0,:,','))") icls, (bench(ibench)%timing%mean, ibench = 1, size(bench))
 
        end do
        write(*,"(*(g0,:,' '))") idum
 
    close(fileUnit)
 
contains
 
    !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    ! procedure wrappers.
    !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
    subroutine setOverhead()
        if (mchanged) idum = idum + 1
    end subroutine
 
    subroutine default()
        use pm_clusKmeans, only: setMember
        integer(IK) :: membersnew(size(membership))
        call setMember(membersnew, disq, sample, center(:, 1 : icls))
        mchanged = all(membersnew == membership)
    end subroutine
 
    subroutine changed()
        use pm_clusKmeans, only: setMember
        call setMember(membership, disq, sample, center(:, 1 : icls), mchanged)
    end subroutine
 
end program benchmark

Example Unix compile command via Intel ifort compiler ⛓

#!/usr/bin/env sh
rm main.exe
ifort -fpp -standard-semantics -O3 -Wl,-rpath,../../../lib -I../../../inc main.F90 ../../../lib/libparamonte* -o main.exe
./main.exe

Example Windows Batch compile command via Intel ifort compiler ⛓

del main.exe
set PATH=..\..\..\lib;%PATH%
ifort /fpp /standard-semantics /O3 /I:..\..\..\include main.F90 ..\..\..\lib\libparamonte*.lib /exe:main.exe
main.exe

Example Unix / MinGW compile command via GNU gfortran compiler ⛓

#!/usr/bin/env sh
rm main.exe
gfortran -cpp -ffree-line-length-none -O3 -Wl,-rpath,../../../lib -I../../../inc main.F90 ../../../lib/libparamonte* -o main.exe
./main.exe

Postprocessing of the benchmark output ⛓

#!/usr/bin/env python
 
import matplotlib.pyplot as plt
import pandas as pd
import numpy as np
 
import os
dirname = os.path.basename(os.getcwd()) 
 
fontsize = 14
 
df = pd.read_csv("main.out", delimiter = ",")
colnames = list(df.columns.values)
 
 
 
ax = plt.figure(figsize = 1.25 * np.array([6.4,4.6]), dpi = 200)
ax = plt.subplot()
 
for colname in colnames[1:]:
    plt.plot( df[colnames[0]].values
            , df[colname].values
            , linewidth = 2
            )
 
plt.xticks(fontsize = fontsize)
plt.yticks(fontsize = fontsize)
ax.set_xlabel(colnames[0], fontsize = fontsize)
ax.set_ylabel("Runtime [ seconds ]", fontsize = fontsize)
ax.set_title(" vs. ".join(colnames[1:])+"\nLower is better.", fontsize = fontsize)
ax.set_xscale("log")
ax.set_yscale("log")
plt.minorticks_on()
plt.grid(visible = True, which = "both", axis = "both", color = "0.85", linestyle = "-")
ax.tick_params(axis = "y", which = "minor")
ax.tick_params(axis = "x", which = "minor")
ax.legend   ( colnames[1:]
           #, loc='center left'
           #, bbox_to_anchor=(1, 0.5)
            , fontsize = fontsize
            )
 
plt.tight_layout()
plt.savefig("benchmark." + dirname + ".runtime.png")
 
 
 
ax = plt.figure(figsize = 1.25 * np.array([6.4,4.6]), dpi = 200)
ax = plt.subplot()
 
plt.plot( df[colnames[0]].values
        , np.ones(len(df[colnames[0]].values))
        , linestyle = "--"
       #, color = "black"
        , linewidth = 2
        )
for colname in colnames[2:]:
    plt.plot( df[colnames[0]].values
            , df[colname].values / df[colnames[1]].values
            , linewidth = 2
            )
 
plt.xticks(fontsize = fontsize)
plt.yticks(fontsize = fontsize)
ax.set_xlabel(colnames[0], fontsize = fontsize)
ax.set_ylabel("Runtime compared to {}".format(colnames[1]), fontsize = fontsize)
ax.set_title("Runtime Ratio Comparison. Lower means faster.\nLower than 1 means faster than {}().".format(colnames[1]), fontsize = fontsize)
ax.set_xscale("log")
ax.set_yscale("log")
plt.minorticks_on()
plt.grid(visible = True, which = "both", axis = "both", color = "0.85", linestyle = "-")
ax.tick_params(axis = "y", which = "minor")
ax.tick_params(axis = "x", which = "minor")
ax.legend   ( colnames[1:]
           #, bbox_to_anchor = (1, 0.5)
           #, loc = "center left"
            , fontsize = fontsize
            )
 
plt.tight_layout()
plt.savefig("benchmark." + dirname + ".runtime.ratio.png")

Visualization of the benchmark output ⛓

Benchmark moral ⛓ The procedures under the generic interface setMember compute the new membership under two different scenarios.

When the input argument changed is missing, the memberships are computed afresh and no comparison with any old membership values is done by the algorithm.
Consequently, any such comparisons would have to be done externally to the procedure by the user, which requires another pass over the membership values for a comparison.
When the input argument changed is present, the memberships are computed afresh but before overwriting the old values, they are compared against them to detect if any memberships change at all and if so, changed = .true. on output.

From the benchmark results above, it appears that when membership comparison with old values is desired, letting the procedure to perform the comparison (by presenting the optional argument changed) is significantly slower than an external comparison of memberships by the user.
However, the difference is relevant only for small number of clusters involved (1 : 4) and the difference become negligible for more number of clusters.
Where is this situation relevant? Within the Kmeans algorithm this situation repeatedly occurs.
Additionally, note that the above benchmark does not include the cost of maintaining two (old and new) copies of cluster memberships which could potentially lead to additional allocation costs if it happens repeatedly, e.g., within the Kmeans algorithm.

Test:: test_pm_clusKmeans

Final Remarks ⛓

If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Copyright: Computational Data Science Lab

Author:: Amir Shahmoradi, September 1, 2012, 12:00 AM, National Institute for Fusion Studies, The University of Texas Austin

Definition at line 249 of file pm_clusKmeans.F90.

The documentation for this interface was generated from the following file:

src/fortran/main/pm_clusKmeans.F90