@@ -1,7 +1,7 @@

 Package: miloR

 Type: Package

 Title: Differential neighbourhood abundance testing on a graph

-Version: 2.1.2

+Version: 2.1.3

 Authors@R:

     c(person("Mike", "Morgan", role=c("aut", "cre"), email="[email protected]",

      comment=c(ORCID="0000-0003-0757-0711")),

@@ -71,7 +71,7 @@ Suggests:

     curl,

     scRNAseq,

     graphics

-RoxygenNote: 7.3.1

+RoxygenNote: 7.3.2

 NeedsCompilation: no

 Packaged: 2020-07-31 14:15:28 UTC; morgan02

 Collate: 

@@ -17,6 +17,7 @@ fitGLMM(

     NULL, init.u = NULL, solver = NULL),

   dispersion = 1,

   geno.only = FALSE,

+  intercept.type = "fixed",

   solver = NULL

 )

 }

@@ -44,6 +45,12 @@ initial parameter values for the fixed (init.beta) and random effects (init.u),

 \item{geno.only}{A logical value that flags the model to use either just the \code{matrix} `Kin` or the supplied random effects.}

+\item{intercept.type}{A character scalar, either \emph{fixed} or \emph{random} that sets the type of the global

+intercept variable in the model. This only applies to the GLMM case where additional random effects variables are

+already included. Setting \code{intercept.type="fixed"} or \code{intercept.type="random"} will require the user to

+test their model for failures with each. In the case of using a kinship matrix, \code{intercept.type="fixed"} is

+set automatically.}

+

 \item{solver}{a character value that determines which optimisation algorithm is used for the variance components. Must be either

 HE (Haseman-Elston regression) or Fisher (Fisher scoring).}

 }

@@ -11,6 +11,8 @@ plotNhoodGraph(

   subset.nhoods = NULL,

   size_range = c(0.5, 3),

   node_stroke = 0.3,

+  is.da = FALSE,

+  highlight.da = FALSE,

   ...

 )

 }

@@ -30,6 +32,14 @@ in the graph)}

 \item{node_stroke}{a numeric indicating the desired thickness of the border around each node}

+\item{is.da}{logical scalar that tells plotNhoodGraph to order nhoods by |LFC| which can help to visually

+emphasise which nhoods are DA.}

+

+\item{highlight.da}{logical or numeric scalar that emphasises the DA nhoods in the layout by adjusting the transparency

+of the non-DA nhoods. Can only be used if \code{is.da=TRUE}, otherwise will give a warning. If highlight.da is a numeric

+then it explicitly sets the transparency level (must be between 0 and 1). If highlight.da is logical then the

+transparency is set to 0.1}

+

 \item{...}{arguments to pass to \code{ggraph}}

 }

 \value{

@@ -73,10 +73,20 @@ these should have the same \code{length} as \code{nrow} of \code{nhoodCounts}. I

 to correspond to indices of \code{nhoodCounts} - if the maximal index is greater than \code{nrow(nhoodCounts(x))}

 an error will be produced.}

+\item{intercept.type}{A character scalar, either \emph{fixed} or \emph{random} that sets the type of the global

+intercept variable in the model. This only applies to the GLMM case where additional random effects variables are

+already included. Setting \code{intercept.type="fixed"} or \code{intercept.type="random"} will require the user to

+test their model for failures with each. In the case of using a kinship matrix, \code{intercept.type="fixed"} is

+set automatically.}

+

 \item{fail.on.error}{A logical scalar the determines the behaviour of the error reporting. Used for debugging only.}

 \item{BPPARAM}{A \linkS4class{BiocParallelParam} object specifying the arguments for parallelisation. By default

 this will evaluate using \code{SerialParam()}. See \code{details}on how to use parallelisation in \code{testNhoods}.}

+

+\item{force}{A logical scalar that overrides the default behaviour to nicely error when N < 50 and using a mixed

+effect model. This is because model parameter estimation may be unstable with these sample sizes, and hence the

+fixed effect GLM is recommended instead. If used with the LMM, a warning will be produced.}

 }

 \value{

 A \code{data.frame} of model results, which contain:

@@ -126,6 +136,14 @@ parallelise - for details see the \code{BiocParallel} package.

 need this to be the first variable. A future update will harmonise these behaviours for

 consistency. While it is strictly feasible to compute multiple contrasts at once, the

 recommendation, for ease of interpretability, is to compute one at a time.

+

+If using the GLMM option, i.e. including a random effect variable in the \code{design}

+formula, then \code{testNhoods} will check for the sample size of the analysis. If this is

+less than 60 it will stop and produce an error. It is \emph{strongly} recommended that

+the GLMM is not used with relatively small sample sizes, i.e. N<60, and even up to N~100

+may have unstable parameter estimates across nhoods. This behaviour can be overriden by

+setting \code{force=TRUE}, but also be aware that parameter estimates may not be

+accurate. A warning will be produced to alert you to this fact.

 }

 \examples{

 library(SingleCellExperiment)

@@ -236,7 +236,7 @@ pbmc.milo <- buildNhoodGraph(pbmc.milo, overlap=25)

 # we need to subset the plotting results as it can't handle the NAs internally.

 plotUMAP(pbmc.milo, colour_by="adjmfc.time") + plotNhoodGraphDA(pbmc.milo, da_results[!is.na(da_results$logFC), ],

-                                                                subset.nhoods=!is.na(da_results$logFC), alpha=0.1) +

+                                                                alpha=0.1) +

   plot_layout(guides="auto" )

 ```