Skip to content
Get packs

Guide · Agent skill

How to use the PyDESeq2 agent skill for differential expression

Updated · written with AI from the project's own documentation and checked against our catalogue data

The pydeseq2 skill gives an AI agent a statistics-aware workflow for finding genes that change between experimental groups in bulk RNA-seq data using PyDESeq2, a Python implementation of DESeq2. This guide explains what the skill does, how to install it from the ZIP on this page, how to ask for it in plain language, and what inputs it needs. By the end you will know how to prepare raw integer counts and sample metadata, run a specific comparison, and read the output files.

PyDESeq2 Differential ExpressionK-Dense-AI/scientific-agent-skills · MIT

Quick start

  1. 1Download and unzip. Download the skill ZIP from this page and unzip the skills/pydeseq2 folder into ~/.claude/skills/ or a project's .claude/skills/ folder.
  2. 2Create the environment. Use uv to create an environment with Python 3.13 and install pydeseq2 0.5.4 and anndata 0.13.4 as shown in the quick start.
  3. 3Prepare counts and metadata. Use raw integer counts with matching sample IDs in metadata, and label the reference level of your comparison variable.
  4. 4Ask the agent. Describe the files, design formula, contrast and alpha in a plain request that mentions PyDESeq2 or biological replicates.
  5. 5Review the run. Check warnings, convergence and the manifest, and confirm the contrast direction before interpreting genes.

What the pydeseq2 skill makes the agent do

An agent skill is a folder of instructions and helper files that an AI agent loads when a task matches the skill's description. This one covers bulk RNA-seq differential expression. The agent checks that count tables and sample metadata line up, fits a negative-binomial model with PyDESeq2, tests an explicit comparison, and exports tables and optional volcano and MA plots.

The skill also warns about common mistakes. It treats cells, lanes and repeated measurements from the same donor as non-independent, and it refuses TPM, FPKM, log or VST values as model inputs because they are not raw counts.

Install the pydeseq2 skill

Download the ZIP for skills/pydeseq2 from this page and unzip it. For a personal install, place the folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder. Alternatively, upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

The skill's own quick start suggests an isolated environment with uv. The commands below are copied from the skill's SKILL.md and install the pinned versions it was tested with.

  • Python 3.11 or newer is required; the tested stack uses Python 3.13.
  • AnnData 0.13.4 requires Python 3.12 or newer.
  • uv is suggested for environment setup.
  • Network access is needed for installation and optional upstream example-data downloads.
uv venv --python 3.13 .venv-pydeseq2 uv pip install --python .venv-pydeseq2/bin/python 'pydeseq2==0.5.4' 'anndata==0.13.4'

Prepare your input files

The bundled driver expects a counts CSV with genes as rows and samples as columns by default, and a metadata CSV with samples as rows and annotations as columns. Each file needs sample or gene IDs in its first column. Counts must be nonnegative integers from raw sequencing counts, not normalized values.

Metadata must include the variable you are comparing, and categories should be clearly labelled. Sample sets in the two files must match exactly; the driver rejects unequal sets rather than silently intersecting them.

  • Use raw integer counts, not TPM, FPKM, log or VST values.
  • Use --no-transpose if your counts file is already samples × genes.
  • Resolve missing design annotations in the metadata before running.
  • Use a fresh output directory for each run.

Run an analysis with the bundled driver

The skill includes scripts/run_deseq2_analysis.py. The example below is the command from the skill's quick start. Paths are illustrative; replace them with your own files. The contrast names the variable, the treated level and the control level, so the positive log2FoldChange means treated / control.

The driver performs Wald testing and LFC shrinkage by default. Use --no-shrink to export only unshrunk estimates. The CLI does not expose thresholded tests or alternative normalization methods; those require the Python API.

  • --design sets the formula, for example '~batch + condition'.
  • --min-counts sets a gene prefilter; 10 is a small example rule, not a universal threshold.
  • --alpha sets the significance cutoff used for the significant-genes table and plots.
  • --plots adds volcano and MA PNGs.
python scripts/run_deseq2_analysis.py \ --counts counts.csv --metadata metadata.csv \ --design '~batch + condition' --contrast condition treated control \ --min-counts 10 --alpha 0.05 --n-cpus 1 --plots --output results/

Trigger the skill with natural requests

You do not need to type the command. Ask the agent in plain language and mention PyDESeq2, Python DESeq2 or differential expression with biological replicates. The skill description is written to match those phrases.

Good requests name the files, the design and the comparison, so the agent can check them before fitting. For example: run PyDESeq2 on counts.csv and metadata.csv with design batch plus condition, comparing treated against control at alpha 0.05, and make volcano plots.

  • Give the experimental unit, for example donor-level replicates.
  • Name the comparison and which level is the reference.
  • Ask for plots if you want volcano and MA figures.

Read the outputs

Each run writes a fixed set of files. The results table keeps the current estimates, and the unshrunken Wald table is preserved separately. Missing adjusted p-values remain missing and are never counted as significant. Record your input provenance and any sample or gene exclusions alongside these files.

  • deseq2_results.csv: estimates with stat, pvalue and padj.
  • deseq2_results_unshrunken.csv: the original Wald table.
  • significant_genes.csv and results_sorted_by_padj.csv.
  • deseq_dataset.h5ad: fitted AnnData snapshot for inspection.
  • analysis_manifest.json: contrast, alpha, shrinkage coefficient and versions.
  • Volcano and MA PNGs when --plots is used.

Safety notes: scripts and network

This skill runs scripts and uses the network. The bundled driver executes Python code on your machine, and the install step and optional upstream example-data downloads need network access. Local analyses need no credentials. Review the script and the commands before you let an agent run them on sensitive data, and keep raw data within the environments your organization allows.

  • Runs scripts: yes.
  • Uses network: yes, for installation and optional example-data downloads.
  • Licence: MIT.

What people use it for

  • Comparing treated and control samples with a batch term in the design, for example '~batch + condition'.
  • Producing a ranked table of Wald statistics for a donor-level pseudobulk comparison, where the design matches the question.
  • Generating volcano and MA plots from the same alpha used for the significant-genes table.
  • Learning differential expression design and contrast logic with guardrails from the skill's checks.

Frequently asked questions

How do I install the pydeseq2 agent skill?

Download the ZIP for skills/pydeseq2 from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

What does the pydeseq2 skill require?

It requires Python 3.11 or newer, with the tested stack using Python 3.13 and AnnData 0.13.4, which needs Python 3.12 or newer. uv is suggested for setup, and network access is needed for installation and optional example-data downloads.

Is the pydeseq2 skill free to use?

The skill is licensed under the MIT licence, as stated on this page. This guide does not cover pricing for any other tools you may need.

Can I use TPM or FPKM values with this skill?

No. The skill states that TPM, FPKM, log and VST data are not model inputs and need raw nonnegative integer counts. Integer checks alone cannot confirm raw-count provenance.

Can I use it for single-cell data?

Not for per-cell testing. The skill says cells from the same donor are not independent biological replicates. Donor-level pseudobulk can be appropriate when the aggregation and design match the question.

How does this compare with R DESeq2?

PyDESeq2 is a Python implementation. The skill notes that current PyDESeq2 provides Wald tests and apeGLM-style shrinkage, and that not every feature or numerical result of R DESeq2 is implemented identically.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you are a bioinformatics researcher or student who wants a Python workflow for bulk RNA-seq differential expression with raw counts, biological replicates and explicit contrasts. Pick something else for single-cell per-cell testing, clinical or diagnostic decisions without expert statistical review, or datasets that only contain TPM, FPKM, log or VST values.

Download the skill

Find exactly what
you're looking for