---
title: "VS3 - Spatial Point Patterns"
author: "Elvan Ceyhan"
date: '`r Sys.Date()` '
output:
  bookdown::html_document2:
    base_format: rmarkdown::html_vignette
bibliography: References.bib
vignette: >
  %\VignetteIndexEntry{VS3 - Spatial Point Patterns}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
  
header-includes:
   - \usepackage[utf8]{inputenc}
   - \usepackage[french]{babel}
   - \usepackage[T1]{fontenc}
---

<style>
.math {
  font-size: small;
}
</style>

```{r, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE,comment = "#>",fig.width=6, fig.height=4, fig.align = "center") 
```

\newcommand{\X}{\mathcal{X}}
\newcommand{\Y}{\mathcal{Y}}
\newcommand{\y}{\mathsf{y}}

First we load the `pcds` package:
```{r setup, message=FALSE, results='hide'}
library(pcds)
```

#  Generation of Points from CSR, Segregation, and Association Patterns
We provide the functions for random point generation from three patterns, namely, complete spatial randomness (CSR)
which is usually the benchmark pattern to test or compare other patterns,
segregation and association patterns (of different types).

 * *CSR* is equivalent to homogeneous point pattern in an unbounded support, and to the uniform distribution in a bounded support. 
 * *Segregation* is the pattern in which classes tend to repel each other in the sense that points tend to be clustered around points from the same class.
 * *Association* is the pattern in which points from one class tend to cluster around points from the other class.

# Generation of Points from CSR
We consider generation of points from CSR in one triangle, multiple triangles, and also in one tetrahedron.
The 1D point generation from CSR can easily be handled with the usual `runif` function in base `R` 
in both the one interval and multiple interval cases,
hence no specialized functions are provided for the CSR in the 1D setting.

## Generation of Uniform Points in One Triangle {#sec:CSR1T}
We choose the triangle $T=T(A,B,C)$ with vertices $A=(1,1)$, $B=(2,0)$, and $C=(1.5,2)$ as the support of uniform points.
The same triangle $T$ was used in other `pcds` Vignette Sections as well.

```{r SPch1}
A<-c(1,1); B<-c(2,0); C<-c(1.5,2);
Tr<-rbind(A,B,C)
n<-5  #try also n<-10, 20, 50 or 100
```

We generate $n=$ `r n` $\X$ points inside the triangle $T$ using the function `runif.tri`,
and provide the summary of these uniform points and the corresponding scatterplot (together with the triangle).
The function `runif.tri` is an object of class `Uniform` and
takes arguments `k,tri` where 

- `n`, a positive integer representing the number of uniform points to be generated in the triangle, and
- `tri` a $3 \times 2$ matrix with each row representing a vertex of the triangle.

Its `call` (with `Xdt` in the below script) just returns the type of the pattern.
Its `summary` returns a description of the pattern, the study window for the points,
the vertices of the support of the uniform distribution (i.e., vertices of $T$),
first 6 or fewer of the generated points,
and the number of points.
The `plot` function (or `plot.Uniform`) returns the plot of the triangle together with the generated points.
```{r CSR1T, eval=F, fig.cap="Scatterplot of the uniform points in the triangle $T=T(A,B,C)$ with vertices $A=(1,1)$, $B=(2,0)$, and $C=(1.5,2)$."}
set.seed(123)
Xdt<-runif.tri(n,Tr)
Xdt
#> Call:
#> runif.tri(n = n, tri = Tr)
#> 
#> Type:
#> [1] "Uniform Distribution in the Triangle with Vertices (1,1), (2,0) and (1.5,2)"
summary(Xdt)
#> Call:
#> runif.tri(n = n, tri = Tr)
#> 
#> Type of the Pattern : [1] "Uniform Distribution in the Triangle with Vertices (1,1), (2,0) and (1.5,2)"
#> 
#> Study Window
#> range in x-coordinate = 1 2 
#> range in y-coordinate = 0 2 
#> 
#>  Vertices of the Support of the Uniform Distribution
#>   [,1] [,2]
#> A  1.0    1
#> B  2.0    0
#> C  1.5    2
#> 
#>  5 uniform points in the triangle with vertices (1,1), (2,0) and (1.5,2)  
#>  (first 6 or fewer are printed) 
#>          [,1]      [,2]
#> [1,] 1.408977 1.7660348
#> [2,] 1.940467 0.0911130
#> [3,] 1.528105 1.7848381
#> [4,] 1.551435 0.9132295
#> [5,] 1.677571 1.1452668
#> 
#> Number of points
#> nx ny 
#>  5  3 
#> nx : the number of uniform points
#> ny : the number of vertices of the support region
plot(Xdt)
```

There is also uniform point generation capability in a standard equilateral triangle, or in  the standard basic triangle,
with the functions `runif.std.tri` and `runif.basic.tri`,
with arguments `n` and `n,c1,c2`, respectively, see the corresponding help pages for the details.
These functions are mostly for simulation purposes, 
as PE- and CS-PCDs are geometry invariant, and AS-PCD is
scale invariant for uniform data in one triangle.

## Generation of Uniform Points in Multiple Triangles
We can generate uniform points in the union of multiple Delaunay triangles, 
that is, in the convex hull of non-target points,
where $n_x$ is number of $\X$ (i.e. target) points and $n_y$ is number of $\Y$ (nontarget) points.
$\Y$ points constitute the vertices of the Delaunay triangles, and when uniform points are generated in the convex hull
of nontarget points, then points in each triangle will also be uniformly distributed (restricted to the triangle,
i.e. scaled by the ratio of the area of the convex hull to the area of the particular triangle).

```{r SPch2}
nx<-10; ny<-5  #try also nx<-40; ny<-5 or nx<-100;  #try also nx<-1000;  ny<-10;
set.seed(1)
Yp<-cbind(runif(ny,0,10),runif(ny,0,10))
```
We first generate `r ny` $\Y$ points uniformly in the unit square $(0,1) \times (0,1)$ 
(which will form the vertices of the Delaunay triangles).

Next, we generate  $n_x=$ `r nx` $\X$ points uniformly in the convex hull of the 5 $Y$ points (i.e. in the union of the Delaunay triangles based on `r ny` $Y$ points) using the function `runif.multi.tri`,
and provide the summary of these uniform points and the corresponding scatterplot (together with the Delaunay triangles).
The function `runif.multi.tri` is an object of class `Uniform`
and takes arguments `n,Yp,DTmesh` where

- `n`, a positive integer representing the number of uniform points to be generated 
in the convex hull of the point set `Yp`,
- `Yp`, a set of 2D points whose convex hull is the support of the uniform points to be generated.
- `DTmesh`, the triangulation nodes with neighbours (result of `interp::tri.mesh` function from `interp` package). 

Its `call` and `plot` is as in `runif.tri` and its `summary`
is similar, with the addition of the $x$ and $y$ coordinates of the nodes on the boundary of the convex hull of $\Y$ points
and their indices (labeled `$i`).
The `plot` of the object returns the scatterplot of the $\X$ points 
together with Delaunay triangulation of $\Y$ points.
```{r CSRmT, fig.cap="Scatterplot of the uniform $X$ points in the Delaunay triangles based on 5 $Y$ points."}
Xdt<-runif.multi.tri(nx,Yp)  #data under CSR in the convex hull of Ypoints
Xdt
summary(Xdt)
plot(Xdt)
```

## Generation of Uniform Points in a Tetrahedron
We first generate four 3D points that will form the arbitrary tetrahedron $T=T(A,B,C,D)$ as the support of uniform points.

```{r SPch3, eval=F}
set.seed(11)
A<-sample(1:12,3); B<-sample(1:12,3); C<-sample(1:12,3); D<-sample(1:12,3)
tetra<-rbind(A,B,C,D)/6
n<-5 #try also n<-10, 20, 50, or 100
```

We generate $n=$ `r n` $\X$ points uniformly inside the tetrahedron $T$ using the function `runif.tetra`,
and provide the summary of these uniform points and the corresponding scatterplot (together with the tetrahedron).
The function `runif.tetra` is an object of class `Uniform` and takes arguments `n,th` where

- `n`, a positive integer representing the number of uniform points to be generated in the tetrahedron, and
- `th`, a $4 \times 3$ matrix with each row representing a vertex of the tetrahedron.

Its `call`, `plot`, and `summary` 
are as in `runif.tri`.
The `plot` of the object returns the 3D scatterplot of the $\X$ points together with tetrahedron.
```{r CSR1th, eval=F, fig.cap="Scatterplot of the uniform $X$ points in the tetrahedron $T=T(A,B,C,D)$."}
Xdt<-runif.tetra(n,tetra)
Xdt
#> Call:
#> runif.tetra(n = n, th = tetra)
#> 
#> Type:
#> [1] "Uniform Distribution in the Tetrahedron with Vertices (1.67,0.33,1.33), (1.5,0.17,0.83), (2,1,0.83) and (1,1.17,0.83)"
summary(Xdt)
#> Call:
#> runif.tetra(n = n, th = tetra)
#> 
#> Type of the Pattern : [1] "Uniform Distribution in the Tetrahedron with Vertices (1.67,0.33,1.33), (1.5,0.17,0.83), (2,1,0.83) and (1,1.17,0.83)"
#> 
#> Study Window
#> range in x-coordinate = 1 2 
#> range in y-coordinate = 0.1666667 1.166667 
#> 
#>  Vertices of the Support of the Uniform Distribution
#>       [,1]      [,2]      [,3]
#> A 1.666667 0.3333333 1.3333333
#> B 1.500000 0.1666667 0.8333333
#> C 2.000000 1.0000000 0.8333333
#> D 1.000000 1.1666667 0.8333333
#> 
#>  5 uniform points in the tetrahedron with vertices (1.67,0.33,1.33), (1.5,0.17,0.83), (2,1,0.83) and (1,1.17,0.83)  
#>  (first 6 or fewer are printed) 
#>          [,1]      [,2]      [,3]
#> [1,] 1.398149 0.6715843 0.9971730
#> [2,] 1.642032 0.4435400 0.8851113
#> [3,] 1.502856 0.7644274 1.0461309
#> [4,] 1.425548 0.5928684 0.9355892
#> [5,] 1.239314 0.9320898 0.9298472
#> 
#> Number of points
#> nx ny 
#>  5  4 
#> nx is the number of Uniform points 
#>  ny is the number of vertices of the support region
plot(Xdt)
```

Similarly, there is also uniform point generation capability in a standard regular tetrahedron
with the function `runif.std.tetra` with the sole argument `n`, 
see the corresponding help page for the details.
This function is also mostly for simulation purposes, 
as PE- and CS-PCDs are geometry invariant for uniform data in a tetrahedron.

# Generation of Points from the Segregation Pattern
We mainly consider two types of segregation, *type I segregation* and *circular segregation* 
(there is also a *type II segregation* which is briefly described at the end of Section \@ref(sec:circ-segmT),
however, it is only implemented in standard equilateral triangle at this point).
We provide the description in the 2D setting, the extensions to higher dimensional and 1D settings are straightforward.

* In *type I segregation*, triangular or polygonal regions around the $\Y$ points
are forbidden for $\X$ points in each Delaunay triangle,
and 
* in *circular segregation*, $\X$ points can not be closer to $\Y$ points than a given distance (radius) in each triangle.

See @ceyhan:arc-density-PE, @ceyhan:arc-density-CS, and @ceyhan:dom-num-NPE-Spat2011 for more on the type I segregation pattern.

## Generation of Points Segregated (in a Type I Fashion) from the Vertices of a Triangle
Here, the points are generated in type I segregation, parameterized by `delta`, 
which is a positive real number in $(0,1)$ so that $\delta 100$ \% area 
around vertices of each Delaunay triangle is forbidden for $\X$ points.
The forbidden regions are chosen in such a way that $\X$ points can not be further from a distance to the opposite edge
where this distance depends on `delta`.
Such a construction preserves geometry invariance for 
arc density and domination number of PE- and CS-PCDs under segregation as well.

```{r SPch4}
A<-c(1,1); B<-c(2,0); C<-c(1.5,7/3);
Tr<-rbind(A,B,C)
del<-.4
n<-10  #try also n<-100 or 1000
```
The same triangle $T$ used in the CSR illustration in Section \@ref(sec:CSR1T) is used here as well
and the support of the segregated $\X$ points will be subset of this triangle.
We specify `delta=` `r del` for the type I segregation pattern.

We generate $n=$ `r n` $\X$ points uniformly inside the type I segregation support in $T$ using the function `rseg.tri`,
and provide the summary of these segregated points and the corresponding scatterplot (together with the triangle).
The function `rseg.tri` is an object of class `Patterns`
and has arguments `n,tri,delta` where 

- `n`, a positive integer representing the number of points to be generated from the segregation pattern
in the triangle, `tri`.
- `tri`, a $3 \times 2$ matrix with each row representing a vertex of the triangle.
- `delta`, a positive real number in $(0,1)$. `delta` is the parameter of segregation (that is,
$\delta \, 100$ \% area around vertices of each Delaunay triangle is forbidden for point generation).

Its `call` and `summary` are as in `runif.tri` with the addition of the segregation parameter.
The `plot` function (or `plot.Patterns`) returns the plot of the triangle together with the generated points.
```{r seg1T, eval=F, fig.cap="Scatterplot of the points segregated (in a type I fashion) from the vertices of the triangle $T=T(A,B,C)$ with vertices $A=(1,1)$, $B=(2,0)$, and $C=(1.5,2)$."}
Xdt<-rseg.tri(n,Tr,del)
Xdt
#> Call:
#> rseg.tri(n = n, tri = Tr, delta = del)
#> 
#> Type:
#> [1] "Type I Segregation of 10 points in the triangle with vertices (1,1), (2,0) and (1.5,2.33) and exclusion parameter delta = 0.4"
summary(Xdt)
#> Call:
#> rseg.tri(n = n, tri = Tr, delta = del)
#> 
#> Type of the Pattern
#> [1] "Type I Segregation of 10 points in the triangle with vertices (1,1), (2,0) and (1.5,2.33) and exclusion parameter delta = 0.4"
#> 
#> Parameters of the Pattern
#> exclusion parameter 
#>                 0.4 
#> 
#> Study Window
#> range in x-coordinate = 1 2 
#> range in y-coordinate = 0 2.333333 
#> 
#>  Generated Points from Pattern of Type I Segregation of One Class from Vertices of the Triangle  
#>  (first 6 or fewer are printed) 
#>         [,1]      [,2]
#> pnt 1.587007 0.5205062
#> pnt 1.409048 0.9539932
#> pnt 1.669594 0.7064556
#> pnt 1.523988 0.5721596
#> pnt 1.271635 1.6545486
#> pnt 1.674897 1.3032453
#> 
#> Number of points:
#> nx ny 
#> 10  3 
#> nx = number of generated points according to the pattern 
#> ny = number of reference (i.e. Y) points
plot(Xdt)
```

## Generation of Points Segregated (in a Type I Fashion) from a Given Set of $\Y$ Points
This case is equivalent to generation of type I segregation in each of the Delaunay triangles
based on the non-target points (i.e., $\Y$ points).
That is, $\X$ points are segregated in type I fashion from the vertices of each Delaunay triangle
at the same level (i.e., parameterized with the same `delta`).
<!-- nx is number of X points (target) and ny is number of Y points (non-target). -->

```{r segI}
ny<-5;
set.seed(1)
Yp<-cbind(runif(ny),runif(ny))
del<-.4
nx<-10;  #try also nx<-100 or 1000;  
```

We first generate `r ny` $\Y$ points uniformly in the unit square which will form the vertices of the Delaunay triangles, 
and specify `delta=` `r del` for type I segregation.

We generate $n=$ `r nx` $\X$ points uniformly inside the type I segregation support in the union of 
the Delaunay triangles (i.e. in the convex hull of the $\Y$ points) using the function `rseg.multi.tri`,
and provide the summary of these segregated points and the corresponding scatterplot (together with the triangles).
The function `rseg.multi.tri` is an object of class `Patterns` and takes arguments `n,Yp,delta,DTmesh,DTr` where

- `n`, a positive integer representing the number of points to be generated.
- `Yp`, a set of 2D points from which Delaunay triangulation is constructed.
- `delta`, a positive real number in $(0,1)$. `delta` is the parameter of segregation 
(that is, $\delta 100$ % area around vertices of each Delaunay triangle is 
forbidden for point generation).
- `DTmesh`, the Delaunay triangulation of `Yp`, default is `NULL`, which is computed via `interp::tri.mesh` function
in `interp` package. `interp::tri.mesh` function yields the triangulation nodes with their neighbors, and
creates a triangulation object.
- `DTr`, the Delaunay triangles based on `Yp`, default is `NULL`, which is computed via `interp::tri.mesh` function
in `interp` package. `interp::triangles` function yields a triangulation data structure from the triangulation object created by `interp::tri.mesh`.

Its `call`, `summary`, and `plot` are as in `rseg.tri`.
The `plot` of the object is the scatterplot of the $\X$ points
together with Delaunay triangulation of $\Y$ points.
```{r segmT, fig.cap="Scatterplot of the $X$ points segregated (in a type I fashion) from the $Y$ points."}
Xdt<-rseg.multi.tri(nx,Yp,del)
Xdt
summary(Xdt)
plot(Xdt)
```

## Generation of Points Segregated (in a Radial or Circular fashion) from a Given Set of $\Y$ Points {#sec:circ-segmT}
In this type of segregation, the points are generated with a parameter, `e`, which is a positive real number
representing the radius of the balls centered at $\Y$ points. 
These balls are forbidden for the generated points (i.e., $\X$ points can not reside in the union of these balls).
Note that same radius is used for each $\Y$ point, and the $\X$ points are not restricted to the convex hull of $\Y$ points
(or the Delaunay triangles).
Such a construction, although more intuitive, does not preserve the geometry invariance property
for the arc density and domination number of PE- and CS-PCDs under segregation.

```{r}
nx<-10;  #try also nx<-100 or 1000; 
ny<-5
e<-.15;
```

```{r SPch5, eval=F}
#with default bounding box (i.e., unit square)
set.seed(1)
Yp<-cbind(runif(ny),runif(ny))
```
We first generate `r ny` $\Y$ points uniformly in the unit square and specify `e=` `r e` for circular segregation.

We generate $n=$ `r nx` $\X$ points uniformly inside the circular segregation support using the function `rseg.circular`,
and provide the summary of these segregated points and the corresponding scatterplot (together with the $\Y$ points).
The function `rseg.circular` is an object of class `Patterns` and takes arguments `n,Yp,e,a1,a2,b1,b2)` where

- `n`, a positive integer representing the number of points to be generated.
- `Yp`, a set of 2D points representing the reference points. The generated points are segregated
(in a circular or radial fashion) from these points.
- `e`, a positive real number representing the radius of the balls centered at `Yp` points. These balls
are forbidden for the generated points (i.e., generated points would be in the complement of union of these
balls).
- `a1,a2`, the real numbers representing the range of $x$-coordinates in the region
(default is the range of $x$-coordinates of the `Yp` points).
- `b1,b2`, the real numbers representing the range of $y$-coordinates in the region
(default is the range of $y$-coordinates of the `Yp` points).

Its `call`, `summary`, and `plot` are as in `rseg.multi.tri`.
The `plot` of the object is the scatterplot of the $\X$ points together with $\Y$ points 
(here we use `asp=1` so that the prohibited regions are actually depicted as circles).
```{r segmTcirc, eval=F, fig.cap="Scatterplot of the $X$ points segregated (in a circular fashion) from the $Y$ points in the unit square."}
Xdt<-rseg.circular(nx,Yp,e)
Xdt
#> Call:
#> rseg.circular(n = nx, Yp = Yp, e = e)
#> 
#> Type:
#> [1] "Segregation of 10 X points from 5 Y points with circular exclusion parameter e = 0.15"
summary(Xdt)
#> Call:
#> rseg.circular(n = nx, Yp = Yp, e = e)
#> 
#> Type of the Pattern
#> [1] "Segregation of 10 X points from 5 Y points with circular exclusion parameter e = 0.15"
#> 
#> Parameters of the Pattern
#> exclusion parameter 
#>                0.15 
#> 
#> Study Window
#> range in x-coordinate = 0.05168193 1.058208 
#> range in y-coordinate = -0.08821373 1.094675 
#> 
#>  Generated Points from Pattern of Segregation of Class X from Class Y  
#>  (first 6 or fewer are printed) 
#>            [,1]       [,2]
#> [1,] 0.82654723 0.50050923
#> [2,] 0.77398352 1.08510108
#> [3,] 0.99248692 0.16272732
#> [4,] 0.70760843 0.06030401
#> [5,] 0.32064644 0.36851638
#> [6,] 0.06515965 0.36410878
#> 
#> Number of points:
#> nx ny 
#> 10  5 
#> nx = number of generated points according to the pattern 
#> ny = number of reference (i.e. Y) points
plot(Xdt,asp=1) 
```

There is also point generation capability from segregation pattern in a standard equilateral triangle with two types of segregation,
type I segregation is the above described one and type II segregation (described below),
with the relevant functions `rseg.std.tri` and `rsegII.std.tri`, 
with arguments `n,eps` for both, see the corresponding help pages for the details.
These functions are mostly for simulation purposes, as arc density and domination number of PE- and CS-PCDs are geometry invariant.
*Type II segregation* is the pattern in which a region at a certain distance from the boundary of the triangle is forbidden. 
That is, there is a parameter, `eps`, which is a positive real number representing
the distance from the interior triangle points to the boundary of $T_e$, (i.e., an annular region
in the interior of the triangle around the edges) which is forbidden under this type of segregation.

# Generation of Points from the Association Pattern 
We mainly consider two types of association, *type I association* and *circular association* 
(there is also a *type II association* which is briefly described at the end of Section \@ref(sec:matern-ascmT),
however, it is only implemented in standard equilateral triangle at this point).
We provide the description in the 2D setting, the extensions to higher dimensional and 1D settings are straightforward.

* In *type I association*, triangular or polygonal regions around the $\Y$ points
are the only regions allowed for $\X$ points in each Delaunay triangle,
and 
 * in *circular association*, $\X$ points must be closer to $\Y$ points than a given distance (i.e., radius) in each triangle.

See @ceyhan:arc-density-PE, @ceyhan:arc-density-CS, and @ceyhan:dom-num-NPE-Spat2011 for more on the type I association pattern.

## Generation of Points Associated (in a Type I Fashion) with the Vertices of a Triangle
Here, the points are generated in type I association, parameterized by `delta`, 
which is a positive real number in $(0,1)$ so that 
$\delta 100$ \% area around vertices of each Delaunay triangle is the only region allowed for $\X$ points.
The allowed regions are chosen in such a way that $\X$ points must be further from a distance to the opposite edge
where this distance depends on `delta`.
Such a construction preserves geometry invariance for arc density and domination number of PE- and CS-PCDs
under association as well.

```{r SPch6}
A<-c(1,1); B<-c(2,0); C<-c(1.5,7/3);
Tr<-rbind(A,B,C)
del<-.4
n<-5  #try also n<-100 or 1000
```
The same triangle $T$ used in the CSR illustration in Section \@ref(sec:CSR1T) is used here as well
and the support of the segregated $\X$ points will be subset of this triangle.
We specify `delta=` `r del` for the type I association pattern.

We generate $n=$ `r n` $\X$ points uniformly inside the type I association support in $T$ using the function `rassoc.tri`, 
and provide the summary of these associated points and the corresponding scatterplot (together with the triangle).
The function `racs.tri` is an object of class `Patterns` and has the arguments as `rseg.tri`. 
Its `call`, `summary`, and `plot` are also as in `rseg.tri`.
```{r asc1T, eval=F, fig.cap="Scatterplot of the points associated (in a type I fashion) with the vertices of the triangle $T=T(A,B,C)$ with vertices $A=(1,1)$, $B=(2,0)$, and $C=(1.5,2)$."}
Xdt<-rassoc.tri(n,Tr,del)
Xdt
#> Call:
#> rassoc.tri(n = n, tri = Tr, delta = del)
#> 
#> Type:
#> [1] "Type I Association of 5 points in the triangle with vertices (1,1), (2,0) and (1.5,2.33) with attraction parameter delta = 0.4"
summary(Xdt)
#> Call:
#> rassoc.tri(n = n, tri = Tr, delta = del)
#> 
#> Type of the Pattern
#> [1] "Type I Association of 5 points in the triangle with vertices (1,1), (2,0) and (1.5,2.33) with attraction parameter delta = 0.4"
#> 
#> Parameters of the Pattern
#> attraction parameter 
#>                  0.4 
#> 
#> Study Window
#> range in x-coordinate = 1 2 
#> range in y-coordinate = 0 2.333333 
#> 
#>  Generated Points from Pattern of Type I Association of One Class with Vertices of the Triangle  
#>  (first 6 or fewer are printed) 
#>         [,1]      [,2]
#> pnt 1.529720 1.8418312
#> pnt 1.477620 2.0094888
#> pnt 1.478545 1.7880582
#> pnt 1.476351 2.0817961
#> pnt 1.757087 0.4729486
#> 
#> Number of points:
#> nx ny 
#>  5  3 
#> nx = number of generated points according to the pattern 
#> ny = number of reference (i.e. Y) points
plot(Xdt)
``` 

## Generation of Points Associated (in a Type I Fashion) with a Given Set of $\Y$ Points

This case is equivalent to generation of type I associated points in each of the Delaunay triangles
based on the non-target points (i.e., $\Y$ points).
That is, $\X$ points are associated in type I fashion with the vertices of each Delaunay triangle
at the same level (i.e., parameterized with the same `delta`).

```{r SPch7}
ny<-5;
set.seed(1)
Yp<-cbind(runif(ny),runif(ny))
del<-.4
nx<-10;  #try also nx<-100 or 1000; 
```
We first generate `r ny` $\Y$ points uniformly in the unit square 
which will form the vertices of the Delaunay triangles, 
and specify `delta=` `r del` for type I association.

We generate $n=$ `r nx` $\X$ points uniformly inside the type I association support 
in the union of the Delaunay triangles (or in the convex hull
of the $\Y$ points) using the function `rassoc.multi.tri`, 
and provide the summary of these associated points and the corresponding scatterplot (together with the triangles).
The function `rassoc.multi.tri` is an object of class `Patterns` and its arguments, `call`, `summary`, and `plot` are as in `rseg.multi.tri`.
```{r ascmT, fig.cap="Scatterplot of the $X$ points associated (in a type I fashion) with the $Y$ points."}
Xdt<-rassoc.multi.tri(nx,Yp,del)
Xdt
summary(Xdt)
plot(Xdt)
```

## Generation of Points Associated (in a Radial or Circular fashion) with a Given Set of $\Y$ Points {#sec:circ-ascmT} 
In this type of association, the points are generated with a parameter, `e`, which is a positive real number
representing the radius of the balls centered at $\Y$ points. 
These balls are the only regions allowed for
the generated points (i.e., $\X$ points must reside in the union of these balls).
Note that same radius is used for each $\Y$ point, and the $\X$ points are not restricted to the convex hull of $\Y$ points
(or the Delaunay triangles).
Such a construction, although more intuitive, does not preserve the geometry invariance property
for the arc density and domination number of PE- and CS-PCDs, under association.

```{r SPch8, eval=F}
ny<-5;
e<-.15;
#with default bounding box (i.e., unit square)
set.seed(1)
Yp<-cbind(runif(ny),runif(ny))
nx<-10;  #try also nx<-100 or 1000; 
```
We first generate `r ny` $\Y$ points uniformly in the unit square and specify `e=` `r e` for circular association.

We generate $n=$ `r nx` $\X$ points uniformly inside the circular association support using the function `rassoc.circular`,
and provide the summary of these associated points and the corresponding scatterplot (together with the $\Y$ points).
The function `rassoc.circular` is an object of class `Patterns` and its arguments,  `call`, `summary`, and `plot` are as in `rseg.circular`.
We use `asp=1` in the `plot` of the object
so that the support of the $\X$ points (i.e., the allowed regions) are actually depicted as circles.
```{r ascmTcirc, eval=F, fig.cap="Scatterplot of the $X$ points associated (in a circular fashion) with the $Y$ points."}
Xdt<-rassoc.circular(nx,Yp,e)
Xdt
#> Call:
#> rassoc.circular(n = nx, Yp = Yp, e = e)
#> 
#> Type:
#> [1] "Association of 10 points with 5 Y points with circular attraction parameter e = 0.15"
summary(Xdt)
#> Call:
#> rassoc.circular(n = nx, Yp = Yp, e = e)
#> 
#> Type of the Pattern
#> [1] "Association of 10 points with 5 Y points with circular attraction parameter e = 0.15"
#> 
#> Parameters of the Pattern
#> attraction parameter 
#>                 0.15 
#> 
#> Study Window
#> range in x-coordinate = 0.05168193 1.058208 
#> range in y-coordinate = -0.08821373 1.094675 
#> 
#>  Generated Points from Pattern of Association of one Class with Class Y  
#>  (first 6 or fewer are printed) 
#>           [,1]      [,2]
#> [1,] 0.4341972 0.8314177
#> [2,] 0.5369080 0.6210061
#> [3,] 0.8844546 0.7025082
#> [4,] 0.8779856 0.6771867
#> [5,] 0.8397240 0.5659668
#> [6,] 0.1228222 0.0294437
#> 
#> Number of points:
#> nx ny 
#> 10  5 
#> nx = number of generated points according to the pattern 
#> ny = number of reference (i.e. Y) points
plot(Xdt,asp=1)
```

## Generation of Points Associated (in a Matérn-like fashion) with a Given Set of $\Y$ Points {#sec:matern-ascmT}
In this case, the points generated uniformly in $\cup_{i=1}^{n_y} B(y_i,e)$ where $\Y_{n_y}=\{\y_1,\y_2,\ldots,\y_{n_y}\}$
for various values of `e` under the association pattern where $n_y$ is the number of $\Y$ points
and $B(\y_i,e)$ is the ball centered at $\y_i$ with radius `e`.

The pattern resembles the Matérn cluster pattern (see `rMatClust` function in `spatstat.random` package for further information (@baddeley:2005).
`rMatClust(kappa, scale, mu, win)` in the simplest
case generates a uniform Poisson point process of "parent" points with intensity `kappa`.
Then each parent point is replaced by a random cluster of
"offspring" points, the number of points per cluster being Poisson(`mu`) distributed, and their positions
being placed and uniformly inside a disc of radius `scale` centered on the parent point. 
The resulting point pattern is a realization of the classical "stationary Matérn cluster process" 
generated inside the window `win`.

The main difference of `rassoc.matern` and `rMatClust` in `spatstat.random` package is that in `rassoc.matern`
the "parent" points are $\Y$ points which are given beforehand and are not discarded at the end 
and the offspring points are the points associated with the reference points, $\Y$.
Notice that in `rassoc.matern`, the parent and offspring points belong to different classes.
The argument `e` must be positive and very large values of `e` provide patterns closer to CSR pattern.

This function is also similar to `rassoc.circular`, 
where `rassoc.circular` needs the study window to be specified,
while `rassoc.matern` does not.

```{r SPch9, eval=F}
ny<-5;
e<-.15;
#with default bounding box (i.e., unit square)
set.seed(1)
Yp<-cbind(runif(ny),runif(ny))
nx<-10;  #try also nx<-100 or 1000; 
```
We first generate `r ny` $\Y$ points and specify `e=` `r e` for the Matérn-like association.

We generate $n=$ `r nx` $\X$ points from the Matérn-like association using the function `rassoc.matern`,
and provide the summary of these associated points and the corresponding scatterplot (together with the $\Y$ points).
The function `rassoc.matern` is an object of class `Patterns` and its arguments, 
`call`, `summary`, and `plot` are as in `rassoc.circular`.
We use `asp=1` in the `plot` of the object so that the support of the $\X$ points 
(i.e., the allowed regions) are actually depicted as circles.
```{r ascmTmat, eval=F, fig.cap="Scatterplot of the $X$ points associated (in a Matérn-like fashion) with the $Y$ points."}
Xdt<-rassoc.matern(nx,Yp,e)
Xdt
#> Call:
#> rassoc.matern(n = nx, Yp = Yp, e = e)
#> 
#> Type:
#> [1] "Matern-like Association of 10 points with 5 Y points with circular attraction parameter e = 0.15"
summary(Xdt)
#> Call:
#> rassoc.matern(n = nx, Yp = Yp, e = e)
#> 
#> Type of the Pattern
#> [1] "Matern-like Association of 10 points with 5 Y points with circular attraction parameter e = 0.15"
#> 
#> Parameters of the Pattern
#> attraction parameter 
#>                 0.15 
#> 
#> Study Window
#> range in x-coordinate = 0.05168193 1.058208 
#> range in y-coordinate = -0.08821373 1.094675 
#> 
#>  Generated Points from Pattern of Matern-like Association of one Class with Class Y  
#>  (first 6 or fewer are printed) 
#>            [,1]       [,2]
#> [1,] 0.56278796 0.75345984
#> [2,] 0.66528156 0.66859254
#> [3,] 0.32528878 0.83448201
#> [4,] 0.08626992 0.07483616
#> [5,] 0.13700582 0.06441234
#> [6,] 0.42942439 0.83624485
#> 
#> Number of points:
#> nx ny 
#> 10  5 
#> nx = number of generated points according to the pattern 
#> ny = number of reference (i.e. Y) points
plot(Xdt,asp=1)
```

There is also point generation capability from association pattern in a standard equilateral triangle with two types of association.
Type I is the above described one and Type II association (described below),
with the relevant functions `rassoc.std.tri` and `rassocII.std.tri`,
with arguments `n,eps` for both, see the corresponding help pages for the details.
These functions are mostly for simulation purposes, as arc density and domination number of PE- and CS-PCDs are geometry invariant.
*Type II association* is the pattern in which only a region of points inside the triangle
closer to the boundary of the triangle than a certain distance is allowed only. 
That is, there is a parameter, `eps`, which is a positive real number representing
the distance from the interior triangle points to the boundary of $T_e$, i.e., an annular region
in the interior of the triangle around the edges which is the only allowed region under this type of association.

**References**
