fork/cellxgene
1
0
Fork 0
mirror of https://github.com/chanzuckerberg/cellxgene.git synced 2026-09-21 23:38:11 +08:00
Code Issues Packages Projects Releases Wiki Activity

cziscience landing page (#1347)

Browse Source 
* fix dead link in launch page

* first cut at landing page

* wording changes

* add additional refinements

* fixes from PR review
This commit is contained in:
Bruce Martin
2020-04-03 16:30:02 -07:00
committed by GitHub
parent de8033e551
commit 0d9f24115c
25 changed files with 446 additions and 260 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/_site/posts/annotations.html
+76 -43
View File
@@ -16,10 +16,10 @@
<meta property="og:url" content="http://localhost:4000/cellxgene/posts/annotations.html" />
<meta property="og:site_name" content="cellxgene" />
<script type="application/ld+json">
{"description":"Creating annotations","publisher":{"@type":"Organization","logo":{"@type":"ImageObject","url":"http://localhost:4000/cellxgene/cellxgene-logo.png"}},"@type":"WebPage","url":"http://localhost:4000/cellxgene/posts/annotations.html","headline":"annotations","@context":"http://schema.org"}</script>
{"description":"Creating annotations","publisher":{"@type":"Organization","logo":{"@type":"ImageObject","url":"http://localhost:4000/cellxgene/cellxgene-logo.png"}},"@type":"WebPage","headline":"annotations","url":"http://localhost:4000/cellxgene/posts/annotations.html","@context":"http://schema.org"}</script>
<!-- End Jekyll SEO tag -->
<link rel="stylesheet" href="/cellxgene/assets/css/style.css?v=d2171b9a2f9935b8b92c3103c93405d1d74ef2b3">
<link rel="stylesheet" href="/cellxgene/assets/css/style.css?v=88411ae4b44d899609d211ed2db5c41e4fba3068">
<!--[if lt IE 9]>
<script src="https://cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv.min.js"></script>
<![endif]-->
@@ -85,6 +85,10 @@
<a href="/cellxgene/posts/contact" class="btn">Contact & finding help</a><br>
<a href="/cellxgene/posts/cellxgene_cziscience_com" class="btn">cellxgene.cziscience.com</a><br>
<a href="https://github.com/chanzuckerberg/cellxgene" class="btn" target="_blank">Code</a>
</p>
@@ -93,60 +97,64 @@
<section>
<h1 id="creating-annotations-in-cellxgene">Creating annotations in cellxgene</h1>
<p>We are <em>piloting</em> a new feature in cellxgene that enables users to create and edit categorical annotations within the app. We’d love for you to try it out and <a href="contact">give us feedback</a>!</p>
<p>We have recently introduced a new feature in cellxgene that enables users to create and edit categorical annotations within the app. We’d love for you to try it out and <a href="contact">give us feedback</a>!</p>
<h2 id="quick-start-for-annotations-recommended-for-most-users">Quick start for annotations (RECOMMENDED for most users)</h2>
<h1 id="data-lifecycle-for-annotations">Data lifecycle for annotations</h1>
<p>You can enable this experimental feature like so:</p>
<h2 id="1-creating-annotations-quickstart">1. Creating annotations (quickstart)</h2>
<p><code class="highlighter-rouge">cellxgene launch mydata.h5ad --experimental-annotations</code></p>
<p>To get started, run:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>cellxgene launch mydata.h5ad
</code></pre></div></div>
<p>To preserve data provenance, <strong><code class="language-plaintext highlighter-rouge">cellxgene</code> does not alter the input h5ad file</strong>. Rather, newly-created annotations are saved in a specified CSV file:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>annotations-directory/name-########.csv
</code></pre></div></div>
<p>To preserve data provenance, <strong><code class="highlighter-rouge">cellxgene</code> does not alter the input h5ad file</strong>. Rather, newly-created annotations are saved in a specified CSV file:</p>
<ul>
<li>The default <code class="language-plaintext highlighter-rouge">annotations-directory</code> is your current working directory (i.e., the directory you were in when you started cellxgene).</li>
<li>You will be prompted to enter a name for your annotations the first time you create a new category.</li>
<li>We also assign a unique identifier in the form of an 8-character suffix, <code class="highlighter-rouge">########</code>; this helps cellxgene identify your file to avoid overwriting your work.</li>
<li>Any annotations you create in the application will be autosaved in <code class="highlighter-rouge">cwd/name-########.csv</code>, where <code class="highlighter-rouge">cwd</code> is your current working directory (i.e., the directory you were in when you started cellxgene).</li>
<li>We also assign a unique identifier in the form of an 8-character suffix, <code class="language-plaintext highlighter-rouge">########</code>; this helps cellxgene identify your file to avoid overwriting your work.</li>
</ul>
<p>If you quit cellxgene and relaunch it with the same h5ad, we will check for this annotations csv and load it in editable mode alongside.</p>
<h2 id="2-loading-editing-and-updating-existing-draft-annotations">2. Loading, editing and updating existing draft annotations</h2>
<h2 id="data-management">Data management</h2>
<p>Cellxgene allows you to load and edit compatible draft annotations across multiple sessions.</p>
<h3 id="loading-editing-and-updating-existing-draft-annotations">Loading, editing and updating existing draft annotations</h3>
<p>Compatible annotations are tabular, with category names as column headers; <code class="language-plaintext highlighter-rouge">anndata.obs.index</code> as the index; and categorical values (i.e., fewer unique values per column than specified in <code class="language-plaintext highlighter-rouge">--max-category-items</code>, default 1000).</p>
<p>There are two options for updating draft annotations.</p>
<h3 id="autodetect-annotations-csv">Autodetect annotations csv</h3>
<p>Cellxgene will automatically find and reload your draft annotations in editable mode.</p>
<p>This assumes that:
1 - The h5ad filename is the same<br />
2 - You launch cellxgene from the <code class="language-plaintext highlighter-rouge">annotations-directory</code> (i.e., the directory that contains your CSV)<br />
3 - You use the same browser and have not cleared your cookies (we use a small cookie to keep track of which user created the file to avoid accidental overwrites; see FAQ)</p>
<h3 id="specify-an-annotations-csv">Specify an annotations csv</h3>
<p><strong>This mode is only appropriate for single-user, local cellxgene instances</strong></p>
<p>If you’d like to specify the complete file path for your annotations, you can do so by running:</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>cellxgene launch mydata.h5ad --experimental-annotations-file path/to/myfile.csv
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>cellxgene launch mydata.h5ad --annotations-file path/to/myfile.csv
</code></pre></div></div>
<p>If this file already exists and contains compatible annotations, these annotations will be loaded as editable categories that you can update directly. Compatible annotations are tabular, with category names as column headers; <code class="highlighter-rouge">anndata.obs.index</code> as the index; and categorical values (i.e., fewer unique values per column than specified in <code class="highlighter-rouge">--max-category-items</code>, default 1000).</p>
<p>Any changes you make will be reflected in the original CSV. If the file does not exist, it will be created.<br />
<strong>Please note that this file will be overwritten, making this mode inappropriate for hosted / multi-user settings (see below).</strong></p>
<p>Any changes you make will be reflected in the original CSV (which will be overwritten). This is helpful if you wish to annotate over multiple sessions.</p>
<h3 id="3-merging-draft-annotations-with-the-main-h5ad-file">3. Merging draft annotations with the main h5ad file</h3>
<p>If the file does not exist, it will be created.</p>
<h3 id="annotations-by-multiple-users">Annotations by multiple users</h3>
<p>An alternative to specifying the file path is to specify the output directory, and allow cellxgene to assign filenames. This is most useful for situations where the same cellxgene instance is being used by multiple users to create annotations.</p>
<p>As described in the <a href="hosted">hosted</a> section, we do not officially support hosted or multi-user use of cellxgene. However, we recognize that the app is often adapted for this purpose, and have tried to provide a “safe path” for multi-user setups that avoids overwriting data.</p>
<p>To specify an output directory, run:</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>cellxgene launch mydata.h5ad --experimental-annotations-output-dir path/to/annotations-directory/
</code></pre></div></div>
<p>For each user, annotations will be saved as follows:</p>
<ul>
<li>Each user will be prompted to enter a name for their annotations the first time they create a new category.</li>
<li>We also assign a unique identifier in the form of an 8-character suffix, <code class="highlighter-rouge">########</code>; this helps cellxgene identify their specific file to avoid overwriting others’ work.</li>
<li>Any annotations created in the application will be autosaved in <code class="highlighter-rouge">annotations-directory/name-########.csv</code></li>
</ul>
<h3 id="merging-draft-annotations-with-the-main-h5ad-file">Merging draft annotations with the main h5ad file</h3>
<p>Once you’re finished with your annotations, you should finalize and preserve your work by merging your <code class="highlighter-rouge">csv</code> into your main <code class="highlighter-rouge">h5ad</code> file.</p>
<p>Once you’re finished with your annotations, you should finalize and preserve your work by merging your <code class="language-plaintext highlighter-rouge">csv</code> into your main <code class="language-plaintext highlighter-rouge">h5ad</code> file.</p>
<p>You can do so like this:</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>import pandas as pd
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>import pandas as pd
import scanpy as sc
new_annotations = pd.read_csv('myannotations.csv',
@@ -157,25 +165,50 @@ anndata = sc.read('mydata.h5ad')
anndata.obs = anndata.obs.join(new_annotations)
</code></pre></div></div>
<h1 id="annotations-by-multiple-users">Annotations by multiple users</h1>
<p>As described in the <a href="hosted">hosted</a> section, we do not officially support hosted or multi-user use of cellxgene. However, we recognize that the app is often adapted for this purpose, and have tried to provide a “safe path” for multi-user setups that avoids overwriting data.</p>
<p>Specifying a single file name for multiple contributors will result in data overwriting. To avoid this, you can instead specify an output directory and allow cellxgene to assign filenames.</p>
<p>To specify an output directory, run:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>cellxgene launch mydata.h5ad --annotations-dir path/to/annotations-directory/
</code></pre></div></div>
<p>For each user, annotations will be saved as follows:</p>
<ul>
<li>Each user will be prompted to enter a name for their annotations the first time they create a new category.</li>
<li>We also assign a unique identifier in the form of an 8-character suffix, <code class="language-plaintext highlighter-rouge">########</code>; this helps cellxgene identify their specific file to avoid overwriting others’ work.</li>
<li>Any annotations created in the application will be autosaved in <code class="language-plaintext highlighter-rouge">annotations-directory/name-########.csv</code></li>
</ul>
<h2 id="faq">FAQ</h2>
<h3 id="how-do-i-know-my-annotations-are-saved">How do I know my annotations are saved?</h3>
<p><code class="highlighter-rouge">cellxgene</code> autosaves any changes made to your annotations every 3 seconds.</p>
<p><code class="language-plaintext highlighter-rouge">cellxgene</code> autosaves any changes made to your annotations every 3 seconds.</p>
<h3 id="i-think-i-deleted-my-annotations-oh-noes">I think I deleted my annotations! Oh noes!</h3>
<p>Not to worry! We save the last 10 versions of your annotations in <code class="highlighter-rouge">annotations-directory/NAME-backups/</code></p>
<p>Not to worry! We save the last 10 versions of your annotations in <code class="language-plaintext highlighter-rouge">annotations-directory/NAME-backups/</code></p>
<h3 id="what-about-creating-continuous-annotations">What about creating continuous annotations?</h3>
<p>Continuous metadata is important! However, these values (e.g., pseudotime) are the result of statistical analyses that are beyond cellxgene’s visualization- and exploration-focused scope. We do, of course, provide visualization of continuous metadata values computed elsewhere and stored in <code class="highlighter-rouge">anndata.obs</code>.</p>
<h3 id="i-keep-getting-weird-index-errors-when-trying-to-join-my-annotations-to-my-anndata">I keep getting weird index errors when trying to join my annotations to my anndata??</h3>
<p>Continuous metadata is important! However, these values (e.g., pseudotime) are the result of statistical analyses that are beyond cellxgene’s visualization- and exploration-focused scope. We do, of course, provide visualization of continuous metadata values computed elsewhere and stored in <code class="language-plaintext highlighter-rouge">anndata.obs</code>.</p>
<h3 id="i-keep-getting-weird-index-errors-when-trying-to-join-my-annotations-to-my-anndata">I keep getting weird index errors when trying to join my annotations to my anndata?</h3>
<p>This is most likely because the h5ad file you are working with is not the original file used to generate the annotations! We recommend merging new annotations in on a regular basis for this reason.</p>
<h3 id="how-do-you-remember-my-unique-id-to-match-my-cellxgene-session-with-my-annotations-file">How do you remember my unique ID to match my cellxgene session with my annotations file?</h3>
<p>We place a small cookie (file) in your browser that identifies where your draft annotations are saved. This file never leaves your machine, and is never sent to the cellxgene team or anyone else.</p>
<h3 id="i-have-feedback-and-ideas-for-you">I have feedback and ideas for you!</h3>
<p>Wonderful! This is a very new and complex feature; we would <em>love</em> to <a href="contact">hear your feedback</a> :)</p>
<p>Wonderful! This is a relatively new feature; we would <em>love</em> to <a href="contact">hear your feedback</a> :)</p>
</section>
<footer>