Add module docstrings

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## Tools 0.1.1
 
 - fix: don't add extra newline to command stdout/stderr for `shell_run()` and `exec_in_context()`. (#10, @kelly-sovacool)
+- minor docuemntation improvements. (#12, @kelly-sovacool)
 
 ## Tools 0.1.0
 

src/ccbr_tools/GSEA/__init__.py

@@ -0,0 +1,8 @@
+"""
+GSEA tools
+
+Modules:
+    - `ccbr_tools.GSEA.deg2gs`
+    - `ccbr_tools.GSEA.multitext2excel`
+    - `ccbr_tools.GSEA.ncbr_huse`
+"""

src/ccbr_tools/GSEA/deg2gs.py

@@ -1,15 +1,13 @@
-#!/usr/bin/env python
-
 """
+deg2gs.py
+    Reads a rnaseq pipeliner *_DEG_all_genes.txt file
+    and outputs a prioritized list of Ensembl gene IDs for ToppFun
+
 Susan Huse
 NIAID Center for Biological Research
 Frederick National Laboratory for Cancer Research
 Leidos Biomedical
 
-deg2gs.py
-    Reads a rnaseq pipeliner *_DEG_all_genes.txt file
-    and outputs a prioritized list of Ensembl gene IDs for ToppFun
-
 v 1.0 - initial code version.
 v 1.1 - updated for new column headers in pipeliner limma_DEG_all_genes.txt
 v 1.2 - top2Excel format is now csv rather than tab-delimited

src/ccbr_tools/GSEA/multitext2excel.py

@@ -1,20 +1,18 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
 """
+multitext2excel.py
+    Reads a list of files to import as separate tabs in Excel
+
 Created on Mon Aug  6 14:59:13 2018
 
 Susan Huse
 NIAID Center for Biological Research
 Frederick National Laboratory for Cancer Research
 Leidos Biomedical
 
-multitext2excel.py
-    Reads a list of files to import as separate tabs in Excel
-
 v 1.0 - initial code version.
 v 1.1 - updated to include first splitter markowitzte@nih.gov
-
 """
+
 __author__ = "Susan Huse"
 __date__ = "August 6, 2018"
 __version__ = "1.1"

src/ccbr_tools/GSEA/ncbr_huse.py

@@ -1,11 +1,10 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
 """
-Created on Mon Aug  6 11:07:30 2018
-
 ncbr_huse.py
     Set of functions supporting the FNL NCBR work
 
+Author: Susan Huse
+
+Created on Mon Aug  6 11:07:30 2018
 """
 
 __author__ = "Susan Huse"

src/ccbr_tools/__init__.py

@@ -0,0 +1,5 @@
+"""
+ccbr_tools package.
+
+Utilities for CCBR Bioinformatics Software
+"""

src/ccbr_tools/homologfinder/__init__.py

@@ -0,0 +1,3 @@
+"""
+hf or HomologFinder finds homologs in human and mouse.
+"""

src/ccbr_tools/pipeline/__init__.py

@@ -0,0 +1,9 @@
+"""
+Helpers for bioinformatics pipelines
+
+Modules:
+    - `ccbr_tools.pipeline.cache`
+    - `ccbr_tools.pipeline.hpc`
+    - `ccbr_tools.pipeline.nextflow`
+    - `ccbr_tools.pipeline.util`
+"""

src/ccbr_tools/pipeline/hpc.py

@@ -1,3 +1,15 @@
+"""
+This module defines classes for working with different HPC clusters.
+
+Classes:
+    Cluster: Parent class for HPC clusters, which evaluates to None.
+    Biowulf: Represents the Biowulf HPC cluster.
+    FRCE: Represents the FRCE HPC cluster.
+
+Functions:
+    get_hpc: Returns an instance of the appropriate HPC cluster based on the current environment.
+"""
+
 from .util import get_hpcname
 from .cache import get_singularity_cachedir
 

src/ccbr_tools/pipeline/nextflow.py

@@ -8,7 +8,8 @@
     Run a Nextflow workflow.
 """
 
-from ..pkg_util import msg_box, use_template
+from ..pkg_util import msg_box
+from ..templates import use_template
 from ..shell import shell_run
 from .hpc import get_hpc
 from .cache import get_singularity_cachedir

src/ccbr_tools/pkg_util.py

@@ -153,46 +153,3 @@ def msg_box(splash, errmsg=None):
     msg(("-" * (len(splash) + 4)))
     if errmsg:
         click.echo("\n" + errmsg, err=True)
-
-
-def read_template(template_name):
-    """
-    Read a template file
-
-    Args:
-        template_name (str): Name of the template file
-
-    Returns:
-        template (str): Contents of the template file
-    """
-
-    template_files = importlib.resources.files(templates)
-    template_path = template_files / template_name
-    with open(template_path, "rt") as template_file:
-        return template_file.read()
-
-
-def use_template(template_name, output_filepath=None, **kwargs):
-    """
-    Uses a template, formats variables, and writes it to a file.
-
-    Args:
-        template_name (str): The name of the template to use.
-        output_filepath (str, optional): The filepath to save the output file. If not provided, it will be written to `template_name` in the current working directory.
-        **kwargs: Keyword arguments to fill in the template variables.
-
-    Returns:
-        None
-
-    Raises:
-        FileNotFoundError: If the template file is not found.
-        IOError: If there is an error writing the output file.
-
-    Examples:
-        use_template("slurm_nxf_biowulf.sh", output_filepath="submit_slurm.sh", PIPELINE="CCBR_nxf", RUN_COMMAND="nextflow run main.nf -stub")
-    """
-    template_str = read_template(template_name)
-    if not output_filepath:
-        output_filepath = template_name
-    with open(output_filepath, "wt") as outfile:
-        outfile.write(template_str.format(**kwargs))

src/ccbr_tools/templates/__init__.py

@@ -0,0 +1,51 @@
+"""
+Template files for CCBR Tools.
+
+Templates:
+    - `ccbr_tools.templates.submit_slurm.sh`
+"""
+
+import importlib.resources
+
+
+def read_template(template_name):
+    """
+    Read a template file
+
+    Args:
+        template_name (str): Name of the template file
+
+    Returns:
+        template (str): Contents of the template file
+    """
+
+    template_files = importlib.resources.files(__package__)
+    template_path = template_files / template_name
+    with open(template_path, "rt") as template_file:
+        return template_file.read()
+
+
+def use_template(template_name, output_filepath=None, **kwargs):
+    """
+    Uses a template, formats variables, and writes it to a file.
+
+    Args:
+        template_name (str): The name of the template to use.
+        output_filepath (str, optional): The filepath to save the output file. If not provided, it will be written to `template_name` in the current working directory.
+        **kwargs: Keyword arguments to fill in the template variables.
+
+    Returns:
+        None
+
+    Raises:
+        FileNotFoundError: If the template file is not found.
+        IOError: If there is an error writing the output file.
+
+    Examples:
+        use_template("submit_slurm.sh", output_filepath="./submit_slurm.sh", PIPELINE="CCBR_nxf", MODULES="ccbrpipeliner nextflow", ENV_VARS="", RUN_COMMAND="nextflow run main.nf -stub")
+    """
+    template_str = read_template(template_name)
+    if not output_filepath:
+        output_filepath = template_name
+    with open(output_filepath, "wt") as outfile:
+        outfile.write(template_str.format(**kwargs))

tests/test_pkg_util.py

@@ -1,11 +1,5 @@
-from ccbr_tools.pkg_util import read_template
+from ccbr_tools.pkg_util import repo_base
 
 
-def test_read_template():
-    template_str = read_template("submit_slurm.sh")
-    assert all(
-        [
-            template_str.startswith("#!/usr/bin/env bash"),
-            template_str.endswith("{RUN_COMMAND}\n"),
-        ]
-    )
+def test_repo_base():
+    assert str(repo_base()).endswith("ccbr_tools")

tests/test_templates.py

@@ -0,0 +1,67 @@
+import os
+import pathlib
+import pytest
+import tempfile
+
+from ccbr_tools.templates import read_template, use_template
+
+
+def test_read_template():
+    template_str = read_template("submit_slurm.sh")
+    assert all(
+        [
+            template_str.startswith("#!/usr/bin/env bash"),
+            template_str.endswith("{RUN_COMMAND}\n"),
+        ]
+    )
+
+
+def test_use_template():
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        out_filepath = pathlib.Path(tmp_dir) / "test.sh"
+        use_template(
+            "submit_slurm.sh",
+            output_filepath=out_filepath,
+            PIPELINE="CCBR_nxf",
+            MODULES="ccbrpipeliner nextflow",
+            ENV_VARS="export HELLO=WORLD",
+            RUN_COMMAND="nextflow run main.nf -stub",
+        )
+        with open(out_filepath, "r") as outfile:
+            template_str = outfile.read()
+        assertions = [
+            '#SBATCH -J "CCBR_nxf"' in template_str,
+            "module load ccbrpipeliner nextflow" in template_str,
+            "export HELLO=WORLD" in template_str,
+            "nextflow run main.nf -stub" in template_str,
+        ]
+    assert all(assertions)
+
+
+def test_use_template_defaults():
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        current_wd = os.getcwd()
+        tmp_wd = pathlib.Path(current_wd) / tmp_dir
+        os.chdir(tmp_wd)
+        use_template(
+            "submit_slurm.sh",
+            PIPELINE="CCBR_nxf",
+            MODULES="ccbrpipeliner nextflow",
+            ENV_VARS="export HELLO=WORLD",
+            RUN_COMMAND="nextflow run main.nf -stub",
+        )
+        os.chdir(current_wd)
+        template_file = pathlib.Path(tmp_wd) / "submit_slurm.sh"
+        assertions = [template_file.is_file()]
+    assert all(assertions)
+
+
+def test_use_template_blanks():
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        out_filepath = pathlib.Path(tmp_dir) / "test.sh"
+        with pytest.raises(KeyError) as exc_info:
+            use_template(
+                "submit_slurm.sh",
+                output_filepath=out_filepath,
+            )
+            assert str(exc_info.value) == "KeyError: 'MODULES'"