paraphrase 0.1.0__tar.gz

paraphrase-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,5 @@
+# These owners will be the default owners for everything in
+# the repo. Unless a later match takes precedence,
+# @global-owner1 and @global-owner2 will be requested for
+# review when someone opens a pull request.
+* @Clinical-Genomics/rare-disease @dnil

paraphrase-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,13 @@
+## Description
+
+### Added
+
+-
+
+### Changed
+
+-
+
+### Fixed
+
+-

paraphrase-0.1.0/.github/workflows/keep_a_changelog.yml

@@ -0,0 +1,15 @@
+name: "Changelog Reminder"
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review, labeled, unlabeled]
+
+jobs:
+  # Enforces the update of a changelog file on every pull request
+  changelog:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: dangoslen/changelog-enforcer@v3
+        with:
+          changeLogPath: "CHANGELOG.md"
+          skipLabels: "Skip-Changelog"

paraphrase-0.1.0/.github/workflows/linting.yml

@@ -0,0 +1,13 @@
+name: linting
+
+on:
+  - pull_request
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Run prek
+        id: prek
+        uses: j178/prek-action@v1

paraphrase-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,21 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - v*
+
+jobs:
+  pypi:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    # Environment and permissions trusted publishing.
+    environment:
+      name: release
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+      - run: uv build
+      - run: uv publish --trusted-publishing always

paraphrase-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,38 @@
+name: Tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version-file: ".python-version"
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run tests with coverage
+        run: uv run pytest --cov=src --cov-report=xml --cov-report=term
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          file: ./coverage.xml
+          fail_ci_if_error: false

paraphrase-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+data/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

paraphrase-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+repos:
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: "v3.1.0"
+    hooks:
+      - id: prettier
+        additional_dependencies:
+          - prettier
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+        args: [--markdown-linebreak-ext=md]
+      - id: end-of-file-fixer
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.2
+    hooks:
+      - id: ruff-check
+      - id: ruff-format

paraphrase-0.1.0/.prettierignore

@@ -0,0 +1 @@
+test-data/HG*

paraphrase-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

paraphrase-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## v0.1.0 [2026-02-24]
+
+### Added
+
+- [#2](https://github.com/Clinical-Genomics/paraphrase/pull/2) - LICENCE
+- [#2](https://github.com/Clinical-Genomics/paraphrase/pull/2) - Paraphase JSON parsing
+- [#2](https://github.com/Clinical-Genomics/paraphrase/pull/2) - Testing framework
+- [#3](https://github.com/Clinical-Genomics/paraphrase/pull/3) - CHANGELOG and reminder workflow
+- [#3](https://github.com/Clinical-Genomics/paraphrase/pull/3) - CODEOWNERS and PR template
+- [#4](https://github.com/Clinical-Genomics/paraphrase/pull/4) - Paraphase test data
+- [#7](https://github.com/Clinical-Genomics/paraphrase/pull/7) - Release workflow
+- [#11](https://github.com/Clinical-Genomics/paraphrase/pull/11) - Pre-commit hooks and GitHub actions workflow for prettier and ruff
+
+### Changed
+
+- [#8](https://github.com/Clinical-Genomics/paraphrase/pull/8) - Phase regions to output
+- [#9](https://github.com/Clinical-Genomics/paraphrase/pull/9) - Rework nested separators for TSV output
+- [#10](https://github.com/Clinical-Genomics/paraphrase/pull/10) - Updated CODEOWNERS

paraphrase-0.1.0/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Felix Lenner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

paraphrase-0.1.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: paraphrase
+Version: 0.1.0
+Summary: Parse paraphase JSONs
+Author-email: Felix Lenner <felix.lenner@scilifelab.se>
+License: MIT License
+License-File: LICENCE
+Requires-Python: >=3.12
+Requires-Dist: coloredlogs>=15.0.1
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: typer>=0.20.0
+Description-Content-Type: text/markdown
+
+# Paraphrase
+
+Parse paraphase JSONs.
+
+## Usage
+
+```
+ Usage: paraphrase [OPTIONS]
+
+ Parse paraphase JSONs.
+
+╭─ Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ *  --input          -f      FILE  Input JSON files (can be multiple) [required]                                                               │
+│ *  --sample         -s      TEXT  Sample names corresponding to input JSON files [required]                                                   │
+│    --rules          -r      FILE  Optional YAML file with per-gene classification rules (adds 'status' fields)                                │
+│    --skip-keys              TEXT  Comma-separated keys to skip (e.g. region_depth,final_haplotypes)                                           │
+│    --genes                  TEXT  Optional comma-separated list of gene names to process                                                      │
+│    --output-format  -o      TEXT  Output format: 'json' (default) or 'tsv' [default: json]                                                    │
+│    --help                         Show this message and exit.                                                                                 │
+╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+```
+
+Example command:
+
+```
+uv run paraphrase \
+    --input test-data/HG002.paraphase.json \
+    --input test-data/HG003.paraphase.json \
+    --input test-data/HG004.paraphase.json \
+    --sample HG002 \
+    --sample HG003 \
+    --sample HG004 \
+    --rules test-data/rules.yaml \
+    --genes CFH,CFHR3,f8,GBA,hba,ikbkg,ncf1,neb,opn1lw,pms2,rccx,smn1,strc
+```
+
+## Rules YAML (per-gene status classification)
+
+Rules are evaluated per gene. Conditions within a single `when` mapping are
+combined with logical AND (all must be true). If multiple rules match, you can
+provide a `status_order` to pick the most severe (last wins by order).
+
+Example:
+
+```yaml
+smn1:
+  # Optional; defaults to "normal" if omitted
+  default_status: normal
+  # Optional; defaults to [normal, intermediate, pathological] if omitted
+  status_order: [normal, intermediate, pathological]
+  rules:
+    - status: intermediate
+      when:
+        smn1_cn: 0
+        smn2_cn: { ">=": 4 }
+      reason: "SMN1 deleted but SMN2 high"
+    - status: pathological
+      when:
+        smn1_cn: { "<": 2 }
+      reason: "SMN1 copy number low"
+```

paraphrase-0.1.0/README.md

@@ -0,0 +1,61 @@
+# Paraphrase
+
+Parse paraphase JSONs.
+
+## Usage
+
+```
+ Usage: paraphrase [OPTIONS]
+
+ Parse paraphase JSONs.
+
+╭─ Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ *  --input          -f      FILE  Input JSON files (can be multiple) [required]                                                               │
+│ *  --sample         -s      TEXT  Sample names corresponding to input JSON files [required]                                                   │
+│    --rules          -r      FILE  Optional YAML file with per-gene classification rules (adds 'status' fields)                                │
+│    --skip-keys              TEXT  Comma-separated keys to skip (e.g. region_depth,final_haplotypes)                                           │
+│    --genes                  TEXT  Optional comma-separated list of gene names to process                                                      │
+│    --output-format  -o      TEXT  Output format: 'json' (default) or 'tsv' [default: json]                                                    │
+│    --help                         Show this message and exit.                                                                                 │
+╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+```
+
+Example command:
+
+```
+uv run paraphrase \
+    --input test-data/HG002.paraphase.json \
+    --input test-data/HG003.paraphase.json \
+    --input test-data/HG004.paraphase.json \
+    --sample HG002 \
+    --sample HG003 \
+    --sample HG004 \
+    --rules test-data/rules.yaml \
+    --genes CFH,CFHR3,f8,GBA,hba,ikbkg,ncf1,neb,opn1lw,pms2,rccx,smn1,strc
+```
+
+## Rules YAML (per-gene status classification)
+
+Rules are evaluated per gene. Conditions within a single `when` mapping are
+combined with logical AND (all must be true). If multiple rules match, you can
+provide a `status_order` to pick the most severe (last wins by order).
+
+Example:
+
+```yaml
+smn1:
+  # Optional; defaults to "normal" if omitted
+  default_status: normal
+  # Optional; defaults to [normal, intermediate, pathological] if omitted
+  status_order: [normal, intermediate, pathological]
+  rules:
+    - status: intermediate
+      when:
+        smn1_cn: 0
+        smn2_cn: { ">=": 4 }
+      reason: "SMN1 deleted but SMN2 high"
+    - status: pathological
+      when:
+        smn1_cn: { "<": 2 }
+      reason: "SMN1 copy number low"
+```

paraphrase-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "paraphrase"
+version = "0.1.0"
+description = "Parse paraphase JSONs"
+authors = [{name="Felix Lenner", email="felix.lenner@scilifelab.se"}]
+license = {text = "MIT License"}
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "coloredlogs>=15.0.1",
+    "pyyaml>=6.0.3",
+    "typer>=0.20.0",
+]
+
+[project.scripts]
+paraphrase = "paraphrase.main:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "pytest-cov>=7.0.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov=src --cov-report=term-missing --cov-report=html"
+
+[tool.coverage.run]
+source = ["src"]
+omit = ["*/tests/*", "*/__pycache__/*"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+]

paraphrase-0.1.0/src/__init__.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+__version__ = version("paraphrase")

paraphrase-0.1.0/src/paraphrase/__init__.py

@@ -0,0 +1 @@
+from .main import main as main

paraphrase-0.1.0/src/paraphrase/config.py

@@ -0,0 +1,17 @@
+from dataclasses import dataclass
+from typing import List, Optional, Set, Dict, Any
+
+
+@dataclass
+class ProcessingConfig:
+    """
+    Configuration for how to process paraphase JSONs.
+
+    - skip_keys: keys under each gene that should be ignored entirely.
+    - genes_list: optional list of genes to keep; if None, keep all.
+    - rules: optional per-gene classification rules YAML structure.
+    """
+
+    skip_keys: Set[str]
+    genes_list: Optional[List[str]] = None
+    rules: Optional[Dict[str, Any]] = None

paraphrase-0.1.0/src/paraphrase/constants.py

@@ -0,0 +1,34 @@
+DEFAULT_SKIP_KEYS: frozenset[str] = frozenset(
+    [
+        "alleles_all_haplotypes",
+        "assembled_haplotypes",
+        "del_read_number",
+        "directional_links",
+        "final_haplotypes",
+        "first_copies",
+        "flanking_summary",
+        "gene_reads",
+        "haplotype_details",
+        "haplotype_links",
+        "het_sites_not_used_in_phasing",
+        "heterozygous_sites",
+        "highest_total_cn",
+        "homozygous_sites",
+        "intergenic_depth",
+        "last_copies",
+        "links_loose",
+        "linked_haplotypes",
+        "middle_copies",
+        "nonunique_supporting_reads",
+        "phasing_success",
+        "pseudo_reads",
+        "raw_alleles",
+        "read_details",
+        "sample_sex",
+        "smn1_read_number",
+        "smn2_read_number",
+        "smn_del78_read_number",
+        "sites_for_phasing",
+        "unique_supporting_reads",
+    ]
+)

paraphrase-0.1.0/src/paraphrase/exceptions.py

@@ -0,0 +1,28 @@
+class InputMismatchError(Exception):
+    """Raised when the number of input files does not match the number of sample names."""
+
+    pass
+
+
+class YAMLLoadError(Exception):
+    """Raised when a YAML file cannot be loaded."""
+
+    pass
+
+
+class JSONLoadError(Exception):
+    """Raised when a JSON file cannot be loaded."""
+
+    pass
+
+
+class InvalidOperatorError(Exception):
+    """Raised when an invalid operator is encountered in normal value processing."""
+
+    pass
+
+
+class ListOpNotSupportedError(Exception):
+    """Raised when an unsupported operation is attempted on a list."""
+
+    pass

paraphrase-0.1.0/src/paraphrase/io.py

@@ -0,0 +1,108 @@
+from pathlib import Path
+import coloredlogs
+import yaml
+import json
+import logging
+from .exceptions import JSONLoadError, YAMLLoadError
+from typing import Dict
+
+coloredlogs.install(level="INFO")
+logging.basicConfig(level=logging.DEBUG)
+logger = logging.getLogger(__name__)
+
+
+def load_yaml(file: Path):
+    try:
+        with file.open("r", encoding="utf-8") as f:
+            return yaml.safe_load(f)
+    except Exception as e:
+        raise YAMLLoadError(f"Failed to read YAML file {file}: {e}")
+
+
+def load_json(file: Path):
+    """Load one JSON file and process its contents."""
+    try:
+        with file.open("r", encoding="utf-8") as f:
+            return json.load(f)
+    except Exception as e:
+        raise JSONLoadError(f"Failed to read JSON file {file}: {e}")
+
+
+def print_tsv(json_data: Dict) -> None:
+    """
+    Print results in TSV format.
+    """
+    print("sample\tlocus\tstatus\tmetric\tvalue")
+
+    for sample, locus in json_data.items():
+        for locus, locus_info in locus.items():
+            # Gene-level status comes from the rules engine; if no rules were
+            # defined or no status was set, report it as "unknown"
+            locus_status = locus_info.get("status")
+            if not isinstance(locus_status, str):
+                locus_status = "unknown"
+
+            # Iterate over locus information, e.g. region_depth, final_haplotypes, etc.
+            for locus_metric, locus_metric_value in locus_info.items():
+                # Do not emit the per-gene status or rule-match metadata as separate rows
+                if locus_metric in {"status", "status_matches"}:
+                    continue
+                prettified_value = stringify_value(locus_metric_value)
+                print(
+                    f"{sample}\t{locus}\t{locus_status}\t{locus_metric}\t{prettified_value}"
+                )
+
+
+def stringify_value(content) -> str | None:
+    """
+    Flatten nested dicts/lists for TSV output.
+
+    Rules:
+        - Skip empty or None values.
+        - Dicts: key:value for top-level, key=subkey=subvalue for nested dicts
+        - Lists:
+            * Lists of simple values (str, int, float) are joined by commas.
+            * Lists of lists -> join inner list by '|', then outer by ','
+    """
+    if content in (None, [], {}):
+        return None
+
+    if isinstance(content, (int, float, str)):
+        return str(content)
+
+    if isinstance(content, list):
+        # If it's a list of simple values, join by commas
+        if all(not isinstance(item, list) for item in content):
+            flat = [str(element) for element in content if element is not None]
+            return ",".join(flat) if flat else None
+        else:
+            # Lists with sublists
+            flat = []
+            for item in content:
+                if isinstance(item, list):
+                    if inner := [
+                        str(element) for element in item if element is not None
+                    ]:
+                        flat.append("|".join(inner))
+                    elif item is not None:
+                        flat.append(str(item))
+            return ",".join(flat) if flat else None
+
+    if isinstance(content, dict):
+        flat = []
+        for key, value in content.items():
+            if value in (None, [], {}):
+                continue
+            if isinstance(value, dict):
+                sub_items = []
+                for subkey, subvalue in value.items():
+                    if prettified_subvalue := stringify_value(subvalue):
+                        sub_items.append(f"{subkey}={prettified_subvalue}")
+                if sub_items:
+                    flat.append(f"{key}:{'|'.join(sub_items)}")
+            else:
+                if prettified_string := stringify_value(value):
+                    flat.append(f"{key}:{prettified_string}")
+        return ",".join(flat) if flat else None
+
+    return str(content)

paraphrase-0.1.0/src/paraphrase/main.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+import json
+from pathlib import Path
+from typing import List, Optional
+import typer
+from .constants import DEFAULT_SKIP_KEYS
+from .pipeline import merge_and_process, assert_equal_inputs_and_samples
+from .io import load_json, load_yaml, print_tsv
+from .exceptions import InputMismatchError
+from .config import ProcessingConfig
+
+app = typer.Typer(
+    rich_markup_mode="rich",
+    invoke_without_command=True,
+    pretty_exceptions_show_locals=False,
+    add_completion=False,
+    help="Call coverage drops over alleles in STR VCFs",
+)
+
+
+@app.command()
+def main(
+    input: List[Path] = typer.Option(
+        ...,
+        "--input",
+        "-f",
+        exists=True,
+        file_okay=True,
+        dir_okay=False,
+        help="Input JSON files (can be multiple)",
+    ),
+    sample: List[str] = typer.Option(
+        ...,
+        "--sample",
+        "-s",
+        help="Sample names corresponding to input JSON files",
+    ),
+    rules_yaml: Optional[Path] = typer.Option(
+        None,
+        "--rules",
+        "-r",
+        exists=True,
+        file_okay=True,
+        dir_okay=False,
+        help="Optional YAML file with per-gene classification rules (adds 'status' fields)",
+    ),
+    skip_keys: str = typer.Option(
+        None, help="Comma-separated keys to skip (e.g. region_depth,final_haplotypes)"
+    ),
+    genes: Optional[str] = typer.Option(
+        None, help="Optional comma-separated list of gene names to process"
+    ),
+    output_format: str = typer.Option(
+        "json", "--output-format", "-o", help="Output format: 'json' (default) or 'tsv'"
+    ),
+):
+    """
+    Parse paraphase JSONs.
+    """
+    try:
+        # Parse and validate parameters
+        skip_keys_list = (
+            [k.strip() for k in skip_keys.split(",")]
+            if skip_keys
+            else list(DEFAULT_SKIP_KEYS)
+        )
+        genes_list = [g.strip().lower() for g in genes.split(",")] if genes else None
+        assert_equal_inputs_and_samples(input, sample)
+
+        # Get input files
+        rules = load_yaml(rules_yaml) if rules_yaml else None
+        json_data_list = [load_json(f) for f in input]
+
+        config = ProcessingConfig(
+            skip_keys=set(skip_keys_list),
+            genes_list=genes_list,
+            rules=rules,
+        )
+
+        merged_data = merge_and_process(json_data_list, sample, config)
+
+        if output_format.lower() == "tsv":
+            print_tsv(merged_data)
+        else:
+            typer.echo(json.dumps(merged_data, indent=2))
+    except InputMismatchError as e:
+        typer.echo(f"[error] {e}", err=True)
+        raise typer.Exit(code=1)
+
+
+if __name__ == "__main__":
+    app()