examples/varcode-quick_start.ipynb is a Python 3.4 notebook that no longer runs; notes/ holds duplicate plans and data build scripts

Open
  • Is something wrong?
#694 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
44/100
Issue type
Refactor
Clarity
Clearly specified
Activity status
Active
Tech stack
python
Domain
documentation, testing, tooling

Research direction

Start by comparing examples/varcode-quick_start.ipynb with docs/getting_started.md, then inspect notes/README.md and the references to notes/build_genetic_code_data.py and notes/build_native_reference_fixtures.py in varcode/effects/codon_tables.py and tests/data/native_references/README.md. The issue suggests deleting or rewriting the notebook, relocating the build scripts, removing obsolete plans, and listing remaining notes. Done means those choices are reflected consistently in files and references.

Written by the indexing model from the issue text.

Description

Problem

Two places in the repository hold stale material that nothing links to.

  1. examples/varcode-quick_start.ipynb is a Python 3.4 notebook that no longer runs. It loads files from ../test/data/, a directory that does not exist (the fixtures are in tests/data/). It uses the deprecated Variant(..., ensembl=...) keyword, and its saved outputs show Biopython Seq(..., SingleLetterAlphabet()) objects and Biopython warnings. Varcode no longer uses Biopython (#293). Nothing in the README, the docs or the tests refers to it, and MANIFEST.in leaves it out of the sdist. A user browsing examples/ finds this notebook before docs/getting_started.md.
  2. notes/ mixes finished per-issue plans with scripts that generate shipped data. notes/README.md names only 3 of its 18 files. orf-layer-design.md and uorf_implementation_plan.md are byte-identical. Plans for closed issues (python-311-plan.md for #607, pr-test-concurrency-plan.md for #604, and others) remain. notes/build_genetic_code_data.py builds the packaged varcode/data/genetic_codes.json (cited from varcode/effects/codon_tables.py:16), and notes/build_native_reference_fixtures.py builds test fixtures (cited from tests/data/native_references/README.md:69). Both are maintained build tools, not notes.

Evidence

Read at d1b4280.

  • Notebook metadata: kernelspec "display_name": "Python 2", language_info.version 3.4.3. Cells: Variant(contig=7, start=140453136, ref="A", alt="T", ensembl=ensembl_grch37), load_maf("../test/data/tcga_ov.head.maf"), load_vcf("../test/data/somatic_hg19_14muts.vcf").
  • grep -r quick_start finds no references outside the file.
  • cmp notes/orf-layer-design.md notes/uorf_implementation_plan.md reports no difference.
  • notes/README.md: "Files: development_audit.md (2026-09-24 quality audit), orf-layer-design.md and uorf_implementation_plan.md (identical ORF-layer design notes)."

Suggested fix

  • Delete the notebook. docs/getting_started.md covers the same workflow. Alternatively, rewrite it as a short examples/quick_start.py that runs against tests/data/ and add it to the test that already runs examples/vcf_header_usage.py.
  • Move build_genetic_code_data.py and build_native_reference_fixtures.py to a scripts/ (or tools/) directory and update the two references.
  • Delete uorf_implementation_plan.md and the plans whose issues are closed (their content lives in the PRs and CHANGELOG), and make notes/README.md list what remains.

https://claude.ai/code/session_01JHJhwj29oDqoeu7TYd34Pi

Dominant language
Python
Stars
88
Forks
28
Avg merge
3h 10m
Merged PRs (30d)
53

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 openvax/varcode

All issues in openvax/varcode

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.