update docs

Author: rob-p

docs/requirements.txt

@@ -1,4 +1,5 @@
 ####### 
 #
 ###### Custom themes (no version specifiers) ######
-furo
+sphinx
+furo

docs/source/chemistry-command.rst

@@ -32,7 +32,7 @@ The ``chemistry`` command provides functionality to manage and inspect custom ch
 These sub-commands are described below.
 
 ``simpleaf chemistry refresh``
------------------------
+-------------------------------
 
 The ``refresh`` sub-command takes no *required* arguments; it's usage is shown below:
 
@@ -81,8 +81,10 @@ Every chemistry added to the registry has three mandatory properties: ``name``,
 - ``name``: A unique name (within the existing registry) of the chemistry. It must be a valid UTF-8 identifier. If the name is already registered, the existing definition will be updated if a higher ``--version`` is provided (see below for details). Otherwise, simpleaf will complain and fail.
 - ``geometry``: The geometry specification must be provided as a quoted string, and must follow the `Sequence Fragment Geometry Description Language <https://hackmd.io/@PI7Og0l1ReeBZu_pjQGUQQ/rJMgmvr13>`_ as used in the `quant command <https://simpleaf.readthedocs.io/en/latest/quant-command.html#a-note-on-the-chemistry-flag>`_. 
 - ``expected-ori``: The expected orientation of the chemistry. It must be one of the following: fw (forward), rc (reverse complement), or both (both orientations). It describes the expected orientation relative to the first (most upstream) mappable biological sequence.
-Imagine we have reads from 10x Chromium 5' protocols with read1s and read2s both of 150 base pairs. With this specification, a read1, which is in the forward orientation, contains, from 5' to 3', a cell barcode, a UMI, a fixed fragment, and a fragment representing the 5' end of the cDNA. A read2, which is in the reverse complementary orientation, contains the second (downstream) cDNA fragment relative to its read1. You can find a detailed explanation of the 10x Chromium 5' protocol from `Single Cell Genomics Library Structure <https://teichlab.github.io/scg_lib_structs/methods_html/10xChromium5.html>`_.
-If we map the biological sequence in read1s and read2s as paired-end reads (currently only supported when using the default mapper -- piscem), as biological read1s are the first mappable sequences, the expected orientation for this chemistry should be ``fw``, the orientation of read1s. However, if we only map read2s, the expected orientation should be ``rc``, because read2s are the first mappable sequences and are in the reverse complementary orientation.
+
+  Imagine we have reads from 10x Chromium 5' protocols with read1s and read2s both of 150 base pairs. With this specification, a read1, which is in the forward orientation, contains, from 5' to 3', a cell barcode, a UMI, a fixed fragment, and a fragment representing the 5' end of the cDNA. A read2, which is in the reverse complementary orientation, contains the second (downstream) cDNA fragment relative to its read1. You can find a detailed explanation of the 10x Chromium 5' protocol from `Single Cell Genomics Library Structure <https://teichlab.github.io/scg_lib_structs/methods_html/10xChromium5.html>`_.
+
+  If we map the biological sequence in read1s and read2s as paired-end reads (currently only supported when using the default mapper -- piscem), as biological read1s are the first mappable sequences, the expected orientation for this chemistry should be ``fw``, the orientation of read1s. However, if we only map read2s, the expected orientation should be ``rc``, because read2s are the first mappable sequences and are in the reverse complementary orientation.
 
 In addition to the required fields, there are 3 optional fields, as described below. A permit list file must be a TSV file without a header, and the first column must contain the sequence of permitted cell barcodes, i.e., the whitelist of cell barcodes.
 

docs/source/flex-quant-command.rst

@@ -0,0 +1,135 @@
+``flex-quant`` command
+======================
+
+The ``flex-quant`` command runs the end-to-end ``simpleaf`` pipeline for 10x Flex Gene Expression data. Unlike :doc:`/quant-command`, which is designed around standard single-cell RNA-seq chemistries and a single cell-barcode whitelist, ``flex-quant`` handles the extra resources and steps required for Flex assays:
+
+- Flex chemistry lookup from the chemistry registry
+- probe set selection by organism
+- probe-set CSV to FASTA conversion and ``probe_t2g.tsv`` generation
+- probe index construction with ``piscem build`` when needed
+- cell barcode whitelist resolution
+- sample barcode list resolution
+- ``piscem map-scrna``
+- multi-barcode permit-list generation with ``alevin-fry generate-permit-list``
+- ``alevin-fry collate`` and ``alevin-fry quant``
+
+At present, ``flex-quant`` expects a registered Flex chemistry such as ``10x-flexv1-gex-3p`` or ``10x-flexv2-gex-3p`` and requires ``piscem`` plus ``alevin-fry`` to be configured with :doc:`/set-paths`.
+
+Overview
+--------
+
+The command needs:
+
+1. a Flex chemistry name via ``--chemistry``
+2. an organism via ``--organism`` for automatic probe-set selection
+3. paired-end reads via ``--reads1`` and ``--reads2``
+4. an output directory via ``--output``
+
+If the chemistry registry contains the needed metadata, ``simpleaf`` can automatically download and cache the probe set, the cell barcode whitelist, and the sample barcode list. If you already have local resources, you can override these defaults with ``--index``, ``--probe-set``, or ``--sample-bc-list``.
+
+The relevant options (which you can obtain by running ``simpleaf flex-quant -h``) are below:
+
+.. code-block:: console
+
+    quantify a 10x Flex GEX sample (probe-based, multiplexed)
+
+    Usage: simpleaf flex-quant [OPTIONS] --chemistry <CHEMISTRY> --organism <ORGANISM> --output <OUTPUT> --reads1 <READS1> --reads2 <READS2>
+
+    Options:
+      -c, --chemistry <CHEMISTRY>    Chemistry name: 10x-flexv1-gex-3p or 10x-flexv2-gex-3p
+          --organism <ORGANISM>      Target organism for automatic probe set selection [possible values: human, mouse]
+      -o, --output <OUTPUT>          Path to output directory
+      -t, --threads <THREADS>        Number of threads to use [default: 16]
+      -r, --resolution <RESOLUTION>  UMI resolution mode [default: cr-like] [possible values: cr-like, cr-like-em, parsimony, parsimony-em, parsimony-gene, parsimony-gene-em]
+      -h, --help                     Print help
+      -V, --version                  Print version
+
+    Mapping Options:
+      -i, --index <INDEX>    Path to pre-built probe index (overrides auto-build)
+      -1, --reads1 <READS1>  Comma-separated list of R1 FASTQ files
+      -2, --reads2 <READS2>  Comma-separated list of R2 FASTQ files
+
+    Probe Set Options:
+          --probe-set <PROBE_SET>            Path to probe set CSV or FASTA (overrides auto-download)
+          --sample-bc-list <SAMPLE_BC_LIST>  Path to sample/probe barcode file with rotation mapping
+          --kmer-length <KMER_LENGTH>        k-mer length for probe index building [default: 23]
+
+    Piscem Mapping Options:
+          --skipping-strategy <SKIPPING_STRATEGY>  The skipping strategy to use for k-mer collection [default: permissive] [possible values: permissive, strict]
+          --struct-constraints                     If piscem >= 0.7.0, enable structural constraints
+          --max-ec-card <MAX_EC_CARD>             Maximum cardinality equivalence class to examine [default: 4096]
+
+    Permit List Options:
+          --min-reads <MIN_READS>  Minimum read count threshold for unfiltered permit list [default: 10]
+
+Resource resolution
+-------------------
+
+``flex-quant`` resolves resources in the following order:
+
+- Probe index:
+  If ``--index`` is provided, ``simpleaf`` uses that index directly. The command expects a corresponding ``probe_t2g.tsv`` next to the index, unless you also provide ``--probe-set`` so it can generate the t2g mapping.
+- Probe set:
+  If ``--probe-set`` is provided, it overrides the registry entry. A CSV probe set is converted into a FASTA plus ``probe_t2g.tsv`` automatically. A FASTA input is accepted as-is, and ``simpleaf`` generates an identity-style t2g mapping from the FASTA headers.
+- Automatic probe-set selection:
+  If neither ``--index`` nor ``--probe-set`` is provided, ``simpleaf`` looks up the requested ``--organism`` in the selected chemistry's registered probe sets, downloads the matching probe CSV if needed, and builds a cached probe index.
+- Cell barcode whitelist:
+  This is resolved from the selected chemistry's permit-list metadata in the registry.
+- Sample barcode list:
+  This is resolved from ``--sample-bc-list`` if provided, otherwise from the selected chemistry's registry metadata.
+
+Examples
+--------
+
+Use a registry-backed Flex chemistry with automatic resource resolution:
+
+.. code-block:: console
+
+   $ export ALEVIN_FRY_HOME=/path/to/af_home
+   $ simpleaf flex-quant \
+       --chemistry 10x-flexv2-gex-3p \
+       --organism human \
+       --reads1 sample_R1.fastq.gz \
+       --reads2 sample_R2.fastq.gz \
+       --output flex_out
+
+Use local probe-set and sample-barcode files instead of downloading them:
+
+.. code-block:: console
+
+   $ simpleaf flex-quant \
+       --chemistry 10x-flexv1-gex-3p \
+       --organism mouse \
+       --probe-set /path/to/probe_set.csv \
+       --sample-bc-list /path/to/sample_bc.tsv \
+       --reads1 lane1_R1.fastq.gz,lane2_R1.fastq.gz \
+       --reads2 lane1_R2.fastq.gz,lane2_R2.fastq.gz \
+       --output flex_out
+
+Use a pre-built probe index:
+
+.. code-block:: console
+
+   $ simpleaf flex-quant \
+       --chemistry 10x-flexv2-gex-3p \
+       --organism human \
+       --index /path/to/probe_index \
+       --reads1 sample_R1.fastq.gz \
+       --reads2 sample_R2.fastq.gz \
+       --output flex_out
+
+Output
+------
+
+The command creates the requested output directory and writes:
+
+- ``af_map/``: the ``piscem`` mapping output
+- ``af_quant/``: the ``alevin-fry`` permit-list, collate, and quantification output
+- ``simpleaf_flex_quant_info.json``: a metadata record describing the resolved inputs, executed commands, and step timings
+
+Notes
+-----
+
+- ``flex-quant`` is specific to registered Flex GEX chemistries. For standard scRNA-seq chemistries and general custom geometries, use :doc:`/quant-command`.
+- The Flex pipeline currently uses ``piscem`` for mapping.
+- When a probe CSV is converted, all probes are kept in the generated FASTA and t2g mapping so that downstream quantification has a complete reference-to-gene map.

docs/source/index.rst

@@ -45,6 +45,7 @@ That's it for initial notes.  Use the menu below to learn more about the `simple
    inspect-command.rst
    index-command.rst
    quant-command.rst
+   flex-quant-command.rst
    refresh-prog-info.rst
    workflow.rst
    LICENSE.rst

docs/source/quant-command.rst

@@ -1,6 +1,8 @@
 ``quant`` command
 =================
 
+For 10x Flex Gene Expression data, use :doc:`/flex-quant-command` instead. The ``quant`` command documented here covers the standard ``simpleaf`` quantification workflow for non-Flex chemistries.
+
 
 The ``quant`` command takes as input **either**:
   1) the index, reads, and relevant information about the experiment (e.g. the chemistry) OR
@@ -95,4 +97,3 @@ The relevant options (which you can obtain by running ``simpleaf quant -h``) are
 
     Output Options:
           --anndata-out  Generate an anndata (h5ad format) count matrix from the standard (matrix-market format) output
-

docs/source/workflow-get.rst

@@ -30,8 +30,8 @@ Usually, a published workflow contains four sections:
 For most users, the ``fast_config`` is the only section needed to instantiate the template. To fill the missing information, one just needs to replace the ``null`` with a meaningful value. For more details, please check out dedicated tutorial on `running workflows from an published template <https://combine-lab.github.io/alevin-fry-tutorials/2023/running-simpleaf-workflow/>`_.
 
 
-Full Usage
-^^^^^^^^^^
+Get Usage
+^^^^^^^^^
 
 The relevant options (which you can obtain by running ``simpleaf workflow get -h``) are:
 
@@ -48,4 +48,3 @@ The relevant options (which you can obtain by running ``simpleaf workflow get -h
       -V, --version          Print version
 
 
-

docs/source/workflow-list.rst

@@ -3,7 +3,7 @@ simpleaf workflow list
 
 ``simpleaf workflow list`` lists all workflows in the registry. If one would like to refresh the registry to keep all workflows up to date, please run the :ref:`simpleaf workflow refresh` command.
 
-Full Usage
+List Usage
 ^^^^^^^^^^
 
 The relevant options (which you can obtain by running ``simpleaf workflow list -h``) are:
@@ -17,4 +17,3 @@ The relevant options (which you can obtain by running ``simpleaf workflow list -
     Options:
     -h, --help     Print help
     -V, --version  Print version
-

docs/source/workflow-refresh.rst

@@ -3,8 +3,8 @@ simpleaf workflow refresh
 
 ``simpleaf workflow refresh`` pulls the latest protocol estuary library from `its GitHub repository <https://github.com/COMBINE-lab/protocol-estuary>`_. We recommend updating the registry everytime before fetching a workflow.
 
-Full Usage
-^^^^^^^^^^
+Refresh Usage
+^^^^^^^^^^^^^
 
 The relevant options (which you can obtain by running ``simpleaf workflow refresh -h``) are:
 
@@ -17,4 +17,3 @@ The relevant options (which you can obtain by running ``simpleaf workflow refres
     Options:
     -h, --help     Print help
     -V, --version  Print version
-