moducomp 0.7.9__tar.gz → 0.7.10__tar.gz

{moducomp-0.7.9 → moducomp-0.7.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: moducomp
-Version: 0.7.9
+Version: 0.7.10
 Summary: moducomp: metabolic module completeness and complementarity for microbiomes.
 Keywords: bioinformatics,microbiome,metabolic,kegg,genomics
 Author-email: "Juan C. Villada" <jvillada@lbl.gov>
@@ -37,6 +37,7 @@ Project-URL: Repository, https://github.com/NeLLi-team/moducomp
 - Generation of complementarity reports highlighting modules completed through genome partnerships.
 - Tracks and reports the actual proteins that are responsible for the completion of the module in the combination of N genomes.
 - **Automatic resource monitoring** with timestamped logs tracking CPU usage, memory consumption, and runtime for reproducibility.
+- **Consistent logging to stdout/stderr** with a per-command resource summary emitted at the end of each run.
 
 ## Installation (Recommended)
 
@@ -107,6 +108,82 @@ You should see the command line help without errors.
 
 `moducomp` provides two main commands: `pipeline` and `analyze-ko-matrix`. You can run these commands using Pixi tasks defined in `pyproject.toml` or directly within the Pixi environment.
 
+### Pipeline overview
+
+The diagram below shows the main stages executed by ModuComp.
+
+```mermaid
+graph TD
+    A([Start run]) --> B[Initialize logging and resource monitoring]
+    B --> C{Input type}
+    C -->|pipeline| D[Validate genome directory]
+    C -->|analyze-ko-matrix| H[Load existing KO matrix]
+    D --> E[Prepare genomes: adapt headers or copy to tmp]
+    E --> F[Merge genomes into single FAA]
+    F --> G[Run eggNOG-mapper (if needed)]
+    G --> H[Create KO matrix (`kos_matrix.csv`)]
+    H --> I[Convert KO matrix to KPCT input]
+    I --> J[Run KPCT (parallel with fallback)]
+    J --> K[Create module completeness matrix]
+    K --> L{Complementarity requested?}
+    L -->|Yes| M[Generate complementarity report(s)]
+    L -->|No| N[Skip]
+    M --> O[Write outputs + logs]
+    N --> O
+    O --> P[Optional cleanup of `tmp/`]
+    P --> Q([Pipeline complete])
+```
+
+### CLI options and defaults
+
+This section lists all CLI options implemented today, along with their default values.
+
+#### `pipeline` command (positional args: `genomedir`, `savedir`)
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `--ncpus`, `-n` | `16` | Number of CPU cores to use for eggNOG-mapper and KPCT. |
+| `--calculate-complementarity`, `-c` | `0` | Complementarity size to compute (0 disables). |
+| `--adapt-headers/--no-adapt-headers` | `false` | Adapt FASTA headers to `genome|protein_N`. |
+| `--del-tmp/--keep-tmp` | `true` | Delete temporary files after completion. |
+| `--lowmem/--fullmem` (`--low-mem/--full-mem`) | `fullmem` | Run eggNOG-mapper without `--dbmem` to reduce RAM. |
+| `--verbose/--quiet` | `false` | Enable verbose progress output. |
+| `--log-level`, `-l` | `INFO` | Logging level: `DEBUG`, `INFO`, `WARNING`, `ERROR`. |
+| `--eggnog-data-dir` | `EGGNOG_DATA_DIR` | Path to eggNOG-mapper data (sets `EGGNOG_DATA_DIR`). |
+
+#### `test` command (bundled test genomes)
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `--output-dir`, `-o` | `output_test_moducomp_<DATETIME>` | Output directory for test run. |
+| `--ncpus`, `-n` | `2` | CPU cores for the test run. |
+| `--calculate-complementarity`, `-c` | `2` | Complementarity size to compute (0 disables). |
+| `--adapt-headers/--no-adapt-headers` | `false` | Adapt FASTA headers before the test. |
+| `--del-tmp/--keep-tmp` | `true` | Delete temporary files after the test completes. |
+| `--lowmem/--fullmem` (`--low-mem/--full-mem`) | `lowmem` | Low-memory mode is the default for tests. |
+| `--verbose/--quiet` | `verbose` | Verbose output is the default for tests. |
+| `--log-level`, `-l` | `INFO` | Logging level: `DEBUG`, `INFO`, `WARNING`, `ERROR`. |
+| `--eggnog-data-dir` | `EGGNOG_DATA_DIR` | Path to eggNOG-mapper data (sets `EGGNOG_DATA_DIR`). |
+
+#### `analyze-ko-matrix` command (positional args: `kos_matrix`, `savedir`)
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `--calculate-complementarity`, `-c` | `0` | Complementarity size to compute (0 disables). |
+| `--kpct-outprefix` | `output_give_completeness` | Prefix for KPCT output files. |
+| `--del-tmp/--keep-tmp` | `true` | Delete temporary files after completion. |
+| `--ncpus`, `-n` | `16` | CPU cores for KPCT parallel processing. |
+| `--verbose/--quiet` | `false` | Enable verbose progress output. |
+| `--log-level`, `-l` | `INFO` | Logging level: `DEBUG`, `INFO`, `WARNING`, `ERROR`. |
+
+#### `download-eggnog-data` command
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `--eggnog-data-dir` | `${XDG_DATA_HOME:-~/.local/share}/moducomp/eggnog` | Destination for eggNOG-mapper data (sets `EGGNOG_DATA_DIR`). |
+| `--log-level`, `-l` | `INFO` | Logging level: `DEBUG`, `INFO`, `WARNING`, `ERROR`. |
+| `--verbose/--quiet` | `verbose` | Stream downloader output to the console. |
+
 ### Performance and parallel processing
 
 `moducomp` includes **parallel processing capabilities** for the KPCT (KEGG Pathways Completeness Tool) analysis, which can significantly improve performance for large datasets:
@@ -166,7 +243,7 @@ moducomp pipeline \
     # Optional flags:
     # --lowmem/--fullmem          # Optional: Use low-mem if you have less than 64GB of RAM (default is full mem)
     # --adapt-headers             # If your FASTA headers need modification
-    # --del-tmp                   # To delete temporary files
+    # --del-tmp/--keep-tmp        # Delete or keep temporary files
     # --eggnog-data-dir /path     # If EGGNOG_DATA_DIR is not set
     # --verbose                   # Enable verbose output with detailed progress information
 ```
@@ -185,7 +262,7 @@ moducomp analyze-ko-matrix \
     --calculate-complementarity <N>  # 0 to disable, 2 for 2-member, 3 for 3-member complementarity.
 
     # Optional flags:
-    # --del-tmp false
+    # --keep-tmp                  # Keep temporary files
     # --verbose                   # Enable verbose output with detailed progress information
 ```
 
@@ -229,7 +306,7 @@ moducomp pipeline ./genomes ./output_lowmem --ncpus 8 --lowmem --calculate-compl
 - **`module_completeness.tsv`**: Module completeness scores for individual genomes and combinations
 - **`module_completeness_complementarity_Nmember.tsv`**: Complementarity reports (if requested)
 - **`logs/resource_usage_YYYYMMDD_HHMMSS.log`**: Resource monitoring log with CPU, memory, and runtime metrics for reproducibility
-- **`logs/moducomp.log`**: Detailed pipeline execution log
+- **`logs/moducomp.log`**: Detailed pipeline execution log with a per-command resource summary at the end of the run
 
 ## Citation
 Villada, JC. & Schulz, F. (2025). Assessment of metabolic module completeness of genomes and metabolic complementarity in microbiomes with `moducomp` . `moducomp` (v0.5.1) Zenodo. https://doi.org/10.5281/zenodo.16116092

{moducomp-0.7.9 → moducomp-0.7.10}/README.md

@@ -12,6 +12,7 @@
 - Generation of complementarity reports highlighting modules completed through genome partnerships.
 - Tracks and reports the actual proteins that are responsible for the completion of the module in the combination of N genomes.
 - **Automatic resource monitoring** with timestamped logs tracking CPU usage, memory consumption, and runtime for reproducibility.
+- **Consistent logging to stdout/stderr** with a per-command resource summary emitted at the end of each run.
 
 ## Installation (Recommended)
 
@@ -82,6 +83,82 @@ You should see the command line help without errors.
 
 `moducomp` provides two main commands: `pipeline` and `analyze-ko-matrix`. You can run these commands using Pixi tasks defined in `pyproject.toml` or directly within the Pixi environment.
 
+### Pipeline overview
+
+The diagram below shows the main stages executed by ModuComp.
+
+```mermaid
+graph TD
+    A([Start run]) --> B[Initialize logging and resource monitoring]
+    B --> C{Input type}
+    C -->|pipeline| D[Validate genome directory]
+    C -->|analyze-ko-matrix| H[Load existing KO matrix]
+    D --> E[Prepare genomes: adapt headers or copy to tmp]
+    E --> F[Merge genomes into single FAA]
+    F --> G[Run eggNOG-mapper (if needed)]
+    G --> H[Create KO matrix (`kos_matrix.csv`)]
+    H --> I[Convert KO matrix to KPCT input]
+    I --> J[Run KPCT (parallel with fallback)]
+    J --> K[Create module completeness matrix]
+    K --> L{Complementarity requested?}
+    L -->|Yes| M[Generate complementarity report(s)]
+    L -->|No| N[Skip]
+    M --> O[Write outputs + logs]
+    N --> O
+    O --> P[Optional cleanup of `tmp/`]
+    P --> Q([Pipeline complete])
+```
+
+### CLI options and defaults
+
+This section lists all CLI options implemented today, along with their default values.
+
+#### `pipeline` command (positional args: `genomedir`, `savedir`)
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `--ncpus`, `-n` | `16` | Number of CPU cores to use for eggNOG-mapper and KPCT. |
+| `--calculate-complementarity`, `-c` | `0` | Complementarity size to compute (0 disables). |
+| `--adapt-headers/--no-adapt-headers` | `false` | Adapt FASTA headers to `genome|protein_N`. |
+| `--del-tmp/--keep-tmp` | `true` | Delete temporary files after completion. |
+| `--lowmem/--fullmem` (`--low-mem/--full-mem`) | `fullmem` | Run eggNOG-mapper without `--dbmem` to reduce RAM. |
+| `--verbose/--quiet` | `false` | Enable verbose progress output. |
+| `--log-level`, `-l` | `INFO` | Logging level: `DEBUG`, `INFO`, `WARNING`, `ERROR`. |
+| `--eggnog-data-dir` | `EGGNOG_DATA_DIR` | Path to eggNOG-mapper data (sets `EGGNOG_DATA_DIR`). |
+
+#### `test` command (bundled test genomes)
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `--output-dir`, `-o` | `output_test_moducomp_<DATETIME>` | Output directory for test run. |
+| `--ncpus`, `-n` | `2` | CPU cores for the test run. |
+| `--calculate-complementarity`, `-c` | `2` | Complementarity size to compute (0 disables). |
+| `--adapt-headers/--no-adapt-headers` | `false` | Adapt FASTA headers before the test. |
+| `--del-tmp/--keep-tmp` | `true` | Delete temporary files after the test completes. |
+| `--lowmem/--fullmem` (`--low-mem/--full-mem`) | `lowmem` | Low-memory mode is the default for tests. |
+| `--verbose/--quiet` | `verbose` | Verbose output is the default for tests. |
+| `--log-level`, `-l` | `INFO` | Logging level: `DEBUG`, `INFO`, `WARNING`, `ERROR`. |
+| `--eggnog-data-dir` | `EGGNOG_DATA_DIR` | Path to eggNOG-mapper data (sets `EGGNOG_DATA_DIR`). |
+
+#### `analyze-ko-matrix` command (positional args: `kos_matrix`, `savedir`)
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `--calculate-complementarity`, `-c` | `0` | Complementarity size to compute (0 disables). |
+| `--kpct-outprefix` | `output_give_completeness` | Prefix for KPCT output files. |
+| `--del-tmp/--keep-tmp` | `true` | Delete temporary files after completion. |
+| `--ncpus`, `-n` | `16` | CPU cores for KPCT parallel processing. |
+| `--verbose/--quiet` | `false` | Enable verbose progress output. |
+| `--log-level`, `-l` | `INFO` | Logging level: `DEBUG`, `INFO`, `WARNING`, `ERROR`. |
+
+#### `download-eggnog-data` command
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `--eggnog-data-dir` | `${XDG_DATA_HOME:-~/.local/share}/moducomp/eggnog` | Destination for eggNOG-mapper data (sets `EGGNOG_DATA_DIR`). |
+| `--log-level`, `-l` | `INFO` | Logging level: `DEBUG`, `INFO`, `WARNING`, `ERROR`. |
+| `--verbose/--quiet` | `verbose` | Stream downloader output to the console. |
+
 ### Performance and parallel processing
 
 `moducomp` includes **parallel processing capabilities** for the KPCT (KEGG Pathways Completeness Tool) analysis, which can significantly improve performance for large datasets:
@@ -141,7 +218,7 @@ moducomp pipeline \
     # Optional flags:
     # --lowmem/--fullmem          # Optional: Use low-mem if you have less than 64GB of RAM (default is full mem)
     # --adapt-headers             # If your FASTA headers need modification
-    # --del-tmp                   # To delete temporary files
+    # --del-tmp/--keep-tmp        # Delete or keep temporary files
     # --eggnog-data-dir /path     # If EGGNOG_DATA_DIR is not set
     # --verbose                   # Enable verbose output with detailed progress information
 ```
@@ -160,7 +237,7 @@ moducomp analyze-ko-matrix \
     --calculate-complementarity <N>  # 0 to disable, 2 for 2-member, 3 for 3-member complementarity.
 
     # Optional flags:
-    # --del-tmp false
+    # --keep-tmp                  # Keep temporary files
     # --verbose                   # Enable verbose output with detailed progress information
 ```
 
@@ -204,7 +281,7 @@ moducomp pipeline ./genomes ./output_lowmem --ncpus 8 --lowmem --calculate-compl
 - **`module_completeness.tsv`**: Module completeness scores for individual genomes and combinations
 - **`module_completeness_complementarity_Nmember.tsv`**: Complementarity reports (if requested)
 - **`logs/resource_usage_YYYYMMDD_HHMMSS.log`**: Resource monitoring log with CPU, memory, and runtime metrics for reproducibility
-- **`logs/moducomp.log`**: Detailed pipeline execution log
+- **`logs/moducomp.log`**: Detailed pipeline execution log with a per-command resource summary at the end of the run
 
 ## Citation
 Villada, JC. & Schulz, F. (2025). Assessment of metabolic module completeness of genomes and metabolic complementarity in microbiomes with `moducomp` . `moducomp` (v0.5.1) Zenodo. https://doi.org/10.5281/zenodo.16116092

{moducomp-0.7.9 → moducomp-0.7.10}/moducomp/__init__.py

@@ -2,7 +2,7 @@
 moducomp: metabolic module completeness and complementarity for microbiomes.
 """
 
-__version__ = "0.7.9"
+__version__ = "0.7.10"
 __author__ = "Juan C. Villada"
 __email__ = "jvillada@lbl.gov"
 __title__ = "moducomp"

{moducomp-0.7.9 → moducomp-0.7.10}/moducomp/moducomp.py

@@ -3122,21 +3122,55 @@ def run_kpct_with_fallback(
 app = typer.Typer()
 
 @app.command()
-def pipeline(genomedir: str,
-             savedir: str,
-             ncpus: int=16,
-             adapt_headers: bool=False,
-             del_tmp: bool=True,
-             calculate_complementarity: int=0,
+def pipeline(
+             genomedir: str = typer.Argument(
+                 ...,
+                 help="Directory containing genome FAA files.",
+             ),
+             savedir: str = typer.Argument(
+                 ...,
+                 help="Directory to write all outputs.",
+             ),
+             ncpus: int = typer.Option(
+                 16,
+                 "--ncpus",
+                 "-n",
+                 min=1,
+                 help="Number of CPU cores to use for eggNOG-mapper and KPCT.",
+             ),
+             adapt_headers: bool = typer.Option(
+                 False,
+                 "--adapt-headers/--no-adapt-headers",
+                 help="Adapt FASTA headers to genome|protein_N before running eggNOG-mapper.",
+             ),
+             del_tmp: bool = typer.Option(
+                 True,
+                 "--del-tmp/--keep-tmp",
+                 help="Delete temporary files after completion.",
+             ),
+             calculate_complementarity: int = typer.Option(
+                 0,
+                 "--calculate-complementarity",
+                 "-c",
+                 help="Complementarity size to compute (0 disables).",
+             ),
              lowmem: bool = typer.Option(
                  False,
                  "--lowmem/--fullmem",
                  "--low-mem/--full-mem",
-                 help="Run emapper with reduced memory footprint, omitting --dbmem flag.",
+                 help="Run eggNOG-mapper with reduced memory footprint by omitting --dbmem.",
+             ),
+             verbose: bool = typer.Option(
+                 False,
+                 "--verbose/--quiet",
+                 help="Enable verbose output with detailed progress information.",
              ),
-             verbose: bool = typer.Option(False, "--verbose", help="Enable verbose output with detailed progress information."),
              log_level: str = typer.Option("INFO", "--log-level", "-l", help="Logging level (DEBUG, INFO, WARNING, ERROR)."),
-             eggnog_data_dir: Optional[str] = typer.Option(None, "--eggnog-data-dir", help="Path to eggNOG-mapper data directory (sets EGGNOG_DATA_DIR)."),
+             eggnog_data_dir: Optional[str] = typer.Option(
+                 None,
+                 "--eggnog-data-dir",
+                 help="Path to eggNOG-mapper data directory (sets EGGNOG_DATA_DIR).",
+             ),
              ) -> None:
     """
     Run the ModuComp pipeline on a directory of genome files.
@@ -3428,7 +3462,7 @@ def test(
     ),
     adapt_headers: bool = typer.Option(
         False,
-        "--adapt-headers",
+        "--adapt-headers/--no-adapt-headers",
         help="Adapt FASTA headers before running the test pipeline.",
     ),
     del_tmp: bool = typer.Option(
@@ -3665,13 +3699,42 @@ def download_eggnog_data_cli() -> None:
 
 @app.command()
 def analyze_ko_matrix(
-    kos_matrix: str,
-    savedir: str,
-    calculate_complementarity: int=0,
-    kpct_outprefix: str="output_give_completeness",
-    del_tmp: bool=True,
-    ncpus: int=16,
-    verbose: bool = typer.Option(False, "--verbose", help="Enable verbose output with detailed progress information."),
+    kos_matrix: str = typer.Argument(
+        ...,
+        help="Path to KO matrix CSV/TSV file.",
+    ),
+    savedir: str = typer.Argument(
+        ...,
+        help="Directory to write outputs.",
+    ),
+    calculate_complementarity: int = typer.Option(
+        0,
+        "--calculate-complementarity",
+        "-c",
+        help="Complementarity size to compute (0 disables).",
+    ),
+    kpct_outprefix: str = typer.Option(
+        "output_give_completeness",
+        "--kpct-outprefix",
+        help="Prefix for KPCT output files.",
+    ),
+    del_tmp: bool = typer.Option(
+        True,
+        "--del-tmp/--keep-tmp",
+        help="Delete temporary files after completion.",
+    ),
+    ncpus: int = typer.Option(
+        16,
+        "--ncpus",
+        "-n",
+        min=1,
+        help="CPU cores for KPCT parallel processing.",
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose/--quiet",
+        help="Enable verbose output with detailed progress information.",
+    ),
     log_level: str = typer.Option("INFO", "--log-level", "-l", help="Logging level (DEBUG, INFO, WARNING, ERROR)."),
     ) -> None:
     """

{moducomp-0.7.9 → moducomp-0.7.10}/pixi.lock

@@ -1340,8 +1340,8 @@ packages:
   timestamp: 1737229717596
 - pypi: ./
   name: moducomp
-  version: 0.6.0
-  sha256: 3e8097938d9ac1aac7ee5221ae805b7374c5bba16b65ef5cfb546010ffde04b8
+  version: 0.7.9
+  sha256: 69bbe817500b6ae5011deb9c4ec4639f8a4c8b54a275b58ac1e8b3ad2d84e798
   requires_dist:
   - typer>=0.9.1,<0.10.0
   - pandas>=1.5,<2.3

{moducomp-0.7.9 → moducomp-0.7.10}/recipe.yaml

@@ -1,5 +1,5 @@
 context:
-  version: 0.7.9
+  version: 0.7.10
 
 package:
   name: moducomp
@@ -7,7 +7,7 @@ package:
 
 source:
 - url: https://pypi.org/packages/source/m/moducomp/moducomp-${{ version }}.tar.gz
-  sha256: be3a979d601c979d4570a31ef37a5ad70206096d3c1a4d7aaa148e0427a9ef45
+  sha256: 440e0dbde36b029c5fb7e874fba8642621b556d9c8914f213e0360294228b019
 
 build:
   script: