cooper-beta 0.1.0__tar.gz

cooper_beta-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Shuyu Zhong
+
+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.

cooper_beta-0.1.0/MANIFEST.in

@@ -0,0 +1,8 @@
+include LICENSE
+include README.md
+include pyproject.toml
+include environment.yml
+include scripts/setup_env.sh
+recursive-include tests *.py
+recursive-include src/cooper_beta/conf *.yaml
+global-exclude __pycache__ *.py[cod] .DS_Store

cooper_beta-0.1.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: cooper-beta
+Version: 0.1.0
+Summary: Beta-barrel-like chain detector for PDB/mmCIF structures.
+Author: Shuyu Zhong
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/GeraltZeroZhong/Cooper-Beta
+Project-URL: Source, https://github.com/GeraltZeroZhong/Cooper-Beta
+Project-URL: Issues, https://github.com/GeraltZeroZhong/Cooper-Beta/issues
+Keywords: bioinformatics,beta-barrel,protein-structure,pdb,mmcif
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: scipy>=1.10
+Requires-Dist: biopython>=1.81
+Requires-Dist: opencv-python-headless>=4.8
+Requires-Dist: hydra-core>=1.3
+Requires-Dist: tqdm>=4.0
+Provides-Extra: eval
+Requires-Dist: pandas>=1.5; extra == "eval"
+Provides-Extra: full
+Requires-Dist: pandas>=1.5; extra == "full"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: check-manifest>=0.49; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# Cooper-Beta
+
+Cooper-Beta detects beta-barrel-like protein chains in PDB, CIF, and mmCIF
+structures. It parses structures with Biopython, runs DSSP, slices beta-sheet
+C-alpha coordinates, fits ellipses to cross sections, applies geometric
+consistency rules, and returns chain-level results.
+
+## Quick Start
+
+Cooper-Beta requires Python 3.10 or newer and a DSSP executable (`mkdssp` or
+`dssp`) on `PATH`.
+
+```bash
+pip install cooper-beta
+cooper-beta --check-env
+cooper-beta path/to/structures --out cooper_beta_results.csv
+```
+
+If DSSP is installed outside `PATH`, pass its location as a configuration
+override:
+
+```bash
+cooper-beta path/to/structures runtime.dssp_bin_path=/absolute/path/to/mkdssp
+```
+
+## Installation
+
+Install the detector:
+
+```bash
+pip install cooper-beta
+```
+
+Install optional tools:
+
+```bash
+pip install "cooper-beta[eval]"   # pandas for evaluation helpers
+pip install "cooper-beta[full]"   # all optional extras
+```
+
+For development from a source checkout:
+
+```bash
+pip install -e ".[full,dev]"
+```
+
+The repository also includes `environment.yml` and `scripts/setup_env.sh` for a
+Conda or Mamba environment that installs DSSP from `conda-forge`:
+
+```bash
+bash scripts/setup_env.sh --dev
+```
+
+## Command Line
+
+Run Cooper-Beta on a single file or a directory:
+
+```bash
+cooper-beta path/to/structure.cif --out results.csv
+cooper-beta path/to/structures --workers 8 --prepare-workers 8 --out results.csv
+```
+
+Useful options:
+
+- `--check-env`: print the Python executable and resolved DSSP executable.
+- `--workers`: number of analysis worker processes.
+- `--prepare-workers`: number of structure-preparation worker processes.
+- `--out`: output CSV path.
+- `--version`: print the installed Cooper-Beta version.
+
+Advanced configuration uses Hydra-style `KEY=VALUE` overrides:
+
+```bash
+cooper-beta path/to/structures \
+  runtime.dssp_bin_path=/absolute/path/to/mkdssp \
+  analyzer.rules.angle.max_gap_deg=160 \
+  output.summary_limit=-1
+```
+
+## Python API
+
+The recommended Python entry point is `detect`, which returns a structured
+`PipelineRunResult`. CSV output is written only when `output` is provided or
+`write_csv=True`.
+
+```python
+from cooper_beta import detect
+
+run = detect(
+    "path/to/structures",
+    workers=4,
+    output="results.csv",
+    overrides={"runtime.dssp_bin_path": "/usr/bin/mkdssp"},
+)
+
+print(run.result_counts)
+for row in run.rows:
+    print(row.filename, row.chain, row.result, row.reason)
+```
+
+Public interfaces:
+
+- `cooper_beta.detect(...)`: run detection and return structured results.
+- `cooper_beta.main(...)`: backward-compatible entry point returning row dicts.
+- `cooper_beta.build_config(...)`: build an `AppConfig` from overrides.
+- `cooper_beta.PipelineRunResult`: complete run result with `rows`,
+  `input_files`, `output_path`, and `result_counts`.
+- `cooper_beta.DetectionResult`: one chain-level result row.
+- `cooper_beta.ProteinLoader`: parse structures and collect per-chain C-alpha
+  and DSSP annotations.
+- `cooper_beta.PCAAligner`, `ProteinSlicer`, and `BarrelAnalyzer`: lower-level
+  analysis components for custom workflows.
+
+User-facing failures raise Cooper-Beta exceptions such as
+`InputValidationError`, `DsspNotFoundError`, `DsspError`, `StructureParseError`,
+and `ChainNotFoundError`.
+
+## Output
+
+The result CSV includes one row per chain. Core columns include:
+
+- `filename` and `chain`
+- `result`: `BARREL`, `NON_BARREL`, `FILTERED_OUT`, or `ERROR`
+- `result_stage` and `reason`
+- `decision_score`, `decision_basis`, and `decision_threshold`
+- `score_raw` and `score_adjust`
+- `valid_layers`, `scored_layers`, `total_layers`, `junk_layers`, and
+  `invalid_layers`
+- `chain_residues`, `sheet_residues`, and `informative_slices`
+
+Large directory runs use bounded prepare and analysis batches, and the CLI writes
+the CSV incrementally. The console summary is capped by default; set
+`output.summary_limit=-1` to print every row.
+
+## Evaluation Helpers
+
+Evaluation utilities are available after installing `cooper-beta[eval]`:
+
+```bash
+cooper-beta-eval \
+  --positives path/to/positive-structures \
+  --negatives path/to/negative-structures \
+  --save-dir evaluation-results
+python -m cooper_beta.evaluation \
+  --positives path/to/positive-structures \
+  --negatives path/to/negative-structures \
+  --ablation
+```
+
+The GitHub repository also contains helper scripts for local datasets and
+Cooper-Beta CSV outputs. Local structure datasets, manual review notes, and
+research-only helper scripts are intentionally excluded from the package
+artifacts.
+
+## Changelog
+
+### 0.1.0
+
+- Initial public release.
+- CLI and Python API for PDB/CIF/mmCIF beta-barrel-like chain detection.
+- DSSP-backed secondary-structure parsing.
+- Ellipse fitting, PCA axis search, geometric rules, and CSV output.
+- Evaluation helpers and ablation utilities.
+
+## License
+
+Cooper-Beta is released under the MIT License. See `LICENSE`.

cooper_beta-0.1.0/README.md

@@ -0,0 +1,167 @@
+# Cooper-Beta
+
+Cooper-Beta detects beta-barrel-like protein chains in PDB, CIF, and mmCIF
+structures. It parses structures with Biopython, runs DSSP, slices beta-sheet
+C-alpha coordinates, fits ellipses to cross sections, applies geometric
+consistency rules, and returns chain-level results.
+
+## Quick Start
+
+Cooper-Beta requires Python 3.10 or newer and a DSSP executable (`mkdssp` or
+`dssp`) on `PATH`.
+
+```bash
+pip install cooper-beta
+cooper-beta --check-env
+cooper-beta path/to/structures --out cooper_beta_results.csv
+```
+
+If DSSP is installed outside `PATH`, pass its location as a configuration
+override:
+
+```bash
+cooper-beta path/to/structures runtime.dssp_bin_path=/absolute/path/to/mkdssp
+```
+
+## Installation
+
+Install the detector:
+
+```bash
+pip install cooper-beta
+```
+
+Install optional tools:
+
+```bash
+pip install "cooper-beta[eval]"   # pandas for evaluation helpers
+pip install "cooper-beta[full]"   # all optional extras
+```
+
+For development from a source checkout:
+
+```bash
+pip install -e ".[full,dev]"
+```
+
+The repository also includes `environment.yml` and `scripts/setup_env.sh` for a
+Conda or Mamba environment that installs DSSP from `conda-forge`:
+
+```bash
+bash scripts/setup_env.sh --dev
+```
+
+## Command Line
+
+Run Cooper-Beta on a single file or a directory:
+
+```bash
+cooper-beta path/to/structure.cif --out results.csv
+cooper-beta path/to/structures --workers 8 --prepare-workers 8 --out results.csv
+```
+
+Useful options:
+
+- `--check-env`: print the Python executable and resolved DSSP executable.
+- `--workers`: number of analysis worker processes.
+- `--prepare-workers`: number of structure-preparation worker processes.
+- `--out`: output CSV path.
+- `--version`: print the installed Cooper-Beta version.
+
+Advanced configuration uses Hydra-style `KEY=VALUE` overrides:
+
+```bash
+cooper-beta path/to/structures \
+  runtime.dssp_bin_path=/absolute/path/to/mkdssp \
+  analyzer.rules.angle.max_gap_deg=160 \
+  output.summary_limit=-1
+```
+
+## Python API
+
+The recommended Python entry point is `detect`, which returns a structured
+`PipelineRunResult`. CSV output is written only when `output` is provided or
+`write_csv=True`.
+
+```python
+from cooper_beta import detect
+
+run = detect(
+    "path/to/structures",
+    workers=4,
+    output="results.csv",
+    overrides={"runtime.dssp_bin_path": "/usr/bin/mkdssp"},
+)
+
+print(run.result_counts)
+for row in run.rows:
+    print(row.filename, row.chain, row.result, row.reason)
+```
+
+Public interfaces:
+
+- `cooper_beta.detect(...)`: run detection and return structured results.
+- `cooper_beta.main(...)`: backward-compatible entry point returning row dicts.
+- `cooper_beta.build_config(...)`: build an `AppConfig` from overrides.
+- `cooper_beta.PipelineRunResult`: complete run result with `rows`,
+  `input_files`, `output_path`, and `result_counts`.
+- `cooper_beta.DetectionResult`: one chain-level result row.
+- `cooper_beta.ProteinLoader`: parse structures and collect per-chain C-alpha
+  and DSSP annotations.
+- `cooper_beta.PCAAligner`, `ProteinSlicer`, and `BarrelAnalyzer`: lower-level
+  analysis components for custom workflows.
+
+User-facing failures raise Cooper-Beta exceptions such as
+`InputValidationError`, `DsspNotFoundError`, `DsspError`, `StructureParseError`,
+and `ChainNotFoundError`.
+
+## Output
+
+The result CSV includes one row per chain. Core columns include:
+
+- `filename` and `chain`
+- `result`: `BARREL`, `NON_BARREL`, `FILTERED_OUT`, or `ERROR`
+- `result_stage` and `reason`
+- `decision_score`, `decision_basis`, and `decision_threshold`
+- `score_raw` and `score_adjust`
+- `valid_layers`, `scored_layers`, `total_layers`, `junk_layers`, and
+  `invalid_layers`
+- `chain_residues`, `sheet_residues`, and `informative_slices`
+
+Large directory runs use bounded prepare and analysis batches, and the CLI writes
+the CSV incrementally. The console summary is capped by default; set
+`output.summary_limit=-1` to print every row.
+
+## Evaluation Helpers
+
+Evaluation utilities are available after installing `cooper-beta[eval]`:
+
+```bash
+cooper-beta-eval \
+  --positives path/to/positive-structures \
+  --negatives path/to/negative-structures \
+  --save-dir evaluation-results
+python -m cooper_beta.evaluation \
+  --positives path/to/positive-structures \
+  --negatives path/to/negative-structures \
+  --ablation
+```
+
+The GitHub repository also contains helper scripts for local datasets and
+Cooper-Beta CSV outputs. Local structure datasets, manual review notes, and
+research-only helper scripts are intentionally excluded from the package
+artifacts.
+
+## Changelog
+
+### 0.1.0
+
+- Initial public release.
+- CLI and Python API for PDB/CIF/mmCIF beta-barrel-like chain detection.
+- DSSP-backed secondary-structure parsing.
+- Ellipse fitting, PCA axis search, geometric rules, and CSV output.
+- Evaluation helpers and ablation utilities.
+
+## License
+
+Cooper-Beta is released under the MIT License. See `LICENSE`.

cooper_beta-0.1.0/environment.yml

@@ -0,0 +1,7 @@
+name: cooperbeta
+channels:
+  - conda-forge
+dependencies:
+  - python>=3.10
+  - pip
+  - dssp

cooper_beta-0.1.0/pyproject.toml

@@ -0,0 +1,86 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cooper-beta"
+version = "0.1.0"
+description = "Beta-barrel-like chain detector for PDB/mmCIF structures."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "Shuyu Zhong" },
+]
+keywords = ["bioinformatics", "beta-barrel", "protein-structure", "pdb", "mmcif"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+dependencies = [
+  "numpy>=1.23",
+  "scipy>=1.10",
+  "biopython>=1.81",
+  "opencv-python-headless>=4.8",
+  "hydra-core>=1.3",
+  "tqdm>=4.0",
+]
+
+[project.optional-dependencies]
+eval = [
+  "pandas>=1.5",
+]
+full = [
+  "pandas>=1.5",
+]
+dev = [
+  "pytest>=7.0",
+  "ruff>=0.5",
+  "build>=1.2",
+  "check-manifest>=0.49",
+  "twine>=5.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/GeraltZeroZhong/Cooper-Beta"
+Source = "https://github.com/GeraltZeroZhong/Cooper-Beta"
+Issues = "https://github.com/GeraltZeroZhong/Cooper-Beta/issues"
+
+[project.scripts]
+cooper-beta = "cooper_beta.cli:main"
+cooper-beta-eval = "cooper_beta.evaluation.app:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["cooper_beta*"]
+
+[tool.setuptools.package-data]
+cooper_beta = ["conf/**/*.yaml"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+extend-exclude = ["data/scripts"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+ignore = ["E501"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.check-manifest]
+ignore = [
+  ".github/**",
+  ".gitignore",
+  "data/scripts/**",
+  "main.py",
+  "scripts/*.py",
+]

cooper_beta-0.1.0/scripts/setup_env.sh

@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+ENV_FILE="$ROOT_DIR/environment.yml"
+ENV_NAME="cooperbeta"
+WITH_DEV=0
+DRY_RUN=0
+
+usage() {
+  cat <<'EOF'
+Usage:
+  bash scripts/setup_env.sh [--name ENV_NAME] [--dev] [--dry-run]
+
+What it does:
+  1. Prefer mamba/micromamba/conda to create an environment from environment.yml
+     so DSSP is installed automatically.
+  2. Install this repository in editable mode inside that environment.
+  3. If no conda-like tool is available but apt-get exists, fall back to:
+       - install DSSP from apt
+       - create .venv
+       - pip install the project
+
+Options:
+  --name ENV_NAME  Override the conda environment name (default: cooperbeta)
+  --dev            Also install the project's dev dependencies
+  --dry-run        Print commands without executing them
+  -h, --help       Show this help message
+EOF
+}
+
+have_cmd() {
+  command -v "$1" >/dev/null 2>&1
+}
+
+run_cmd() {
+  printf '+'
+  printf ' %q' "$@"
+  printf '\n'
+  if [[ "$DRY_RUN" -eq 1 ]]; then
+    return 0
+  fi
+  "$@"
+}
+
+choose_conda_frontend() {
+  local candidate
+  for candidate in mamba micromamba conda; do
+    if have_cmd "$candidate"; then
+      echo "$candidate"
+      return 0
+    fi
+  done
+  return 1
+}
+
+conda_env_exists() {
+  local frontend="$1"
+  local env_name="$2"
+  "$frontend" env list 2>/dev/null | awk 'NF && $1 !~ /^#/ { print $1 }' | grep -Fxq "$env_name"
+}
+
+install_spec() {
+  if [[ "$WITH_DEV" -eq 1 ]]; then
+    echo "$ROOT_DIR[full,dev]"
+  else
+    echo "$ROOT_DIR[full]"
+  fi
+}
+
+setup_with_conda() {
+  local frontend="$1"
+
+  if conda_env_exists "$frontend" "$ENV_NAME"; then
+    run_cmd "$frontend" env update --yes --name "$ENV_NAME" --file "$ENV_FILE" --prune
+  else
+    run_cmd "$frontend" env create --yes --name "$ENV_NAME" --file "$ENV_FILE"
+  fi
+
+  run_cmd "$frontend" run -n "$ENV_NAME" python -m pip install -e "$(install_spec)"
+
+  echo
+  echo "Environment is ready."
+  if [[ "$frontend" == "micromamba" ]]; then
+    echo "Activate it with: micromamba activate $ENV_NAME"
+  else
+    echo "Activate it with: conda activate $ENV_NAME"
+  fi
+}
+
+setup_with_apt_venv() {
+  local venv_dir="$ROOT_DIR/.venv"
+
+  if [[ "$EUID" -ne 0 ]]; then
+    run_cmd sudo apt-get update
+    run_cmd sudo apt-get install -y dssp
+  else
+    run_cmd apt-get update
+    run_cmd apt-get install -y dssp
+  fi
+
+  run_cmd python3 -m venv "$venv_dir"
+  run_cmd "$venv_dir/bin/python" -m pip install --upgrade pip setuptools wheel
+  run_cmd "$venv_dir/bin/python" -m pip install -e "$(install_spec)"
+
+  echo
+  echo "Environment is ready."
+  echo "Activate it with: source $venv_dir/bin/activate"
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --name)
+      ENV_NAME="${2:?missing value for --name}"
+      shift 2
+      ;;
+    --dev)
+      WITH_DEV=1
+      shift
+      ;;
+    --dry-run)
+      DRY_RUN=1
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+if [[ ! -f "$ENV_FILE" ]]; then
+  echo "Missing environment file: $ENV_FILE" >&2
+  exit 1
+fi
+
+if frontend="$(choose_conda_frontend)"; then
+  setup_with_conda "$frontend"
+  exit 0
+fi
+
+if have_cmd apt-get; then
+  setup_with_apt_venv
+  exit 0
+fi
+
+cat >&2 <<'EOF'
+No supported installer was found.
+
+Recommended options:
+  1. Install mamba/conda, then rerun: bash scripts/setup_env.sh
+  2. Install DSSP manually and then run:
+       python3 -m venv .venv
+       source .venv/bin/activate
+       pip install -e ".[full]"
+
+You can also point Cooper-Beta to a custom DSSP binary with
+`runtime.dssp_bin_path=/absolute/path/to/mkdssp` (Hydra)
+or `cooper_beta.config.Config.DSSP_BIN_PATH` (legacy Python API).
+EOF
+exit 1

cooper_beta-0.1.0/setup.cfg

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