R: Predecessor and Successor Functions

pred_succ {rPref} | R Documentation

## Predecessor and Successor Functions

### Description

Function for traversing the BTG (Better-Than-Graph or Hasse diagram) of a preference.

### Usage

    init_pred_succ(p, df = NULL)

    hasse_pred(p, v, intersect = FALSE)

    hasse_succ(p, v, intersect = FALSE)

    all_pred(p, v, intersect = FALSE)

    all_succ(p, v, intersect = FALSE)

### Arguments

`p` | A preference. Worse tuples in the induced order are successors and better tuples are predecessors.
`df` | (optional) A data frame characterizing the set wherein predecessors/successors are searched. If `df` is `NULL` then the data frame associated with the preference is used. Causes an error if `df == NULL` and no data frame is associated.
`v` | A numeric vector of indices in `df`. This represents the set of tuples for which predecessors/successors are searched.
`intersect` | (optional) Logical value. If it is `FALSE` (by default) the union of all predecessors/successors of `v` is returned. For `intersect = TRUE` the intersection of those values is returned.

### Details

These functions return the predecessors and successors in the Better-Than-Graph of a preference. Note that the successors/predecessors can can be plotted via `get_btg`. Before any of the successor/predecessor functions can be used the initialization has to be called as follows:

`init_pred_succ(p, df)`

There `p` is a preference object and `df` a data frame. When this done, the data frame `df` is associated with `p`, i.e., implicitly `assoc.df` is called. If the preference has already an associcated data frame, `df` can be omitted. For example

`p <- low(mpg, df = mtcars)`
`init_pred_succ(p)`

does the initialization of the preference `low(mpg)` on the data set `mtcars`.

The `init_pred_succ` function calculates the Better-Than-Relation on `df` w.r.t. `p`. Afterwards the predecessor and successor functions, as subsequently described, can be called. The value of `v` is a numeric vector within `1:nrow(df)` and characterizes a subset of tuples in `df`. The return value of these functions is again a numeric vector referring to the row numbers in `df` and it is always ordered ascending, independently of the order of the indices in `v`.

`all_pred(p, v)`

  Returns all predecessors of `v`, i.e., indices of better tuples than `v`.

`all_succ(p, v)`

  Returns all successors of `v`, i.e., indices of worse tuples than `v`.

`hasse_pred(p, v)`

  Returns the direct predecessors of `v`, i.e., indices of better tuples than `v` where the better-than-relation is contained in the transitive reduction.

`hasse_succ(p, v)`

  Returns the direct successors of `v`, i.e., indices of worse tuples than `v` where the better-than-relation is contained in the transitive reduction.

If `v` has length 1, then the value of `intersect` does not matter, as there is nothing to intersect or join. For scalar values `x` and `y` the following identities hold, where `f` is one of the predecessor/successor functions:

`f(p, c(x, y), intersect = FALSE) == union(f(p, x), f(p, y))`

`f(p, c(x, y), intersect = TRUE) == intersect(f(p, x), f(p, y))`

### Examples

    # preference on mtcars for high mpg and low weight
    p <- high(mpg) * low(wt)
    init_pred_succ(p, mtcars)

    # helper to show mpg/hp values
    show_vals <- function(x) mtcars[x,c('mpg','wt')]

    # pick some tuple "in the middle"
    show_vals(10)

    # show (direct) predecessors/successors of tuple 10
    show_vals(hasse_pred(p, 10)) # Next better car
    show_vals(hasse_succ(p, 10)) # Next worse car
    show_vals(all_pred(p, 10))   # All better cars
    show_vals(all_succ(p, 10))   # All worse cars

[Package rPref version 1.3 Index]