This function randomly samples vertcies on a graph to define neighbourhoods.
These are then refined by computing the median profile for the neighbourhood
in reduced dimensional space and selecting the nearest vertex to this
position. Thus, multiple neighbourhoods may be collapsed down together to
prevent over-sampling the graph space.

makeNhoods(x, prop = 0.1, k = 21, d = 30, refined = TRUE, reduced_dims = "PCA")

## Arguments

x |
A `Milo` object with a non-empty `graph`
slot. Alternatively an `igraph` object on which neighbourhoods will
be defined. |

prop |
A double scalar that defines what proportion of graph vertices
to randomly sample. Must be 0 < prop < 1. |

k |
An integer scalar - the same k used to construct the input graph. |

d |
The number of dimensions to use if the input is a matrix of cells
X reduced dimensions. |

refined |
A logical scalar that determines the sampling behaviour, default=TRUE implements the refined sampling scheme. |

reduced_dims |
If x is an `Milo` object, a character indicating the name of the `reducedDim` slot in the
`Milo` object to use as (default: 'PCA'). If x is an `igraph` object, a
matrix of vertices X reduced dimensions. |

## Value

A `Milo`

object containing a list of vertices and
the indices of vertices that constitute the neighbourhoods in the
isIndex slot. If the input is a `igraph`

object then the output
is a list of vertices and the indices of vertices that constitute the
neighbourhoods.

## Details

This function randomly samples graph vertices, then refines them to collapse
down the number of neighbourhoods to be tested. The refinement behaviour can
be turned off by setting `refine=FALSE`

, however, we do not recommend
this as neighbourhoods will contain a lot of redundancy and lead to an
unncecessarily larger multiple-testing burden.

## Examples

#> Constructing kNN graph with k:10

milo <- makeNhoods(milo, prop=0.1)

#> Checking valid object

#> Warning: Warning: specified d is higher than the total number of dimensions in reducedDim(x, reduced_dims). Falling back to using 11 dimensions

#> Warning: Rownames not set on reducedDims - setting to row indices

milo

#> class: Milo
#> dim: 1000 100
#> metadata(0):
#> assays(1): logcounts
#> rownames: NULL
#> rowData names(0):
#> colnames: NULL
#> colData names(0):
#> reducedDimNames(1): PCA
#> spikeNames(0):
#> altExpNames(0):
#> nhoods dimensions(1): 6
#> nhoodCounts dimensions(2): 1 1
#> nhoodDistances dimension(1): 0
#> graph names(1): graph
#> nhoodIndex names(1): 6
#> nhoodExpression dimension(2): 1 1
#> nhoodReducedDim names(0):
#> nhoodGraph names(0):
#> nhoodAdjacency dimension(0):