captnseq-toolkit 0.1.1__tar.gz

captnseq_toolkit-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,18 @@
+name: CI
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.9", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # setuptools-scm needs tags
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e ".[test]"
+      - run: pytest -q
+      - run: captnseq-toolkit --version

captnseq_toolkit-0.1.1/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.venv/

captnseq_toolkit-0.1.1/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## Unreleased
+
+- Initial import of `sam2sites`, `sites2genes` and `essentiality` from the nf-core/captnseq pipeline `bin/` (logic unchanged).
+- The `captnseq-toolkit` command is now a standard argparse CLI with subparsers. `--help`, `--version` and error handling come from argparse, so running with no subcommand or an unknown one exits with status 2 and argparse's usage message. Each tool's options are unchanged.

captnseq_toolkit-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) The nf-core/captnseq team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

captnseq_toolkit-0.1.1/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: captnseq-toolkit
+Version: 0.1.1
+Summary: Analysis tools for CAPTn-seq transposon-insertion sequencing data (used by nf-core/captnseq)
+Author: Simon Jeanneau
+License: MIT
+Project-URL: Homepage, https://github.com/simonjeanneau/captnseq-toolkit
+Project-URL: Pipeline, https://github.com/nf-core/proposals/issues/173
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: scipy
+Requires-Dist: matplotlib
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# captnseq-toolkit
+
+Analysis tools for CAPTn-seq (transposon-insertion sequencing) data. This package holds the
+scientific logic used by the [nf-core/captnseq](https://github.com/nf-core/proposals/issues/173)
+pipeline, so the pipeline itself only contains Nextflow code.
+
+## Install
+
+```bash
+pip install captnseq-toolkit        # once released on PyPI
+conda install -c bioconda captnseq-toolkit   # once the Bioconda recipe is merged
+```
+
+## Usage
+
+```bash
+captnseq-toolkit --help
+captnseq-toolkit sam2sites    --help   # SAM -> insertion sites (BED + bedGraph)
+captnseq-toolkit sites2genes  --help   # insertion sites -> per-gene counts
+captnseq-toolkit essentiality --help   # per-gene counts -> essential / ambiguous / non-essential
+```
+
+## Development
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+Releases are tagged `vX.Y.Z` (version comes from git tags via setuptools-scm).

captnseq_toolkit-0.1.1/README.md

@@ -0,0 +1,30 @@
+# captnseq-toolkit
+
+Analysis tools for CAPTn-seq (transposon-insertion sequencing) data. This package holds the
+scientific logic used by the [nf-core/captnseq](https://github.com/nf-core/proposals/issues/173)
+pipeline, so the pipeline itself only contains Nextflow code.
+
+## Install
+
+```bash
+pip install captnseq-toolkit        # once released on PyPI
+conda install -c bioconda captnseq-toolkit   # once the Bioconda recipe is merged
+```
+
+## Usage
+
+```bash
+captnseq-toolkit --help
+captnseq-toolkit sam2sites    --help   # SAM -> insertion sites (BED + bedGraph)
+captnseq-toolkit sites2genes  --help   # insertion sites -> per-gene counts
+captnseq-toolkit essentiality --help   # per-gene counts -> essential / ambiguous / non-essential
+```
+
+## Development
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+Releases are tagged `vX.Y.Z` (version comes from git tags via setuptools-scm).

captnseq_toolkit-0.1.1/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=64", "setuptools-scm>=8"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "captnseq-toolkit"
+dynamic = ["version"]
+description = "Analysis tools for CAPTn-seq transposon-insertion sequencing data (used by nf-core/captnseq)"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Simon Jeanneau" }]
+requires-python = ">=3.9"
+dependencies = [
+    "numpy",
+    "pandas",
+    "scipy",
+    "matplotlib",
+]
+
+[project.optional-dependencies]
+test = ["pytest"]
+
+[project.scripts]
+captnseq-toolkit = "captnseq_toolkit.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/simonjeanneau/captnseq-toolkit"
+Pipeline = "https://github.com/nf-core/proposals/issues/173"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools_scm]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

captnseq_toolkit-0.1.1/recipe/meta.yaml

@@ -0,0 +1,47 @@
+# Draft Bioconda recipe - copy to bioconda/bioconda-recipes/recipes/captnseq-toolkit/meta.yaml
+# once a release exists on PyPI, filling in the sha256 of the sdist.
+{% set name = "captnseq-toolkit" %}
+{% set version = "0.1.0" %}
+
+package:
+  name: {{ name|lower }}
+  version: {{ version }}
+
+source:
+  url: https://pypi.io/packages/source/{{ name[0] }}/{{ name }}/captnseq_toolkit-{{ version }}.tar.gz
+  sha256: REPLACE_ME
+
+build:
+  noarch: python
+  number: 0
+  script: {{ PYTHON }} -m pip install . -vvv --no-deps --no-build-isolation
+  entry_points:
+    - captnseq-toolkit = captnseq_toolkit.cli:main
+
+requirements:
+  host:
+    - python >=3.9
+    - pip
+    - setuptools >=64
+    - setuptools-scm >=8
+  run:
+    - python >=3.9
+    - numpy
+    - pandas
+    - scipy
+    - matplotlib-base
+
+test:
+  imports:
+    - captnseq_toolkit
+  commands:
+    - captnseq-toolkit --version
+    - captnseq-toolkit sam2sites --help
+    - captnseq-toolkit sites2genes --help
+    - captnseq-toolkit essentiality --help
+
+about:
+  home: https://github.com/simonjeanneau/captnseq-toolkit
+  license: MIT
+  license_file: LICENSE
+  summary: Analysis tools for CAPTn-seq transposon-insertion sequencing data

captnseq_toolkit-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

captnseq_toolkit-0.1.1/src/captnseq_toolkit/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("captnseq-toolkit")
+except PackageNotFoundError:  # not installed
+    __version__ = "0+unknown"

captnseq_toolkit-0.1.1/src/captnseq_toolkit/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from captnseq_toolkit.cli import main
+
+sys.exit(main())

captnseq_toolkit-0.1.1/src/captnseq_toolkit/cli.py

@@ -0,0 +1,42 @@
+"""Top-level `captnseq-toolkit` command: one argparse subcommand per tool."""
+
+import argparse
+import sys
+
+from captnseq_toolkit import __version__, essentiality, sam2sites, sites2genes
+
+# name -> (module, one-line help). Each module provides add_arguments(parser) and run_args(args).
+SUBCOMMANDS = {
+    "sam2sites": (sam2sites, "SAM -> insertion sites (BED + bedGraph tracks)"),
+    "sites2genes": (sites2genes, "insertion sites -> per-gene insertion counts / index"),
+    "essentiality": (essentiality, "per-gene counts -> essential / ambiguous / non-essential calls"),
+}
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog="captnseq-toolkit",
+        description="Analysis tools for CAPTn-seq transposon-insertion sequencing data.",
+    )
+    parser.add_argument("-V", "--version", action="version", version=f"%(prog)s {__version__}")
+    subparsers = parser.add_subparsers(dest="command", metavar="<subcommand>", required=True)
+    for name, (module, help_text) in SUBCOMMANDS.items():
+        sub = subparsers.add_parser(
+            name,
+            help=help_text,
+            description=module.__doc__,
+            formatter_class=argparse.RawDescriptionHelpFormatter,
+        )
+        module.add_arguments(sub)
+        sub.set_defaults(func=module.run_args)
+    return parser
+
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+    args.func(args)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

captnseq_toolkit-0.1.1/src/captnseq_toolkit/essentiality.py

@@ -0,0 +1,209 @@
+"""Classify genes as essential / ambiguous / non-essential from sites2genes output
+(Python re-port of tradis_essentiality_wscore.R). Writes QC / changepoint plots as PDF.
+
+Ported verbatim from the CAPTn-seq Snakemake pipeline; only the entrypoint changed, plus an
+explicit Agg backend so it runs headless in containers / HPC jobs.
+"""
+
+# Faithful re-port of tradis_essentiality_wscore.R
+#
+# Fixes vs. the previous python port (tradis_essentiality_wscore.py):
+#   1. lower/upper threshold indexing was off by one bin (0-based numpy index
+#      divided directly by 10000, instead of mapped through the same 1-indexed
+#      x-grid R uses) -> thresholds were systematically ~0.0001 too low.
+#   2. loess() (local weighted quadratic regression) was replaced by a global
+#      degree-3 np.polyfit, which finds a different minimum -> different m.
+#   3. scipy's expon.fit / gamma.fit float the `loc` parameter by default;
+#      R's fitdistr assumes loc=0 for both. Now fit with floc=0 to match.
+#   4. First histogram (finding the second maxima) used bins='fd' where R
+#      uses breaks=200 equal-width bins.
+#   5. Second histogram (finding the inter-mode minimum m) used a fixed
+#      99-bin linspace where R uses r bins of fixed width 1/2000 (r depends
+#      on the data via maxval).
+#
+# ValueError guards (abort_and_output early exits) and the epsilon in the
+# log-odds ratio are kept from the previous python port; R has no equivalent
+# and would simply error on this pathological input.
+
+import argparse
+
+import pandas as pd
+import numpy as np
+from scipy import stats
+import matplotlib
+matplotlib.use('Agg')
+import matplotlib.pyplot as plt
+
+
+def loess_predict(x, y, span=0.75, degree=2):
+    """Local weighted polynomial regression (R's loess default: span=0.75,
+    degree=2, tricube weights), evaluated at the original x points -
+    equivalent to R's predict(loess(y ~ x)) with no newdata."""
+    x = np.asarray(x, dtype=float)
+    y = np.asarray(y, dtype=float)
+    n = len(x)
+    k = min(max(int(np.floor(span * n)), degree + 1), n)
+    fitted = np.empty(n)
+    for i in range(n):
+        d = np.abs(x - x[i])
+        order = np.argsort(d, kind="mergesort")[:k]
+        dmax = d[order].max()
+        w = np.ones(k) if dmax == 0 else np.clip(1 - (d[order] / dmax) ** 3, 0, None) ** 3
+        dx = x[order] - x[i]
+        X = np.vstack([dx ** p for p in range(degree + 1)]).T
+        sw = np.sqrt(w)
+        beta, *_ = np.linalg.lstsq(X * sw[:, None], y[order] * sw, rcond=None)
+        fitted[i] = beta[0]
+    return fitted
+
+
+def run(input_file, output_all, output_essen, output_ambig, output_nonessen):
+    STM_baseline = pd.read_csv(input_file, sep="\t", header=0)
+    input_base = input_file.split(".")[0]
+    ii = STM_baseline['ins_index'].values
+    STM_baseline['read_index'] = STM_baseline['read_count'] / STM_baseline['gene_length']
+
+    def abort_and_output(score_E=0, lower=1, upper=99):
+        STM_baseline['score_E'] = score_E
+        STM_baseline['F_threshold'] = lower
+        STM_baseline['N_threshold'] = upper
+        STM_baseline.to_csv(output_all, index=False)
+        STM_baseline[STM_baseline['ins_index'] < lower].to_csv(output_essen, index=False)
+        STM_baseline[STM_baseline['ins_index'] >= upper].to_csv(output_nonessen, index=False)
+        if lower < upper:
+            STM_baseline[(STM_baseline['ins_index'] >= lower) & (STM_baseline['ins_index'] < upper)].to_csv(output_ambig, index=False)
+        else:
+            STM_baseline[STM_baseline['ins_index'] >= upper].to_csv(output_ambig, index=False)
+        return
+
+    # Identify second maxima (R: hist(ii, breaks=200))
+    h, bin_edges = np.histogram(ii, bins=200, density=True)
+    if len(h) < 10:
+        abort_and_output()
+        return
+    maxindex = np.argmax(h[10:])
+    midpoints = (bin_edges[:-1] + bin_edges[1:]) / 2
+    maxval = midpoints[maxindex + 3]
+
+    nG = len(STM_baseline['read_count'])
+    r = int(np.floor(maxval * 2000))
+    if r <= 0:
+        abort_and_output()
+        return
+
+    fig1 = plt.figure()
+
+    # R: hist(ii[I], breaks=(0:r/2000)) -> r bins of fixed width 1/2000
+    I = ii < r / 2000
+    h1, edges1 = np.histogram(ii[I], bins=np.linspace(0, r / 2000, r + 1))
+    loess_curve = loess_predict(np.arange(1, len(h1) + 1), h1)
+
+    plt.plot(h1, label="Density")
+    plt.plot(loess_curve, color='red', lw=2, label="Loess Curve")
+    plt.legend()
+    plt.title("Density")
+
+    mid1 = (edges1[:-1] + edges1[1:]) / 2
+    m = mid1[np.argmin(loess_curve)]
+    I1 = (ii < m) & (ii >= 0)
+
+    h_full, edges_full = np.histogram(ii, bins='fd')
+    I2 = (ii >= m) & (ii < edges_full[np.max(np.where(h_full > 5))])
+
+    f1 = (np.sum(I1) + np.sum(ii == 0)) / nG
+    f2 = np.sum(I2) / nG
+
+    # Fit exponential and gamma distributions, anchored at loc=0 like R's fitdistr
+    try:
+        d1 = stats.expon.fit(ii[I1], floc=0)
+        d2 = stats.gamma.fit(ii[I2], floc=0)
+    except ValueError:
+        abort_and_output()
+        return
+
+    # Generate and save the plot
+    x_vals = np.linspace(0, max(ii), 500)
+    fig2 = plt.figure()
+    plt.hist(ii, bins='fd', density=True, label="Data")
+    plt.plot(x_vals, f1 * stats.expon.pdf(x_vals, *d1), label="Exponential fit")
+    plt.plot(x_vals, f2 * stats.gamma.pdf(x_vals, *d2), label="Gamma fit")
+
+    # Calculate log-odds ratios (x grid matches R's 1:1000/10000 exactly)
+    epsilon = 1e-10  # prevents log(0)/log(inf) on pathological input; no R equivalent
+    x_grid = np.arange(1, 1001) / 10000.0
+    log_odds = np.log2(
+        ((stats.gamma.cdf(x_grid, *d2) *
+          (1 - stats.expon.sf(x_grid, *d1))) + epsilon) /
+        ((stats.expon.sf(x_grid, *d1) *
+          (1 - stats.gamma.cdf(x_grid, *d2))) + epsilon)
+    )
+
+    where_lower = np.where(log_odds < -2)[0]
+    where_upper = np.where(log_odds > 2)[0]
+    if len(where_lower) == 0 or len(where_upper) == 0:
+        abort_and_output()
+        return
+    lower = x_grid[np.max(where_lower)]
+    upper = x_grid[np.min(where_upper)]
+
+    # Adding lines to the plot for thresholds
+    plt.legend()
+    plt.axvline(lower, color='red', label="Lower Threshold")
+    plt.axvline(upper, color='red', label="Upper Threshold")
+    plt.text(lower, 30, f"Essential changepoint: {lower:.4f}", color='red')
+    plt.text(upper, 10, f"Ambiguous changepoint: {upper:.4f}", color='red')
+    plt.title("Gamma fits")
+
+    with plt.rc_context():
+        from matplotlib.backends.backend_pdf import PdfPages
+        with PdfPages(f"{input_base}_QC_and_changepoint_plots.pdf") as pdf:
+            pdf.savefig(fig1)
+            pdf.savefig(fig2)
+    plt.close(fig1)
+    plt.close(fig2)
+
+    # Calculate 'read_index' and 'score_E'
+    score_E = []
+    for iindex in STM_baseline['ins_index']:
+        if iindex <= lower:
+            score_E.append(iindex / lower)
+        elif lower < iindex <= upper:
+            score_E.append((iindex - lower) / lower + 1)
+        else:
+            score_E.append((iindex - upper) / upper + 2)
+
+    abort_and_output(score_E, lower, upper)
+
+
+def add_arguments(parser):
+    """Register this subcommand's options on *parser*."""
+    parser.add_argument("--input", required=True, help="sites2genes output (genes_insertions.tsv)")
+    parser.add_argument("--output-all", required=True)
+    parser.add_argument("--output-essen", required=True)
+    parser.add_argument("--output-ambig", required=True)
+    parser.add_argument("--output-nonessen", required=True)
+
+
+def run_args(args):
+    """Run the subcommand from an ``argparse.Namespace``."""
+    run(
+        input_file=args.input,
+        output_all=args.output_all,
+        output_essen=args.output_essen,
+        output_ambig=args.output_ambig,
+        output_nonessen=args.output_nonessen,
+    )
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        prog="captnseq-toolkit essentiality",
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    add_arguments(parser)
+    run_args(parser.parse_args(argv))
+
+
+if __name__ == "__main__":
+    main()

captnseq_toolkit-0.1.1/src/captnseq_toolkit/sam2sites.py

@@ -0,0 +1,347 @@
+"""Call transposon insertion sites from a SAM file and write BED / bedGraph tracks.
+
+Ported verbatim from the CAPTn-seq Snakemake pipeline (pipeline/scripts/sam2sites.py);
+only the entrypoint changed (argparse instead of the injected `snakemake` object).
+"""
+
+import argparse
+import csv
+
+import numpy as np
+import pandas as pd
+
+
+def parse_sam_file(samfile: str, aligned_length_threshold: int = 21, pos_offset: tuple = (3, -6)) -> pd.DataFrame:
+    """
+    Parses a SAM-like file and retains only first-in-pair reads
+    with aligned read length above threshold.
+
+    Determines strand from the SAM flag using bitwise logic.
+
+    pos_offset: (forward_offset, reverse_offset) position-correction offset,
+    empirically determined per transposon/library-prep system - passed in
+    from config (sam2sites_params.pos_offset_fwd/pos_offset_rev) rather than
+    hardcoded here, since a different experiment's transposon may need
+    different values.
+    """
+    df = pd.read_csv(
+        samfile,
+        sep="\t",
+        header=None,
+        usecols=range(6),
+        names=["name", "flag", "chr_name", "pos", "score", "cigar"],
+        dtype={
+            "name": str,
+            "flag": int,
+            "chr_name": str,
+            "pos": int,
+            "score": int,
+            "cigar": str
+        },
+        engine="python",
+        quoting=csv.QUOTE_NONE,
+        on_bad_lines="warn"
+    )
+
+    # Determine strand and filter to first-in-pair reads only
+    df["strand"] = df["flag"].apply(lambda x: "-" if x & 0x10 else "+") #	0x10 == True is mapped to the reverse strand
+    df["first_in_pair"] = df["flag"].apply(lambda x: bool(x & 0x40)) #	0x40 == True is the first read in a pair
+    df = df[df["first_in_pair"]].copy()
+
+    # use regex to extract each int/marker and build a secondary df holding these info.
+    #
+    # typic input:
+    # ------------
+    #
+    # 20      42M
+    # 25    72M3S
+    # Name: cigar
+    #
+    # typic output:
+    # -------------
+    #
+    #           size marker
+    #    match
+    # 20 0        42      M
+    # 25 0        72      M
+    #    1         3      S
+
+    # Extract cigar operations
+    cigar_components = df["cigar"].str.extractall(r"(?P<size>\d+)(?P<op>[A-Z])")
+    cigar_components["size"] = cigar_components["size"].astype(int)
+
+    # Group cigar operations by index
+    cigar_group = cigar_components.groupby(level=0)
+
+    # First and last CIGAR op per read (used for validity check)
+    cigar_first_op = cigar_group["op"].first()
+    cigar_last_op = cigar_group["op"].last()
+
+    # Aligned length = sum of sizes for relevant ops (M, D, N, =, X)
+    aligned_ops = cigar_components[cigar_components["op"].isin(["M", "D", "N", "=", "X"])]
+    aligned_length = aligned_ops.groupby(level=0)["size"].sum()
+
+    # Inject back into main df using .map()
+    df["cigar_first_op"] = df.index.map(cigar_first_op)
+    df["cigar_last_op"] = df.index.map(cigar_last_op)
+    df["aligned_read_length"] = df.index.map(aligned_length).fillna(0).astype(int)
+
+    # Define valid reads based on strand and expected CIGAR structure
+    valid_positive = (df["strand"] == "+") & (df["cigar_first_op"] == "M")
+    valid_negative = (df["strand"] == "-") & (df["cigar_last_op"] == "M")
+    df["valid"] = (valid_positive | valid_negative) & (df["aligned_read_length"] > aligned_length_threshold)
+
+    # Position correction offset (empirically determined; not derived from a
+    # documented formula), passed in from config. (+offset[0]) shifts a
+    # forward-strand read's aligned start to the actual insertion site;
+    # (offset[1]) does the same for a reverse-strand read's aligned end.
+
+    # Compute adjusted start position
+    valid_df = df[df["valid"]].copy()
+    valid_df["start"] = np.where(
+        valid_df["strand"] == "+",
+        valid_df["pos"] + pos_offset[0],
+        valid_df["pos"] + valid_df["aligned_read_length"] + pos_offset[1]
+    )
+    return valid_df
+
+
+def filter_reads_by_site_support(sam_df: pd.DataFrame, score_threshold: int) -> pd.DataFrame:
+    """
+    Retain only reads whose (chr_name, start) occurs with at least `score_threshold` other reads.
+    Keeps all columns including QNAMEs (name) and strand info.
+    """
+    group_keys = ["chr_name", "start"]
+    # Count number of reads per position per strand
+    site_counts = (
+        sam_df.groupby(group_keys + ["strand"])["name"]
+        .count()
+        .unstack(fill_value=0)
+        # CHANGE: unstack() only produces a column for strands actually
+        #         present in sam_df. If every surviving read happens to be on
+        #         one strand (plausible for a low-coverage/failing sample),
+        #         "+" or "-" would be missing entirely and the score_pos/
+        #         score_neg lookups below would raise a KeyError. Reindexing
+        #         guarantees both columns always exist, filled with 0.
+        .reindex(columns=["+", "-"], fill_value=0)
+        .rename(columns={"+": "score_pos", "-": "score_neg"})
+        .reset_index()
+    )
+    # Keep only positions with sufficient read support on either strand
+    supported_sites = site_counts[
+        (site_counts["score_pos"] > score_threshold) |
+        (site_counts["score_neg"] > score_threshold)
+    ][["chr_name", "start"]]
+    # Inner join back with reads
+    filtered_reads = sam_df.merge(supported_sites, on=["chr_name", "start"], how="inner")
+    return filtered_reads
+
+
+def sam_to_site(filtered_dedup_reads: pd.DataFrame) -> pd.DataFrame:
+    """
+    Convert a filtered and deduplicated read set into strand-specific insertion site counts.
+
+    Parameters
+    ----------
+    filtered_dedup_reads : pd.DataFrame
+        DataFrame with at least the following columns:
+        - 'chr_name': reference sequence
+        - 'start': insertion position (already corrected)
+        - 'strand': '+' or '-'
+        - 'name': QNAME (used for counting insertions)
+
+    Returns
+    -------
+    pd.DataFrame
+        A DataFrame with one row per (chr_name, start), containing:
+        - 'chr_name'
+        - 'start'
+        - 'end': start + 1 (BED-style interval)
+        - 'name': fixed to 'i' (placeholder for BED)
+        - 'score_pos': insertion count on + strand
+        - 'score_neg': insertion count on - strand
+    """
+    group_keys = ["chr_name", "start"]
+    score_pos = (
+        filtered_dedup_reads[filtered_dedup_reads["strand"] == "+"]
+        .groupby(group_keys)["name"]
+        .count()
+        .rename("score_pos")
+    )
+    score_neg = (
+        filtered_dedup_reads[filtered_dedup_reads["strand"] == "-"]
+        .groupby(group_keys)["name"]
+        .count()
+        .rename("score_neg")
+    )
+
+    site_df = pd.concat([score_pos, score_neg], axis=1).reset_index()
+    site_df["end"] = site_df["start"] + 1
+    site_df["name"] = "i"
+    site_df = site_df.fillna({"score_pos": 0, "score_neg": 0})
+    site_df = site_df[["chr_name", "start", "end", "name", "score_pos", "score_neg"]]
+    site_df = site_df.sort_values(by=["chr_name", "start"])
+    return site_df
+
+
+def site_to_interval(site_df: pd.DataFrame, *, normalization_value: int) -> pd.DataFrame:
+    total_reads = site_df["score_pos"].sum() + site_df["score_neg"].sum()
+    pos_interval_df = (
+        site_df[["chr_name", "start", "end", "name", "score_pos"]]
+        .rename(columns={"score_pos": "score"})
+    )
+    pos_interval_df["strand"] = "+"
+    neg_interval_df = (
+        site_df[["chr_name", "start", "end", "name", "score_neg"]]
+        .rename(columns={"score_neg": "score"})
+    )
+    neg_interval_df["strand"] = "-"
+    interval_df = pd.concat([pos_interval_df, neg_interval_df], ignore_index=True)
+    # Normalize scores to target total, clip at 1 to ensure non-zero presence
+    interval_df["normalized_score"] = (
+        (interval_df["score"] / total_reads * normalization_value)
+        .astype(int)
+        .clip(lower=1)
+    )
+    interval_df["fake_score"] = 999 # Placeholder fixed score
+    interval_df = interval_df.sort_values(by=["chr_name", "start"])
+    interval_df = interval_df[interval_df["score"] != 0]
+    return interval_df
+
+
+def build_bed_file(interval_df: pd.DataFrame, filename):
+    """
+    bed_file
+    --------
+
+    "chr_name", "start", "end", "name", "fake_score", "strand"
+
+    pVCR94deltaX3deltaacr2FRT	26	27	i	999	+
+    pVCR94deltaX3deltaacr2FRT	47	48	i	999	+
+    pVCR94deltaX3deltaacr2FRT	68	69	i	999	+
+    pVCR94deltaX3deltaacr2FRT	97	98	i	999	-
+    pVCR94deltaX3deltaacr2FRT	245	246	i	999	-
+    """
+    interval_df[["chr_name", "start", "end", "name", "fake_score", "strand"]].to_csv(
+        filename, header=False, index=False, sep="\t"
+    )
+
+
+def build_stranded_unnormalized_bedgraph_file(
+    interval_df: pd.DataFrame, filename):
+    """
+    stranded_unnormalized_bedgraph_file
+    --------
+
+    "chr_name", "start", "end", "score"
+
+    pVCR94deltaX3deltaacr2FRT	26	27	2400
+    pVCR94deltaX3deltaacr2FRT	47	48	60
+    pVCR94deltaX3deltaacr2FRT	68	69	60
+    pVCR94deltaX3deltaacr2FRT	97	98	1380
+    pVCR94deltaX3deltaacr2FRT	245	246	3780
+    """
+    interval_df[["chr_name", "start", "end", "score"]].to_csv(
+        filename, header=False, index=False, sep="\t"
+    )
+
+
+def build_stranded_bedgraph_file(interval_df: pd.DataFrame, filename):
+    """
+    stranded_bedgraph_file
+    --------
+
+    "chr_name", "start", "end", "normalized_score"
+
+    pVCR94deltaX3deltaacr2FRT	26	27	2189
+    pVCR94deltaX3deltaacr2FRT	47	48	54
+    pVCR94deltaX3deltaacr2FRT	47	48	54
+    pVCR94deltaX3deltaacr2FRT	68	69	54
+    pVCR94deltaX3deltaacr2FRT	97	98	1258
+    pVCR94deltaX3deltaacr2FRT	245	246	3448
+    """
+    interval_df[["chr_name", "start", "end", "normalized_score"]].to_csv(
+        filename, header=False, index=False, sep="\t"
+    )
+
+
+def build_unstranded_bedgraph_file(interval_df: pd.DataFrame, filename):
+    """
+    unstranded_bedgraph_file
+    --------
+
+    "chr_name", "start", "end", "normalized_score"
+
+    pVCR94deltaX3deltaacr2FRT	26	27	2189
+    pVCR94deltaX3deltaacr2FRT	47	48	108<-(score for insertions on the same position, but different strands are merged)
+    pVCR94deltaX3deltaacr2FRT	68	69	54
+    pVCR94deltaX3deltaacr2FRT	97	98	1258
+    pVCR94deltaX3deltaacr2FRT	245	246	3448
+    """
+    interval_df = interval_df.groupby(["chr_name", "start", "end"], sort=False).agg({'normalized_score': 'sum'}).reset_index()
+    interval_df[["chr_name", "start", "end", "normalized_score"]].to_csv(
+        filename, header=False, index=False, sep="\t"
+    )
+
+
+def build_unstranded_unnormalized_bedgraph_file(interval_df: pd.DataFrame, filename):
+    """
+    unstranded_bedgraph_file
+    --------
+
+    "chr_name", "start", "end", "score"
+
+    pVCR94deltaX3deltaacr2FRT	26	27	2400
+    pVCR94deltaX3deltaacr2FRT	47	48	60
+    pVCR94deltaX3deltaacr2FRT	68	69	60<-(score for insertions on the same position, but different strands are merged)
+    pVCR94deltaX3deltaacr2FRT	97	98	1380
+    pVCR94deltaX3deltaacr2FRT	245	246	3780
+    """
+
+    interval_df = interval_df.groupby(["chr_name", "start", "end"], sort=False).agg({'score': 'sum'}).reset_index()
+    interval_df[["chr_name", "start", "end", "score"]].to_csv(
+        filename, header=False, index=False, sep="\t"
+    )
+
+
+def add_arguments(parser):
+    """Register this subcommand's options on *parser*."""
+    parser.add_argument("--sam", required=True)
+    parser.add_argument("--norm-value", type=int, required=True)
+    parser.add_argument("--read-len-threshold", type=int, required=True)
+    parser.add_argument("--score-threshold", type=int, required=True)
+    parser.add_argument("--pos-offset-fwd", type=int, required=True)
+    parser.add_argument("--pos-offset-rev", type=int, required=True)
+    parser.add_argument("--bed-output", required=True)
+    parser.add_argument("--normalized-output", required=True)
+    parser.add_argument("--unstranded-output", required=True)
+    parser.add_argument("--unnormalized-output", required=True)
+    parser.add_argument("--unstranded-unnormalized-output", required=True)
+
+
+def run_args(args):
+    """Run the subcommand from an ``argparse.Namespace``."""
+    pos_offset = (args.pos_offset_fwd, args.pos_offset_rev)
+    sam_df = parse_sam_file(args.sam, args.read_len_threshold, pos_offset)
+    filtered_reads = filter_reads_by_site_support(sam_df, args.score_threshold)
+    site_df = sam_to_site(filtered_reads)
+    interval_df = site_to_interval(site_df, normalization_value=args.norm_value)
+    build_bed_file(interval_df, args.bed_output)
+    build_stranded_bedgraph_file(interval_df, args.normalized_output)
+    build_unstranded_bedgraph_file(interval_df, args.unstranded_output)
+    build_stranded_unnormalized_bedgraph_file(interval_df, args.unnormalized_output)
+    build_unstranded_unnormalized_bedgraph_file(interval_df, args.unstranded_unnormalized_output)
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        prog="captnseq-toolkit sam2sites",
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    add_arguments(parser)
+    run_args(parser.parse_args(argv))
+
+
+if __name__ == "__main__":
+    main()

captnseq_toolkit-0.1.1/src/captnseq_toolkit/sites2genes.py

@@ -0,0 +1,126 @@
+"""Count insertions per gene from a BED/intersect file, with optional trimming of the
+informative gene region (--length-pc-start / --length-pc-stop).
+
+Usage: captnseq-toolkit sites2genes --features CDS.bed --sample intersect.bed
+       --length-pc-start 0 --length-pc-stop 100 --output genes_insertions.tsv
+
+Ported verbatim from the CAPTn-seq Snakemake pipeline (pipeline_ref/scripts/sites2genes.py);
+only the entrypoint changed.
+"""
+
+import argparse
+import pandas as pd
+
+
+def compute_gene_insertions(features_path, sample_path, length_pc_start, length_pc_stop, output_path):
+    # Read files
+    gene_df = pd.read_csv(
+        str(features_path),
+        dtype={
+            "chr_name": str,
+            "start": "Int64",
+            "end": "Int64",
+            "name": str,
+            "score": "Int64",
+            "strand": str
+        },
+        sep="\t",
+        header=None,
+        names=["chr_name", "start", "end", "name", "score", "strand"],
+    )
+
+    intersect_df = pd.read_csv(
+        str(sample_path),
+        dtype={
+            "chr_name_gene": str,
+            "start_gene": "Int64",
+            "end_gene": "Int64",
+            "name_gene": str,
+            "score_gene": "Int64",
+            "strand_gene": str,
+            "chr_name_insertion": str,
+            "start_insertion": "Int64",
+            "end_insertion": "Int64",
+            "score_insertion": "Int64"
+        },
+        sep="\t",
+        header=None,
+        usecols=range(10),
+        names=["chr_name_gene", "start_gene", "end_gene", "name_gene", "score_gene", "strand_gene", "chr_name_insertion", "start_insertion", "end_insertion", "score_insertion"],
+    )
+
+    # filter insertions outside of genes (due to insertion duplication and excluding length_pc_start length_pc_end)
+    intersect_df.replace({'strand_gene': {"+": "1", "-": "-1"}}, inplace=True)
+    gene_df.replace({'strand': {"+": "1", "-": "-1"}}, inplace=True)
+
+    intersect_df = intersect_df.loc[
+        (
+            (intersect_df['strand_gene'] == "1") &
+            ((intersect_df['start_insertion'] - 5) >= (intersect_df['start_gene'] + ((intersect_df['end_gene'] - intersect_df['start_gene']) * length_pc_start / 100.0))) &
+            ((intersect_df['start_insertion'] + 5) <= (intersect_df['end_gene'] - 1 - ((intersect_df['end_gene'] - intersect_df['start_gene']) * (100 - length_pc_stop) / 100.0)))
+        )
+        |
+        (
+            (intersect_df['strand_gene'] == "-1") &
+            ((intersect_df['start_insertion'] + 5) <= (intersect_df['end_gene'] - 1 - ((intersect_df['end_gene'] - intersect_df['start_gene']) * length_pc_start / 100.0))) &
+            ((intersect_df['start_insertion'] - 5) >= (intersect_df['start_gene'] + ((intersect_df['end_gene'] - intersect_df['start_gene']) * (100 - length_pc_stop) / 100.0)))
+        )
+    ]
+
+    # make columns required for biotradis toolkit (almost, usually no chr_name)
+    gene_df["locus_tag"] = gene_df["name"]
+    gene_df["gene_name"] = gene_df["name"]
+    gene_df["ncrna"] = 0
+    gene_df["read_count"] = 0
+    gene_df["ins_index"] = 0.0
+    gene_df["gene_length"] = gene_df["end"] - gene_df["start"]
+    gene_df["ins_count"] = 0
+    gene_df["fcn"] = "NA"
+    gene_df = gene_df.set_index('name')
+
+    # Compute insertion index and read_count
+    # Perform groupby and specify the aggregation dictionary
+    intersect_df = intersect_df.groupby('name_gene', sort=False).agg({'score_insertion': ['sum', 'mean', 'count']})
+    # This creates a MultiIndex in columns, so you need to flatten these for easier access
+    intersect_df.columns = ['_'.join(col).strip() for col in intersect_df.columns.values]
+    for index, row in intersect_df.iterrows():
+        gene_df.loc[index, "read_count"] = row['score_insertion_sum']
+        gene_df.loc[index, "ins_count"] = row['score_insertion_count']
+    gene_df["ins_index"] = gene_df["ins_count"] / gene_df["gene_length"]
+    gene_df[["chr_name", "locus_tag", "gene_name", "ncrna", "start", "end", "strand", "read_count", "ins_index", "gene_length", "ins_count", "fcn"]].to_csv(
+        str(output_path), header=True, index=False, sep="\t"
+    )
+
+
+def add_arguments(parser):
+    """Register this subcommand's options on *parser*."""
+    parser.add_argument("--features", required=True)
+    parser.add_argument("--sample", required=True)
+    parser.add_argument("--length-pc-start", type=float, required=True)
+    parser.add_argument("--length-pc-stop", type=float, required=True)
+    parser.add_argument("--output", required=True)
+
+
+def run_args(args):
+    """Run the subcommand from an ``argparse.Namespace``."""
+    compute_gene_insertions(
+        features_path=args.features,
+        sample_path=args.sample,
+        length_pc_start=args.length_pc_start,
+        length_pc_stop=args.length_pc_stop,
+        output_path=args.output,
+    )
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        prog="captnseq-toolkit sites2genes",
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    add_arguments(parser)
+    run_args(parser.parse_args(argv))
+
+
+if __name__ == "__main__":
+    main()

captnseq_toolkit-0.1.1/src/captnseq_toolkit.egg-info/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: captnseq-toolkit
+Version: 0.1.1
+Summary: Analysis tools for CAPTn-seq transposon-insertion sequencing data (used by nf-core/captnseq)
+Author: Simon Jeanneau
+License: MIT
+Project-URL: Homepage, https://github.com/simonjeanneau/captnseq-toolkit
+Project-URL: Pipeline, https://github.com/nf-core/proposals/issues/173
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: scipy
+Requires-Dist: matplotlib
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# captnseq-toolkit
+
+Analysis tools for CAPTn-seq (transposon-insertion sequencing) data. This package holds the
+scientific logic used by the [nf-core/captnseq](https://github.com/nf-core/proposals/issues/173)
+pipeline, so the pipeline itself only contains Nextflow code.
+
+## Install
+
+```bash
+pip install captnseq-toolkit        # once released on PyPI
+conda install -c bioconda captnseq-toolkit   # once the Bioconda recipe is merged
+```
+
+## Usage
+
+```bash
+captnseq-toolkit --help
+captnseq-toolkit sam2sites    --help   # SAM -> insertion sites (BED + bedGraph)
+captnseq-toolkit sites2genes  --help   # insertion sites -> per-gene counts
+captnseq-toolkit essentiality --help   # per-gene counts -> essential / ambiguous / non-essential
+```
+
+## Development
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+Releases are tagged `vX.Y.Z` (version comes from git tags via setuptools-scm).

captnseq_toolkit-0.1.1/src/captnseq_toolkit.egg-info/SOURCES.txt

@@ -0,0 +1,23 @@
+.gitignore
+CHANGELOG.md
+LICENSE
+README.md
+pyproject.toml
+.github/workflows/ci.yml
+recipe/meta.yaml
+src/captnseq_toolkit/__init__.py
+src/captnseq_toolkit/__main__.py
+src/captnseq_toolkit/cli.py
+src/captnseq_toolkit/essentiality.py
+src/captnseq_toolkit/sam2sites.py
+src/captnseq_toolkit/sites2genes.py
+src/captnseq_toolkit.egg-info/PKG-INFO
+src/captnseq_toolkit.egg-info/SOURCES.txt
+src/captnseq_toolkit.egg-info/dependency_links.txt
+src/captnseq_toolkit.egg-info/entry_points.txt
+src/captnseq_toolkit.egg-info/requires.txt
+src/captnseq_toolkit.egg-info/scm_file_list.json
+src/captnseq_toolkit.egg-info/scm_version.json
+src/captnseq_toolkit.egg-info/top_level.txt
+tests/test_cli.py
+tests/test_sites2genes.py

captnseq_toolkit-0.1.1/src/captnseq_toolkit.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

captnseq_toolkit-0.1.1/src/captnseq_toolkit.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+captnseq-toolkit = captnseq_toolkit.cli:main

captnseq_toolkit-0.1.1/src/captnseq_toolkit.egg-info/requires.txt

@@ -0,0 +1,7 @@
+numpy
+pandas
+scipy
+matplotlib
+
+[test]
+pytest

captnseq_toolkit-0.1.1/src/captnseq_toolkit.egg-info/scm_file_list.json

@@ -0,0 +1,19 @@
+{
+  "files": [
+    ".github/workflows/ci.yml",
+    ".gitignore",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
+    "pyproject.toml",
+    "recipe/meta.yaml",
+    "src/captnseq_toolkit/__init__.py",
+    "src/captnseq_toolkit/__main__.py",
+    "src/captnseq_toolkit/cli.py",
+    "src/captnseq_toolkit/essentiality.py",
+    "src/captnseq_toolkit/sam2sites.py",
+    "src/captnseq_toolkit/sites2genes.py",
+    "tests/test_cli.py",
+    "tests/test_sites2genes.py"
+  ]
+}

captnseq_toolkit-0.1.1/src/captnseq_toolkit.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.1.1",
+  "distance": 0,
+  "node": "ge329bc5a188d033b542ea387db5e85c55475b3c4",
+  "dirty": false,
+  "branch": "build/bioconda-release",
+  "node_date": "2026-10-16"
+}

captnseq_toolkit-0.1.1/src/captnseq_toolkit.egg-info/top_level.txt

@@ -0,0 +1 @@
+captnseq_toolkit

captnseq_toolkit-0.1.1/tests/test_cli.py

@@ -0,0 +1,72 @@
+import subprocess
+import sys
+
+import pandas as pd
+import pytest
+
+from captnseq_toolkit import __version__
+from captnseq_toolkit.cli import SUBCOMMANDS, main
+
+
+def test_help_lists_all_subcommands(capsys):
+    with pytest.raises(SystemExit) as exc:
+        main(["--help"])
+    assert exc.value.code == 0
+    out = capsys.readouterr().out
+    for name in SUBCOMMANDS:
+        assert name in out
+
+
+def test_version(capsys):
+    with pytest.raises(SystemExit) as exc:
+        main(["--version"])
+    assert exc.value.code == 0
+    assert capsys.readouterr().out.strip() == f"captnseq-toolkit {__version__}"
+
+
+def test_no_subcommand_is_an_error(capsys):
+    with pytest.raises(SystemExit) as exc:
+        main([])
+    assert exc.value.code == 2
+    assert "required" in capsys.readouterr().err
+
+
+def test_unknown_subcommand_is_an_error(capsys):
+    with pytest.raises(SystemExit) as exc:
+        main(["nope"])
+    assert exc.value.code == 2
+    assert "invalid choice" in capsys.readouterr().err
+
+
+@pytest.mark.parametrize("name", list(SUBCOMMANDS))
+def test_subcommand_help(name):
+    r = subprocess.run([sys.executable, "-m", "captnseq_toolkit", name, "--help"], capture_output=True, text=True)
+    assert r.returncode == 0
+    assert f"captnseq-toolkit {name}" in r.stdout
+
+
+@pytest.mark.parametrize("name", list(SUBCOMMANDS))
+def test_subcommand_missing_required_options(name, capsys):
+    with pytest.raises(SystemExit) as exc:
+        main([name])
+    assert exc.value.code == 2
+    assert "required" in capsys.readouterr().err
+
+
+def test_sites2genes_runs_through_top_level_cli(tmp_path):
+    features = tmp_path / "cds.bed"
+    features.write_text("chr\t0\t1000\tgeneA\t0\t1\n")
+    sample = tmp_path / "intersect.bed"
+    sample.write_text("chr\t0\t1000\tgeneA\t0\t1\tchr\t500\t501\t10\n")
+    out = tmp_path / "out.tsv"
+    rc = main([
+        "sites2genes",
+        "--features", str(features),
+        "--sample", str(sample),
+        "--length-pc-start", "0",
+        "--length-pc-stop", "100",
+        "--output", str(out),
+    ])
+    assert rc == 0
+    df = pd.read_csv(out, sep="\t").set_index("gene_name")
+    assert df.loc["geneA", "ins_count"] == 1

captnseq_toolkit-0.1.1/tests/test_sites2genes.py

@@ -0,0 +1,20 @@
+import pandas as pd
+
+from captnseq_toolkit.sites2genes import compute_gene_insertions
+
+
+def test_counts_insertions_inside_gene(tmp_path):
+    features = tmp_path / "cds.bed"
+    features.write_text("chr\t0\t1000\tgeneA\t0\t1\nchr\t2000\t3000\tgeneB\t0\t1\n")
+    # 10 columns: gene BED6 (chr,start,end,name,score,strand) + insertion (chr,start,end,score)
+    sample = tmp_path / "intersect.bed"
+    sample.write_text(
+        "chr\t0\t1000\tgeneA\t0\t1\tchr\t500\t501\t10\n"
+        "chr\t0\t1000\tgeneA\t0\t1\tchr\t600\t601\t5\n"
+    )
+    out = tmp_path / "out.tsv"
+    compute_gene_insertions(features, sample, 0, 100, out)
+    df = pd.read_csv(out, sep="\t").set_index("gene_name")
+    assert df.loc["geneA", "ins_count"] == 2
+    assert df.loc["geneA", "read_count"] == 15
+    assert df.loc["geneB", "ins_count"] == 0