de: clarify model choice, design matrices, and result interpretation#60
Merged
Conversation
Addresses several of the open narrative TODOs in scverse/pertpy#615 without restructuring the notebook: - Expand the intro to spell out the three families of DE models in pertpy (simple tests, pseudobulk + GLM, generic linear models) and when to pick which. - Replace the partial "<!-- ... -->" lead-in to the edgeR section with a short explainer of design matrices and Wilkinson-formula syntax, using the model fitted right below as the running example. - Replace the one-liner before `test_contrasts` with a brief contrast primer so readers understand what `contrast()` actually returns. - Add a result-table interpretation cell that names every column the reader will see (`log_fc`, `adj_p_value`, ...) and the standard significance rule of thumb. - Point readers to decoupler's pathway-enrichment workflow as the natural next step after producing a ranked gene table. No code cells were modified; existing outputs are untouched. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Check out this pull request on See visual diffs & provide feedback on Jupyter Notebooks. Powered by ReviewNB |
Cleanup pass on the previous narrative additions:
- Every sentence in every new markdown cell now lives on its own line,
matching the source-prose convention used elsewhere in this repo.
- pertpy class references switch from full readthedocs URLs to MyST
cross-references ({class}`~pertpy.tools.EdgeR`, etc.) so the links
stay valid as the API moves and render with proper styling.
- {meth}`~pertpy.tools.EdgeR.contrast` is used in place of the inline
signature.
- decoupler references stay as plain URLs / `code` spans for now —
decoupler's published objects.inv currently contains no py: entries,
so intersphinx targets there would fail at build time.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sweep across the tutorials replacing readthedocs URLs with MyST
cross-references wherever a populated objects.inv exists for the target.
- differential_gene_expression.ipynb: switch decoupler enrichment
pointers to {mod}/{func}/{any} refs (decoupler exposes its methods
as py:data, so `{any}` is used for `decoupler.mt.ulm`).
- distance_tests.ipynb, distances.ipynb,
expression_prediction_evaluation.ipynb: replace pertpy.tools.Distance
URLs with {class}`~pertpy.tools.Distance`.
- distances.ipynb, expression_prediction_evaluation.ipynb: replace
cross-tutorial readthedocs URLs (distance_tests, distances,
scgen_perturbation_prediction) with relative {doc} refs so they no
longer go stale when paths/versions move.
- milo.ipynb: MuData URL -> {class}`~mudata.MuData`.
Pages without a clean intersphinx target (perturbation_space anchor,
statsmodels example_formulas page, ete3 project homepage) are left as
plain URL links.
Requires the matching decoupler entry in pertpy's docs/conf.py
intersphinx_mapping (sent in companion pertpy PR).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The top-level `decoupler` module is not registered as a py:module entry
in decoupler's objects.inv (only the submodules decoupler.mt, .op, etc.
are), so `{mod}\`decoupler\`` would render as a broken target. The four
specific function refs ({any}/{func}\`decoupler.mt.ulm\` etc.) still
resolve through the new intersphinx mapping in the pertpy companion PR.
Verified by parsing https://decoupler.readthedocs.io/en/latest/objects.inv
and checking every {role}\`target\` in the touched notebooks.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Zethson
added a commit
to scverse/pertpy
that referenced
this pull request
May 25, 2026
…sweep Points docs/tutorials/notebooks at scverse/pertpy-tutorials@7ae61d5 (merge commit of scverse/pertpy-tutorials#60), which contains the companion DE narrative additions and the intersphinx sweep that consumes the new decoupler entry added to docs/conf.py in this PR. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Zethson
added a commit
to scverse/pertpy
that referenced
this pull request
May 25, 2026
* docs: refresh DE docstring pseudobulk examples (#615) The example code in EdgeR/PyDESeq2 docstrings still called PseudobulkSpace.compute() with the long-removed `min_cells` and `min_counts` parameters, so anyone copy-pasting the example hit a TypeError. Replace each example with the current PseudobulkSpace.compute(target_col=..., groups_col=..., layer_key=..., mode=...) call that actually runs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: add decoupler to intersphinx_mapping Lets MyST/sphinx cross-references like {func}`~decoupler.op.collectri` in the DE tutorial resolve to decoupler's docs instead of dropping to plain text. decoupler publishes its objects.inv at decoupler.readthedocs.io (not decoupler-py.readthedocs.io, which has an empty inventory). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: bump tutorials submodule to pick up DE narrative + intersphinx sweep Points docs/tutorials/notebooks at scverse/pertpy-tutorials@7ae61d5 (merge commit of scverse/pertpy-tutorials#60), which contains the companion DE narrative additions and the intersphinx sweep that consumes the new decoupler entry added to docs/conf.py in this PR. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Two-part cleanup of the tutorials, both addressing open items from scverse/pertpy#615:
differential_gene_expression.ipynb— narrative improvements<!-- … -->lead-in to the edgeR section with a short explainer of design matrices and Wilkinson-formula syntax, using the~ Efficacy + Treatmentmodel fitted right below as the running example.test_contrastswith a brief contrast primer so readers understand whatcontrast()actually returns.log_fc,adj_p_value, …) and the standard significance rule of thumb.Intersphinx sweep across the tutorials
Replace plain readthedocs URLs with MyST cross-references wherever a populated
objects.invexists for the target:differential_gene_expression.ipynb:{class}~pertpy.tools.{TTest,WilcoxonTest,EdgeR,PyDESeq2,Statsmodels}, `{meth}`~pertpy.tools.EdgeR.contrast{mod}statsmodels, `{any}`decoupler.mt.ulm{func}~decoupler.op.{collectri,progeny,hallmark}``.distance_tests.ipynb,distances.ipynb,expression_prediction_evaluation.ipynb:{class}~pertpy.tools.Distancefor API URLs and `{doc}`./milo.ipynb:{class}~mudata.MuData``.Pages without a clean intersphinx target are left as plain URLs (statsmodels'
example_formulas.html, the ete3 project homepage, an anchor intopertpy/api/api.html).Verified every introduced cross-ref against the live
objects.invof pertpy/decoupler/statsmodels/mudata (21 refs, 0 misses).Depends on the companion pertpy PR scverse/pertpy#996 which adds
decouplertointersphinx_mapping.Refs: scverse/pertpy#615
Test plan
prek run --files differential_gene_expression.ipynb distance_tests.ipynb distances.ipynb expression_prediction_evaluation.ipynb milo.ipynb— prettier/ruff all pass.{role}target`` references parsed and matched against the right intersphinx inventory.🤖 Generated with Claude Code