scverse / scverse/mantispy

Replace dict-literal result cells in the tutorials

Open
#46 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation
Dominant language
Python
Stars
8
Forks
0
Avg merge
12h 39m
Merged PRs (30d)
20

Description

Problem

25 code cells across the tutorials end in a hand-assembled dict literal used to print labelled
numbers. Examples:

{"flagged": sorted(flagged), "injected": sorted(truth["bad_images"])}
{"correlation with plate row, before": round(float(before), 3), "after": round(float(after), 3)}
{"constant features kept": [...], "duplicate pairs left intact": [...]}

Counts per notebook: 00 3, 02 1, 03 1, 04 1, 05 2, 06 3, 07 4, 08 4, 09 5, 10 1.

Reasoning

Two problems.

The output is not reusable. A reader cannot sort it, filter it, plot it or paste it into their own
analysis. Every one of these numbers came from a DataFrame or an array that was more useful before it
was flattened into a dict of prose keys.

The pattern is also the main reason the pages read as generated rather than written. No tutorial in
scanpy, squidpy, decoupler or pertpy prints results this way.

Most of these cells are also assertions rather than demonstrations: they compare a result against
uns["mantispy"]["truth"] to show the function recovered an injected effect. That is a unit test.
It belongs in tests/, and several equivalents are already there.

Proposed fix

For each of the 25 cells:

  • If it demonstrates a result, end the cell in a DataFrame, a figure or an object repr
  • If it asserts correctness against injected ground truth, move the check to tests/ and replace
    the cell with the figure or table a reader would actually look at
  • Keep at most two ground-truth comparisons in the whole documentation, on Examples pages where
    "here is the answer, verified" is the point of the page

Depends on #44 and #45. Take one
notebook per agent.

Contributor guide

Open the contributing guide

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.

Research direction

Review dependencies #44 and #45, then choose one of the listed tutorial notebooks and inspect its dict-literal cells alongside equivalent checks in tests/. Replace demonstration cells with a DataFrame, figure, or object repr, move ground-truth assertions to tests/, and keep at most two documented comparisons overall.

Written by the indexing model from the issue text.

Assessment

Tech stack
jupyter-notebook, python
Domain
documentation, testing
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
65/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.