sabr-kit 0.4.3.dev1__tar.gz → 0.4.4__tar.gz

{sabr_kit-0.4.3.dev1 → sabr_kit-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sabr-kit
-Version: 0.4.3.dev1
+Version: 0.4.4
 Summary: Structure-based Antibody Renumbering
 Project-URL: Homepage, https://github.com/delalamo/sabr
 Project-URL: Issues, https://github.com/delalamo/sabr/issues
@@ -31,7 +31,6 @@ Requires-Python: >=3.11
 Requires-Dist: biopython<2,>=1.87
 Requires-Dist: click<9,>=8.4.2
 Requires-Dist: dm-haiku<0.1,>=0.0.16
-Requires-Dist: gemmi<1,>=0.7.5
 Requires-Dist: jax<0.11,>=0.10.2
 Requires-Dist: jaxlib<0.11,>=0.10.2
 Requires-Dist: numpy<3,>=2.4.6
@@ -78,6 +77,7 @@ sabr -i INPUT -c CHAIN -o OUTPUT
      [-m sabr|softalign]
      [--residue-range START END]
      [--scfv]
+     [--no-mmcif]
      [--overwrite] [-v]
 ```
 
@@ -99,13 +99,15 @@ already specifies both domain types, scFv mode requires automatic chain type.
 Composite references use the selected parameter mode, so `--scfv` can be
 combined with `--mode softalign`.
 
-Input and output may be PDB (`.pdb`) or mmCIF (`.cif` or `.mmcif`). Use mmCIF
-when chain names or ANARCI insertion codes exceed PDB's one-character fields.
-Writes are atomic, so a failed run does not leave a partial output.
+Input and output may be PDB (`.pdb`) or mmCIF (`.cif` or `.mmcif`). When a
+requested PDB output needs multi-character insertion codes, SAbR warns and
+automatically writes it to the corresponding `.cif` path instead. Pass
+`--no-mmcif` to forbid this conversion and fail. Other values that exceed PDB
+field limits still require an explicitly named mmCIF output. Writes are atomic,
+so a failed run does not leave a partial output.
 
 CLI conversion guarantees preservation of atomic structure content, not
-arbitrary non-atomic mmCIF categories. It warns for every mmCIF input. When
-those categories matter, load a Gemmi structure and use the in-memory API.
+arbitrary non-atomic mmCIF categories. It warns for every mmCIF input.
 
 ## Python API
 
@@ -117,38 +119,19 @@ structure = PDBParser(QUIET=True).get_structure("antibody", "antibody.pdb")
 numbered = renumber_structure(structure, chain="H")
 ```
 
-Gemmi structures use the same function:
+`renumber_structure` accepts a Biopython `Structure`, never mutates its input,
+and returns a new Biopython `Structure`. Non-target chains, hetero residues,
+waters, and residues outside an inclusive `residue_range` are preserved. SAbR
+rejects multi-model structures rather than silently modifying only one model.
+If a partial range would create duplicate residue IDs with unchanged residues,
+the operation fails with an explanation.
 
-```python
-import gemmi
-from sabr import renumber_structure
-
-structure = gemmi.read_structure("antibody.cif")
-numbered = renumber_structure(
-    structure,
-    chain="heavy_chain",
-    scheme="chothia",
-    chain_type="auto",
-    noise_level=0.0,
-    mode="softalign",
-    residue_range=None,
-    scfv=False,
-)
-```
-
-`renumber_structure` never mutates its input and returns the same concrete
-structure type. Non-target chains, hetero residues, waters, and residues
-outside an inclusive `residue_range` are preserved. SAbR rejects multi-model
-structures rather than silently modifying only one model. If a partial range
-would create duplicate residue IDs with unchanged residues, the operation
-fails with an explanation.
-
-The same-type clone preserves metadata represented by the input BioPython or
-Gemmi object. Alternate conformers are normalized deterministically: a
-complete blank-altloc backbone is preferred, then the complete conformer with
-the greatest summed occupancy, with altloc name as the final tie-breaker.
-Selections above 1,024 polymer residues are rejected before quadratic model
-work; use `residue_range` to select the antibody domain.
+The copy preserves metadata represented by the input Biopython object.
+Alternate conformers are normalized deterministically: a complete blank-altloc
+backbone is preferred, then the complete conformer with the greatest summed
+occupancy, with altloc name as the final tie-breaker. Selections above 1,024
+polymer residues are rejected before quadratic model work; use
+`residue_range` to select the antibody domain.
 
 Modified peptide residues are translated only for sequence generation. Their
 original names and atoms remain unchanged. The committed mapping was generated
@@ -159,9 +142,7 @@ contains only peptide-linking components with exactly one canonical amino-acid
 parent. Unsupported or ambiguous polymer chemistry fails explicitly; no
 runtime network access occurs.
 
-Gemmi itself only represents one-character insertion codes. For unusually
-long loops that need extended codes, use a BioPython structure in memory or
-the CLI with mmCIF output.
+For unusually long loops that need extended insertion codes, use mmCIF output.
 
 ## Scientific behavior
 

{sabr_kit-0.4.3.dev1 → sabr_kit-0.4.4}/README.md

@@ -34,6 +34,7 @@ sabr -i INPUT -c CHAIN -o OUTPUT
      [-m sabr|softalign]
      [--residue-range START END]
      [--scfv]
+     [--no-mmcif]
      [--overwrite] [-v]
 ```
 
@@ -55,13 +56,15 @@ already specifies both domain types, scFv mode requires automatic chain type.
 Composite references use the selected parameter mode, so `--scfv` can be
 combined with `--mode softalign`.
 
-Input and output may be PDB (`.pdb`) or mmCIF (`.cif` or `.mmcif`). Use mmCIF
-when chain names or ANARCI insertion codes exceed PDB's one-character fields.
-Writes are atomic, so a failed run does not leave a partial output.
+Input and output may be PDB (`.pdb`) or mmCIF (`.cif` or `.mmcif`). When a
+requested PDB output needs multi-character insertion codes, SAbR warns and
+automatically writes it to the corresponding `.cif` path instead. Pass
+`--no-mmcif` to forbid this conversion and fail. Other values that exceed PDB
+field limits still require an explicitly named mmCIF output. Writes are atomic,
+so a failed run does not leave a partial output.
 
 CLI conversion guarantees preservation of atomic structure content, not
-arbitrary non-atomic mmCIF categories. It warns for every mmCIF input. When
-those categories matter, load a Gemmi structure and use the in-memory API.
+arbitrary non-atomic mmCIF categories. It warns for every mmCIF input.
 
 ## Python API
 
@@ -73,38 +76,19 @@ structure = PDBParser(QUIET=True).get_structure("antibody", "antibody.pdb")
 numbered = renumber_structure(structure, chain="H")
 ```
 
-Gemmi structures use the same function:
+`renumber_structure` accepts a Biopython `Structure`, never mutates its input,
+and returns a new Biopython `Structure`. Non-target chains, hetero residues,
+waters, and residues outside an inclusive `residue_range` are preserved. SAbR
+rejects multi-model structures rather than silently modifying only one model.
+If a partial range would create duplicate residue IDs with unchanged residues,
+the operation fails with an explanation.
 
-```python
-import gemmi
-from sabr import renumber_structure
-
-structure = gemmi.read_structure("antibody.cif")
-numbered = renumber_structure(
-    structure,
-    chain="heavy_chain",
-    scheme="chothia",
-    chain_type="auto",
-    noise_level=0.0,
-    mode="softalign",
-    residue_range=None,
-    scfv=False,
-)
-```
-
-`renumber_structure` never mutates its input and returns the same concrete
-structure type. Non-target chains, hetero residues, waters, and residues
-outside an inclusive `residue_range` are preserved. SAbR rejects multi-model
-structures rather than silently modifying only one model. If a partial range
-would create duplicate residue IDs with unchanged residues, the operation
-fails with an explanation.
-
-The same-type clone preserves metadata represented by the input BioPython or
-Gemmi object. Alternate conformers are normalized deterministically: a
-complete blank-altloc backbone is preferred, then the complete conformer with
-the greatest summed occupancy, with altloc name as the final tie-breaker.
-Selections above 1,024 polymer residues are rejected before quadratic model
-work; use `residue_range` to select the antibody domain.
+The copy preserves metadata represented by the input Biopython object.
+Alternate conformers are normalized deterministically: a complete blank-altloc
+backbone is preferred, then the complete conformer with the greatest summed
+occupancy, with altloc name as the final tie-breaker. Selections above 1,024
+polymer residues are rejected before quadratic model work; use
+`residue_range` to select the antibody domain.
 
 Modified peptide residues are translated only for sequence generation. Their
 original names and atoms remain unchanged. The committed mapping was generated
@@ -115,9 +99,7 @@ contains only peptide-linking components with exactly one canonical amino-acid
 parent. Unsupported or ambiguous polymer chemistry fails explicitly; no
 runtime network access occurs.
 
-Gemmi itself only represents one-character insertion codes. For unusually
-long loops that need extended codes, use a BioPython structure in memory or
-the CLI with mmCIF output.
+For unusually long loops that need extended insertion codes, use mmCIF output.
 
 ## Scientific behavior
 

{sabr_kit-0.4.3.dev1 → sabr_kit-0.4.4}/pyproject.toml

@@ -17,7 +17,6 @@ authors = [
 dependencies = [
   "biopython>=1.87,<2",
   "click>=8.4.2,<9",
-  "gemmi>=0.7.5,<1",
   "jax>=0.10.2,<0.11",
   "jaxlib>=0.10.2,<0.11",
   "numpy>=2.4.6,<3",

{sabr_kit-0.4.3.dev1 → sabr_kit-0.4.4}/src/sabr/alignment.py

@@ -162,12 +162,12 @@ def load_references(
     with path.open("rb") as handle:
         data = np.load(handle, allow_pickle=True)["arr_0"].item()
     references = {}
-    for chain_type in constants.CHAIN_TYPES:
-        embeddings = np.asarray(data[chain_type]["array"])
+    for chain_type, reference in data.items():
+        embeddings = np.asarray(reference["array"])
         embeddings.flags.writeable = False
         references[chain_type] = (
             embeddings,
-            tuple(int(position) for position in data[chain_type]["idxs"]),
+            tuple(int(position) for position in reference["idxs"]),
         )
 
     if scfv:

sabr_kit-0.4.4/src/sabr/api.py

@@ -0,0 +1,159 @@
+"""The public, in-memory SAbR API."""
+
+import logging
+from dataclasses import dataclass
+
+from sabr import constants
+from sabr.alignment import align, load_references
+from sabr.model import encode
+from sabr.numbering import number_alignment
+from sabr.structure import apply_numbering, extract_chain
+
+LOGGER = logging.getLogger(__name__)
+
+
+def _normalize_choice(value: str, name: str, choices: tuple[str, ...]) -> str:
+    """Normalize a case-insensitive string constrained to known choices."""
+    if not isinstance(value, str) or value.lower() not in choices:
+        raise ValueError(f"{name} must be one of {', '.join(choices)}.")
+    return value.lower()
+
+
+def _normalize_chain_type(
+    chain_type: str,
+    noise_level: float,
+    mode: str,
+) -> str:
+    if not isinstance(chain_type, str):
+        raise ValueError("chain_type must be a reference type or 'auto'.")
+    normalized = "auto" if chain_type.lower() == "auto" else chain_type.upper()
+    if normalized == "auto":
+        return normalized
+
+    reference_types = tuple(load_references(noise_level, mode))
+    if normalized not in reference_types:
+        choices = ", ".join(("auto", *reference_types))
+        raise ValueError(f"chain_type must be one of {choices}.")
+    return normalized
+
+
+def _normalize_noise_level(noise_level: float) -> float:
+    if isinstance(noise_level, bool):
+        raise ValueError(
+            f"noise_level must be one of {constants.NOISE_LEVELS}."
+        )
+    try:
+        normalized_noise = float(noise_level)
+    except (TypeError, ValueError) as error:
+        raise ValueError(
+            f"noise_level must be one of {constants.NOISE_LEVELS}."
+        ) from error
+    if normalized_noise not in constants.NOISE_LEVELS:
+        raise ValueError(
+            f"noise_level must be one of {constants.NOISE_LEVELS}."
+        )
+    return normalized_noise
+
+
+def _validate_residue_range(
+    residue_range: tuple[int, int] | None,
+) -> None:
+    """Validate inclusive structure residue-number bounds.
+
+    The bounds are compared with BioPython ``residue.id[1]`` or Gemmi
+    ``residue.seqid.num``. They are residue numbers from the input structure,
+    not zero-based sequence or array indices, and need not begin at one or be
+    contiguous. Every insertion-code variant sharing a selected residue number
+    is included.
+    """
+    if residue_range is None:
+        return
+    error = "residue_range must be an inclusive (start, end) tuple."
+    if not isinstance(residue_range, tuple):
+        raise ValueError(error)
+    if len(residue_range) != 2:
+        raise ValueError(error)
+    if not all(
+        isinstance(value, int) and not isinstance(value, bool)
+        for value in residue_range
+    ):
+        raise ValueError(error)
+    if residue_range[0] > residue_range[1]:
+        raise ValueError("residue_range start must not exceed its end.")
+
+
+@dataclass(slots=True)
+class _RenumberOptions:
+    """Validated and normalized arguments for one renumbering operation."""
+
+    scheme: str
+    chain_type: str
+    noise_level: float
+    residue_range: tuple[int, int] | None
+    mode: str
+    scfv: bool
+
+    def __post_init__(self) -> None:
+        self.scheme = _normalize_choice(
+            self.scheme, "scheme", constants.NUMBERING_SCHEMES
+        )
+        self.noise_level = _normalize_noise_level(self.noise_level)
+        self.mode = _normalize_choice(self.mode, "mode", constants.MODES)
+        self.chain_type = _normalize_chain_type(
+            self.chain_type,
+            self.noise_level,
+            self.mode,
+        )
+        _validate_residue_range(self.residue_range)
+        if not isinstance(self.scfv, bool):
+            raise ValueError("scfv must be a boolean.")
+        if self.scfv and self.chain_type != "auto":
+            raise ValueError("scfv requires chain_type='auto'.")
+
+
+def renumber_structure(
+    structure,
+    chain: str,
+    scheme: str = "imgt",
+    chain_type: str = "auto",
+    noise_level: float = 0.0,
+    residue_range: tuple[int, int] | None = None,
+    mode: str = "sabr",
+    scfv: bool = False,
+):
+    """Return a renumbered copy of a Biopython structure.
+
+    ``mode="softalign"`` selects the SoftAlign encoder, references, and gap
+    penalties as one scientifically consistent parameter set. ``scfv=True``
+    adds the four supported two-domain composite references.
+    """
+    options = _RenumberOptions(
+        scheme=scheme,
+        chain_type=chain_type,
+        noise_level=noise_level,
+        residue_range=residue_range,
+        mode=mode,
+        scfv=scfv,
+    )
+    data = extract_chain(structure, chain, options.residue_range)
+    embeddings = encode(data.coords, options.mode)
+    imgt_alignment, selected_type, score = align(
+        embeddings,
+        data.gap_indices,
+        options.chain_type,
+        options.noise_level,
+        mode=options.mode,
+        scfv=options.scfv,
+    )
+    LOGGER.info(
+        "Selected %s reference with alignment score %.4f.",
+        selected_type,
+        score,
+    )
+    numbered = number_alignment(
+        imgt_alignment,
+        data.sequence,
+        options.scheme,
+        selected_type,
+    )
+    return apply_numbering(structure, chain, data, numbered)

{sabr_kit-0.4.3.dev1 → sabr_kit-0.4.4}/src/sabr/cli.py

@@ -51,6 +51,22 @@ def _validate_pdb_output(structure) -> None:
                 )
 
 
+def _has_extended_insertion_codes(structure) -> bool:
+    return any(
+        len(residue.id[2].strip()) > 1 for residue in structure.get_residues()
+    )
+
+
+def _resolve_output_path(structure, path: Path, no_mmcif: bool = False) -> Path:
+    if (
+        path.suffix.lower() == ".pdb"
+        and not no_mmcif
+        and _has_extended_insertion_codes(structure)
+    ):
+        return path.with_suffix(".cif")
+    return path
+
+
 def _write_structure(structure, path: Path) -> None:
     suffix = path.suffix.lower()
     if suffix == ".pdb":
@@ -122,6 +138,11 @@ def _write_structure(structure, path: Path) -> None:
     is_flag=True,
     help="Also try H:K, H:L, K:H, and L:H composite references.",
 )
+@click.option(
+    "--no-mmcif",
+    is_flag=True,
+    help="Forbid automatic mmCIF output for extended insertion codes.",
+)
 @click.option("--overwrite", is_flag=True)
 @click.option("-v", "--verbose", is_flag=True)
 def main(
@@ -134,6 +155,7 @@ def main(
     mode: str,
     residue_range: tuple | None,
     scfv: bool,
+    no_mmcif: bool,
     overwrite: bool,
     verbose: bool,
 ) -> None:
@@ -143,22 +165,13 @@ def main(
         format="%(levelname)s: %(message)s",
         force=True,
     )
-    if output_path.exists() and not overwrite:
-        raise click.ClickException(
-            f"Output already exists: {output_path}. "
-            "Use --overwrite to replace it."
-        )
-
-    temporary = output_path.with_name(
-        f".{output_path.stem}.{uuid.uuid4().hex}.tmp{output_path.suffix}"
-    )
+    temporary = None
     try:
         structure = _read_structure(input_path)
         if input_path.suffix.lower() in (".cif", ".mmcif"):
             LOGGER.warning(
-                "Non-atomic mmCIF categories may not be preserved by CLI "
-                "conversion; use the in-memory Gemmi API when metadata "
-                "preservation is required."
+                "Non-atomic mmCIF categories are not preserved when parsed "
+                "with Biopython."
             )
         LOGGER.info("JAX backend: %s", jax.default_backend())
         result = renumber_structure(
@@ -171,12 +184,31 @@ def main(
             residue_range=residue_range,
             scfv=scfv,
         )
+        resolved_output_path = _resolve_output_path(
+            result, output_path, no_mmcif=no_mmcif
+        )
+        if resolved_output_path.exists() and not overwrite:
+            raise click.ClickException(
+                f"Output already exists: {resolved_output_path}. "
+                "Use --overwrite to replace it."
+            )
+        if resolved_output_path != output_path:
+            LOGGER.warning(
+                "PDB cannot represent multi-character insertion codes; "
+                "automatically saving mmCIF output to %s. Use --no-mmcif "
+                "to forbid this behavior.",
+                resolved_output_path,
+            )
+        temporary = resolved_output_path.with_name(
+            f".{resolved_output_path.stem}.{uuid.uuid4().hex}"
+            f".tmp{resolved_output_path.suffix}"
+        )
         _write_structure(result, temporary)
-        os.replace(temporary, output_path)
+        os.replace(temporary, resolved_output_path)
     except click.ClickException:
         raise
     except Exception as error:
-        if temporary.exists():
+        if temporary is not None and temporary.exists():
             try:
                 temporary.unlink()
             except OSError as cleanup_error: