docs

README.md → README.rst

@@ -4,20 +4,34 @@ UCSC Single Cell Browser
 Funded by the California Institute of Regenerative Medicine and the
 Chan-Zuckerberg Initiative https://www.chanzuckerberg.com/.
 
-The UCSC Cell Browser is a viewer for single cell data. You can click on and hover over cells to get meta information, search for genes to color on and click clusters to show cluster-specific marker genes, which in turn are clickable again.
+The UCSC Cell Browser is a viewer for single cell data. You can click on and
+hover over cells to get meta information, search for genes to color on and
+click clusters to show cluster-specific marker genes, which in turn are
+clickable again.
 
 For a demo of the browser, see http://cells.ucsc.edu
 
 The main script is cbBuild. It is a Python program that takes a gene expression
 matrix and related files and converts the output to JSON and binary files to
-an output directory which can be served over http. The importers for cbBuild
-are cbCellranger, cbSeurat and cbScanpy.
+an output directory which can be put onto a webserver or shown with the built-in
+webserver.
+
+The following documentation explains how to create a cellbrowser from a:
+
+* Cellranger directory: command line tool `cbImportCellranger`
+* Seurat rds file: command line tool `cbImportSeurat`
+* Scanpy h5ad file: command line tool `cbImportScanpy`
+* Seurat object: `ExportToCellbrowser()` from R
+* Scanpy object: `scanpyToCellbrowser()` from Python
+* Expression matrix
+  * running a basic Seurat pipeline: `cbSeurat` command line tool
+  * running a basic Scanpy pipeline: `cbScanpy` command line tool
 
 This is early research software. You are likely to find bugs. Please open a Github
 ticket or email us at cells@ucsc.edu, we can usually fix them quickly.
 
-Installation
-============
+Installation with pip
+---------------------
 
 You need Python2.5+ or Python3+ and pip. On a Mac or any Linux, simply run:
 
@@ -31,20 +45,30 @@ On Linux, if you you're not allowed to run the sudo command, you can install int
 
     pip install --user cellbrowser
     export PATH=$PATH:~/.local/bin
+
+Installation with conda
+-----------------------
 
-As an alternative to these pip commands, you can also git clone the repo and
+Alternatively, if you prefer to install through bioconda, since 0.4.23 you can do:
+
+    conda install -c bioconda ucsc-cell-browser
+
+Installation: git clone
+-----------------------
+
+As an alternative to pip or conda, you can also git clone the repo and
 run the command line scripts under cellbrowser/src:
 
     git clone https://github.com/maximilianh/cellBrowser.git --depth=10
     cd cellBrowser/src
+
+Create site with data
+---------------------
 
-Now you should be able to run the cbBuild command and see the help messages:
+After installing through one of the methods above, you should be able to run the cbBuild command and see the help messages:
 
     cbBuild
 
-A sample dataset
-================
-
 Here is a small example dataset (Nowakowski et al 2018, fetal brains). The
 expression matrix includes only the first 100 genes, otherwise quite a few
 features of the browser are used. Download and extract it to the current directory with:
@@ -86,8 +110,8 @@ your ~/.bashrc to point to your html directory:
 
     export CBOUT=/var/www
 
-A more permanent alternative to the built-in webserver with the -p option is to
-run a real webserver on your machine and build directly into its web directory.
+The -p 8888 is optional. A more permanent alternative to the -p option is to
+run a webserver on your machine and build directly into its web directory.
 
 On a Mac you can use the Apache that ships with OSX:
 
@@ -160,21 +184,50 @@ The cbScanpy wrapper runs some generic analysis steps with very crude default
 values. If you have done the analysis already, you can build a cellbrowser from
 your existing Scanpy object.
 
-From Jupyter or Python3, create a data directory with the tab-sep files:
+From Jupyter or Python3, create a data directory with the tab-sep files and a basic cellbrowser.conf:
+
+    import cellbrowser.cellbrowser as cb
+    cb.scanpyToTsv(adata, "scanpyOut", "myScanpyDataset")
 
-    from cellbrowser import cellbrowser
-    # convert to tsv files and create a cellbrowser.conf
-    cellbrowser.scanpyToTsv(adata, "scanpyOut", "myScanpyDataset")
+Then, build the cell browser into a html directory:
 
-Then, build the cell browser into a html directory, from Jupyter:
+    cb.build("scanpyOut", "~/public_html/cells")
 
-    cellbrowser.cbBuild(["scanpyOut/cellbrowser.conf"], "~/public_html/cells", 8888)
+If you don't have a webserver running already, start an http server to serve this directory: 
 
-Or from a Unix Shell:
+    cb.serve("~/public_html/cells", 8888)
 
-    cbBuild -i scanpyOut/cellbrowser.conf -o ~/public_html/cells/ -p 8888
+You can later stop this http server:
 
-### Convert CellRanger results
+    cb.stop()
+
+Or from a Unix Shell, build and start the http server:
+
+    cd scanpyOut
+    cbBuild -o ~/public_html/cells/ -p 8888
+
+Convert an Seurat object
+========================
+
+The function ExportToCellbrowser() will be part of Seurat 3. You can install the pre-release Seurat3 like this:
+
+    install.packages("devtools")
+    devtools::install_github("satijalab/seurat", ref = "release/3.0")
+
+For Seurat 2, you have to load the function with this command:
+
+    source("https://raw.githubusercontent.com/maximilianh/cellBrowser/master/src/R/ExportToCellbrowser-Seurat2.R")
+
+You can then write a Seurat object to a directory from which you can run cbBuild:
+
+    ExportToCellbrowser(pbmc_small, dir="pbmcSmall", cb.dir="htdocs", dataset.name="pbmcSmall")
+
+Or immediately convert the files to html and serve the result on port 8080 and open a web browser:
+
+    ExportToCellbrowser(pbmc_small, dir="pbmcSmall", cb.dir="htdocs", dataset.name="pbmcSmall", port=8080)
+
+Convert CellRanger results
+==========================
 
 Find the cellranger OUT directory, it contains an "analysis" directory and also
 a subdirectory "filtered_gene_bc_matrices". This is the directory that is the
@@ -188,14 +241,10 @@ To import Cellranger .mtx files, we need the scipy package (add --user if you ar
 Let's use an example, the pbmc3k cellranger output files from the 10x website:
 
     rsync -Lavzp genome-test.gi.ucsc.edu::cells/datasets/pbmc3kCellranger/ ./pbmc3kCellranger/ --progress
-    cbImportCellranger -i pbmc3kCellranger -o cellrangerOut -n pbmc3kCellranger
+    cbImportCellranger -i pbmc3kCellranger -o cellrangerOut --name pbmc3k_cellranger
     cd cellrangerOut
     cbBuild -o ~/public_html/cells -p 9999
 
-### Import a Seurat object
-
-Use src/cbImportSeurat. More instructions later.
-
 ### Process an expression matrix with a basic Seurat pipeline
 
 First make sure that you can install the package "hdf5r" in R:
@@ -255,8 +304,8 @@ Then you need at least three but ideally four files, they can be in .tsv or .csv
    the name of the cluster. Ideally your expression matrix is a tab-separated
    file and has as many cell columns as you have rows in the meta data file
    and they appear in the same order in both files, as cbBuild doesn't have to
-   trim the matrix then or reorder the meta file. The meta file as has a header
-   file, the names of the columns are used in the cellbrowser.conf file.
+   trim the matrix then or reorder the meta file. The meta file has a header
+   file, the names of the columns will be refered to later in the cellbrowser.conf file.
 
 3. The coordinates of the cells, often t-SNE coordinates. This file always has three
    columns, (cellName, x, y). The cellName must be the same as in the expression
@@ -298,7 +347,8 @@ You can use `cbTool metaCat` to merge the meta.tsv files from different pipeline
 
     cbTool metaCat myMeta.tsv seuratOut/meta.tsv scanpyOut/meta.tsv ./newMeta.tsv --fixDot
 
-The option --fixDot will work around R's strange habit of replacing special characters in the cell identifier with ".".
+The option --fixDot will work around R's strange habit of replacing special characters in the cell identifiers with ".".
+Directories created with ExportToCellbrowser() should not have this problem, but others may.
 
 You can now take one of the auto-generated cellbrowser.conf files or start from a fresh one with `cbBuild --init`.
 In this cellbrowser.conf, add all the coordinates files from all your pipelines. Unfortunately, right now you can

docs/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/cellbrowser.conf

@@ -0,0 +1 @@
+../src/cbPyLib/cellbrowser/sampleConfig/cellbrowser.conf

docs/conf.py

@@ -0,0 +1,177 @@
+# -*- coding: utf-8 -*-
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'cellbrowser'
+copyright = '2018, Maximilian Haeussler, Lucas Seninge, Nikolai Markov'
+author = 'Maximilian Haeussler, Lucas Seninge, Nikolai Markov'
+
+# The short X.Y version
+version = ''
+# The full version, including alpha/beta/rc tags
+release = ''
+
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.viewcode',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = None
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'cellbrowserdoc'
+
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'cellbrowser.tex', 'cellbrowser Documentation',
+     'Maximilian Haeussler, Lucas Seninge, Nikolai Markov', 'manual'),
+]
+
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'cellbrowser', 'cellbrowser Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output ----------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'cellbrowser', 'cellbrowser Documentation',
+     author, 'cellbrowser', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+
+# -- Options for Epub output -------------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = project
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#
+# epub_identifier = ''
+
+# A unique identification for the text.
+#
+# epub_uid = ''
+
+# A list of files that should not be packed into the epub file.
+epub_exclude_files = ['search.html']
+
+
+# -- Extension configuration -------------------------------------------------