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:

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

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, 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.

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, 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.

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, 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.

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, 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.

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, 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.

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, 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.

Data Types

Variables

Detailed Description

Variable Documentation

◆ dense

◆ fractional

◆ modified

◆ MODULE_NAME

◆ ordinal

◆ standard