tacular 1.0.0__tar.gz

tacular-1.0.0/.github/copilot-instructions.md

@@ -0,0 +1,215 @@
+
+
+
+# ProForma Notation - Basic Summary
+
+
+1 - Never make summary documentation unles specifically asked.
+2 - check makfile for commands
+
+## Documentation & Comments
+
+### Docstring Format
+
+Use **Google-style docstrings** but keep them minimal - type hints handle the rest.
+
+**Simple function:**
+```python
+def calculate_mass(sequence: str, charge: int = 1) -> float:
+    """Calculate the mass-to-charge ratio of a peptide."""
+```
+
+**When you need more detail:**
+```python
+def find_isotopes(mz: float, tolerance: float = 0.01) -> list[Peak]:
+    """Find isotopic peaks within the tolerance window.
+    
+    Uses a greedy algorithm to identify the most intense peaks first,
+    then searches for their isotopic patterns.
+    """
+```
+
+**Classes:**
+```python
+class Peptide:
+    """Represents a peptide sequence with ProForma modifications."""
+```
+
+### What to Document
+
+- **One-line summary** for all public functions/classes
+- **Additional details** only when the implementation is non-obvious
+- **Don't repeat** what's already in type hints
+- **Private functions** (`_name`) can skip docstrings if obvious
+
+### Building Docs
+```bash
+cd docs
+make html
+# View at docs/_build/html/index.html
+```
+
+see **proforma.schema.json** for the full ProForma 2.0 json object specification.
+
+## What is ProForma?
+
+ProForma is a **standardized text notation for representing peptides and proteins with modifications**. It's designed to be both human-readable and machine-parsable, allowing scientists to precisely describe modified peptide sequences in mass spectrometry data.
+
+## Core Concept
+
+Think of it as a way to write: **"amino acid sequence + where modifications are located + what those modifications are"**
+
+## Basic Examples
+
+### 1. Simple Unmodified Peptide
+```
+PEPTIDE
+```
+Just amino acids using standard one-letter codes (A, C, D, E, F, G, H, I, K, L, M, N, P, Q, R, S, T, V, W, Y)
+
+### 2. Peptide with Modification
+```
+PEM[Oxidation]TIDE
+```
+- Methionine (M) is oxidized
+- Modifications go in square brackets `[]` right after the modified amino acid
+
+### 3. Multiple Modifications
+```
+PEM[Oxidation]TIS[Phospho]DE
+```
+- M is oxidized
+- S is phosphorylated
+
+### 4. Terminal Modifications
+```
+[Acetyl]-PEPTIDE
+[iTRAQ4plex]-PEPTIDE-[Amidated]
+```
+- N-terminal modifications: `[mod]-` before sequence
+- C-terminal modifications: `-[mod]` after sequence
+
+## Ways to Specify Modifications
+
+ProForma supports multiple ways to describe the same modification:
+
+```
+EM[Oxidation]TIDE              # By name (Unimod)
+EM[UNIMOD:35]TIDE              # By accession number
+EM[+15.995]TIDE                # By mass change
+EM[Formula:O]TIDE              # By chemical formula
+```
+
+## Key Advanced Features
+
+### Ambiguous Modification Position
+When you know a modification exists but not exactly where:
+```
+[Phospho]?PEPTIDE              # Phospho is somewhere, location unknown
+```
+
+### Multiple Possible Sites
+```
+PEP[Phospho#g1]TIS[#g1]DE     # Phospho is on either T or S
+```
+
+### Labile Modifications
+Modifications that fall off during fragmentation:
+```
+{Glycan:Hex}PEPTIDE            # Glycan present but lost in MS2
+```
+
+### Cross-linked Peptides
+This is somewhat handled at the parsing level but will not will not be implmented in the codebased. Dont worry about this too much.
+```
+PEPTK[#XL1]IDE//SEQK[#XL1]    # Two peptides linked together
+```
+
+### Chimeric Spectra
+Multiple peptides in same spectrum:
+This is somewhat handled at the parsing level but will not will not be implmented int eh codebased. Dont worry about this too much.
+```
+PEPTIDE+SEQUENCE               # Two co-eluting peptides
+```
+
+### Charge States
+```
+PEPTIDE/2                      # Charge state +2
+```
+
+### Charge Adducts
+```
+PEPTIDE/[Na+:z+1]              # Sodium adduct with +1 charge
+PEPTIDE/[Na+:z+1^2]            # added 2 times (total charge: +2)
+EPT[Formula:Zn:z+2]IDE/[Na:z+1^2] # total +4
+
+```
+
+both charge and charge adduct cannot occur simultaneously.
+
+```
+PEPTIDE/[Na+:z+1^2]              # Sodium adduct with +1 charge 2 times
+```
+
+
+
+## Compliance Levels
+
+ProForma has different levels of complexity:
+
+1. **Base-ProForma** - Simple sequences with basic modifications
+2. **Level 2-ProForma** - Adds ambiguity, formulas, delta masses
+3. **Extensions** - Specialized features for:
+   - Top-down proteomics
+   - Cross-linking
+   - Glycoproteomics
+   - Advanced complexity
+
+## Common Use Cases
+
+### Bottom-up Proteomics
+```
+[Acetyl]-EM[Oxidation]EVTSES[Phospho]PEK
+```
+Typical tryptic peptide with PTMs
+
+### Top-down Proteomics
+```
+<[Oxidation]@M>FULLPROTEINSEQUENCE...
+```
+Full protein with fixed modifications
+
+### Glycopeptide
+```
+NEEYN[Glycan:Hex5HexNAc4]K
+```
+N-glycosylation site
+
+### Cross-linking
+```
+PEPTK[XLMOD:02001#XL1]IDE//SEQK[#XL1]
+```
+DSS cross-link between two lysines
+
+## Why ProForma?
+
+**Before ProForma:** Everyone used different formats to describe modified peptides
+- Hard to share data
+- Hard to write software that works with different tools
+- Ambiguous representations
+
+**With ProForma:** Standard notation means:
+- Data can be easily exchanged between labs
+- Software tools can interoperate
+- Unambiguous communication of results
+- Integration with databases (Unimod, PSI-MOD, etc.)
+
+## Key Design Principles
+
+1. **Human readable** - Scientists can read and understand it
+2. **Machine parsable** - Software can reliably parse it
+3. **Extensible** - Can add new features as needs evolve
+4. **Precise** - Captures uncertainty and ambiguity when present
+5. **Standards-based** - Uses controlled vocabularies (Unimod, PSI-MOD, etc.)
+
+

tacular-1.0.0/.github/workflows/pylint.yml

@@ -0,0 +1,26 @@
+name: Lint and Type Check
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12"]
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+    - name: Install just
+      uses: extractions/setup-just@v2
+    - name: Install dependencies
+      run: just install
+    - name: Lint with ruff
+      run: just lint
+    - name: Type check with ty
+      run: just check

tacular-1.0.0/.github/workflows/python-package.yml

@@ -0,0 +1,44 @@
+# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
+
+name: Python package
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12"]
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+    - name: Install just
+      uses: extractions/setup-just@v2
+    - name: Install dependencies
+      run: just install
+    - name: Lint with ruff
+      run: just lint
+    - name: Type check with ty
+      run: just check
+    - name: Test with pytest
+      run: just test-cov
+    - name: Upload coverage reports to Codecov
+      uses: codecov/codecov-action@v5
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}
+        slug: tacular-omics/tacular
+        fail_ci_if_error: false

tacular-1.0.0/.github/workflows/python-publish.yml

@@ -0,0 +1,37 @@
+# This workflow will upload a Python Package using Twine when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.x'
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+    - name: Build package with uv
+      run: uv build
+    - name: Publish package
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        user: __token__
+        password: ${{ secrets.PYPI_API_TOKEN }}

tacular-1.0.0/.gitignore

@@ -0,0 +1,122 @@
+*GNOme.obo
+*PSI-MOD.obo
+*UNIMOD.obo
+*XLMod.obo
+
+*try_*.py
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   with no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducible builds.
+#   However, if you need to use different versions of dependencies on different environments,
+#   you may want to ignore it.
+#poetry.lock
+
+# uv
+.venv
+uv.lock
+
+# ruff
+.ruff_cache/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# editors
+.vscode/
+.idea/

tacular-1.0.0/HISTORY.md

@@ -0,0 +1,5 @@
+# History
+
+## 0.1.0 (2026-01-15)
+
+* First release on PyPI.

tacular-1.0.0/MANIFEST.in

@@ -0,0 +1,8 @@
+include HISTORY.md
+include README.md
+
+recursive-include tests *
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+
+recursive-include *.md justfile *.jpg *.png *.gif

tacular-1.0.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: tacular
+Version: 1.0.0
+Summary: Includes lookups for modifications, amino acids, and other data types.
+Author-email: Patrick Garrett <pgarrett@scripps.edu>
+Maintainer-email: Patrick Garrett <pgarrett@scripps.edu>
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# tacular
+
+[![Python package](https://github.com/pgarrett-scripps/tacular/actions/workflows/python-package.yml/badge.svg)](https://github.com/pgarrett-scripps/tacular/actions/workflows/python-package.yml)
+[![codecov](https://codecov.io/github/tacular-omics/tacular/graph/badge.svg?token=1CTVZVFXF7)](https://codecov.io/github/tacular-omics/tacular)
+[![PyPI version](https://badge.fury.io/py/tacular.svg)](https://badge.fury.io/py/tacular)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A helper package for peptacular and paftacular. Includes lookups for modifications, amino acids, and other data types.
+
+## Generate Data
+
+See data_gen/README.md
+
+## Generating JSONs
+
+It's possible to generate JSON objects for all parsed data used within tacular. This isn't used within tacular or its downstream packages, but may be useful in other projects, especially those not Python-based. This will be created from the data within the python package, so ensure that this is up to date. See data_gen/README.md for more info. 
+
+```bash
+just gen-jsons
+```
+
+## Overview
+
+The following lookups are available:
+
+### Amino Acids
+- Standard and non-standard amino acid lookups
+- Query by single-letter code, three-letter code, or full name
+- Access to molecular properties (mass, formula, etc.)
+
+### Modifications
+- Post-translational modifications (PTMs)
+- Query by modification name, ID, or delta mass
+- Support for Unimod, PSI-MOD, RESID, XLMOD and GNOme
+
+### Elements
+- Chemical element data
+- Query by symbol, name
+- Isotope information and masses
+
+### Additional Data Types
+- Fragment ions
+- Common neutral deltas (mainly neutral losses)
+- mzPAF reference molecules
+- Common Proteases
+
+## Architecture
+
+Each lookup contains three core components:
+
+- **data.py**: Auto-generated data file (should not be modified manually)
+- **dclass.py**: Dataclass definitions for the data structures
+- **lookup.py**: Lookup implementation with query methods
+
+Each lookup provides multiple query options to enable data retrieval by various means. Lookups are cached for faster repeat queries.
+
+## Usage
+
+```python
+import tacular as t
+
+# Query amino acids
+alanine = t.AA_LOOKUP['A']
+carbon_13 = t.ELEMENT_LOOKUP['13C']
+```

tacular-1.0.0/README.md

@@ -0,0 +1,66 @@
+# tacular
+
+[![Python package](https://github.com/pgarrett-scripps/tacular/actions/workflows/python-package.yml/badge.svg)](https://github.com/pgarrett-scripps/tacular/actions/workflows/python-package.yml)
+[![codecov](https://codecov.io/github/tacular-omics/tacular/graph/badge.svg?token=1CTVZVFXF7)](https://codecov.io/github/tacular-omics/tacular)
+[![PyPI version](https://badge.fury.io/py/tacular.svg)](https://badge.fury.io/py/tacular)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A helper package for peptacular and paftacular. Includes lookups for modifications, amino acids, and other data types.
+
+## Generate Data
+
+See data_gen/README.md
+
+## Generating JSONs
+
+It's possible to generate JSON objects for all parsed data used within tacular. This isn't used within tacular or its downstream packages, but may be useful in other projects, especially those not Python-based. This will be created from the data within the python package, so ensure that this is up to date. See data_gen/README.md for more info. 
+
+```bash
+just gen-jsons
+```
+
+## Overview
+
+The following lookups are available:
+
+### Amino Acids
+- Standard and non-standard amino acid lookups
+- Query by single-letter code, three-letter code, or full name
+- Access to molecular properties (mass, formula, etc.)
+
+### Modifications
+- Post-translational modifications (PTMs)
+- Query by modification name, ID, or delta mass
+- Support for Unimod, PSI-MOD, RESID, XLMOD and GNOme
+
+### Elements
+- Chemical element data
+- Query by symbol, name
+- Isotope information and masses
+
+### Additional Data Types
+- Fragment ions
+- Common neutral deltas (mainly neutral losses)
+- mzPAF reference molecules
+- Common Proteases
+
+## Architecture
+
+Each lookup contains three core components:
+
+- **data.py**: Auto-generated data file (should not be modified manually)
+- **dclass.py**: Dataclass definitions for the data structures
+- **lookup.py**: Lookup implementation with query methods
+
+Each lookup provides multiple query options to enable data retrieval by various means. Lookups are cached for faster repeat queries.
+
+## Usage
+
+```python
+import tacular as t
+
+# Query amino acids
+alanine = t.AA_LOOKUP['A']
+carbon_13 = t.ELEMENT_LOOKUP['13C']
+```

tacular-1.0.0/conftest.py

@@ -0,0 +1,8 @@
+import pytest
+
+from tacular.elements import ELEMENT_LOOKUP
+
+
+@pytest.fixture(autouse=True)
+def add_lookup(doctest_namespace):
+    doctest_namespace["lookup"] = ELEMENT_LOOKUP