<!-- 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>Write data to an HDF5 group — WriteH5Group • SeuratDisk</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 href="https://cdnjs.cloudflare.com/ajax/libs/bootswatch/3.4.0/flatly/bootstrap.min.css" rel="stylesheet" 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="Write data to an HDF5 group — WriteH5Group" />
<meta property="og:description" content="Writing data to HDF5 files can be done simply with usually sensible defaults.
However, when wanting any semblance of control over how an R object is
written out, the code constructs get complicated quickly. WriteH5Group
provides a wrapper with sensible defaults over some of these complex code
constructs to provide greater control over how data are written to disk.
These defaults were chosen to fit best with h5Seurat files, see
vignette(&quot;h5Seurat-spec&quot;) for more
details" />




<!-- 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">SeuratDisk</a>
        <span class="version label label-danger" data-toggle="tooltip" data-placement="bottom" title="Unreleased version">0.0.0.9011</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/convert-anndata.html">Conversions: h5Seurat and AnnData</a>
    </li>
    <li>
      <a href="../articles/h5Seurat-load.html">Saving and Loading Data from an h5Seurat File</a>
    </li>
    <li>
      <a href="../articles/h5Seurat-spec.html">h5Seurat File Format Specification</a>
    </li>
  </ul>
</li>
      </ul>
      <ul class="nav navbar-nav navbar-right">
        <li>
  <a href="https://github.com/mojaveazure/seurat-disk/">
    <span class="fab fa fab fa-github fa-lg"></span>
     
  </a>
</li>
      </ul>
      
    </div><!--/.nav-collapse -->
  </div><!--/.container -->
</div><!--/.navbar -->

      

      </header>

<div class="row">
  <div class="col-md-9 contents">
    <div class="page-header">
    <h1>Write data to an HDF5 group</h1>
    <small class="dont-index">Source: <a href='https://github.com/mojaveazure/seurat-disk/blob/master/R/WriteH5Group.R'><code>R/WriteH5Group.R</code></a></small>
    <div class="hidden name"><code>WriteH5Group.Rd</code></div>
    </div>

    <div class="ref-description">
    <p>Writing data to HDF5 files can be done simply with usually sensible defaults.
However, when wanting any semblance of control over how an R object is
written out, the code constructs get complicated quickly. <code>WriteH5Group</code>
provides a wrapper with sensible defaults over some of these complex code
constructs to provide greater control over how data are written to disk.
These defaults were chosen to fit best with <a href='h5Seurat-class.html'>h5Seurat</a> files, see
<code><a href='../doc/h5Seurat-spec.html'>vignette("h5Seurat-spec")</a></code> for more
details</p>
    </div>

    <pre class="usage"><span class='fu'>WriteH5Group</span>(<span class='no'>x</span>, <span class='no'>name</span>, <span class='no'>hgroup</span>, <span class='kw'>verbose</span> <span class='kw'>=</span> <span class='fl'>TRUE</span>)

<span class='co'># S4 method for ANY</span>
<span class='fu'>WriteH5Group</span>(<span class='no'>x</span>, <span class='no'>name</span>, <span class='no'>hgroup</span>, <span class='kw'>verbose</span> <span class='kw'>=</span> <span class='fl'>TRUE</span>)

<span class='co'># S4 method for array</span>
<span class='fu'>WriteH5Group</span>(<span class='no'>x</span>, <span class='no'>name</span>, <span class='no'>hgroup</span>, <span class='kw'>verbose</span> <span class='kw'>=</span> <span class='fl'>TRUE</span>)

<span class='co'># S4 method for Assay</span>
<span class='fu'>WriteH5Group</span>(<span class='no'>x</span>, <span class='no'>name</span>, <span class='no'>hgroup</span>, <span class='kw'>verbose</span> <span class='kw'>=</span> <span class='fl'>TRUE</span>)

<span class='co'># S4 method for data.frame</span>
<span class='fu'>WriteH5Group</span>(<span class='no'>x</span>, <span class='no'>name</span>, <span class='no'>hgroup</span>, <span class='kw'>verbose</span> <span class='kw'>=</span> <span class='fl'>TRUE</span>)

<span class='co'># S4 method for dgCMatrix</span>
<span class='fu'>WriteH5Group</span>(<span class='no'>x</span>, <span class='no'>name</span>, <span class='no'>hgroup</span>, <span class='kw'>verbose</span> <span class='kw'>=</span> <span class='fl'>TRUE</span>)

<span class='co'># S4 method for DimReduc</span>
<span class='fu'>WriteH5Group</span>(<span class='no'>x</span>, <span class='no'>name</span>, <span class='no'>hgroup</span>, <span class='kw'>verbose</span> <span class='kw'>=</span> <span class='fl'>TRUE</span>)

<span class='co'># S4 method for factor</span>
<span class='fu'>WriteH5Group</span>(<span class='no'>x</span>, <span class='no'>name</span>, <span class='no'>hgroup</span>, <span class='kw'>verbose</span> <span class='kw'>=</span> <span class='fl'>TRUE</span>)

<span class='co'># S4 method for Graph</span>
<span class='fu'>WriteH5Group</span>(<span class='no'>x</span>, <span class='no'>name</span>, <span class='no'>hgroup</span>, <span class='kw'>verbose</span> <span class='kw'>=</span> <span class='fl'>TRUE</span>)

<span class='co'># S4 method for list</span>
<span class='fu'>WriteH5Group</span>(<span class='no'>x</span>, <span class='no'>name</span>, <span class='no'>hgroup</span>, <span class='kw'>verbose</span> <span class='kw'>=</span> <span class='fl'>TRUE</span>)

<span class='co'># S4 method for logical</span>
<span class='fu'>WriteH5Group</span>(<span class='no'>x</span>, <span class='no'>name</span>, <span class='no'>hgroup</span>, <span class='kw'>verbose</span> <span class='kw'>=</span> <span class='fl'>TRUE</span>)

<span class='co'># S4 method for SeuratCommand</span>
<span class='fu'>WriteH5Group</span>(<span class='no'>x</span>, <span class='no'>name</span>, <span class='no'>hgroup</span>, <span class='kw'>verbose</span> <span class='kw'>=</span> <span class='fl'>TRUE</span>)</pre>

    <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>An object</p></td>
    </tr>
    <tr>
      <th>name</th>
      <td><p>Name to save data as</p></td>
    </tr>
    <tr>
      <th>hgroup</th>
      <td><p>An HDF5 file or group (<code>H5File</code> or <code>H5Group</code> objects
from hdf5r)</p></td>
    </tr>
    <tr>
      <th>verbose</th>
      <td><p>Show progress updates</p></td>
    </tr>
    </table>

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

    <p>Invisibly returns <code>NULL</code></p>

    <h2 class="hasAnchor" id="examples"><a class="anchor" href="#examples"></a>Examples</h2>
    <pre class="examples"><div class='input'><span class='co'># \donttest{</span>
<span class='co'># Setup an HDF5 file</span>
<span class='no'>hfile</span> <span class='kw'>&lt;-</span> <span class='kw pkg'>hdf5r</span><span class='kw ns'>::</span><span class='no'><a href='http://hhoeflin.github.io/hdf5r/reference/H5File-class.html'>H5File</a></span>$<span class='fu'>new</span>(<span class='kw'>filename</span> <span class='kw'>=</span> <span class='fu'><a href='https://rdrr.io/r/base/tempfile.html'>tempfile</a></span>(<span class='kw'>fileext</span> <span class='kw'>=</span> <span class='st'>'.h5'</span>), <span class='kw'>mode</span> <span class='kw'>=</span> <span class='st'>'a'</span>)
<span class='co'># }</span>

<span class='co'># \donttest{</span>
<span class='co'># Data frames are stored as either datasets or groups, depending on the</span>
<span class='co'># presence of factor columns</span>
<span class='no'>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'>x</span> <span class='kw'>=</span> <span class='fu'><a href='https://rdrr.io/r/base/c.html'>c</a></span>(<span class='st'>'g1'</span>, <span class='st'>'g1'</span>, <span class='st'>'g2'</span>, <span class='st'>'g1'</span>, <span class='st'>'g2'</span>),
  <span class='kw'>y</span> <span class='kw'>=</span> <span class='fl'>1</span>:<span class='fl'>5</span>,
  <span class='kw'>stringsAsFactors</span> <span class='kw'>=</span> <span class='fl'>FALSE</span>
)

<span class='co'># When no factor columns are present, the data frame is written as a single</span>
<span class='co'># HDF5 compound dataset</span>
<span class='fu'>WriteH5Group</span>(<span class='kw'>x</span> <span class='kw'>=</span> <span class='no'>df</span>, <span class='kw'>name</span> <span class='kw'>=</span> <span class='st'>'df'</span>, <span class='kw'>hgroup</span> <span class='kw'>=</span> <span class='no'>hfile</span>)
<span class='no'>hfile</span><span class='kw'>[[</span><span class='st'>'df'</span>]]</div><div class='output co'>#&gt; Class: H5Group
#&gt; Filename: /tmp/RtmpVp8Dsb/file1e06c235d56.h5
#&gt; Group: /df
#&gt; Attributes: colnames
#&gt; Listing:
#&gt;  name    obj_type dataset.dims dataset.type_class
#&gt;     x H5I_DATASET            5         H5T_STRING
#&gt;     y H5I_DATASET            5        H5T_INTEGER</div><div class='input'>
<span class='co'># When factors are present, the data frame is written as a group</span>
<span class='co'># This is because h5py does not implement HDF5 Enums, so factor level</span>
<span class='co'># information would be lost</span>
<span class='no'>df</span>$<span class='no'>x</span> <span class='kw'>&lt;-</span> <span class='fu'><a href='https://rdrr.io/r/base/factor.html'>factor</a></span>(<span class='kw'>x</span> <span class='kw'>=</span> <span class='no'>df</span>$<span class='no'>x</span>)
<span class='fu'>WriteH5Group</span>(<span class='kw'>x</span> <span class='kw'>=</span> <span class='no'>df</span>, <span class='kw'>name</span> <span class='kw'>=</span> <span class='st'>'df.factor'</span>, <span class='kw'>hgroup</span> <span class='kw'>=</span> <span class='no'>hfile</span>)
<span class='no'>hfile</span><span class='kw'>[[</span><span class='st'>'df.factor'</span>]]</div><div class='output co'>#&gt; Class: H5Group
#&gt; Filename: /tmp/RtmpVp8Dsb/file1e06c235d56.h5
#&gt; Group: /df.factor
#&gt; Attributes: colnames
#&gt; Listing:
#&gt;  name    obj_type dataset.dims dataset.type_class
#&gt;     x   H5I_GROUP         &lt;NA&gt;               &lt;NA&gt;
#&gt;     y H5I_DATASET            5        H5T_INTEGER</div><div class='input'><span class='co'># }</span>

<span class='co'># \donttest{</span>
<span class='co'># Factors turn into a group with two components: values and levels</span>
<span class='co'># This is to preserve level information for HDF5 APIs that don't implement</span>
<span class='co'># the HDF5 Enum type (eg. h5py)</span>
<span class='co'># values corresponds to the integer values of each member of a factor</span>
<span class='co'># levels is a string dataset with one entry per level</span>
<span class='no'>fctr</span> <span class='kw'>&lt;-</span> <span class='fu'><a href='https://rdrr.io/r/base/factor.html'>factor</a></span>(<span class='kw'>x</span> <span class='kw'>=</span> <span class='fu'><a href='https://rdrr.io/r/base/c.html'>c</a></span>(<span class='st'>'g1'</span>, <span class='st'>'g1'</span>, <span class='st'>'g2'</span>, <span class='st'>'g1'</span>, <span class='st'>'g2'</span>))
<span class='fu'>WriteH5Group</span>(<span class='kw'>x</span> <span class='kw'>=</span> <span class='no'>fctr</span>, <span class='kw'>name</span> <span class='kw'>=</span> <span class='st'>'factor'</span>, <span class='kw'>hgroup</span> <span class='kw'>=</span> <span class='no'>hfile</span>)
<span class='no'>hfile</span><span class='kw'>[[</span><span class='st'>'factor'</span>]]</div><div class='output co'>#&gt; Class: H5Group
#&gt; Filename: /tmp/RtmpVp8Dsb/file1e06c235d56.h5
#&gt; Group: /factor
#&gt; Listing:
#&gt;    name    obj_type dataset.dims dataset.type_class
#&gt;  levels H5I_DATASET            2         H5T_STRING
#&gt;  values H5I_DATASET            5        H5T_INTEGER</div><div class='input'><span class='co'># }</span>

<span class='co'># \donttest{</span>
<span class='co'># Logicals get encoded as integers with the following mapping</span>
<span class='co'># FALSE becomes 0L</span>
<span class='co'># TRUE becomes 1L</span>
<span class='co'># NA becomes 2L</span>
<span class='co'># These are stored as H5T_INTEGERS instead of H5T_LOGICALS</span>
<span class='co'># Additionally, an attribute called "s3class" is written with the value of "logical"</span>
<span class='fu'>WriteH5Group</span>(<span class='fu'><a href='https://rdrr.io/r/base/c.html'>c</a></span>(<span class='fl'>TRUE</span>, <span class='fl'>FALSE</span>, <span class='fl'>NA</span>), <span class='kw'>name</span> <span class='kw'>=</span> <span class='st'>"logicals"</span>, <span class='kw'>hgroup</span> <span class='kw'>=</span> <span class='no'>hfile</span>)
<span class='no'>hfile</span><span class='kw'>[[</span><span class='st'>"logicals"</span>]]</div><div class='output co'>#&gt; Class: H5D
#&gt; Dataset: /logicals
#&gt; Filename: /tmp/RtmpVp8Dsb/file1e06c235d56.h5
#&gt; Access type: H5F_ACC_RDWR
#&gt; Attributes: s3class
#&gt; Datatype: H5T_STD_I32LE
#&gt; Space: Type=Simple     Dims=3     Maxdims=Inf
#&gt; Chunk: 2048</div><div class='input'><span class='no'>hfile</span><span class='kw'>[[</span><span class='st'>"logicals"</span>]]$<span class='fu'>attr_open</span>(<span class='st'>"s3class"</span>)$<span class='fu'>read</span>()</div><div class='output co'>#&gt; [1] "logical"</div><div class='input'><span class='co'># }</span>

<span class='co'># \donttest{</span>
<span class='co'># Close and remove the HDF5 file</span>
<span class='no'>hfile</span>$<span class='fu'>close_all</span>()
<span class='fu'><a href='https://rdrr.io/r/base/files.html'>file.remove</a></span>(<span class='no'>hfile</span>$<span class='no'>filename</span>)</div><div class='output co'>#&gt; [1] TRUE</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 Paul Hoffman.</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>


