LEapply {POSetR}

Applies scalar functions over the set of linear extensions of a poset and returns the corresponding average values

Description

"LEapply" is composed of three main elements: (i) the linear extensions generator, (ii) the application of the argument functions to the linear extensions and (iii) the computation of the averages of the results, for each function separately; see Fattore M (2016). “Partially ordered sets and the measurement of multidimensional ordinal deprivation.” Social Indicators Research, 128(2), 835–858..

Usage

LEapply(x, ...)

## S3 method for class 'poset'
LEapply(
  x,
  FUN = "MutualRankingProbability",
  ...,
  generator = c("AllLE", "BubleyDyer"),
  bubleydyer.precision = 10,
  bubleydyer.nit = NULL,
  bubleydyer.progressBar = TRUE,
  degrees = NULL
)

Arguments

x

an environment of class poset, see poset for details.

...

optional arguments to FUN.

FUN

the function, or a list of functions, to be applied to each linear extension: see 'Details'.

generator

a string specifying the method used to generate the linear extensions. The default value is "AllLE". See section 'Details' below.

bubleydyer.precision

considered only if "BubleyDyer" generator is selected. It corresponds to the number of digit precision of the frequencies in the sampling distributions of linear extensions.

bubleydyer.nit

considered only if "BubleyDyer" generator is selected. Number of iterations in the Bubley-Dyer algorithm, if NULL (default) it is set as indicated in Bubley and Dyer (1999) depending on the value of bubleydyer.precision and the number of elements of the poset.

bubleydyer.progressBar

logical that indicates whether to show a text progress bar or not

degrees

to generate the lexicographic linear extensions of a product order, the poset x describes the dominance (e.g. relative importance) between ordinal variables and degrees is a numerical vector specifying the number of degrees of each variable, represented by in the poset.

Details

Argument FUN must be either a function or a list of functions, each one depending on a vector of characters representing the names of the elements of the poset.

If degrees is not NULL but a numerical vector as long as the number of elements in the poset, the poset elements are considered as ordinal variables. Therefore degrees represents their number of degrees that are represented as integer numbers starting from 0. In this case, LEapply generates the lexicographical linear extensions of the product order of the ordeinal variables. Its elements are called profiles and they are obtained by the combination of the degrees of variables separated by a dash. For details about lexicographical linear extensions and profiles see Fattore M, Arcagni A (2018). “A reduced posetic approach to the measurement of multidimensional ordinal deprivation.” Social Indicators Research, 136(3), 1053–1070..

Some functions are already implemented in the C++ library and they can be called by their names. Currently, such functions are "MutualRankingProbability", "Separation", and "AverageHeight".

Each function in FUN must return a numerical or logical matrix. Each function can depend on additional arguments that can be passed through ...; such additional arguments must be the same for all the functions in the list.

Argument generator specifies the linear extension generation algorithm. The available generators are "AllLE", that produces all of the linear extensions of the input poset, and "BubleyDyer", which samples uniformly from the set of linear extensions, through an MCMC algorithm (Bubley and Dyer 1999).

Value

The average values of the argument functions FUN over the set of linear extensions (or lexicographic ones if degrees argument is not NULL).

References

Bubley R, Dyer M (1999). “Faster random generation of linear extensions.” Discrete mathematics, 201(1-3), 81–88.

Fattore M (2016). “Partially ordered sets and the measurement of multidimensional ordinal deprivation.” Social Indicators Research, 128(2), 835–858.

Fattore M, Arcagni A (2018). “A reduced posetic approach to the measurement of multidimensional ordinal deprivation.” Social Indicators Research, 136(3), 1053–1070.

Habib M, Medina R, Nourine L, Steiner G (2001). “Efficient algorithms on distributive lattices.” Discrete Applied Mathematics, 110(2-3), 169–187.

See Also

poset

Examples

dom <- matrix(c(
"a", "b",
"c", "b",
"b", "d"
), ncol = 2, byrow = TRUE)
p <- poset(x = dom)

## Not run: 
LEapply(
  x = p,
  FUN = "MutualRankingProbability",
  generator = "AllLE",
  degrees = c(3, 2, 3, 2)
)

a_rank_dist <- function(le) {
  return(matrix(le == "a"))
}
LEapply(x = p, FUN = a_rank_dist)
## End(Not run)