[WIP] Support DOT inputs (and multigraphs); much improved boundary node splitting in pattern identification; add back frayed rope support; lots of other improvements

.github/workflows/python.yml

@@ -8,7 +8,10 @@ jobs:
 
     strategy:
       matrix:
-        python-version: [3.6]
+        # Gotta specify 3.10 as a string to avoid it being converted to 3.1:
+        # https://github.com/actions/setup-python/issues/160,
+        # https://github.com/fedarko/pyfastg/blob/master/.github/workflows/main.yml
+        python-version: [3.6, 3.7, 3.8, 3.9, "3.10"]
 
     steps:
 
@@ -27,7 +30,13 @@ jobs:
       - name: Install MetagenomeScope (and its pip dependencies)
         run: conda run -n mgsc pip install -e .[dev]
 
+      # I think later versions of black (e.g. 23.1) changed things in ways that
+      # will cause this to fail. Since not all black versions support all
+      # python versions, the easiest solution is to just only do stylechecking
+      # when we're working with python 3.6.
+      # See https://stackoverflow.com/q/73598359 re: "if" expressions here.
       - name: Lint and stylecheck the Python code
+        if: ${{ matrix.python-version == 3.6 }}
         run: conda run -n mgsc make pystylecheck
 
       - name: Run Python tests

.gitignore

@@ -145,7 +145,6 @@ js_coverage.json
 metagenomescope/tests/js_tests/instrumented_js/*
 dist/
 big-list-of-naughty-strings/
-*.gv
 *.xdot
 *.db
 mg2/

CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# MetagenomeScope development documentation
+
+Thanks for your interest in this project! Or, at least, I'm assuming you're
+interested, because you clicked on this document, and you're reading it now,
+and wow, you're still reading this sentence -- aren't you a persistent person?
+Okay, you've made it to the third sentence of this document; if you've made it
+this far, our fates are now intertwined. You're now officially a maintainer of
+this project.
+
+## Code structure
+
+MetagenomeScope's code is composed of two main components:
+
+### 1. Preprocessing script
+
+MetagenomeScope's **preprocessing script** (contained in the
+`metagenomescope/` directory of this repository) is a mostly-Python script that
+takes as input an assembly graph file and produces a directory containing a
+HTML visualization of the graph. Once installed, it can be run from the command
+line using the `mgsc` command.
+
+### 2. Viewer interface
+
+MetagenomeScope's **viewer interface** (contained in the
+`metagenomescope/support_files/` directory
+of this repository) is a client-side web application that visualizes laid-out
+assembly graphs using [Cytoscape.js](https://js.cytoscape.org/). This interface
+includes various features for interacting with the graph and the
+identified structural patterns within it.
+
+You should be able to load visualizations created by MetagenomeScope
+in most modern web browsers (mobile browsers probably will also work, although
+using a desktop browser is recommended).
+
+## That was the worst developer documentation I've read in my life
+
+Sorry -- I'll try to add more stuff here later `._.`

Makefile

@@ -19,15 +19,18 @@
 
 .PHONY: pytest jstest test pystylecheck jsstylecheck stylecheck pystyle jsstyle style demo
 
-PYTEST_COMMAND = python3 -B -m pytest metagenomescope/tests/ --cov-report xml --cov-report term --cov metagenomescope
 PYLOCS = metagenomescope/ setup.py
 JSLOCS = metagenomescope/support_files/js/*.js metagenomescope/tests/js_tests/*.js docs/js/extra_functionality.js .jshintrc
 HTMLCSSLOCS = metagenomescope/support_files/index.html metagenomescope/tests/js_tests/*.html metagenomescope/support_files/css/viewer_style.css docs/404.html docs/index.html docs/css/mgsc_docs_style.css
 
 # -B: don't create __pycache__/ directories
 pytest:
-	$(PYTEST_COMMAND)
-	rm -f metagenomescope/tests/output/*
+	python3 -B -m pytest \
+		metagenomescope/tests/ \
+		--cov-report xml \
+		--cov-report term \
+		--cov-report html \
+		--cov metagenomescope
 
 jstest:
 	nyc instrument metagenomescope/support_files/js/ metagenomescope/tests/js_tests/instrumented_js/

environment.yml

@@ -3,7 +3,7 @@ channels:
     - conda-forge
     - defaults
 dependencies:
-    - python = 3.6
+    - python >= 3.6
     - pip
     - numpy
     - graphviz

metagenomescope/__init__.py

@@ -18,23 +18,29 @@
 
 # Import submodules so they're easy to see from REPL
 from . import (
-    arg_utils,
-    assembly_graph_parser,
     config,
+    errors,
     file_utils,
+    graph,
     input_node_utils,
     layout_utils,
+    misc_utils,
     msg_utils,
+    parsers,
 )
 
 # ... And explicitly declare them in __all__. This will stop flake8 from
 # yelling at us about these imports being unused.
 __all__ = [
-    "arg_utils",
-    "assembly_graph_parser",
     "config",
+    "errors",
     "file_utils",
+    "graph",
     "input_node_utils",
     "layout_utils",
+    "misc_utils",
     "msg_utils",
+    "parsers",
 ]
+
+__version__ = "0.1.0-dev"

metagenomescope/_cli.py

@@ -21,13 +21,19 @@
 # https://github.com/biocore/qurro/blob/master/qurro/scripts/_plot.py.
 
 import click
+from . import __version__
 from .config import MAXN_DEFAULT, MAXE_DEFAULT
 from .main import make_viz
 from ._param_descriptions import (
     INPUT,
     OUTPUT_DIR,
+    OUTPUT_DOT,
+    OUTPUT_CCSTATS,
+    NODE_METADATA,
+    EDGE_METADATA,
     MAXN,
     MAXE,
+    PATTERNS_FLAG,
 )
 
 
@@ -36,129 +42,110 @@
     context_settings={"help_option_names": ["-h", "--help"]},
     no_args_is_help=True,
 )
-@click.option("-i", "--input-file", required=True, help=INPUT)
-@click.option("-o", "--output-dir", required=True, help=OUTPUT_DIR)
-# @click.option(
-#    "-ao",
-#    "--assume-oriented",
-#    required=False,
-#    default=False,
-#    help=ASSUME_ORIENTED,
-# )
+@click.option(
+    "-i",
+    "--input-file",
+    type=click.Path(exists=True, dir_okay=False, readable=True),
+    required=True,
+    help=INPUT,
+)
+@click.option(
+    "-o",
+    "--output-viz-dir",
+    type=click.Path(exists=False),
+    default=None,
+    show_default=True,
+    help=OUTPUT_DIR,
+)
+@click.option(
+    "-od",
+    "--output-dot",
+    type=click.Path(dir_okay=False, writable=True),
+    default=None,
+    show_default=True,
+    help=OUTPUT_DOT,
+)
+@click.option(
+    "-os",
+    "--output-ccstats",
+    type=click.Path(dir_okay=False, writable=True),
+    default=None,
+    show_default=True,
+    help=OUTPUT_CCSTATS,
+)
+@click.option(
+    "-n",
+    "--node-metadata",
+    type=click.Path(exists=True, dir_okay=False, readable=True),
+    required=False,
+    default=None,
+    show_default=True,
+    help=NODE_METADATA,
+)
+@click.option(
+    "-e",
+    "--edge-metadata",
+    type=click.Path(exists=True, dir_okay=False, readable=True),
+    required=False,
+    default=None,
+    show_default=True,
+    help=EDGE_METADATA,
+)
 @click.option(
     "-maxn",
     "--max-node-count",
+    type=click.IntRange(min=0),
     required=False,
     default=MAXN_DEFAULT,
-    help=MAXN,
     show_default=True,
+    help=MAXN,
 )
 @click.option(
     "-maxe",
     "--max-edge-count",
+    type=click.IntRange(min=0),
     required=False,
     default=MAXE_DEFAULT,
+    show_default=True,
     help=MAXE,
+)
+@click.option(
+    "--patterns/--no-patterns",
+    is_flag=True,
+    default=True,
     show_default=True,
+    help=PATTERNS_FLAG,
 )
-# @click.option(
-#    "-mbf", "--metacarvel-bubble-file", required=False, default=None, help=MBF
-# )
-# @click.option(
-#    "-up", "--user-pattern-file", required=False, default=None, help=UP
-# )
-# @click.option(
-#    "-spqr",
-#    "--compute-spqr-data",
-#    required=False,
-#    is_flag=True,
-#    default=False,
-#    help=SPQR,
-# )
-# @click.option(
-#    "-sp",
-#    "--save-structural-patterns",
-#    is_flag=True,
-#    required=False,
-#    default=False,
-#    help=STRUCTPATT,
-# )
-# @click.option(
-#    "-pg",
-#    "--preserve-gv",
-#    is_flag=True,
-#    required=False,
-#    default=False,
-#    help=PG,
-# )
-# @click.option(
-#    "-px",
-#    "--preserve-xdot",
-#    required=False,
-#    is_flag=True,
-#    default=False,
-#    help=PX,
-# )
-# @click.option(
-#    "-nbdf",
-#    "--save-no-backfill-dot-files",
-#    is_flag=True,
-#    required=False,
-#    default=False,
-#    help=NBDF,
-# )
-# @click.option(
-#    "-npdf",
-#    "--save-no-pattern-dot-files",
-#    is_flag=True,
-#    required=False,
-#    default=False,
-#    help=NPDF,
-# )
+@click.version_option(__version__, "-v", "--version")
 def run_script(
     input_file: str,
-    output_dir: str,
-    # assume_oriented: bool,
+    output_viz_dir: str,
+    output_dot: str,
+    output_ccstats: str,
+    node_metadata: str,
+    edge_metadata: str,
     max_node_count: int,
     max_edge_count: int,
-    # metacarvel_bubble_file: str,
-    # user_pattern_file: str,
-    # compute_spqr_data: bool,
-    # save_structural_patterns: bool,
-    # preserve_gv: bool,
-    # preserve_xdot: bool,
-    # save_no_backfill_dot_files: bool,
-    # save_no_pattern_dot_files: bool,
+    patterns: bool,
 ) -> None:
-    """Visualizes an assembly graph and the structural patterns in it.
-
-    This generates a folder containing an interactive HTML/JS visualization of
-    the graph. The folder's index.html file can be opened in a web browser to
-    access the visualization.
-
-    There are many options available to customize the visualization / output,
-    but the only two you probably need to worry about are the input file and
-    output directory: generating a visualization can be as simple as
+    """Visualizes an assembly graph.
 
-        mgsc -i graph.gfa -o viz
+    MetagenomeScope supports multiple types of output (-o, -od, -os);
+    you will probably want to start with -o.
 
-    ...which will generate an output directory named "viz". (You'll need to
-    replace "graph.gfa" with whatever the path to your assembly graph is.)
+    Please check out https://github.com/marbl/MetagenomeScope if you have any
+    questions, suggestions, etc. about this tool.
     """
     make_viz(
         input_file,
-        output_dir,
-        # assume_oriented,
         max_node_count,
         max_edge_count,
-        # metacarvel_bubble_file,
-        # user_pattern_file,
-        # compute_spqr_data,
-        # save_structural_patterns,
-        # preserve_gv,
-        # preserve_xdot,
-        # save_no_backfill_dot_files,
-        # save_no_pattern_dot_files,
+        patterns,
+        output_viz_dir,
+        output_dot,
+        output_ccstats,
+        node_metadata,
+        edge_metadata,
     )