bsvae 0.2.0__tar.gz → 0.2.1__tar.gz

{bsvae-0.2.0 → bsvae-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bsvae
-Version: 0.2.0
+Version: 0.2.1
 Summary: Biologically structured variational autoencoder for gene expression data with PPI priors.
 License: GPL-3.0-only
 License-File: LICENSE
@@ -136,10 +136,15 @@ bsvae-networks export-latents \
     --output results/exp1/latents.h5ad
 ```
 
-The extractor writes adjacency matrices, edge lists, and optional heatmaps for
-each requested method. By default the decoder-loading cosine similarity
-(``w_similarity``) is computed; add other methods with ``--methods``. Latent exports include per-sample ``mu`` and
-``logvar`` as tidy CSV or AnnData files.
+The extractor writes **sparse NPZ** adjacency matrices and **Parquet** edge
+lists by default (``--sparse`` and ``--compress`` are on unless disabled with
+``--no-sparse``/``--no-compress``). When ``--threshold 0`` with sparse output,
+an adaptive threshold is computed from ``--target-sparsity`` (default 0.01 =
+top 1% of edges). Use ``--quantize`` (default ``int8``) to reduce adjacency
+size. Legacy dense CSV/TSV/NPY outputs are available only with ``--no-sparse``
+or explicit legacy formats. By default the decoder-loading cosine similarity
+(``w_similarity``) is computed; add other methods with ``--methods``. Latent
+exports include per-sample ``mu`` and ``logvar`` as tidy CSV or AnnData files.
 
 ---
 

{bsvae-0.2.0 → bsvae-0.2.1}/README.md

@@ -104,10 +104,15 @@ bsvae-networks export-latents \
     --output results/exp1/latents.h5ad
 ```
 
-The extractor writes adjacency matrices, edge lists, and optional heatmaps for
-each requested method. By default the decoder-loading cosine similarity
-(``w_similarity``) is computed; add other methods with ``--methods``. Latent exports include per-sample ``mu`` and
-``logvar`` as tidy CSV or AnnData files.
+The extractor writes **sparse NPZ** adjacency matrices and **Parquet** edge
+lists by default (``--sparse`` and ``--compress`` are on unless disabled with
+``--no-sparse``/``--no-compress``). When ``--threshold 0`` with sparse output,
+an adaptive threshold is computed from ``--target-sparsity`` (default 0.01 =
+top 1% of edges). Use ``--quantize`` (default ``int8``) to reduce adjacency
+size. Legacy dense CSV/TSV/NPY outputs are available only with ``--no-sparse``
+or explicit legacy formats. By default the decoder-loading cosine similarity
+(``w_similarity``) is computed; add other methods with ``--methods``. Latent
+exports include per-sample ``mu`` and ``logvar`` as tidy CSV or AnnData files.
 
 ---
 

{bsvae-0.2.0 → bsvae-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "bsvae"
-version = "0.2.0"  # dynamically resolved by poetry-dynamic-versioning
+version = "0.2.1"  # dynamically resolved by poetry-dynamic-versioning
 description = "Biologically structured variational autoencoder for gene expression data with PPI priors."
 readme = "README.md"
 authors = ["Kynon J Benjamin <kj.benjamin90@gmail.com>"]

{bsvae-0.2.0 → bsvae-0.2.1}/src/bsvae/networks/cli.py

@@ -20,8 +20,11 @@ from bsvae.networks.extract_networks import (
 from bsvae.latent.latent_export import extract_latents, save_latents
 from bsvae.networks.module_extraction import (
     compute_module_eigengenes,
+    leiden_modules_from_graph,
     leiden_modules,
     load_adjacency,
+    optimize_resolution_modularity,
+    prepare_leiden_graph,
     save_eigengenes,
     save_modules,
     spectral_modules,
@@ -104,7 +107,64 @@ def build_parser() -> argparse.ArgumentParser:
     module_parser.add_argument("--expr", required=True, help="Expression matrix (genes × samples) for eigengenes")
     module_parser.add_argument("--output-dir", required=True, help="Directory to write module outputs")
     module_parser.add_argument("--cluster-method", choices=["leiden", "spectral"], default="leiden")
-    module_parser.add_argument("--resolution", type=float, default=1.0, help="Leiden resolution parameter")
+    module_parser.add_argument("--resolution", type=float, default=1.0, help="Leiden resolution parameter (ignored if --resolutions or --resolution-auto is used)")
+    module_parser.add_argument(
+        "--resolutions",
+        type=float,
+        nargs="+",
+        help="Multiple resolution values for sweep (e.g., --resolutions 1.0 2.0 5.0 10.0). "
+        "Creates separate output subdirectories for each resolution.",
+    )
+    module_parser.add_argument(
+        "--resolution-auto",
+        action="store_true",
+        help="Automatically select resolution by maximizing modularity (no ground truth needed). "
+        "Can be combined with --resolutions to also run fixed resolutions.",
+    )
+    module_parser.add_argument(
+        "--resolution-min",
+        type=float,
+        default=0.5,
+        help="Minimum resolution for auto-optimization search (default: 0.5)",
+    )
+    module_parser.add_argument(
+        "--resolution-max",
+        type=float,
+        default=15.0,
+        help="Maximum resolution for auto-optimization search (default: 15.0)",
+    )
+    module_parser.add_argument(
+        "--resolution-steps",
+        type=int,
+        default=30,
+        help="Number of resolution values to test during auto-optimization (default: 30). "
+        "Ignored when --resolution-two-phase is used.",
+    )
+    module_parser.add_argument(
+        "--resolution-two-phase",
+        action="store_true",
+        help="Use memory-efficient two-phase search: coarse sweep to find ballpark, "
+        "then fine sweep in narrower range. Reduces peak memory usage.",
+    )
+    module_parser.add_argument(
+        "--resolution-coarse-steps",
+        type=int,
+        default=10,
+        help="Number of steps in coarse phase of two-phase search (default: 10)",
+    )
+    module_parser.add_argument(
+        "--resolution-fine-steps",
+        type=int,
+        default=10,
+        help="Number of steps in fine phase of two-phase search (default: 10)",
+    )
+    module_parser.add_argument(
+        "--resolution-fine-range",
+        type=float,
+        default=0.3,
+        help="Fraction of original range for fine search, centered on best coarse "
+        "resolution (default: 0.3 = 30%% of original range)",
+    )
     module_parser.add_argument("--n-clusters", type=int, help="Number of clusters for spectral clustering")
     module_parser.add_argument("--n-components", type=int, help="Number of eigenvectors for spectral clustering")
     module_parser.add_argument("--batch-size", type=int, default=128)
@@ -123,6 +183,11 @@ def build_parser() -> argparse.ArgumentParser:
         default="w_similarity",
         help="Network extraction method to run when computing adjacency (default: w_similarity)",
     )
+    module_parser.add_argument(
+        "--progress",
+        action="store_true",
+        help="Show progress bar during resolution auto-optimization",
+    )
 
     latent_analysis_parser = subparsers.add_parser("latent-analysis", help="Sample-level latent space analysis.")
     latent_analysis_parser.add_argument("--model-path", required=True, help="Directory with specs.json/model.pt or checkpoint path")
@@ -201,6 +266,94 @@ def _load_covariates(path: str, sample_ids: Sequence[str]) -> pd.DataFrame:
     return df
 
 
+def _run_single_clustering(
+    adjacency_df: pd.DataFrame,
+    expr_df: pd.DataFrame,
+    output_dir: Path,
+    resolution: float,
+    adjacency_mode: str,
+    cluster_method: str,
+    n_clusters: Optional[int],
+    n_components: Optional[int],
+    logger: logging.Logger,
+    resolution_label: Optional[str] = None,
+    graph=None,
+    genes: Optional[Sequence[str]] = None,
+    compute_eigengenes: bool = True,
+    precomputed_modules: Optional[pd.Series] = None,
+) -> int:
+    """Run clustering at a single resolution and save results.
+
+    Parameters
+    ----------
+    precomputed_modules:
+        Optional pre-computed module assignments (e.g., from resolution
+        optimization) to avoid redundant Leiden computation.
+
+    Returns the number of modules detected.
+    """
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    if precomputed_modules is not None:
+        modules = precomputed_modules
+        logger.info(
+            "Using precomputed modules (resolution=%.3f, %d modules)",
+            resolution,
+            modules.nunique(),
+        )
+    elif cluster_method == "leiden":
+        logger.info(
+            "Running Leiden clustering (resolution=%.3f, adjacency_mode=%s)",
+            resolution,
+            adjacency_mode,
+        )
+        if graph is not None and genes is not None:
+            modules = leiden_modules_from_graph(graph, genes, resolution)
+        else:
+            modules = leiden_modules(
+                adjacency_df,
+                resolution=resolution,
+                adjacency_mode=adjacency_mode,
+            )
+    else:
+        modules = spectral_modules(
+            adjacency_df,
+            n_clusters=n_clusters,
+            n_components=n_components,
+            adjacency_mode=adjacency_mode,
+        )
+
+    n_modules = modules.nunique()
+
+    save_modules(modules, output_dir / "modules.csv")
+    if compute_eigengenes:
+        eigengenes = compute_module_eigengenes(expr_df, modules)
+        save_eigengenes(eigengenes, output_dir / "eigengenes.csv")
+    else:
+        logger.info("Skipping eigengene computation for resolution %.3f", resolution)
+
+    # Save resolution metadata for reproducibility
+    if cluster_method == "leiden":
+        metadata = {
+            "resolution": resolution,
+            "resolution_label": resolution_label or str(resolution),
+            "n_modules": n_modules,
+            "adjacency_mode": adjacency_mode,
+        }
+        metadata_path = output_dir / "clustering_metadata.json"
+        import json
+        with open(metadata_path, "w") as f:
+            json.dump(metadata, f, indent=2)
+
+    logger.info(
+        "Resolution %.3f: %d modules detected, saved to %s",
+        resolution,
+        n_modules,
+        output_dir,
+    )
+    return n_modules
+
+
 def handle_extract_modules(args, logger: logging.Logger) -> None:
     if not args.adjacency and (not args.model_path or not args.dataset):
         raise ValueError("Either --adjacency or both --model-path and --dataset must be provided")
@@ -235,26 +388,100 @@ def handle_extract_modules(args, logger: logging.Logger) -> None:
     # Convert adjacency to DataFrame with gene labels so clustering functions
     # return modules indexed by gene name instead of numeric indices
     adjacency_df = pd.DataFrame(adjacency, index=genes, columns=genes)
-
+    expr_df = load_expression(args.expr)
+    leiden_graph = None
+    leiden_genes = None
     if args.cluster_method == "leiden":
-        logger.info(
-            "Running Leiden clustering (resolution=%.2f, adjacency_mode=%s)",
-            args.resolution,
-            args.adjacency_mode,
-        )
-        modules = leiden_modules(
+        leiden_graph, leiden_genes = prepare_leiden_graph(
             adjacency_df,
-            resolution=args.resolution,
             adjacency_mode=args.adjacency_mode,
         )
-    else:
-        modules = spectral_modules(adjacency_df, n_clusters=args.n_clusters, n_components=args.n_components)
 
-    expr_df = load_expression(args.expr)
-    eigengenes = compute_module_eigengenes(expr_df, modules)
+    # Determine which resolutions to run
+    # (resolution, label, output_dir, precomputed_modules)
+    resolutions_to_run: List[tuple[float, str, Path, Optional[pd.Series]]] = []
+
+    # Handle resolution auto-optimization
+    if args.resolution_auto and args.cluster_method == "leiden":
+        two_phase = getattr(args, "resolution_two_phase", False)
+        if two_phase:
+            logger.info("Running two-phase resolution auto-optimization (modularity-based)")
+        else:
+            logger.info("Running resolution auto-optimization (modularity-based)")
+        best_res, best_qual, auto_modules = optimize_resolution_modularity(
+            adjacency_df,
+            adjacency_mode=args.adjacency_mode,
+            resolution_min=args.resolution_min,
+            resolution_max=args.resolution_max,
+            n_steps=args.resolution_steps,
+            graph=leiden_graph,
+            return_modules=True,
+            progress=getattr(args, "progress", False),
+            two_phase=two_phase,
+            coarse_steps=getattr(args, "resolution_coarse_steps", 10),
+            fine_steps=getattr(args, "resolution_fine_steps", 10),
+            fine_range_fraction=getattr(args, "resolution_fine_range", 0.3),
+        )
+        auto_output = Path(args.output_dir) / "res_auto"
+        resolutions_to_run.append((best_res, "auto", auto_output, auto_modules))
+        logger.info("Auto-selected resolution: %.3f (modularity=%.4f)", best_res, best_qual)
+
+    # Handle resolution sweep
+    if args.resolutions and args.cluster_method == "leiden":
+        for res in args.resolutions:
+            # Format resolution for directory name (e.g., 1.0 -> "1.0", 10.0 -> "10.0")
+            res_label = f"{res:.1f}".replace(".", "_")
+            res_output = Path(args.output_dir) / f"res_{res_label}"
+            resolutions_to_run.append((res, f"fixed_{res}", res_output, None))
+
+    # If no sweep or auto, use single resolution (original behavior)
+    if not resolutions_to_run:
+        resolutions_to_run.append((args.resolution, "single", Path(args.output_dir), None))
+
+    # Run clustering for each resolution
+    results_summary = []
+    multiple_resolutions = len(resolutions_to_run) > 1
+    for resolution, label, output_dir, precomputed_modules in resolutions_to_run:
+        compute_eigengenes = not (label == "auto" and multiple_resolutions)
+        n_modules = _run_single_clustering(
+            adjacency_df=adjacency_df,
+            expr_df=expr_df,
+            output_dir=output_dir,
+            resolution=resolution,
+            adjacency_mode=args.adjacency_mode,
+            cluster_method=args.cluster_method,
+            n_clusters=args.n_clusters,
+            n_components=args.n_components,
+            logger=logger,
+            resolution_label=label,
+            graph=leiden_graph,
+            genes=leiden_genes,
+            compute_eigengenes=compute_eigengenes,
+            precomputed_modules=precomputed_modules,
+        )
+        results_summary.append({
+            "resolution": resolution,
+            "label": label,
+            "n_modules": n_modules,
+            "output_dir": str(output_dir),
+        })
+
+    # Save summary if multiple resolutions were run
+    if len(resolutions_to_run) > 1:
+        import json
+        summary_path = Path(args.output_dir) / "resolution_sweep_summary.json"
+        with open(summary_path, "w") as f:
+            json.dump(results_summary, f, indent=2)
+        logger.info("Resolution sweep summary saved to %s", summary_path)
+
+        # Also save as TSV for easy viewing
+        summary_df = pd.DataFrame(results_summary)
+        summary_df.to_csv(
+            Path(args.output_dir) / "resolution_sweep_summary.tsv",
+            sep="\t",
+            index=False,
+        )
 
-    save_modules(modules, Path(args.output_dir) / "modules.csv")
-    save_eigengenes(eigengenes, Path(args.output_dir) / "eigengenes.csv")
     logger.info("Module extraction complete; outputs saved to %s", args.output_dir)