pmotools 0.1.0__py3-none-any.whl

pmotools/__init__.py

@@ -0,0 +1,26 @@
+# pmotools/__init__.py
+from __future__ import annotations
+
+try:
+    # Python 3.8+
+    from importlib.metadata import version, PackageNotFoundError
+except Exception:  # pragma: no cover
+    # Very old Pythons can fallback to pkg_resources if you ever needed it
+    from pkg_resources import get_distribution as _gd  # type: ignore
+
+    class PackageNotFoundError(Exception):
+        ...
+
+    def version(pkg: str) -> str:  # type: ignore
+        try:
+            return _gd(pkg).version
+        except Exception as e:  # noqa: BLE001
+            raise PackageNotFoundError from e
+
+
+try:
+    # Use the installed distribution name (matches [project].name)
+    __version__ = version("pmotools")
+except PackageNotFoundError:
+    # When running from a source tree without being installed
+    __version__ = "0+local"

pmotools/cli.py

@@ -0,0 +1,374 @@
+#!/usr/bin/env python3
+
+import argparse
+from dataclasses import dataclass
+from typing import Callable, Dict, Tuple
+
+from pmotools import __version__
+from pmotools.utils.color_text import ColorText as CT
+
+# convertors_to_pmo
+from pmotools.scripts.convertors_to_pmo.text_meta_to_json_meta import (
+    text_meta_to_json_meta,
+)
+from pmotools.scripts.convertors_to_pmo.excel_meta_to_json_meta import (
+    excel_meta_to_json_meta,
+)
+from pmotools.scripts.convertors_to_pmo.microhaplotype_table_to_json_file import (
+    microhaplotype_table_to_json_file,
+)
+from pmotools.scripts.convertors_to_pmo.terra_amp_output_to_json import (
+    terra_amp_output_to_json,
+)
+
+# extractors_from_pmo
+from pmotools.scripts.extractors_from_pmo.extract_pmo_with_selected_meta import (
+    extract_pmo_with_selected_meta,
+)
+from pmotools.scripts.extractors_from_pmo.extract_pmo_with_select_specimen_names import (
+    extract_pmo_with_select_specimen_names,
+)
+from pmotools.scripts.extractors_from_pmo.extract_pmo_with_select_library_sample_names import (
+    extract_pmo_with_select_library_sample_names,
+)
+from pmotools.scripts.extractors_from_pmo.extract_pmo_with_select_targets import (
+    extract_pmo_with_select_targets,
+)
+from pmotools.scripts.extractors_from_pmo.extract_pmo_with_read_filter import (
+    extract_pmo_with_read_filter,
+)
+from pmotools.scripts.extractors_from_pmo.extract_allele_table import (
+    extract_for_allele_table,
+)
+
+# pmo_utils
+from pmotools.scripts.pmo_utils.combine_pmos import combine_pmos
+from pmotools.scripts.pmo_utils.validate_pmo import validate_pmo
+
+# extract_info_from_pmo
+from pmotools.scripts.extract_info_from_pmo.list_library_sample_names_per_specimen_name import (
+    list_library_sample_names_per_specimen_name,
+)
+from pmotools.scripts.extract_info_from_pmo.list_specimen_meta_fields import (
+    list_specimen_meta_fields,
+)
+from pmotools.scripts.extract_info_from_pmo.list_bioinformatics_run_names import (
+    list_bioinformatics_run_names,
+)
+from pmotools.scripts.extract_info_from_pmo.count_specimen_meta import (
+    count_specimen_meta,
+)
+from pmotools.scripts.extract_info_from_pmo.count_targets_per_library_sample import (
+    count_targets_per_library_sample,
+)
+from pmotools.scripts.extract_info_from_pmo.count_library_samples_per_target import (
+    count_library_samples_per_target,
+)
+
+# panel info subset
+from pmotools.scripts.extract_info_from_pmo.extract_insert_of_panels import (
+    extract_insert_of_panels,
+)
+from pmotools.scripts.extract_info_from_pmo.extract_refseq_of_inserts_of_panels import (
+    extract_refseq_of_inserts_of_panels,
+)
+
+
+@dataclass(frozen=True)
+class PmoCommand:
+    func: Callable[[], None]
+    help: str
+
+
+REGISTRY: Dict[str, Dict[str, PmoCommand]] = {
+    "convertors_to_json": {
+        "text_meta_to_json_meta": PmoCommand(
+            text_meta_to_json_meta, "Convert text file meta to JSON Meta"
+        ),
+        "excel_meta_to_json_meta": PmoCommand(
+            excel_meta_to_json_meta, "Convert Excel file meta to JSON Meta"
+        ),
+        "microhaplotype_table_to_json_file": PmoCommand(
+            microhaplotype_table_to_json_file,
+            "Convert microhaplotype table to a JSON file",
+        ),
+        "terra_amp_output_to_json": PmoCommand(
+            terra_amp_output_to_json, "Convert Terra output to JSON sequence table"
+        ),
+    },
+    "extractors_from_pmo": {
+        "extract_pmo_with_selected_meta": PmoCommand(
+            extract_pmo_with_selected_meta,
+            "Extract samples + haplotypes using selected meta",
+        ),
+        "extract_pmo_with_select_specimen_names": PmoCommand(
+            extract_pmo_with_select_specimen_names,
+            "Extract specific samples from the specimens table",
+        ),
+        "extract_pmo_with_select_library_sample_names": PmoCommand(
+            extract_pmo_with_select_library_sample_names,
+            "Extract experiment sample names from experiment_info table",
+        ),
+        "extract_pmo_with_select_targets": PmoCommand(
+            extract_pmo_with_select_targets, "Extract specific targets"
+        ),
+        "extract_pmo_with_read_filter": PmoCommand(
+            extract_pmo_with_read_filter, "Extract with a read filter"
+        ),
+        "extract_allele_table": PmoCommand(
+            extract_for_allele_table,
+            "Extract allele tables for tools like dcifer or moire",
+        ),
+        "extract_insert_of_panels": PmoCommand(
+            extract_insert_of_panels, "Extract inserts of panels from a PMO"
+        ),
+        "extract_refseq_of_inserts_of_panels": PmoCommand(
+            extract_refseq_of_inserts_of_panels,
+            "Extract ref_seq of panel inserts from a PMO",
+        ),
+    },
+    "working_with_multiple_pmos": {
+        "combine_pmos": PmoCommand(
+            combine_pmos, "Combine multiple PMOs of the same panel"
+        ),
+    },
+    "extract_basic_info_from_pmo": {
+        "list_library_sample_names_per_specimen_name": PmoCommand(
+            list_library_sample_names_per_specimen_name,
+            "List experiment_sample_ids per specimen_id",
+        ),
+        "list_specimen_meta_fields": PmoCommand(
+            list_specimen_meta_fields,
+            "List specimen meta fields in the specimen_info section",
+        ),
+        "list_bioinformatics_run_names": PmoCommand(
+            list_bioinformatics_run_names,
+            "List all tar_amp_bioinformatics_info_ids in a PMO",
+        ),
+        "count_specimen_meta": PmoCommand(
+            count_specimen_meta, "Count values of selected specimen meta fields"
+        ),
+        "count_targets_per_library_sample": PmoCommand(
+            count_targets_per_library_sample, "Count number of targets per sample"
+        ),
+        "count_library_samples_per_target": PmoCommand(
+            count_library_samples_per_target, "Count number of samples per target"
+        ),
+    },
+    "validation": {
+        "validate_pmo": PmoCommand(
+            validate_pmo, "Validate a PMO file against a JSON Schema"
+        )
+    },
+}
+
+
+def _iter_all_commands():
+    for group, commands in REGISTRY.items():
+        for name, cmd in commands.items():
+            yield group, name, cmd.help
+
+
+def _print_catalog_plain():
+    """
+    Print commands in a machine-friendly, no-color format:
+    '<command>\t<group>\t<help>'
+    One per line; used by bash completion.
+    """
+    import sys
+
+    for group, name, cmdhelp in _iter_all_commands():
+        sys.stdout.write(f"{name}\t{group}\t{cmdhelp}\n")
+
+
+def _print_catalog() -> None:
+    """Print all groups and their commands like your previous version."""
+    import sys
+
+    sys.stdout.write(
+        f"pmotools-python v{__version__} - A suite of tools for interacting with "
+        + CT.boldGreen("Portable Microhaplotype Object (PMO)")
+        + " file format\n\n"
+    )
+    sys.stdout.write("Available functions organized by groups are\n")
+    for group, commands in REGISTRY.items():
+        sys.stdout.write(CT.boldBlue(group) + "\n")
+        for name, cmd in commands.items():
+            sys.stdout.write(f"\t{name} - {cmd.help}\n")
+        sys.stdout.write("\n")
+
+
+def _print_group(group: str) -> int:
+    """Print a single group's commands (blue header) if it exists."""
+    import sys
+
+    if group not in REGISTRY:
+        sys.stdout.write(
+            CT.boldRed("Did not find group ") + CT.boldWhite(group) + "\n\n"
+        )
+        _print_catalog()
+        return 2
+
+    sys.stdout.write(CT.boldBlue(group) + "\n")
+    for name, cmd in REGISTRY[group].items():
+        sys.stdout.write(f"\t{name} - {cmd.help}\n")
+    sys.stdout.write("\n")
+    return 0
+
+
+def _print_bash_completion():
+    # NOTE: this uses --list-plain to avoid ANSI color parsing and be stable.
+    script = r"""# bash completion for pmotools-python
+# add the below to your ~/.bash_completion
+
+_pmotools_python_complete()
+{
+    local cur prev
+    COMPREPLY=()
+    cur="${COMP_WORDS[COMP_CWORD]}"
+    prev="${COMP_WORDS[COMP_CWORD-1]}"
+
+    # 1) Completing the command name (1st arg): list all commands
+    if [[ ${COMP_CWORD} -eq 1 ]]; then
+        # Our CLI prints machine-friendly list via --list-plain:
+        # "<command>\t<group>\t<help>"
+        local lines cmds
+        lines="$(${COMP_WORDS[0]} --list-plain 2>/dev/null)"
+        cmds="$(printf '%s\n' "${lines}" | awk -F'\t' '{print $1}')"
+        COMPREPLY=( $(compgen -W "${cmds}" -- "${cur}") )
+        return 0
+    fi
+
+    # 2) Completing flags for a leaf command: scrape leaf -h
+    if [[ "${cur}" == -* ]]; then
+        local helps opts
+        helps="$(${COMP_WORDS[0]} ${COMP_WORDS[1]} -h 2>/dev/null)"
+        # Pull out flag tokens and split comma-separated forms
+        opts="$(printf '%s\n' "${helps}" \
+            | sed -n 's/^[[:space:]]\{0,\}\(-[-[:alnum:]][-[:alnum:]]*\)\(, *-[[:alnum:]][-[:alnum:]]*\)\{0,\}.*/\1/p' \
+            | sed 's/, / /g')"
+        COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+        return 0
+    fi
+
+    # 3) Otherwise, fall back to filename completion for positional args
+    COMPREPLY=( $(compgen -f -- "${cur}") )
+    return 0
+}
+
+complete -F _pmotools_python_complete pmotools-python
+"""
+    import sys
+
+    sys.stdout.write(script)
+
+
+def _build_parser() -> (
+    Tuple[argparse.ArgumentParser, Dict[str, Tuple[str, PmoCommand]]]
+):
+    """
+    Build a flat CLI:
+      pmotools-python <command> [args...]
+    Returns the parser and an index mapping command_name -> (group, PmoCommand)
+    """
+    description = (
+        f"pmotools-python v{__version__} – A suite of tools for interacting with "
+        f"{CT.boldGreen('Portable Microhaplotype Object (PMO)')} files"
+    )
+    parser = argparse.ArgumentParser(
+        prog="pmotools-python",
+        description=description,
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+    parser.add_argument(
+        "--list-plain",
+        action="store_true",
+        help=argparse.SUPPRESS,  # keep it hidden; for completion script
+    )
+    parser.add_argument(
+        "--bash-completion",
+        action="store_true",
+        help="Print bash completion script for pmotools-python",
+    )
+    parser.add_argument(
+        "-V", "--version", action="version", version=f"%(prog)s {__version__}"
+    )
+    parser.add_argument(
+        "--list",
+        nargs="?",
+        const="__ALL__",
+        metavar="[group]",
+        help="List all commands, or only those within a specific group",
+    )
+
+    subparsers = parser.add_subparsers(
+        title="Commands", dest="command", metavar="<command>"
+    )
+
+    command_index: Dict[str, Tuple[str, PmoCommand]] = {}
+
+    for group, commands in REGISTRY.items():
+        for cmd_name, cmd in commands.items():
+            if cmd_name in command_index:
+                # Hard fail early if duplicate command names exist across groups
+                raise RuntimeError(
+                    f"Duplicate command name detected: '{cmd_name}'. "
+                    f"Please rename one of the commands or add an alias."
+                )
+            sp = subparsers.add_parser(
+                cmd_name,
+                help=f"{cmd.help}  [{group}]",
+                description=f"{cmd.help} (group: {group})",
+                add_help=False,
+            )
+            sp.set_defaults(_handler=cmd.func, _group=group, _cmd_name=cmd_name)
+            command_index[cmd_name] = (group, cmd)
+
+    return parser, command_index
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser, command_index = _build_parser()
+    args, unknown = parser.parse_known_args(argv)
+
+    if getattr(args, "bash_completion", False):
+        _print_bash_completion()
+        return 0
+
+    if getattr(args, "list_plain", False):
+        _print_catalog_plain()
+        return 0
+
+    if getattr(args, "list", None):
+        group = args.list
+        if group == "__ALL__":
+            _print_catalog()
+            return 0
+        else:
+            return _print_group(group)
+
+    # No command provided: show the catalog
+    if not getattr(args, "command", None):
+        _print_catalog()
+        return 0
+
+    # Dispatch to the leaf and forward remaining args to its own argparse
+    handler = getattr(args, "_handler", None)
+    if handler is None:
+        parser.error("No handler bound for this command (internal error).")
+
+    import sys
+
+    leaf_prog = f"pmotools-python {getattr(args, '_cmd_name', 'unknown')}"
+    old_argv = sys.argv[:]
+    try:
+        sys.argv = [leaf_prog, *unknown]
+        handler()
+    finally:
+        sys.argv = old_argv
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pmotools/pmo_builder/json_convert_utils.py

@@ -0,0 +1,5 @@
+def check_additional_columns_exist(df, additional_column_list):
+    if additional_column_list:
+        missing_cols = set(additional_column_list) - set(df.columns)
+        if missing_cols:
+            raise ValueError(f"Missing additional columns: {missing_cols}")

pmotools/pmo_builder/merge_to_pmo.py

@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+from datetime import date
+import json
+
+
+def merge_to_pmo(
+    specimen_info: list,
+    library_sample_info: list,
+    sequencing_info: list,
+    panel_info: dict,
+    mhap_info: dict,
+    bioinfo_method_info: list,
+    bioinfo_run_info: list,
+    project_info: list,
+):
+    """
+    Merge components into PMO, replacing names with indeces.
+
+    :param specimen_info (list): a list of all the specimens within this project
+    :param library_sample_info (list) : a list of library samples within this project
+    :param sequencing_info (list) : a list of sequencing info for this project
+    :param panel_info (list) : a dictionary containing the panel and target information for this project
+    :param mhap_info (list) : a dictionary containing the microhaplotypes within this project, both detected and representative
+    :param bioinfo_method_info (list) : the bioinformatics pipeline/methods used to generated the amplicon analysis for this project
+    :param bioinfo_run_info (list) : the runtime info for the bioinformatics pipeline used to generated the amplicon analysis for this project
+    :param project_info (list) : the information about the projects stored in this PMO
+
+    :return: a json formatted PMO string.
+    """
+    # Make copies to avoid editing input
+    specimen_info = [dict(d) for d in specimen_info]
+    library_sample_info = [dict(d) for d in library_sample_info]
+    sequencing_info = [dict(d) for d in sequencing_info]
+    bioinfo_method_info = [dict(d) for d in bioinfo_method_info]
+    bioinfo_run_info = [dict(d) for d in bioinfo_run_info]
+    project_info = [dict(d) for d in project_info]
+    panel_info = json.loads(json.dumps(panel_info))
+    mhap_info = json.loads(json.dumps(mhap_info))
+
+    _replace_names_with_IDs(
+        specimen_info,
+        project_info,
+        library_sample_info,
+        sequencing_info,
+        panel_info,
+        mhap_info,
+        bioinfo_run_info,
+    )
+
+    # Build PMO
+    pmo_header = _generate_pmo_header()
+    pmo = (
+        {
+            "pmo_header": pmo_header,
+            "library_sample_info": library_sample_info,
+            "specimen_info": specimen_info,
+            "sequencing_info": sequencing_info,
+            "bioinformatics_methods_info": bioinfo_method_info,
+            "bioinformatics_run_info": bioinfo_run_info,
+            "project_info": project_info,
+        }
+        | panel_info
+        | mhap_info
+    )
+    return pmo
+
+
+def _make_lookup(dict, key):
+    lookup = {entry[key]: idx for idx, entry in enumerate(dict)}
+    return lookup
+
+
+def _replace_key_with_id(target_list, reference_list, name_key, id_key, lookup=None):
+    """
+    Replaces name_key in target_list with id_key, based on lookup from reference_list.
+    """
+    if not lookup:
+        lookup = _make_lookup(reference_list, name_key)
+    unique_names = set()
+    for entry in target_list:
+        name = str(entry.pop(name_key))
+        unique_names.add(name)
+        entry[id_key] = lookup.get(name)
+    missing_items = list(unique_names - lookup.keys())
+    return missing_items
+
+
+def _generate_pmo_header():
+    today = date.today().isoformat()
+    # TODO: update to grab pmo version - will put this in a seperate PR
+    pmo_header = {
+        "pmo_version": "1.0.0",
+        "creation_date": today,
+        "generation_method": {
+            "program_name": "pmotools-python",
+            "program_version": "1.0.0",
+        },
+    }
+    return pmo_header
+
+
+def _report_missing_IDs(
+    missing_projects,
+    missing_sequencing,
+    missing_specimen,
+    missing_panels,
+    missing_targets,
+    missing_bioinfo_runs,
+    missing_libs,
+):
+    if any(
+        [
+            missing_projects,
+            missing_sequencing,
+            missing_specimen,
+            missing_panels,
+            missing_targets,
+            missing_bioinfo_runs,
+            missing_libs,
+        ]
+    ):
+        error_message = (
+            "The following fields were found in one table and not another:\n"
+        )
+        if missing_projects:
+            error_message += f"Project names in Specimen Info not in Project Info: {missing_projects}\n"
+        if missing_sequencing:
+            error_message += f"Sequencing names in Library Sample Info not in Sequencing Info: {missing_sequencing}\n"
+        if missing_specimen:
+            error_message += f"Specimen names in Library Sample Info not in Specimen Info: {missing_specimen}\n"
+        if missing_panels:
+            error_message += f"Panel names in Library Sample Info not in Panel Info: {missing_panels}\n"
+        if missing_targets:
+            error_message += f"Target names in Representative Microhaplotypes not in Target Info: {missing_targets}\n"
+        if missing_bioinfo_runs:
+            error_message += f"Bioinformatics run names in Detected Microhaplotypes not in Bioinformatic Run Info: {missing_bioinfo_runs}\n"
+        if missing_libs:
+            error_message += f"Library Sample names in Detected Microhaplotypes not in Library Sample Info: {missing_libs}\n"
+        raise ValueError(error_message)
+
+
+def _replace_names_with_IDs(
+    specimen_info,
+    project_info,
+    library_sample_info,
+    sequencing_info,
+    panel_info,
+    mhap_info,
+    bioinfo_run_info,
+):
+    # SPECIMEN INFO
+    # replace name with project ID
+    missing_projects = _replace_key_with_id(
+        specimen_info, project_info, "project_name", "project_id"
+    )
+
+    # LIBRARY SAMPLE INFO
+    # replace with sequencing_info_id, specimen_id, panel_id
+    missing_sequencing = _replace_key_with_id(
+        library_sample_info,
+        sequencing_info,
+        "sequencing_info_name",
+        "sequencing_info_id",
+    )
+    missing_specimen = _replace_key_with_id(
+        library_sample_info, specimen_info, "specimen_name", "specimen_id"
+    )
+    missing_panels = _replace_key_with_id(
+        library_sample_info, panel_info["panel_info"], "panel_name", "panel_id"
+    )
+
+    # REP MHAPS
+    # replace target_name with ID
+    missing_targets = _replace_key_with_id(
+        mhap_info["representative_microhaplotypes"]["targets"],
+        panel_info["target_info"],
+        "target_name",
+        "target_id",
+    )
+
+    # DETECTED MHAPS
+    # Replace library_sample_name and bioinformatics_run_name
+    missing_bioinfo_runs = _replace_key_with_id(
+        mhap_info["detected_microhaplotypes"],
+        bioinfo_run_info,
+        "bioinformatics_run_name",
+        "bioinformatics_run_id",
+    )
+    lib_sample_lookup = _make_lookup(library_sample_info, "library_sample_name")
+    missing_libs = []
+    for detected in mhap_info["detected_microhaplotypes"]:
+        missing_libs += _replace_key_with_id(
+            detected["library_samples"],
+            library_sample_info,
+            "library_sample_name",
+            "library_sample_id",
+            lookup=lib_sample_lookup,
+        )
+
+    # If any names were missing from reference tables error
+    _report_missing_IDs(
+        missing_projects,
+        missing_sequencing,
+        missing_specimen,
+        missing_panels,
+        missing_targets,
+        missing_bioinfo_runs,
+        missing_libs,
+    )