prot-rsa 1.0.1__tar.gz

prot_rsa-1.0.1/HISTORY.md

@@ -0,0 +1,111 @@
+# Release history
+
+## 1.0.1 — current release
+
+`prot-rsa` is an importable Python module and command-line program for
+calculating solvent-accessible surface area (SASA) for protein structures.
+
+### Current capabilities
+
+- Reads PDB, mmCIF, `.pdb.gz`, and `.cif.gz` structures.
+- Resolves alternate locations and rejects multiple coordinate models.
+- Calculates atom SASA with deterministic Fibonacci sphere sampling (960 points
+  by default; configurable with `--sphere-points`, minimum 122).
+- Uses cKDTree neighbor pruning, vectorized occlusion masks, ordered neighbors,
+  cached geometric terms, complete-burial skipping, and a Numba CPU backend.
+- Supports one or more Numba worker threads through `--workers`.
+- Supports explicit-hydrogen mode (`--use-h`) and optional retained loose
+  hetero-atoms (`--preserve-het`).
+- Produces both complete-residue (`ALL`) and side-chain (`SIDE`) contextual
+  exposure fractions (CEF).
+- Uses `NA` for SIDE values of residues without retained side-chain atoms,
+  including glycine under the canonical backbone definition.
+- Exposes reusable calculation and parsing functions through `protrsa` without
+  command-line or filesystem side effects on import.
+- Uses compact SAS column names with one-line `#` explanations at the start of
+  each atom and residue output file.
+- Names the tab-separated outputs `<base>.atom_sas.tsv` and
+  `<base>.res_sas.tsv` so their format and purpose are explicit.
+- Prints a concise completion summary containing the generated filenames,
+  atom/residue counts, and elapsed time.
+
+The separate atom-file comparison helper is not part of this release.
+
+### Output files and schemas
+
+For an input such as `1LYZ.pdb`, the command writes:
+
+```text
+1LYZ.atom_sas.tsv
+1LYZ.res_sas.tsv
+1LYZ.pqr
+```
+
+`*.atom_sas.tsv` is a UTF-8 tab-separated file. It begins with one `#` comment per
+column, followed by this header:
+
+```text
+# atom: 1-based output atom index
+# rec: source record type
+# src: source atom identifier
+# name: atom name
+# res: residue name
+# chain: chain identifier
+# seq: residue sequence identifier
+# ins: insertion code
+# elem: resolved element
+# radius: assigned atomic radius, Å
+# sasa: solvent-accessible surface area, Ų
+atom	rec	src	name	res	chain	seq	ins	elem	radius	sasa
+```
+
+`*.res_sas.tsv` follows the same comment-plus-header convention:
+
+```text
+# res: residue name
+# chain: chain identifier
+# seq: residue sequence identifier
+# ins: insertion code
+# all: in-protein SASA of all residue atoms, Ų
+# a_ref: isolated-residue reference SASA of all atoms, Ų
+# a_cef: all-atom contextual exposure fraction
+# side: in-protein side-chain SASA, Ų
+# s_ref: isolated side-chain reference SASA, Ų
+# s_cef: side-chain contextual exposure fraction
+res	chain	seq	ins	all	a_ref	a_cef	side	s_ref	s_cef
+```
+
+The first four residue fields identify the residue. The `*_all` values use all
+normalized residue atoms. The `*_side` values exclude backbone atoms `N`,
+`CA`, `C`, `O`, and `OXT`. Reference values are calculated with the selected
+residue atoms isolated from the rest of the protein. Numeric residue values
+are formatted to three decimal places; SIDE fields are `NA` when no SIDE atoms
+remain.
+
+`*.pqr` contains PDB-style records with the input coordinates, a placeholder
+charge of `0.000`, and the assigned radius. It has no tabular header.
+
+### Expected performance
+
+Representative one-thread timings on the canonical benchmark structures are
+shown below. These are wall-clock medians and are hardware- and environment-
+dependent; they are performance expectations rather than guarantees.
+
+| Configuration | Sphere points | 1LYZ (1,001 atoms) | 1CA2 (2,040 atoms) | 1UOR (4,616 atoms) |
+| --- | ---: | ---: | ---: | ---: |
+| Naive reference | 960 | 551 s | 2,185 s | 11,634 s |
+| cKDTree | 960 | 19.490 s | 40.644 s | 86.590 s |
+| Vectorized mask | 960 | 0.609 s | 1.285 s | 2.820 s |
+| Occlusion-ordered neighbors | 960 | 0.319 s | 0.630 s | 1.620 s |
+| Cached NumPy kernel | 960 | 0.276 s | 0.536 s | 1.393 s |
+| Numba CPU | 960 | 0.328 s | 0.388 s | 0.735 s |
+| Numba CPU, reduced sampling | 480 | 0.358 s | 0.382 s | 0.494 s |
+
+Halving the sphere-point count does not halve total wall-clock time because
+validation, neighbor construction, and other fixed costs remain. The 480-point
+results had atom-SASA MAE values of approximately 0.164, 0.145, and 0.184 Ų
+per atom for 1LYZ, 1CA2, and 1UOR, respectively, relative to 960-point output.
+
+## 1.0.0 — initial release
+
+Initial TestPyPI release of the atom-SASA and dual residue-CEF calculation.

prot_rsa-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Junjun Mao
+
+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.

prot_rsa-1.0.1/MANIFEST.in

@@ -0,0 +1 @@
+include HISTORY.md

prot_rsa-1.0.1/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: prot-rsa
+Version: 1.0.1
+Summary: Fast protein residue surface-area calculation in Python
+Author: Junjun Mao
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/newbooks/prot-rsa
+Project-URL: Repository, https://github.com/newbooks/prot-rsa
+Project-URL: Issues, https://github.com/newbooks/prot-rsa/issues
+Project-URL: Changelog, https://github.com/newbooks/prot-rsa/blob/main/HISTORY.md
+Project-URL: Documentation, https://github.com/newbooks/prot-rsa/blob/main/README.md
+Keywords: bioinformatics,computational biology,protein,residue surface area,structural biology
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: numba
+Dynamic: license-file
+
+# prot-rsa
+
+Fast protein residue surface-area calculation in Python.
+
+## Installation
+
+Install the distribution from PyPI:
+
+```bash
+pip install prot-rsa
+```
+
+## Command-line use
+
+Run the installed application with:
+
+```bash
+prot-rsa structure.pdb
+# optionally choose a lower sampling resolution (minimum 122 points)
+prot-rsa structure.pdb --sphere-points 480
+```
+
+Run `prot-rsa --help` to see the supported PDB/mmCIF input suffixes, calculation
+options, defaults, and derived output filenames.
+
+The command writes `<base>.atom_sas.tsv` and `<base>.res_sas.tsv` as TSV files, plus a
+normalized `<base>.pqr` containing the selected radii and placeholder charge
+`0.000`. The production calculation uses cKDTree neighbor pruning; the
+deliberately naive serial implementation remains available as a correctness
+reference.
+
+## Python use
+
+The application can also be imported as the `protrsa` module so its functions
+and constants can be used directly:
+
+```python
+import protrsa
+```
+
+The distribution and command are named `prot-rsa`. The import name is
+`protrsa` because Python module names cannot contain hyphens.
+
+## Residue exposure
+
+Residue solvent-accessible surface area will be calculated by summing the
+already computed atom SASAs for each residue. The residue report will contain
+both complete-residue (`ALL`) and side-chain (`SIDE`) **Contextual Exposure
+Fraction (CEF)** values rather than conventional RSA:
+
+```text
+CEF = selected-atom SASA in the complete protein
+      / SASA of the same selected residue conformation in isolation
+```
+
+The denominator is a naked-residue calculation using the same selected atoms,
+atomic radii, probe radius, and sphere points, but without other residues
+present. The compact output columns are `all`, `a_ref`, `a_cef`, `side`,
+`s_ref`, and `s_cef`; leading `#` comment lines explain every field. CEF therefore represents
+the fraction of the selected residue surface retained in its protein context.
+It is distinct from conventional RSA, which normally uses a fixed residue-type
+reference or maximum ASA.
+
+Residues without retained side-chain atoms, such as glycine under the
+canonical backbone definition, use `NA` for the three SIDE fields.
+
+CEF lies in `[0, 1]` up to floating-point roundoff. The complete residue
+output contract is documented in `docs/specs/residue-cef.md`.
+
+
+## Optimization Comparison
+
+This program targets the speed optimization of residue surface solvent exposure calculation.
+
+The table below compares protein RSA calculation times under each
+optimization. Execution times are reported in seconds; lower values are
+better.
+
+| Optimization | Sphere points | Time (small) | Time (medium) | Time (large) | Atom-SASA MAE vs `*.sas.baseline` (small / medium / large, Ų) |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| Naive | 960 | 551 | 2185 | 11634 | 0.000 / 0.000 / 0.000 |
+| cKDTree | 960 | 19.490 | 40.644 | 86.590 | 0.000 / 0.000 / 0.000 |
+| Vectorized mask | 960 | 0.609 | 1.285 | 2.820 | 0.000 / 0.000 / 0.000 |
+| Occlusion-ordered neighbors | 960 | 0.319 | 0.630 | 1.620 | 0.000 / 0.000 / 0.000 |
+| Cache | 960 | 0.276 | 0.536 | 1.393 | 0.000 / 0.000 / 0.000 |
+| Numba CPU | 960 | 0.328 | 0.388 | 0.735 | 0.000 / 0.000 / 0.000 |
+| Reduced points | 480 | 0.358 | 0.382 | 0.494 | 0.164 / 0.145 / 0.184 |
+
+Benchmark structures are **small** — 1LYZ (129 residues); **medium** — 1CA2
+(256 residues); **large** — 1UOR (580 residues). Residue counts are the numbers
+of unique residues represented by `ATOM` records; waters, ions, and other
+`HETATM` records are excluded.

prot_rsa-1.0.1/README.md

@@ -0,0 +1,92 @@
+# prot-rsa
+
+Fast protein residue surface-area calculation in Python.
+
+## Installation
+
+Install the distribution from PyPI:
+
+```bash
+pip install prot-rsa
+```
+
+## Command-line use
+
+Run the installed application with:
+
+```bash
+prot-rsa structure.pdb
+# optionally choose a lower sampling resolution (minimum 122 points)
+prot-rsa structure.pdb --sphere-points 480
+```
+
+Run `prot-rsa --help` to see the supported PDB/mmCIF input suffixes, calculation
+options, defaults, and derived output filenames.
+
+The command writes `<base>.atom_sas.tsv` and `<base>.res_sas.tsv` as TSV files, plus a
+normalized `<base>.pqr` containing the selected radii and placeholder charge
+`0.000`. The production calculation uses cKDTree neighbor pruning; the
+deliberately naive serial implementation remains available as a correctness
+reference.
+
+## Python use
+
+The application can also be imported as the `protrsa` module so its functions
+and constants can be used directly:
+
+```python
+import protrsa
+```
+
+The distribution and command are named `prot-rsa`. The import name is
+`protrsa` because Python module names cannot contain hyphens.
+
+## Residue exposure
+
+Residue solvent-accessible surface area will be calculated by summing the
+already computed atom SASAs for each residue. The residue report will contain
+both complete-residue (`ALL`) and side-chain (`SIDE`) **Contextual Exposure
+Fraction (CEF)** values rather than conventional RSA:
+
+```text
+CEF = selected-atom SASA in the complete protein
+      / SASA of the same selected residue conformation in isolation
+```
+
+The denominator is a naked-residue calculation using the same selected atoms,
+atomic radii, probe radius, and sphere points, but without other residues
+present. The compact output columns are `all`, `a_ref`, `a_cef`, `side`,
+`s_ref`, and `s_cef`; leading `#` comment lines explain every field. CEF therefore represents
+the fraction of the selected residue surface retained in its protein context.
+It is distinct from conventional RSA, which normally uses a fixed residue-type
+reference or maximum ASA.
+
+Residues without retained side-chain atoms, such as glycine under the
+canonical backbone definition, use `NA` for the three SIDE fields.
+
+CEF lies in `[0, 1]` up to floating-point roundoff. The complete residue
+output contract is documented in `docs/specs/residue-cef.md`.
+
+
+## Optimization Comparison
+
+This program targets the speed optimization of residue surface solvent exposure calculation.
+
+The table below compares protein RSA calculation times under each
+optimization. Execution times are reported in seconds; lower values are
+better.
+
+| Optimization | Sphere points | Time (small) | Time (medium) | Time (large) | Atom-SASA MAE vs `*.sas.baseline` (small / medium / large, Ų) |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| Naive | 960 | 551 | 2185 | 11634 | 0.000 / 0.000 / 0.000 |
+| cKDTree | 960 | 19.490 | 40.644 | 86.590 | 0.000 / 0.000 / 0.000 |
+| Vectorized mask | 960 | 0.609 | 1.285 | 2.820 | 0.000 / 0.000 / 0.000 |
+| Occlusion-ordered neighbors | 960 | 0.319 | 0.630 | 1.620 | 0.000 / 0.000 / 0.000 |
+| Cache | 960 | 0.276 | 0.536 | 1.393 | 0.000 / 0.000 / 0.000 |
+| Numba CPU | 960 | 0.328 | 0.388 | 0.735 | 0.000 / 0.000 / 0.000 |
+| Reduced points | 480 | 0.358 | 0.382 | 0.494 | 0.164 / 0.145 / 0.184 |
+
+Benchmark structures are **small** — 1LYZ (129 residues); **medium** — 1CA2
+(256 residues); **large** — 1UOR (580 residues). Residue counts are the numbers
+of unique residues represented by `ATOM` records; waters, ions, and other
+`HETATM` records are excluded.

prot_rsa-1.0.1/prot_rsa.egg-info/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: prot-rsa
+Version: 1.0.1
+Summary: Fast protein residue surface-area calculation in Python
+Author: Junjun Mao
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/newbooks/prot-rsa
+Project-URL: Repository, https://github.com/newbooks/prot-rsa
+Project-URL: Issues, https://github.com/newbooks/prot-rsa/issues
+Project-URL: Changelog, https://github.com/newbooks/prot-rsa/blob/main/HISTORY.md
+Project-URL: Documentation, https://github.com/newbooks/prot-rsa/blob/main/README.md
+Keywords: bioinformatics,computational biology,protein,residue surface area,structural biology
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: numba
+Dynamic: license-file
+
+# prot-rsa
+
+Fast protein residue surface-area calculation in Python.
+
+## Installation
+
+Install the distribution from PyPI:
+
+```bash
+pip install prot-rsa
+```
+
+## Command-line use
+
+Run the installed application with:
+
+```bash
+prot-rsa structure.pdb
+# optionally choose a lower sampling resolution (minimum 122 points)
+prot-rsa structure.pdb --sphere-points 480
+```
+
+Run `prot-rsa --help` to see the supported PDB/mmCIF input suffixes, calculation
+options, defaults, and derived output filenames.
+
+The command writes `<base>.atom_sas.tsv` and `<base>.res_sas.tsv` as TSV files, plus a
+normalized `<base>.pqr` containing the selected radii and placeholder charge
+`0.000`. The production calculation uses cKDTree neighbor pruning; the
+deliberately naive serial implementation remains available as a correctness
+reference.
+
+## Python use
+
+The application can also be imported as the `protrsa` module so its functions
+and constants can be used directly:
+
+```python
+import protrsa
+```
+
+The distribution and command are named `prot-rsa`. The import name is
+`protrsa` because Python module names cannot contain hyphens.
+
+## Residue exposure
+
+Residue solvent-accessible surface area will be calculated by summing the
+already computed atom SASAs for each residue. The residue report will contain
+both complete-residue (`ALL`) and side-chain (`SIDE`) **Contextual Exposure
+Fraction (CEF)** values rather than conventional RSA:
+
+```text
+CEF = selected-atom SASA in the complete protein
+      / SASA of the same selected residue conformation in isolation
+```
+
+The denominator is a naked-residue calculation using the same selected atoms,
+atomic radii, probe radius, and sphere points, but without other residues
+present. The compact output columns are `all`, `a_ref`, `a_cef`, `side`,
+`s_ref`, and `s_cef`; leading `#` comment lines explain every field. CEF therefore represents
+the fraction of the selected residue surface retained in its protein context.
+It is distinct from conventional RSA, which normally uses a fixed residue-type
+reference or maximum ASA.
+
+Residues without retained side-chain atoms, such as glycine under the
+canonical backbone definition, use `NA` for the three SIDE fields.
+
+CEF lies in `[0, 1]` up to floating-point roundoff. The complete residue
+output contract is documented in `docs/specs/residue-cef.md`.
+
+
+## Optimization Comparison
+
+This program targets the speed optimization of residue surface solvent exposure calculation.
+
+The table below compares protein RSA calculation times under each
+optimization. Execution times are reported in seconds; lower values are
+better.
+
+| Optimization | Sphere points | Time (small) | Time (medium) | Time (large) | Atom-SASA MAE vs `*.sas.baseline` (small / medium / large, Ų) |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| Naive | 960 | 551 | 2185 | 11634 | 0.000 / 0.000 / 0.000 |
+| cKDTree | 960 | 19.490 | 40.644 | 86.590 | 0.000 / 0.000 / 0.000 |
+| Vectorized mask | 960 | 0.609 | 1.285 | 2.820 | 0.000 / 0.000 / 0.000 |
+| Occlusion-ordered neighbors | 960 | 0.319 | 0.630 | 1.620 | 0.000 / 0.000 / 0.000 |
+| Cache | 960 | 0.276 | 0.536 | 1.393 | 0.000 / 0.000 / 0.000 |
+| Numba CPU | 960 | 0.328 | 0.388 | 0.735 | 0.000 / 0.000 / 0.000 |
+| Reduced points | 480 | 0.358 | 0.382 | 0.494 | 0.164 / 0.145 / 0.184 |
+
+Benchmark structures are **small** — 1LYZ (129 residues); **medium** — 1CA2
+(256 residues); **large** — 1UOR (580 residues). Residue counts are the numbers
+of unique residues represented by `ATOM` records; waters, ions, and other
+`HETATM` records are excluded.

prot_rsa-1.0.1/prot_rsa.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+HISTORY.md
+LICENSE
+MANIFEST.in
+README.md
+protrsa.py
+pyproject.toml
+prot_rsa.egg-info/PKG-INFO
+prot_rsa.egg-info/SOURCES.txt
+prot_rsa.egg-info/dependency_links.txt
+prot_rsa.egg-info/entry_points.txt
+prot_rsa.egg-info/requires.txt
+prot_rsa.egg-info/top_level.txt
+tests/test_atom_pipeline.py
+tests/test_atom_sasa_naive.py
+tests/test_atom_sasa_spatial.py
+tests/test_cli.py
+tests/test_residue_cef.py
+tests/test_structure_reader.py

prot_rsa-1.0.1/prot_rsa.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

prot_rsa-1.0.1/prot_rsa.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+prot-rsa = protrsa:main

prot_rsa-1.0.1/prot_rsa.egg-info/requires.txt

@@ -0,0 +1,3 @@
+numpy
+scipy
+numba

prot_rsa-1.0.1/prot_rsa.egg-info/top_level.txt

@@ -0,0 +1 @@
+protrsa