README.rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# landmark

```{r, echo=FALSE, message=FALSE, results=FALSE}
devtools::load_all()
```

Calculate landmark sets for finite metric spaces using the maxmin procedure (for fixed-radius balls) or an adaptation of it for rank data (for roughly fixed-cardinality nearest neighborhoods).

```{r example, fig.height=3}
(x <- matrix(c(-1, -.5, 0, .75, .875, 1), dimnames = list(letters[1:6], "x")))
plot(cbind(x, 0), asp = 1, pch = 16)
text(cbind(x, .05), labels = rownames(x))
```

## `maxmin` procedure

The original `maxmin` procedure produces a landmark set for covering a point cloud with either of two minimal ball covers:

* a minimum number of balls of fixed uniform radius
* a fixed number of balls of minimum uniform radius

```{r maxmin landmark sets using C++ engine}
x[landmarks_maxmin(x, radius = 0.5, engine = "C++"), , drop = FALSE]
x[landmarks_maxmin(x, radius = 0.25, engine = "C++"), , drop = FALSE]
x[landmarks_maxmin(x, radius = 0.125, engine = "C++"), , drop = FALSE]
x[landmarks_maxmin(x, num = 6L, engine = "C++"), , drop = FALSE]
```

```{r ball covers using R engine}
landmarks_maxmin(x, num = 4L, engine = "R", cover = TRUE)
landmarks_maxmin(x, radius = 0.5, engine = "R", cover = TRUE)
landmarks_maxmin(x, radius = 1.5, engine = "R", cover = TRUE)
landmarks_maxmin(x, radius = 3.5, engine = "R", cover = TRUE)
```

## `lastfirst` procedure

An adaptation of `maxmin` to ranked distances will produce a landmark set for covering a point cloud with either of two minimal neighborhood covers:

* a minimum number of neighborhoods of fixed (approximately) uniform cardinality
* a fixed number of neighborhoods of minimal (approximately) uniform cardinality

Cardinality is only exact up to ties, which may be handled different ways and will result in cover sets of different cardinalities.

```{r lastfirst landmark sets using R engine}
x[landmarks_lastfirst(x, cardinality = 3L, seed_index = 6L), , drop = FALSE]
x[landmarks_lastfirst(x, cardinality = 2L, seed_index = 6L), , drop = FALSE]
x[landmarks_lastfirst(x, num = 4L, seed_index = 6L), , drop = FALSE]
x[landmarks_lastfirst(x, cardinality = 1L, seed_index = 6L), , drop = FALSE]
```

```{r neighborhood covers using C++ engine}
landmarks_lastfirst(x, cardinality = 1L, seed_index = 6L, engine = "C++", cover = TRUE)
landmarks_lastfirst(x, num = 4L, seed_index = 6L, engine = "C++", cover = TRUE)
landmarks_lastfirst(x, cardinality = 3L, seed_index = 6L, engine = "C++", cover = TRUE)
landmarks_lastfirst(x, cardinality = 5L, seed_index = 6L, engine = "C++", cover = TRUE)
```

# references

This package was spun off from [the Mapper package](https://github.com/peekxc/Mapper/).

A rigorous mathematical treatment is underway at [this Overleaf project](https://www.overleaf.com/read/fpjrtgfjstyx).