ParaMonte Fortran 2.0.0
Parallel Monte Carlo and Machine Learning Library
See the latest version documentation.
pm_arrayRank Module Reference

This module contains procedures and generic interfaces for obtaining various rankings of elements of arrays of various types. More...

Data Types

type  dense_type
 This is a concrete derived type whose instances are exclusively used to request dense ranking of a given array within an interface of a procedure of the ParaMonte library.
More...
 
type  fractional_type
 This is a concrete derived type whose instances are exclusively used to request the fractional ranking of a given array within an interface of a procedure of the ParaMonte library.
More...
 
interface  getRankDense
 Generate and return the Dense rank of the input scalar string or contiguous array of rank 1 in ascending order or in the order specified by the input procedure isSorted() using the Quicksort algorithm such that array(rank) will be in ascending order (or in the requested order as specified by isSorted(). More...
 
interface  getRankFractional
 Generate and return the Fractional rank of the input scalar string or contiguous array of rank 1 in ascending order or in the order specified by the input procedure isSorted() using the Quicksort algorithm such that array(rank) will be in ascending order (or in the requested order as specified by isSorted(). More...
 
interface  getRankModified
 Generate and return the Modified rank of the input scalar string or contiguous array of rank 1 in ascending order or in the order specified by the input procedure isSorted() using the Quicksort algorithm such that array(rank) will be in ascending order (or in the requested order as specified by isSorted(). More...
 
interface  getRankOrdinal
 Generate and return the ordinal rank of the input scalar string or contiguous array of rank 1 in ascending order or in the order specified by the input procedure isSorted() using the Quicksort algorithm such that array(rank) will be in ascending order (or in the requested order as specified by isSorted(). More...
 
interface  getRankStandard
 Generate and return the Standard rank of the input scalar string or contiguous array of rank 1 in ascending order or in the order specified by the input procedure isSorted() using the Quicksort algorithm such that array(rank) will be in ascending order (or in the requested order as specified by isSorted(). More...
 
type  modified_type
 This is a concrete derived type whose instances are exclusively used to request the modified ranking of a given array within an interface of a procedure of the ParaMonte library.
More...
 
type  ordinal_type
 This is a concrete derived type whose instances are exclusively used to request the ordinal ranking of a given array within an interface of a procedure of the ParaMonte library.
More...
 
type  rank_type
 This is an abstract derived type for constructing concrete derived types to distinguish various procedure signatures that require different forms of array ranking (dense, fractional, modified, ordinal, standard, ...).
More...
 
interface  setRankDense
 Return the Dense rank of the input scalar string or contiguous array of rank 1 in ascending order or in the order specified by the input procedure isSorted() using the Quicksort algorithm such that array(rank) will be in ascending order (or in the requested order as specified by isSorted(). More...
 
interface  setRankFractional
 Return the Fractional rank of the input scalar string or contiguous array of rank 1 in ascending order or in the order specified by the input procedure isSorted() using the Quicksort algorithm such that array(rank) will be in ascending order (or in the requested order as specified by isSorted(). More...
 
interface  setRankModified
 Return the Modified rank of the input scalar string or contiguous array of rank 1 in ascending order or in the order specified by the input procedure isSorted() using the Quicksort algorithm such that array(rank) will be in ascending order (or in the requested order as specified by isSorted(). More...
 
interface  setRankOrdinal
 Return the ordinal rank of the input scalar string or contiguous array of rank 1 in ascending order or in the order specified by the input procedure isSorted() using the Quicksort algorithm such that array(rank) will be in ascending order (or in the requested order as specified by isSorted(). More...
 
interface  setRankStandard
 Return the Standard rank of the input scalar string or contiguous array of rank 1 in ascending order or in the order specified by the input procedure isSorted() using the Quicksort algorithm such that array(rank) will be in ascending order (or in the requested order as specified by isSorted(). More...
 
type  standard_type
 This is a concrete derived type whose instances are exclusively used to request the standard ranking of a given array within an interface of a procedure of the ParaMonte library.
More...
 

Variables

character(*, SK), parameter MODULE_NAME = "@pm_arrayRank"
 
type(dense_type), parameter dense = dense_type()
 This is a scalar parameter object of type dense_type that is exclusively used to request the dense ranking of a given array within an interface of a procedure of the ParaMonte library.
More...
 
type(ordinal_type), parameter ordinal = ordinal_type()
 This is a scalar parameter object of type ordinal_type that is exclusively used to request the ordinal ranking of a given array within an interface of a procedure of the ParaMonte library.
More...
 
type(modified_type), parameter modified = modified_type()
 This is a scalar parameter object of type modified_type that is exclusively used to request the modified ranking of a given array within an interface of a procedure of the ParaMonte library.
More...
 
type(standard_type), parameter standard = standard_type()
 This is a scalar parameter object of type standard_type that is exclusively used to request the standard ranking of a given array within an interface of a procedure of the ParaMonte library.
More...
 
type(fractional_type), parameter fractional = fractional_type()
 This is a scalar parameter object of type fractional_type that is exclusively used to request the fractional ranking of a given array within an interface of a procedure of the ParaMonte library.
More...
 

Detailed Description

This module contains procedures and generic interfaces for obtaining various rankings of elements of arrays of various types.

Depending on the applications, the rank of the elements of an array can be defined in different ways:

  1. Ordinal ranking (1234) ranking: getRankOrdinal or setRankOrdinal
    This kind of ranking of values is widely known as ordinal (1234) ranking.
    In ordinal ranking, all items receive distinct ordinal numbers, including items that compare equal.
    The assignment of distinct ordinal numbers to items that compare equal can be done at random, or arbitrarily, but it is generally preferable to use a system that is arbitrary but consistent, as this gives stable results if the ranking is done multiple times.
    In computer data processing, ordinal ranking is also referred to as row numbering. That is, if A < B == C < D, then the sequence ABCD has the ordinal ranking 1234.

  2. Standard competition (1224) ranking: getRankStandard or setRankStandard
    This kind of ranking of values is widely known as Standard Competition (1224) ranking.
    In Standard Competition ranking, items that compare equal receive the same ranking number, and then a gap is left in the ranking numbers. The number of ranking numbers that are left out in this gap is one less than the number of items that compared equal.
    Equivalently, the ranking number of each item is 1 plus the number of items ranked above it.
    This ranking strategy is frequently adopted for competitions, as it means that if two (or more) competitors tie for a position in the ranking, and the position of all those ranked below them is unaffected (i.e., a competitor only comes second if exactly one person scores better than them, third if exactly two people score better than them, fourth if exactly three people score better than them, etc.).
    Thus if A ranks ahead of B and C (which compare equal) which are both ranked ahead of D, then A gets ranking number 1 (first), B gets ranking number 2 (joint second), C also gets ranking number 2 (joint second) and D gets ranking number 4 (fourth).
    That is, if A < B == C < D, then the sequence ABCD has the Standard Competition ranking 1224.

  3. Modified competition (1334) ranking: getRankModified or setRankModified
    This kind of ranking of values is widely known as Modified Competition (1334) ranking.
    Sometimes, competition ranking is done by leaving the gaps in the ranking numbers before the sets of equal-ranking items (rather than after them as in Standard Competition ranking).
    The number of ranking numbers that are left out in this gap remains one less than the number of items that compared equal.
    Equivalently, the ranking number of each item is equal to the number of items ranked equal to it or above it.
    This ranking ensures that a competitor only comes second if they score higher than all but one of their opponents, third if they score higher than all but two of their opponents, etc.
    Thus if A ranks ahead of B and C (which compare equal) which are both ranked head of D, then A gets ranking number 1 (first), B gets ranking number 3 (joint third), C also gets ranking number 3 (joint third) and D gets ranking number 4 (fourth). In this case, nobody would get ranking number 2 (second) (left as a gap).
    That is, if A < B == C < D, then the sequence ABCD has the Modified Competition ranking 1334.

  4. Dense (1223) ranking: getRankDense or setRankDense
    This kind of ranking of values is widely known as dense (1223) ranking.
    In Dense ranking, items that compare equally receive the same ranking number, and the next items receive the immediately following ranking number.
    Equivalently, the ranking number of each item is 1 plus the number of items ranked above it that are distinct with respect to the ranking order.
    Thus if A ranks ahead of B and C (which compare equal) which are both ranked ahead of D, then A gets ranking number 1 (first), B gets ranking number 2 (joint second), C also gets ranking number 2 (joint second) and D gets ranking number 3 (Third).
    That is, if A < B == C < D, then the sequence ABCD has the Dense ranking 1223.
    Dense ranking effective factorizes the array into classes of unique values.
    Therefore, the Dense rank of each element of the array is simply its class level.

  5. Fractional (1 2.5 2.5 4) ranking: getRankFractional or setRankFractional
    This kind of ranking of values is widely known as fractional (1 2.5 2.5 4) ranking.
    In Fractional ranking, items that compare equal receive the same ranking number, which is the mean of what they would have under ordinal rankings;
    Equivalently, the ranking number of 1 plus the number of items ranked above it plus half the number of items equal to it.
    This strategy has the property that the sum of the ranking numbers is the same as under ordinal ranking.
    For this reason, it is used in computing Borda counts and ranking statistics (e.g., Spearman Correlation).
    Thus if A ranks ahead of B and C (which compare equal) which are both ranked ahead of D, then A gets ranking number 1 (first), B and C each get ranking number 2.5 (average of joint second/third) and D gets ranking number 4 (fourth).
    That is, if A < B == C < D, then the sequence ABCD has the Fractional ranking 1223.
    Example:
    Suppose the data set is 1.0, 1.0, 2.0, 3.0, 3.0, 4.0, 5.0, 5.0, 5.0.
    The ordinal ranks are 1, 2, 3, 4, 5, 6, 7, 8, 9.
    For v = 1.0, the Fractional rank is the average of the ordinal ranks: (1 + 2) / 2 = 1.5.
    In a similar manner, for v = 5.0, the Fractional rank is (7 + 8 + 9) / 3 = 8.0.
    Thus the Fractional ranks are: 1.5, 1.5, 3.0, 4.5, 4.5, 6.0, 8.0, 8.0, 8.0
Warning
The support for ranking of string containers is disabled when the library is built with the GNU Fortran compiler because of the lack of support for Parameterized Derived Types (PDTs) in GNU Fortran Compiler gfortran.
Note
Obtaining the ordinal ranking of an array is very similar to obtaining the sorted indices of the array.
For more information see this article.
Todo:
Low Priority: The relevant benchmarks comparing the functional and subroutine interfaces should be added here.
Todo:
Critical Priority: Support for ranking of arrays of PDTs must be enabled again as soon as GNU Fortran Compiler gfortran supports PDTs.
Todo:
High Priority: An optional argument sorted must be added to all interfaces within this module to allow fast computation of the rankings of previously sorted arrays without redundant resorting.
Test:
test_pm_arrayRank
Todo:
Normal Priority: The generic interfaces of this module must be extended to support rankings of matrices along a specified dimension.
Such a pattern occurs, for example, in computing the Spearman rank correlation matrix.
Todo:
Normal Priority: The current implementation of the generic ranking interfaces of this module are separated from each other.
However, it may be preferrable to merge all generic interfaces into single interface bindings getRank() and setRank().
Consequently, an extra argument of class rank_type must be added to all procedure interfaces to make them distinguishable.
For now, the procedures for different ranking methods were are under separate generic interface names, because of the complexity in the merging of the fractional ranking procedures (which output real ranks of default kind RK) with the rest (which output integer ranks of default kind IK).


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.

  1. 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.
  2. 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.

Author:
Amir Shahmoradi, April 21, 2017, 1:54 AM, Institute for Computational Engineering and Sciences (ICES), The University of Texas Austin

Variable Documentation

◆ dense

type(dense_type), parameter pm_arrayRank::dense = dense_type()

This is a scalar parameter object of type dense_type that is exclusively used to request the dense ranking of a given array within an interface of a procedure of the ParaMonte library.

For example usage, see the documentation of the target procedure requiring this object.

See also
dense
ordinal
modified
standard
fractional
dense_type
ordinal_type
modified_type
standard_type
fractional_type
rank_type


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.

  1. 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.
  2. 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.

Author:
Amir Shahmoradi, September 1, 2017, 12:00 AM, Institute for Computational Engineering and Sciences (ICES), The University of Texas Austin

Definition at line 232 of file pm_arrayRank.F90.

◆ fractional

type(fractional_type), parameter pm_arrayRank::fractional = fractional_type()

This is a scalar parameter object of type fractional_type that is exclusively used to request the fractional ranking of a given array within an interface of a procedure of the ParaMonte library.

For example usage, see the documentation of the target procedure requiring this object.

See also
dense
ordinal
modified
standard
fractional
dense_type
ordinal_type
modified_type
standard_type
fractional_type
rank_type


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.

  1. 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.
  2. 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.

Author:
Amir Shahmoradi, September 1, 2017, 12:00 AM, Institute for Computational Engineering and Sciences (ICES), The University of Texas Austin

Definition at line 480 of file pm_arrayRank.F90.

◆ modified

type(modified_type), parameter pm_arrayRank::modified = modified_type()

This is a scalar parameter object of type modified_type that is exclusively used to request the modified ranking of a given array within an interface of a procedure of the ParaMonte library.

For example usage, see the documentation of the target procedure requiring this object.

See also
dense
ordinal
modified
standard
fractional
dense_type
ordinal_type
modified_type
standard_type
fractional_type
rank_type


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.

  1. 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.
  2. 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.

Author:
Amir Shahmoradi, September 1, 2017, 12:00 AM, Institute for Computational Engineering and Sciences (ICES), The University of Texas Austin

Definition at line 356 of file pm_arrayRank.F90.

◆ MODULE_NAME

character(*,SK), parameter pm_arrayRank::MODULE_NAME = "@pm_arrayRank"

Definition at line 140 of file pm_arrayRank.F90.

◆ ordinal

type(ordinal_type), parameter pm_arrayRank::ordinal = ordinal_type()

This is a scalar parameter object of type ordinal_type that is exclusively used to request the ordinal ranking of a given array within an interface of a procedure of the ParaMonte library.

For example usage, see the documentation of the target procedure requiring this object.

See also
dense
ordinal
modified
standard
fractional
dense_type
ordinal_type
modified_type
standard_type
fractional_type
rank_type


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.

  1. 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.
  2. 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.

Author:
Amir Shahmoradi, September 1, 2017, 12:00 AM, Institute for Computational Engineering and Sciences (ICES), The University of Texas Austin

Definition at line 294 of file pm_arrayRank.F90.

◆ standard

type(standard_type), parameter pm_arrayRank::standard = standard_type()

This is a scalar parameter object of type standard_type that is exclusively used to request the standard ranking of a given array within an interface of a procedure of the ParaMonte library.

For example usage, see the documentation of the target procedure requiring this object.

See also
dense
ordinal
modified
standard
fractional
dense_type
ordinal_type
modified_type
standard_type
fractional_type
rank_type


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.

  1. 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.
  2. 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.

Author:
Amir Shahmoradi, September 1, 2017, 12:00 AM, Institute for Computational Engineering and Sciences (ICES), The University of Texas Austin

Definition at line 418 of file pm_arrayRank.F90.