<!-- Generated by pkgdown: do not edit by hand -->
<!DOCTYPE html>
<html lang="en">
  <head>
  <meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">

<title>Identify post-hoc neighbourhood marker genes — findNhoodMarkers • miloR</title>


<!-- jquery -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.4.1/jquery.min.js" integrity="sha256-CSXorXvZcTkaix6Yvo6HppcZGetbYMGWSFlBw8HfCJo=" crossorigin="anonymous"></script>
<!-- Bootstrap -->

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.4.1/css/bootstrap.min.css" integrity="sha256-bZLfwXAP04zRMK2BjiO8iu9pf4FbLqX6zitd+tIvLhE=" crossorigin="anonymous" />

<script src="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.4.1/js/bootstrap.min.js" integrity="sha256-nuL8/2cJ5NDSSwnKD8VqreErSWHtnEP9E7AySL+1ev4=" crossorigin="anonymous"></script>

<!-- bootstrap-toc -->
<link rel="stylesheet" href="../bootstrap-toc.css">
<script src="../bootstrap-toc.js"></script>

<!-- Font Awesome icons -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.1/css/all.min.css" integrity="sha256-mmgLkCYLUQbXn0B1SRqzHar6dCnv9oZFPEC1g1cwlkk=" crossorigin="anonymous" />
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.1/css/v4-shims.min.css" integrity="sha256-wZjR52fzng1pJHwx4aV2AO3yyTOXrcDW7jBpJtTwVxw=" crossorigin="anonymous" />

<!-- clipboard.js -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.6/clipboard.min.js" integrity="sha256-inc5kl9MA1hkeYUt+EC3BhlIgyp/2jDIyBLS6k3UxPI=" crossorigin="anonymous"></script>

<!-- headroom.js -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/headroom/0.11.0/headroom.min.js" integrity="sha256-AsUX4SJE1+yuDu5+mAVzJbuYNPHj/WroHuZ8Ir/CkE0=" crossorigin="anonymous"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/headroom/0.11.0/jQuery.headroom.min.js" integrity="sha256-ZX/yNShbjqsohH1k95liqY9Gd8uOiE1S4vZc+9KQ1K4=" crossorigin="anonymous"></script>

<!-- pkgdown -->
<link href="../pkgdown.css" rel="stylesheet">
<script src="../pkgdown.js"></script>




<meta property="og:title" content="Identify post-hoc neighbourhood marker genes — findNhoodMarkers" />
<meta property="og:description" content="This function will perform differential gene expression analysis on
differentially abundant neighbourhoods, by first aggregating adjacent and
concordantly DA neighbourhoods, then comparing cells between these
aggregated groups. For differential gene experession based on an input design
within DA neighbourhoods see testDiffExp." />




<!-- mathjax -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js" integrity="sha256-nvJJv9wWKEm88qvoQl9ekL2J+k/RWIsaSScxxlsrv8k=" crossorigin="anonymous"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/config/TeX-AMS-MML_HTMLorMML.js" integrity="sha256-84DKXVJXs0/F8OTMzX4UR909+jtl4G7SPypPavF+GfA=" crossorigin="anonymous"></script>

<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/html5shiv/3.7.3/html5shiv.min.js"></script>
<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
<![endif]-->



  </head>

  <body data-spy="scroll" data-target="#toc">
    <div class="container template-reference-topic">
      <header>
      <div class="navbar navbar-default navbar-fixed-top" role="navigation">
  <div class="container">
    <div class="navbar-header">
      <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false">
        <span class="sr-only">Toggle navigation</span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
      </button>
      <span class="navbar-brand">
        <a class="navbar-link" href="../index.html">miloR</a>
        <span class="version label label-default" data-toggle="tooltip" data-placement="bottom" title="Released version">0.1.0</span>
      </span>
    </div>

    <div id="navbar" class="navbar-collapse collapse">
      <ul class="nav navbar-nav">
        <li>
  <a href="../index.html">
    <span class="fas fa fas fa-home fa-lg"></span>
     
  </a>
</li>
<li>
  <a href="../reference/index.html">Reference</a>
</li>
<li class="dropdown">
  <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-expanded="false">
    Articles
     
    <span class="caret"></span>
  </a>
  <ul class="dropdown-menu" role="menu">
    <li>
      <a href="../articles/milo_demo.html">Differential abundance testing with Milo</a>
    </li>
    <li>
      <a href="../articles/milo_gastrulation.html">Differential abundance testing with Milo - Mouse gastrulation example</a>
    </li>
  </ul>
</li>
      </ul>
      <ul class="nav navbar-nav navbar-right">
        
      </ul>
      
    </div><!--/.nav-collapse -->
  </div><!--/.container -->
</div><!--/.navbar -->

      

      </header>

<div class="row">
  <div class="col-md-9 contents">
    <div class="page-header">
    <h1>Identify post-hoc neighbourhood marker genes</h1>
    
    <div class="hidden name"><code>findNhoodMarkers.Rd</code></div>
    </div>

    <div class="ref-description">
    <p>This function will perform differential gene expression analysis on
differentially abundant neighbourhoods, by first aggregating adjacent and
concordantly DA neighbourhoods, then comparing cells <em>between</em> these
aggregated groups. For differential gene experession based on an input design
<em>within</em> DA neighbourhoods see <code><a href='testDiffExp.html'>testDiffExp</a></code>.</p>
    </div>


    <h2 class="hasAnchor" id="arguments"><a class="anchor" href="#arguments"></a>Arguments</h2>
    <table class="ref-arguments">
    <colgroup><col class="name" /><col class="desc" /></colgroup>
    <tr>
      <th>x</th>
      <td><p>A <code><a href='Milo.html'>Milo</a></code> object containing single-cell gene expression
and neighbourhoods.</p></td>
    </tr>
    <tr>
      <th>da.res</th>
      <td><p>A <code>data.frame</code> containing DA results, as expected from running
<code>testNhoods</code>.</p></td>
    </tr>
    <tr>
      <th>da.fdr</th>
      <td><p>A numeric scalar that determines at what FDR neighbourhoods are declared
DA for the purposes of aggregating across concorantly DA neighbourhoods.</p></td>
    </tr>
    <tr>
      <th>assay</th>
      <td><p>A character scalar determining which <code>assays</code> slot to extract from the
<code><a href='Milo.html'>Milo</a></code> object to use for DGE testing.</p></td>
    </tr>
    <tr>
      <th>aggregate.samples</th>
      <td><p>logical indicating wheather the expression values for cells in the same sample 
and neighbourhood group should be merged for DGE testing. This allows to perform testing exploiting the replication structure
in the experimental design, rather than treating single-cells as independent replicates. The function used for aggregation depends on the 
selected gene expression assay: if <code>assay="counts"</code> the expression values are summed, otherwise we take the mean.</p></td>
    </tr>
    <tr>
      <th>sample_col</th>
      <td><p>a character scalar indicating the column in the colData storing sample information
(only relevant if <code>aggregate.samples==TRUE</code>)</p></td>
    </tr>
    <tr>
      <th>overlap</th>
      <td><p>A scalar integer that determines the number of cells that must
overlap between adjacent neighbourhoods for merging.</p></td>
    </tr>
    <tr>
      <th>lfc.threshold</th>
      <td><p>A scalar that determines the absolute log fold change above
which neighbourhoods should be considerd 'DA' for merging. Default=NULL</p></td>
    </tr>
    <tr>
      <th>merge.discord</th>
      <td><p>A logical scalar that overrides the default behaviour and allows
adjacent neighbourhoods to be merged if they have discordant log fold change signs. Using
this argument is generally discouraged, but may be useful for constructing an empirical null
group of cells, regardless of DA sign.</p></td>
    </tr>
    <tr>
      <th>subset.row</th>
      <td><p>A logical, integer or character vector indicating the rows
of <code>x</code> to use for sumamrizing over cells in neighbourhoods.</p></td>
    </tr>
    <tr>
      <th>gene.offset</th>
      <td><p>A logical scalar the determines whether a per-cell offset
is provided in the DGE GLM to adjust for the number of detected genes with
expression &gt; 0.</p></td>
    </tr>
    <tr>
      <th>return.groups</th>
      <td><p>A logical scalar that returns a <code><a href='https://rdrr.io/r/base/data.frame.html'>data.frame</a></code> of the
aggregated groups per single-cell. Cells that are members of non-DA neighbourhoods contain
<code>NA</code> values.</p></td>
    </tr>
    <tr>
      <th>subset.nhoods</th>
      <td><p>A logical, integer or character vector indicating which neighbourhoods
to subset before aggregation and DGE testing.</p></td>
    </tr>
    <tr>
      <th>na.function</th>
      <td><p>A valid NA action function to apply, should be one of
<code>na.fail, na.omit, na.exclude, na.pass</code>.</p></td>
    </tr>
    <tr>
      <th>compute.new</th>
      <td><p>A logical scalar indicating whether to force computing a new neighbourhood
adjacency matrix if already present.</p></td>
    </tr>
    </table>

    <h2 class="hasAnchor" id="value"><a class="anchor" href="#value"></a>Value</h2>

    <p>A <code>data.frame</code> of DGE results containing a log fold change and adjusted
p-value for each aggregated group of neighbourhoods. If <code>return.groups</code> then
the return value is a list with the slots <code>groups</code> and <code>dge</code> containing the
aggregated neighbourhood groups per single-cell and marker gene results, respectively.</p>
<p><em>Warning</em>: If all neighbourhoods are grouped together, then it is impossible to
run <code>findNhoodMarkers</code>. In this (hopefully rare) instance, this function will spit
out a warning and return <code>NULL</code>.</p>
    <h2 class="hasAnchor" id="details"><a class="anchor" href="#details"></a>Details</h2>

    <p>Adjacent neighbourhoods are first merged based on two criteria: 1) they share at
least <code>overlap</code> number of cells, and 2) the DA log fold change sign is concordant.
This behaviour can be modulated by setting <code>overlap</code> to be more or less stringent.
Additionally, a threshold on the log fold-changes can be set, such that <code>lfc.threshold</code>
is required to merge adjacent neighbourhoods. Note: adjacent neighbourhoods will never be
merged with opposite signs.</p>
<p>Using a one vs. all approach, each aggregated group of cells is compared to all others
using the single-cell log normalized gene expression with a GLM
(for details see <code><a href='https://rdrr.io/pkg/limma/man/01Introduction.html'>limma-package</a></code>), or the single-cell counts using a
negative binomial GLM (for details see <code><a href='https://rdrr.io/pkg/edgeR/man/edgeR-package.html'>edgeR-package</a></code>). When using
the latter it is recommended to set <code>gene.offset=TRUE</code> as this behaviour adjusts
the model offsets by the number of detected genes in each cell.</p>

    <h2 class="hasAnchor" id="examples"><a class="anchor" href="#examples"></a>Examples</h2>
    <pre class="examples"><div class='input'><span class='fu'><a href='https://rdrr.io/r/base/library.html'>library</a></span>(<span class='no'>SingleCellExperiment</span>)
<span class='no'>ux.1</span> <span class='kw'>&lt;-</span> <span class='fu'><a href='https://rdrr.io/r/base/matrix.html'>matrix</a></span>(<span class='fu'><a href='https://rdrr.io/r/stats/Poisson.html'>rpois</a></span>(<span class='fl'>12000</span>, <span class='fl'>5</span>), <span class='kw'>ncol</span><span class='kw'>=</span><span class='fl'>400</span>)
<span class='no'>ux.2</span> <span class='kw'>&lt;-</span> <span class='fu'><a href='https://rdrr.io/r/base/matrix.html'>matrix</a></span>(<span class='fu'><a href='https://rdrr.io/r/stats/Poisson.html'>rpois</a></span>(<span class='fl'>12000</span>, <span class='fl'>4</span>), <span class='kw'>ncol</span><span class='kw'>=</span><span class='fl'>400</span>)
<span class='no'>ux</span> <span class='kw'>&lt;-</span> <span class='fu'><a href='https://rdrr.io/r/base/cbind.html'>rbind</a></span>(<span class='no'>ux.1</span>, <span class='no'>ux.2</span>)
<span class='no'>vx</span> <span class='kw'>&lt;-</span> <span class='fu'><a href='https://rdrr.io/r/base/Log.html'>log2</a></span>(<span class='no'>ux</span> + <span class='fl'>1</span>)
<span class='no'>pca</span> <span class='kw'>&lt;-</span> <span class='fu'><a href='https://rdrr.io/r/stats/prcomp.html'>prcomp</a></span>(<span class='fu'><a href='https://rdrr.io/r/base/t.html'>t</a></span>(<span class='no'>vx</span>))

<span class='no'>sce</span> <span class='kw'>&lt;-</span> <span class='fu'><a href='https://rdrr.io/pkg/SingleCellExperiment/man/SingleCellExperiment.html'>SingleCellExperiment</a></span>(<span class='kw'>assays</span><span class='kw'>=</span><span class='fu'><a href='https://rdrr.io/r/base/list.html'>list</a></span>(<span class='kw'>counts</span><span class='kw'>=</span><span class='no'>ux</span>, <span class='kw'>logcounts</span><span class='kw'>=</span><span class='no'>vx</span>),
                            <span class='kw'>reducedDims</span><span class='kw'>=</span><span class='fu'>SimpleList</span>(<span class='kw'>PCA</span><span class='kw'>=</span><span class='no'>pca</span>$<span class='no'>x</span>))
<span class='fu'><a href='https://rdrr.io/r/base/colnames.html'>colnames</a></span>(<span class='no'>sce</span>) <span class='kw'>&lt;-</span> <span class='fu'><a href='https://rdrr.io/r/base/paste.html'>paste0</a></span>(<span class='st'>"Cell"</span>, <span class='fl'>1</span>:<span class='fu'><a href='https://rdrr.io/r/base/nrow.html'>ncol</a></span>(<span class='no'>sce</span>))
<span class='no'>milo</span> <span class='kw'>&lt;-</span> <span class='fu'><a href='Milo.html'>Milo</a></span>(<span class='no'>sce</span>)
<span class='no'>milo</span> <span class='kw'>&lt;-</span> <span class='fu'><a href='buildGraph.html'>buildGraph</a></span>(<span class='no'>milo</span>, <span class='kw'>k</span><span class='kw'>=</span><span class='fl'>20</span>, <span class='kw'>d</span><span class='kw'>=</span><span class='fl'>10</span>, <span class='kw'>transposed</span><span class='kw'>=</span><span class='fl'>TRUE</span>)</div><div class='output co'>#&gt; <span class='message'>Constructing kNN graph with k:20</span></div><div class='input'><span class='no'>milo</span> <span class='kw'>&lt;-</span> <span class='fu'><a href='makeNhoods.html'>makeNhoods</a></span>(<span class='no'>milo</span>, <span class='kw'>k</span><span class='kw'>=</span><span class='fl'>20</span>, <span class='kw'>d</span><span class='kw'>=</span><span class='fl'>10</span>, <span class='kw'>prop</span><span class='kw'>=</span><span class='fl'>0.3</span>)</div><div class='output co'>#&gt; <span class='message'>Checking valid object</span></div><div class='input'><span class='no'>milo</span> <span class='kw'>&lt;-</span> <span class='fu'><a href='calcNhoodDistance.html'>calcNhoodDistance</a></span>(<span class='no'>milo</span>, <span class='kw'>d</span><span class='kw'>=</span><span class='fl'>10</span>)

<span class='no'>cond</span> <span class='kw'>&lt;-</span> <span class='fu'><a href='https://rdrr.io/r/base/rep.html'>rep</a></span>(<span class='st'>"A"</span>, <span class='fu'><a href='https://rdrr.io/r/base/nrow.html'>ncol</a></span>(<span class='no'>milo</span>))
<span class='no'>cond.a</span> <span class='kw'>&lt;-</span> <span class='fu'><a href='https://rdrr.io/r/base/sample.html'>sample</a></span>(<span class='fl'>1</span>:<span class='fu'><a href='https://rdrr.io/r/base/nrow.html'>ncol</a></span>(<span class='no'>milo</span>), <span class='kw'>size</span><span class='kw'>=</span><span class='fu'><a href='https://rdrr.io/r/base/Round.html'>floor</a></span>(<span class='fu'><a href='https://rdrr.io/r/base/nrow.html'>ncol</a></span>(<span class='no'>milo</span>)*<span class='fl'>0.25</span>))
<span class='no'>cond.b</span> <span class='kw'>&lt;-</span> <span class='fu'><a href='https://rdrr.io/r/base/sets.html'>setdiff</a></span>(<span class='fl'>1</span>:<span class='fu'><a href='https://rdrr.io/r/base/nrow.html'>ncol</a></span>(<span class='no'>milo</span>), <span class='no'>cond.a</span>)
<span class='no'>cond</span>[<span class='no'>cond.b</span>] <span class='kw'>&lt;-</span> <span class='st'>"B"</span>
<span class='no'>meta.df</span> <span class='kw'>&lt;-</span> <span class='fu'><a href='https://rdrr.io/r/base/data.frame.html'>data.frame</a></span>(<span class='kw'>Condition</span><span class='kw'>=</span><span class='no'>cond</span>, <span class='kw'>Replicate</span><span class='kw'>=</span><span class='fu'><a href='https://rdrr.io/r/base/c.html'>c</a></span>(<span class='fu'><a href='https://rdrr.io/r/base/rep.html'>rep</a></span>(<span class='st'>"R1"</span>, <span class='fl'>132</span>), <span class='fu'><a href='https://rdrr.io/r/base/rep.html'>rep</a></span>(<span class='st'>"R2"</span>, <span class='fl'>132</span>), <span class='fu'><a href='https://rdrr.io/r/base/rep.html'>rep</a></span>(<span class='st'>"R3"</span>, <span class='fl'>136</span>)))
<span class='no'>meta.df</span>$<span class='no'>SampID</span> <span class='kw'>&lt;-</span> <span class='fu'><a href='https://rdrr.io/r/base/paste.html'>paste</a></span>(<span class='no'>meta.df</span>$<span class='no'>Condition</span>, <span class='no'>meta.df</span>$<span class='no'>Replicate</span>, <span class='kw'>sep</span><span class='kw'>=</span><span class='st'>"_"</span>)
<span class='no'>milo</span> <span class='kw'>&lt;-</span> <span class='fu'><a href='countCells.html'>countCells</a></span>(<span class='no'>milo</span>, <span class='kw'>meta.data</span><span class='kw'>=</span><span class='no'>meta.df</span>, <span class='kw'>samples</span><span class='kw'>=</span><span class='st'>"SampID"</span>)</div><div class='output co'>#&gt; <span class='message'>Checking meta.data validity</span></div><div class='output co'>#&gt; <span class='message'>Setting up matrix with 69 neighbourhoods</span></div><div class='output co'>#&gt; <span class='message'>Counting cells in neighbourhoods</span></div><div class='input'>
<span class='no'>test.meta</span> <span class='kw'>&lt;-</span> <span class='fu'><a href='https://rdrr.io/r/base/data.frame.html'>data.frame</a></span>(<span class='st'>"Condition"</span><span class='kw'>=</span><span class='fu'><a href='https://rdrr.io/r/base/c.html'>c</a></span>(<span class='fu'><a href='https://rdrr.io/r/base/rep.html'>rep</a></span>(<span class='st'>"A"</span>, <span class='fl'>3</span>), <span class='fu'><a href='https://rdrr.io/r/base/rep.html'>rep</a></span>(<span class='st'>"B"</span>, <span class='fl'>3</span>)), <span class='st'>"Replicate"</span><span class='kw'>=</span><span class='fu'><a href='https://rdrr.io/r/base/rep.html'>rep</a></span>(<span class='fu'><a href='https://rdrr.io/r/base/c.html'>c</a></span>(<span class='st'>"R1"</span>, <span class='st'>"R2"</span>, <span class='st'>"R3"</span>), <span class='fl'>2</span>))
<span class='no'>test.meta</span>$<span class='no'>Sample</span> <span class='kw'>&lt;-</span> <span class='fu'><a href='https://rdrr.io/r/base/paste.html'>paste</a></span>(<span class='no'>test.meta</span>$<span class='no'>Condition</span>, <span class='no'>test.meta</span>$<span class='no'>Replicate</span>, <span class='kw'>sep</span><span class='kw'>=</span><span class='st'>"_"</span>)
<span class='fu'><a href='https://rdrr.io/r/base/colnames.html'>rownames</a></span>(<span class='no'>test.meta</span>) <span class='kw'>&lt;-</span> <span class='no'>test.meta</span>$<span class='no'>Sample</span>
<span class='no'>da.res</span> <span class='kw'>&lt;-</span> <span class='fu'><a href='testNhoods.html'>testNhoods</a></span>(<span class='no'>milo</span>, <span class='kw'>design</span><span class='kw'>=</span>~<span class='fl'>0</span> + <span class='no'>Condition</span>, <span class='kw'>design.df</span><span class='kw'>=</span><span class='no'>test.meta</span>[<span class='fu'><a href='https://rdrr.io/r/base/colnames.html'>colnames</a></span>(<span class='fu'><a href='methods.html'>nhoodCounts</a></span>(<span class='no'>milo</span>)), ])</div><div class='output co'>#&gt; <span class='message'>Performing spatial FDR correction withk-distance weightingPerforming spatial FDR correction withneighbour-distance weightingPerforming spatial FDR correction withedge weightingPerforming spatial FDR correction withvertex weightingPerforming spatial FDR correction withnone weighting</span></div><div class='input'>
<span class='no'>nhood.dge</span> <span class='kw'>&lt;-</span> <span class='fu'>findNhoodMarkers</span>(<span class='no'>milo</span>, <span class='no'>da.res</span>, <span class='kw'>overlap</span><span class='kw'>=</span><span class='fl'>1</span>, <span class='kw'>compute.new</span><span class='kw'>=</span><span class='fl'>TRUE</span>)</div><div class='output co'>#&gt; <span class='message'>Found 37 DA neighbourhoods at FDR 10%</span></div><div class='output co'>#&gt; <span class='message'>Calculating nhood adjacency</span></div><div class='output co'>#&gt; <span class='message'>Nhoods aggregated into 1 groups</span></div><div class='output co'>#&gt; <span class='warning'>Warning: All graph neighbourhoods are in the same group - cannot perform DGE testing. Returning NULL</span></div><div class='input'><span class='no'>nhood.dge</span></div><div class='output co'>#&gt; NULL</div><div class='input'>
</div></pre>
  </div>
  <div class="col-md-3 hidden-xs hidden-sm" id="pkgdown-sidebar">
    <nav id="toc" data-toggle="toc" class="sticky-top">
      <h2 data-toc-skip>Contents</h2>
    </nav>
  </div>
</div>


      <footer>
      <div class="copyright">
  <p>Developed by Mike Morgan, Emma Dann.</p>
</div>

<div class="pkgdown">
  <p>Site built with <a href="https://pkgdown.r-lib.org/">pkgdown</a> 1.5.1.</p>
</div>

      </footer>
   </div>

  


  </body>
</html>


