dense-arrays 0.2.0__tar.gz

dense_arrays-0.2.0/CITATION.cff

@@ -0,0 +1,12 @@
+cff-version: 1.2.0
+message: Cite Dense Arrays and retain the exact release or source revision used.
+type: software
+title: Dense Arrays
+authors:
+  - family-names: Andreani
+    given-names: Virgile
+  - family-names: South
+    given-names: Eric J.
+repository-code: https://github.com/e-south/dense-arrays
+url: https://dunloplab.gitlab.io/dense-arrays
+license: MIT

dense_arrays-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Dunlop lab
+
+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.

dense_arrays-0.2.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include CITATION.cff
+include docs/assets/dense-arrays-banner.png

dense_arrays-0.2.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: dense-arrays
+Version: 0.2.0
+Summary: A library to create densely packed DNA arrays from motifs
+Author-email: Virgile Andreani <andreani@bu.edu>, Eric J South <ericjohnsouth@gmail.com>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/e-south/dense-arrays
+Project-URL: Documentation, https://dunloplab.gitlab.io/dense-arrays
+Project-URL: Issues, https://github.com/e-south/dense-arrays/issues
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.25.2
+Requires-Dist: ortools>=9.7.2996
+Requires-Dist: rich>=13.7.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: playback
+Requires-Dist: matplotlib>=3.8.0; extra == "playback"
+Requires-Dist: networkx>=3.6.1; extra == "playback"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6.1; extra == "docs"
+Requires-Dist: mkdocs-material>=9.7.3; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=1.0.3; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: pre-commit>=4.5.1; extra == "dev"
+Requires-Dist: pip-audit>=2.10.0; extra == "dev"
+Requires-Dist: pytest>=9.0.3; extra == "dev"
+Requires-Dist: ruff>=0.14.14; extra == "dev"
+Dynamic: license-file
+
+# ![Dense Arrays — overlapping motifs within a sequence-length limit](https://raw.githubusercontent.com/e-south/dense-arrays/v0.2.0/docs/assets/dense-arrays-banner.png)
+
+[![CI](https://github.com/e-south/dense-arrays/actions/workflows/ci.yml/badge.svg)](https://github.com/e-south/dense-arrays/actions/workflows/ci.yml)
+[![docs](https://img.shields.io/badge/docs-gitlab_pages-blue)](https://dunloplab.gitlab.io/dense-arrays)
+
+Pack overlapping DNA motifs into a sequence-length limit. Dense Arrays selects
+an arrangement and returns the sequence and each motif's position, so you can
+inspect the overlaps or generate further solutions. Choose single- or
+double-strand placement, require motif groups, or constrain positions.
+
+The package also renders saved placements as images and video. [Watch the
+worked playback](https://dunloplab.gitlab.io/dense-arrays/playback/#watch-four-overlapping-motifs)
+to see how four motifs share sequence space.
+
+## First array
+
+With Python 3.12 or later and [uv](https://docs.astral.sh/uv/), run from a
+[source checkout](https://github.com/e-south/dense-arrays/blob/main/docs/quickstart.md#install-from-source):
+
+```bash
+uv sync --frozen
+uv run dense-arrays optimize \
+  --motif ACGTTGCAAGTCCTGA \
+  --motif AGTCCTGATCGTACCG \
+  --motif TCGTACCGATGCTTAG \
+  --motif ATGCTTAGGACGTTCA \
+  --length 40 --strands double
+```
+
+The search considers both strands. One optimal arrangement packs all four
+16-base motifs into 40 bases:
+
+```text
+ACGTTGCAAGTCCTGATCGTACCGATGCTTAGGACGTTCA
+```
+
+In this orientation, the motifs start at 0, 8, 16, and 24. The solver may return
+the reverse-complement arrangement. The
+[quickstart](https://github.com/e-south/dense-arrays/blob/main/docs/quickstart.md) explains these offsets and shows Python use
+and bounded enumeration of further solutions.
+
+## Documentation
+
+- [Create and read your first array](https://github.com/e-south/dense-arrays/blob/main/docs/quickstart.md).
+- [Set positional and regulator constraints](https://github.com/e-south/dense-arrays/blob/main/docs/constraints.md).
+- [Render saved placements as images or video](https://github.com/e-south/dense-arrays/blob/main/docs/playback.md).
+- [Understand the packing method](https://github.com/e-south/dense-arrays/blob/main/docs/method.md).
+- [Look up Python interfaces](https://github.com/e-south/dense-arrays/blob/main/docs/api.md).
+- [Update an existing caller](https://github.com/e-south/dense-arrays/blob/main/docs/migration.md).
+
+The [documentation index](https://github.com/e-south/dense-arrays/blob/main/docs/index.md) also routes integrators and
+contributors to the relevant interfaces and checks.
+
+## Citation
+
+If you use Dense Arrays in your research, please cite:
+
+Andreani V, South EJ, Dunlop MJ (2024). Generating information-dense promoter
+sequences with optimal string packing. *PLOS Computational Biology* 20(7):
+e1012276. [doi:10.1371/journal.pcbi.1012276](https://doi.org/10.1371/journal.pcbi.1012276).
+
+Record the package version or commit alongside your results.
+
+## Contribute
+
+[Development](https://github.com/e-south/dense-arrays/blob/main/docs/development.md) covers local checks and documentation builds.
+[Report bugs](https://github.com/e-south/dense-arrays/issues) and follow the
+[security policy](https://github.com/e-south/dense-arrays/blob/main/SECURITY.md) for vulnerabilities.
+Dense Arrays is available under the [MIT license](https://github.com/e-south/dense-arrays/blob/main/LICENSE).

dense_arrays-0.2.0/README.md

@@ -0,0 +1,69 @@
+# ![Dense Arrays — overlapping motifs within a sequence-length limit](https://raw.githubusercontent.com/e-south/dense-arrays/v0.2.0/docs/assets/dense-arrays-banner.png)
+
+[![CI](https://github.com/e-south/dense-arrays/actions/workflows/ci.yml/badge.svg)](https://github.com/e-south/dense-arrays/actions/workflows/ci.yml)
+[![docs](https://img.shields.io/badge/docs-gitlab_pages-blue)](https://dunloplab.gitlab.io/dense-arrays)
+
+Pack overlapping DNA motifs into a sequence-length limit. Dense Arrays selects
+an arrangement and returns the sequence and each motif's position, so you can
+inspect the overlaps or generate further solutions. Choose single- or
+double-strand placement, require motif groups, or constrain positions.
+
+The package also renders saved placements as images and video. [Watch the
+worked playback](https://dunloplab.gitlab.io/dense-arrays/playback/#watch-four-overlapping-motifs)
+to see how four motifs share sequence space.
+
+## First array
+
+With Python 3.12 or later and [uv](https://docs.astral.sh/uv/), run from a
+[source checkout](https://github.com/e-south/dense-arrays/blob/main/docs/quickstart.md#install-from-source):
+
+```bash
+uv sync --frozen
+uv run dense-arrays optimize \
+  --motif ACGTTGCAAGTCCTGA \
+  --motif AGTCCTGATCGTACCG \
+  --motif TCGTACCGATGCTTAG \
+  --motif ATGCTTAGGACGTTCA \
+  --length 40 --strands double
+```
+
+The search considers both strands. One optimal arrangement packs all four
+16-base motifs into 40 bases:
+
+```text
+ACGTTGCAAGTCCTGATCGTACCGATGCTTAGGACGTTCA
+```
+
+In this orientation, the motifs start at 0, 8, 16, and 24. The solver may return
+the reverse-complement arrangement. The
+[quickstart](https://github.com/e-south/dense-arrays/blob/main/docs/quickstart.md) explains these offsets and shows Python use
+and bounded enumeration of further solutions.
+
+## Documentation
+
+- [Create and read your first array](https://github.com/e-south/dense-arrays/blob/main/docs/quickstart.md).
+- [Set positional and regulator constraints](https://github.com/e-south/dense-arrays/blob/main/docs/constraints.md).
+- [Render saved placements as images or video](https://github.com/e-south/dense-arrays/blob/main/docs/playback.md).
+- [Understand the packing method](https://github.com/e-south/dense-arrays/blob/main/docs/method.md).
+- [Look up Python interfaces](https://github.com/e-south/dense-arrays/blob/main/docs/api.md).
+- [Update an existing caller](https://github.com/e-south/dense-arrays/blob/main/docs/migration.md).
+
+The [documentation index](https://github.com/e-south/dense-arrays/blob/main/docs/index.md) also routes integrators and
+contributors to the relevant interfaces and checks.
+
+## Citation
+
+If you use Dense Arrays in your research, please cite:
+
+Andreani V, South EJ, Dunlop MJ (2024). Generating information-dense promoter
+sequences with optimal string packing. *PLOS Computational Biology* 20(7):
+e1012276. [doi:10.1371/journal.pcbi.1012276](https://doi.org/10.1371/journal.pcbi.1012276).
+
+Record the package version or commit alongside your results.
+
+## Contribute
+
+[Development](https://github.com/e-south/dense-arrays/blob/main/docs/development.md) covers local checks and documentation builds.
+[Report bugs](https://github.com/e-south/dense-arrays/issues) and follow the
+[security policy](https://github.com/e-south/dense-arrays/blob/main/SECURITY.md) for vulnerabilities.
+Dense Arrays is available under the [MIT license](https://github.com/e-south/dense-arrays/blob/main/LICENSE).

dense_arrays-0.2.0/pyproject.toml

@@ -0,0 +1,90 @@
+[project]
+name = "dense-arrays"
+version = "0.2.0"
+description = "A library to create densely packed DNA arrays from motifs"
+authors = [
+    {name = "Virgile Andreani", email = "andreani@bu.edu"},
+    {name = "Eric J South", email = "ericjohnsouth@gmail.com"},
+]
+dependencies = [
+    "numpy>=1.25.2",
+    "ortools>=9.7.2996",
+    "rich>=13.7.0",
+    "typer>=0.12.0",
+]
+requires-python = ">=3.12"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+
+[project.urls]
+Repository = "https://github.com/e-south/dense-arrays"
+Documentation = "https://dunloplab.gitlab.io/dense-arrays"
+Issues = "https://github.com/e-south/dense-arrays/issues"
+
+[project.optional-dependencies]
+playback = [
+    "matplotlib>=3.8.0",
+    "networkx>=3.6.1",
+]
+docs = [
+    "mkdocs>=1.6.1",
+    "mkdocs-material>=9.7.3",
+    "mkdocstrings[python]>=1.0.3",
+]
+dev = [
+    "pre-commit>=4.5.1",
+    "pip-audit>=2.10.0",
+    "pytest>=9.0.3",
+    "ruff>=0.14.14",
+]
+
+[project.scripts]
+dense-arrays = "dense_arrays.cli:app"
+dense-arrays-playback = "dense_arrays.playback.cli:app"
+
+[build-system]
+requires = ["setuptools>=77.0.3", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.ruff.lint]
+preview = true
+explicit-preview-rules = true
+select = ["ALL"]
+ignore = [
+    # The formatter owns trailing commas.
+    "COM812",
+    # Implicitly concatenated string literals on one line
+    # (does not work well with ruff format)
+    "ISC001",
+    # Unnecessary assignment to return
+    "RET504",
+    # Commented code
+    "ERA001",
+    # Copyright stuff
+    "CPY001",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"maintenance/release.py" = ["T201"]
+# Optional visualization imports stay inside the functions that use them.
+# Relative imports follow the playback package boundary.
+"src/dense_arrays/playback/**/*.py" = [
+    "PLC0415",
+    "TID252",
+]
+"tests/test_optional_playback_imports.py" = ["S101", "S404", "S603"]
+"src/dense_arrays/main.py" = ["T201"]
+# Typer evaluates Path annotations and supplies option defaults at runtime.
+"src/dense_arrays/cli.py" = ["FBT002"]
+"src/dense_arrays/playback/cli.py" = ["TC003", "PLR0913", "PLR0917"]
+# Keep the existing explicit media option signatures.
+"src/dense_arrays/playback/matplotlib_renderer.py" = ["PLR0913"]
+"src/dense_arrays/playback/export.py" = ["PLR0913"]
+"tests/test_*.py" = ["ANN201", "D103", "S101", "PLR2004", "FBT001"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+
+[tool.ruff.lint.flake8-pytest-style]
+parametrize-names-type = "csv"

dense_arrays-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

dense_arrays-0.2.0/src/dense_arrays/__init__.py

@@ -0,0 +1,51 @@
+"""Pack DNA motif libraries and describe their realized placements.
+
+Module Author(s): Virgile Andreani, Eric J. South
+Dunlop Lab
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .errors import (
+        InfeasibleError,
+        InvalidSolverResultError,
+        OptimizationError,
+        SolverBackendError,
+        UnprovenSolutionError,
+    )
+    from .optimizer import Optimizer
+    from .solution import DenseArray
+
+__all__ = [
+    "DenseArray",
+    "InfeasibleError",
+    "InvalidSolverResultError",
+    "OptimizationError",
+    "Optimizer",
+    "SolverBackendError",
+    "UnprovenSolutionError",
+]
+
+
+def __getattr__(name: str) -> object:
+    """Load public classes on demand so playback does not import a solver.
+
+    Returns
+    -------
+    object
+        The requested public class.
+
+    Raises
+    ------
+    AttributeError
+        If the name is not part of the public package interface.
+    """
+    if name not in __all__:
+        msg = f"module {__name__!r} has no attribute {name!r}"
+        raise AttributeError(msg)
+    module = {"Optimizer": "optimizer", "DenseArray": "solution"}.get(name, "errors")
+    return getattr(import_module(f"{__name__}.{module}"), name)

dense_arrays-0.2.0/src/dense_arrays/_record_validation.py

@@ -0,0 +1,138 @@
+"""Validate scalar fields and immutable JSON snapshots for persisted records.
+
+Module Author(s): Eric J. South
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping, Sequence
+from enum import StrEnum
+from types import MappingProxyType
+
+_IUPAC_DNA = frozenset("ACGTRYSWKMBDHVN")
+_SHA256_LENGTH = 64
+
+
+def required_text(value: object, *, field_name: str) -> str:
+    """Return nonblank text without coercing identities."""
+    if not isinstance(value, str):
+        msg = f"{field_name} must be a non-empty string"
+        raise TypeError(msg)
+    if not value.strip():
+        msg = f"{field_name} must be a non-empty string"
+        raise ValueError(msg)
+    return value
+
+
+def normalized_dna(value: object, *, field_name: str) -> str:
+    """Return uppercase DNA after checking the IUPAC alphabet."""
+    sequence = required_text(value, field_name=field_name).strip().upper()
+    invalid = sorted(set(sequence) - _IUPAC_DNA)
+    if invalid:
+        msg = f"{field_name} contains non-IUPAC DNA symbols: {invalid}"
+        raise ValueError(msg)
+    return sequence
+
+
+def integer(value: object, *, field_name: str, minimum: int | None = None) -> int:
+    """Return an integer within its declared domain, excluding booleans."""
+    if isinstance(value, bool) or not isinstance(value, int):
+        msg = f"{field_name} must be an integer"
+        raise TypeError(msg)
+    if minimum is not None and value < minimum:
+        msg = f"{field_name} must be an integer >= {minimum}"
+        raise ValueError(msg)
+    return value
+
+
+def enum_value[T: StrEnum](value: object, enum: type[T], *, field_name: str) -> T:
+    """Return a supported enum value from an enum or exact string."""
+    required_text(value, field_name=field_name)
+    return enum(value)
+
+
+def digest(value: object, *, field_name: str) -> str:
+    """Return a canonical SHA-256 hexadecimal digest."""
+    text = required_text(value, field_name=field_name).strip().lower()
+    if len(text) != _SHA256_LENGTH or any(
+        char not in "0123456789abcdef" for char in text
+    ):
+        msg = f"{field_name} must be a SHA-256 hex digest"
+        raise ValueError(msg)
+    return text
+
+
+def records[T](
+    value: object, record_type: type[T], *, field_name: str
+) -> tuple[T, ...]:
+    """Freeze a sequence of records after checking every member's type."""
+    if isinstance(value, (str, bytes)) or not isinstance(value, Sequence):
+        msg = f"{field_name} must be a sequence of {record_type.__name__} records"
+        raise TypeError(msg)
+    result = tuple(value)
+    if any(not isinstance(item, record_type) for item in result):
+        msg = f"{field_name} must contain only {record_type.__name__} records"
+        raise TypeError(msg)
+    return result
+
+
+def _freeze_json(value: object, ancestors: frozenset[int]) -> object:
+    if value is None or isinstance(value, (str, bool, int)):
+        return value
+    if isinstance(value, float):
+        if math.isfinite(value):
+            return value
+        msg = "JSON provenance numbers must be finite"
+        raise ValueError(msg)
+    if id(value) in ancestors:
+        msg = "JSON provenance must not contain cyclic containers"
+        raise ValueError(msg)
+    parents = ancestors | {id(value)}
+    if isinstance(value, Mapping):
+        if any(not isinstance(key, str) for key in value):
+            msg = "JSON provenance object keys must be strings"
+            raise TypeError(msg)
+        return MappingProxyType(
+            {key: _freeze_json(item, parents) for key, item in value.items()}
+        )
+    if isinstance(value, (list, tuple)):
+        return tuple(_freeze_json(item, parents) for item in value)
+    msg = "provenance and metadata must contain only JSON values"
+    raise TypeError(msg)
+
+
+def immutable_json_mapping(value: object) -> Mapping[str, object]:
+    """Return a recursively immutable, detached JSON object snapshot."""
+    if not isinstance(value, Mapping):
+        msg = "provenance and metadata must be JSON objects"
+        raise TypeError(msg)
+    return _freeze_json(value, frozenset())
+
+
+def mutable_json(value: object) -> object:
+    """Return independent JSON dictionaries and arrays from a frozen snapshot."""
+    if isinstance(value, Mapping):
+        return {key: mutable_json(item) for key, item in value.items()}
+    if isinstance(value, tuple):
+        return [mutable_json(item) for item in value]
+    return value
+
+
+def validate_placement_sequence(
+    *, placement_id: str, start: int, end: int, sequence: str, realized_sequence: str
+) -> None:
+    """Check placement bounds and exact alignment with the realized sequence."""
+    if end > len(realized_sequence):
+        msg = (
+            f"placement {placement_id!r} ends at {end}, "
+            f"beyond sequence length {len(realized_sequence)}"
+        )
+        raise ValueError(msg)
+    observed = realized_sequence[start:end]
+    if observed != sequence:
+        msg = (
+            f"placement {placement_id!r} is sequence-inconsistent: "
+            f"expected {sequence!r}, observed {observed!r}"
+        )
+        raise ValueError(msg)