Add type hints to GRN plots; tidy FAQ formatting

docs/faq.md

@@ -1,16 +1,16 @@
 # Frequently Asked Questions
 
-## My commitment scores look inverted — stem/progenitor cells score low, differentiated cells score high, and in disease samples nearly all cell types are elevated. Is this a RegVelo bug?
+### Q1: My commitment scores look inverted — stem/progenitor cells score low, differentiated cells score high, and in disease samples nearly all cell types are elevated. Is this a RegVelo bug?
 
-Not necessarily. In most cases this reflects the inferred **velocity field**, not the
+**A:** Not necessarily. In most cases this reflects the inferred **velocity field**, not the
 commitment score itself. CellRank derives commitment probabilities from the velocity
 transition matrix, so a reversed or unreliable velocity field will directly produce
 unexpected commitment scores.
 
 Before concluding that RegVelo is at fault, validate whether the velocity field is
 reasonable.
 
-### How do I check whether the velocity field is the problem?
+#### How do I check whether the velocity field is the problem?
 
 Run one or more simpler velocity models on the same dataset and compare the velocity
 streams side by side with RegVelo:
@@ -34,7 +34,7 @@ trajectory, RegVelo generally won't either, because the underlying dynamics aren
 identifiable.
 ```
 
-### What could cause this?
+#### What could cause this?
 
 - The dataset is very sparse, making velocity estimation unreliable.
 - Transcriptional dynamics are weak or ambiguous, so RNA velocity can't robustly resolve
@@ -46,7 +46,7 @@ identifiable.
 In these cases the velocity field, and therefore the commitment score, may not match
 prior biological expectations.
 
-### What should I include when reporting this issue?
+#### What should I include when reporting this issue?
 
 - The biological system (in vivo, organoid, cell line, etc.)
 - Velocity stream plots from RegVelo, scVelo (stochastic and/or dynamical), and veloVI if

src/regvelo/plotting/_plot_TF_regulon.py

@@ -8,19 +8,20 @@
 import scanpy as sc
 import scvelo as scv
 import mplscience
+from anndata import AnnData
 import regvelo as rgv
 
 def plot_TF_regulon(
-    adata,
-    rgv_model,
-    cluster_key,
-    TF,
-    terminal_state_to_plot,
-    coef_targets,
-    coef_regulators,
-    n_hits=10,
-    device="cpu",
-):
+    adata: AnnData,
+    rgv_model: str,
+    cluster_key: str,
+    TF: str,
+    terminal_state_to_plot: str,
+    coef_targets: dict[str, pd.DataFrame],
+    coef_regulators: dict[str, pd.DataFrame],
+    n_hits: int = 10,
+    device: str = "cpu",
+) -> None:
     """Plot a TF's regulon ranking, regulatory network, and cell-resolved weights.
 
     Loads ``rgv_model``, builds the inferred GRN and the mixed GRN

src/regvelo/plotting/_plot_grn_weight.py

@@ -1,17 +1,24 @@
+from typing import TYPE_CHECKING, Sequence
+
 import numpy as np
 import pandas as pd
 import matplotlib.pyplot as plt
 import seaborn as sns
 import scvelo as scv
 import mplscience
+from anndata import AnnData
 import regvelo as rgv
 
+if TYPE_CHECKING:
+    from regvelo import REGVELOVI
+
 def plot_grn_weight(
-    adata,
-    vae,
-    TF,
-    target_list,
-    device="cpu"):
+    adata: AnnData,
+    vae: "REGVELOVI",
+    TF: str,
+    target_list: Sequence[str],
+    device: str = "cpu",
+) -> None:
 
     """Plot cell-resolved regulatory weights for one TF against several targets.