Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

docs: clustering tutorial - mouse mitochondrial gene pattern incorrect character case

Closed Beginner friendly
  • Is something wrong?
#4,386 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
1/5
Estimated time
Under an hour
Newbie friendliness
82/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Active
Tech stack
jupyter-notebook, python
Domain
bioinformatics, documentation

Research direction

Open tutorials/basics/clustering.ipynb and inspect the fifth code cell containing the mitochondrial gene naming comment and prefix example. Update the mouse convention, then run or preview the tutorial to confirm the wording and example are consistent; the optional hemoglobin concern may need clarification before expanding the scope.

Written by the indexing model from the issue text.

Description

Triage 🩺
Please make sure these conditions are met
  • I have checked that this issue has not already been reported.
  • I have confirmed this bug exists on the latest version of scanpy.
  • (optional) I have confirmed this bug exists on the main branch of scanpy.
What happened?

The fifth code cell of the tutorial starts with the comment:

# mitochondrial genes, "MT-" for human, "Mt-" for mouse

when describing mitochondrial gene naming conventions. However, "Mt-" is a rat naming convention rather than a mouse convention. A naive user (like myself) might use adata.var_names.str.startswith("Mt-") to search for mouse mitochnodrial genes and find 0 hits (as I did).

A little troubleshooting revealed that "Mt" returns several gene matches in the mm10 genome I was using, so I went with that until I realized that none of those were actually mitochondrial genes and the actual mouse naming convention is "mt-". In fact, "Mt" matched many times more genes than exist in the mouse mitochondrial genome (apparently only 13 protein coding genes). I'm pretty sure the "mt-" prefix is used in most or all current reference genomes for mouse including GRCm39.

Image

It appears that the tutorial website stems from a different GitHub page, the issue applies to that website as well.

Also, a secondary issue might be the hemoglobin pattern suggested, following the upper-followed-by-lowercase pattern in the mitochondrial gene comment and applying that to the human hemoglobin search pattern leads to a non hemoglobin gene (Hbp1) being matched. But, the example page isn't really focused on mouse anyway so it maybe doesn't need to go into that much detail for every step.

Reproduction: easy to see the naming convention by searching each pattern in the mm10 or other reference genome for example in the search bar provided on the genome.ucsc.edu page. If you need a code example I had Claude generate one.

Attributions: I am grateful for scanpy contributors + for the tutorial. I got the correct pattern for mouse as well as hemoglobin pattern suggestion + help with the code example from Claude AI + Google. I wrote this issue myself with images from my code.

Sources:

Minimal code sample
# /// script
# requires-python = ">=3.12"
# dependencies = [
#   "scanpy@git+https://github.com/scverse/scanpy.git@main",
# ]
# ///
#
# This script automatically imports the development branch of scanpy to check for issues

"""The clustering tutorial says mouse mitochondrial genes start with "Mt-".
 
In the Ensembl GRCm38 (mm10) annotation, they start with lowercase "mt-",
so the tutorial's mouse prefix matches none of them.
"""
 
import gzip
import re
import urllib.request
 
# Ensembl release 102 is the last release on GRCm38 (mm10)
URL = "https://ftp.ensembl.org/pub/release-102/gtf/mus_musculus/Mus_musculus.GRCm38.102.gtf.gz"
 
var_names, mito = set(), set()
with urllib.request.urlopen(URL) as response, gzip.open(response, "rt") as gtf:
    for line in gtf:
        if line.startswith("#"):
            continue
        contig, _, feature, *_, attrs = line.split("\t", 8)
        if feature != "gene" or 'gene_biotype "protein_coding"' not in attrs:
            continue
        if match := re.search(r'gene_name "([^"]+)"', attrs):
            var_names.add(match[1])
            if contig == "MT":
                mito.add(match[1])
 
print(f"Protein-coding genes on chrMT ({len(mito)}): {sorted(mito)}")
for prefix in ("Mt-", "mt-"):
    hits = sum(name.startswith(prefix) for name in var_names)
    print(f'startswith("{prefix}"): {hits} matches out of {len(var_names)} protein-coding genes')
Error output
Versions

Warning: :1: FutureWarning: The function print_versions is deprecated and will be removed in the future. Use :func:print_header instead.

'1.12.4'
Dominant language
Python
Stars
2.6k
Forks
796
Avg merge
1d 4h
Merged PRs (30d)
22

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from scverse/scanpy

All issues in scverse/scanpy

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.