v0.3.0

.dockerignore

@@ -0,0 +1,10 @@
+**/.git
+.github
+examples
+docs
+wdl
+dist
+cellbender.egg-info
+.pytest_cache
+*.h5
+*.tar.gz

.dockstore.yml

@@ -0,0 +1,6 @@
+version: 1.2
+
+workflows:
+  - subclass: WDL
+    primaryDescriptorPath: /wdl/cellbender_remove_background.wdl
+    name: cellbender_remove_background

.github/workflows/miniwdl_check.yml

@@ -0,0 +1,17 @@
+name: 'validate WDL'
+on: [pull_request]
+env:
+  MINIWDL_VERSION: 1.8.0
+jobs:
+  miniwdl-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.7'
+      - name: 'Install miniwdl and Run Validation Test'
+        run: |
+          pip install miniwdl==$MINIWDL_VERSION;
+          ./cellbender/remove_background/tests/miniwdl_check_wdl.sh;
+        shell: bash

.github/workflows/run_packaging_check.yml

@@ -0,0 +1,45 @@
+# Package for PyPI
+
+name: 'packaging'
+
+on: pull_request
+
+jobs:
+  build:
+
+    runs-on: 'ubuntu-latest'
+    strategy:
+      matrix:
+        python-version: ['3.7']
+
+    steps:
+    - name: 'Checkout repo'
+      uses: actions/checkout@v3
+
+    - name: 'Set up Python ${{ matrix.python-version }}'
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+        cache: 'pip'
+
+    - name: 'Install packaging software'
+      run: pip install --upgrade setuptools build twine
+
+    - name: 'Print package versions'
+      run: pip list
+
+    - name: 'Package code using build'
+      run: python -m build
+
+    - name: 'Check package using twine'
+      run: python -m twine check dist/*
+
+    - name: 'Extract branch name'
+      shell: bash
+      run: echo "branch=$(echo ${GITHUB_REF#refs/heads/})" >>$GITHUB_OUTPUT
+      id: extract_branch
+
+    - name: 'Install from github branch and run a test'
+      run: |
+        pip install pytest git+https://github.com/broadinstitute/CellBender@${{ steps.extract_branch.outputs.branch }}
+        cellbender -v

.github/workflows/run_pytest.yml

@@ -0,0 +1,32 @@
+# Run cellbender's tests
+
+name: 'pytest'
+
+on: pull_request
+
+jobs:
+  build:
+
+    runs-on: 'ubuntu-latest'
+    strategy:
+      matrix:
+        python-version: ['3.7']
+
+    steps:
+    - name: 'Checkout repo'
+      uses: actions/checkout@v3
+
+    - name: 'Set up Python ${{ matrix.python-version }}'
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+        cache: 'pip'
+
+    - name: 'Install package including pytest'
+      run: pip install .[dev]
+
+    - name: 'Print package versions'
+      run: pip list
+
+    - name: 'Test with pytest'
+      run: pytest -v

.gitignore

@@ -12,3 +12,9 @@ dist/
 .eggs/
 .idea/
 *.iml
+*.h5
+*.h5ad
+*.tsv
+*.csv
+*.npz
+*.tar.gz

MANIFEST.in

@@ -1 +1,4 @@
-include README.rst
+include README.rst
+include LICENSE
+include requirements.txt
+include requirements-rtd.txt

README.rst

@@ -1,11 +1,27 @@
 CellBender
 ==========
 
+.. image:: https://img.shields.io/github/license/broadinstitute/CellBender?color=white
+   :target: LICENSE
+   :alt: License
+
 .. image:: https://readthedocs.org/projects/cellbender/badge/?version=latest
    :target: https://cellbender.readthedocs.io/en/latest/?badge=latest
    :alt: Documentation Status
 
-.. image:: https://github.com/broadinstitute/CellBender/blob/master/docs/source/_static/design/logo_250_185.png
+.. image:: https://img.shields.io/pypi/v/CellBender.svg
+   :target: https://pypi.org/project/CellBender
+   :alt: PyPI
+
+.. image:: https://static.pepy.tech/personalized-badge/cellbender?period=total&units=international_system&left_color=grey&right_color=blue&left_text=pypi%20downloads
+   :target: https://pepy.tech/project/CellBender
+   :alt: Downloads
+
+.. image:: https://img.shields.io/github/stars/broadinstitute/CellBender?color=yellow&logoColor=yellow)
+   :target: https://github.com/broadinstitute/CellBender/stargazers
+   :alt: Stars
+
+.. image:: docs/source/_static/design/logo_250_185.png
    :alt: CellBender Logo
 
 CellBender is a software package for eliminating technical artifacts from
@@ -16,67 +32,123 @@ The current release contains the following modules. More modules will be added i
 * ``remove-background``:
 
   This module removes counts due to ambient RNA molecules and random barcode swapping from (raw)
-  UMI-based scRNA-seq count matrices. At the moment, only the count matrices produced by the
-  CellRanger ``count`` pipeline is supported. Support for additional tools and protocols will be
-  added in the future. A quick start tutorial can be found
-  `here <https://cellbender.readthedocs.io/en/latest/getting_started/remove_background/index.html>`_.
+  UMI-based scRNA-seq count matrices.  Also works for snRNA-seq and CITE-seq.
 
-Please refer to the `documentation <https://cellbender.readthedocs.io/en/latest/>`_ for a quick start tutorial on using CellBender.
+Please refer to `the documentation <https://cellbender.readthedocs.io/en/latest/>`_ for a quick start tutorial.
 
 Installation and Usage
 ----------------------
 
-Manual installation
-~~~~~~~~~~~~~~~~~~~
+CellBender can be installed via
+
+.. code-block:: console
+
+  $ pip install cellbender
+
+(and we recommend installing in its own ``conda`` environment to prevent
+conflicts with other software).
+
+CellBender is run as a command-line tool, as in
+
+.. code-block:: console
+
+  (cellbender) $ cellbender remove-background \
+        --cuda \
+        --input my_raw_count_matrix_file.h5 \
+        --output my_cellbender_output_file.h5
+
+See `the usage documentation <https://cellbender.readthedocs.io/en/latest/usage/index.html>`_
+for details.
+
+
+Using The Official Docker Image
+-------------------------------
+
+A GPU-enabled docker image is available from the Google Container Registry (GCR) as:
+
+``us.gcr.io/broad-dsde-methods/cellbender:latest``
+
+Available image tags track release tags in GitHub, and include ``latest``,
+``0.1.0``, ``0.2.0``, ``0.2.1``, ``0.2.2``, and ``0.3.0``.
+
+
+WDL Users
+---------
+
+A workflow written in the
+`workflow description language (WDL) <https://github.com/openwdl/wdl>`_
+is available for CellBender remove-background.
+
+For `Terra <https://app.terra.bio>`_ users, a workflow called
+``cellbender/remove-background`` is
+`available from the Broad Methods repository
+<https://portal.firecloud.org/#methods/cellbender/remove-background/>`_.
+
+There is also a `version available on Dockstore
+<https://dockstore.org/workflows/github.com/broadinstitute/CellBender>`_.
 
-The recommended installation is as follows. Create a conda environment and activate it:
 
-.. code-block:: bash
+Advanced installation
+---------------------
 
-   $ conda create -n cellbender python=3.7
-   $ source activate cellbender
+From source for development
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Create a conda environment and activate it:
+
+.. code-block:: console
+
+  $ conda create -n cellbender python=3.7
+  $ conda activate cellbender
 
 Install the `pytables <https://www.pytables.org>`_ module:
 
-.. code-block:: bash
+.. code-block:: console
+
+  (cellbender) $ conda install -c anaconda pytables
 
-   (cellbender) $ conda install -c anaconda pytables
+Install `pytorch <https://pytorch.org>`_ via
+`these instructions <https://pytorch.org/get-started/locally/>`_, for example:
 
-Install `pytorch <https://pytorch.org>`_ (shown below for CPU; if you have a CUDA-ready GPU, please skip
-this part and follow `these <https://pytorch.org/get-started/locally/>`_ instructions instead):
+.. code-block:: console
 
-.. code-block:: bash
+   (cellbender) $ pip install torch
 
-   (cellbender) $ conda install pytorch torchvision -c pytorch
+and ensure that your installation is appropriate for your hardware (i.e. that
+the relevant CUDA drivers get installed and that ``torch.cuda.is_available()``
+returns ``True`` if you have a GPU available.
 
-Clone this repository and install CellBender:
+Clone this repository and install CellBender (in editable ``-e`` mode):
 
-.. code-block:: bash
+.. code-block:: console
 
+   (cellbender) $ git clone https://github.com/broadinstitute/CellBender.git
    (cellbender) $ pip install -e CellBender
 
-Using The Official Docker Image
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-A GPU-enabled docker image is available from the Google Container Registry (GCR) as:
+From a specific commit
+~~~~~~~~~~~~~~~~~~~~~~
 
-``us.gcr.io/broad-dsde-methods/cellbender:latest``
+This can be achieved via
 
-Terra Users
-~~~~~~~~~~~
+.. code-block:: console
 
-For `Terra <https://app.terra.bio>`_ users, a `workflow <https://portal.firecloud.org/#methods/cellbender/remove-background/>`_
-is available as:
+   (cellbender) $ pip install --no-cache-dir -U git+https://github.com/broadinstitute/CellBender.git@<SHA>
 
-``cellbender/remove-background``
+where ``<SHA>`` must be replaced by any reference to a particular git commit,
+such as a tag, a branch name, or a commit sha.
 
 
 Citing CellBender
 -----------------
 
 If you use CellBender in your research (and we hope you will), please consider
-citing `our paper on bioRxiv <https://doi.org/10.1101/791699>`_.
+citing our paper in Nature Methods:
+
+Stephen J Fleming, Mark D Chaffin, Alessandro Arduini, Amer-Denis Akkad,
+Eric Banks, John C Marioni, Anthony A Phillipakis, Patrick T Ellinor,
+and Mehrtash Babadi. Unsupervised removal of systematic background noise from
+droplet-based single-cell experiments using CellBender.
+`Nature Methods` (in press), 2023.
 
-Stephen J Fleming, John C Marioni, and Mehrtash Babadi. CellBender remove-background:
-a deep generative model for unsupervised removal of background noise from scRNA-seq
-datasets. bioRxiv 791699; doi: `https://doi.org/10.1101/791699 <https://doi.org/10.1101/791699>`_
+See also `our preprint on bioRxiv <https://doi.org/10.1101/791699>`_.

build_docker_local.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+
+tag=$(cat cellbender/__init__.py | sed -e 's?__version__ = ??' | sed "s/^'\(.*\)'$/\1/")
+
+docker build \
+    -t us.gcr.io/broad-dsde-methods/cellbender:${tag} \
+    -f docker/Dockerfile \
+    .

build_docker_release.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+
+tag=$(cat cellbender/__init__.py | sed -e 's?__version__ = ??' | sed "s/^'\(.*\)'$/\1/")
+release=v${tag}
+
+docker build \
+    -t us.gcr.io/broad-dsde-methods/cellbender:${tag} \
+    --build-arg GIT_SHA=${release} \
+    -f docker/DockerfileGit \
+    .

cellbender/__init__.py

@@ -0,0 +1 @@
+__version__ = '0.3.0'