Metadata-Version: 2.4
Name: csa3d
Version: 0.2.1
Summary: Extract and analyze enzyme catalytic sites in 3D from the Mechanism and Catalytic Site Atlas (M-CSA)
Author-email: Ioannis Riziotis <riziotis@ebi.ac.uk>
License: Apache-2.0
Project-URL: Homepage, https://github.com/your-username/csa3d
Project-URL: Documentation, https://csa3d.readthedocs.io
Project-URL: Repository, https://github.com/your-username/csa3d
Project-URL: Issue Tracker, https://github.com/your-username/csa3d/issues
Keywords: enzymes,catalysis,structural-biology,M-CSA,active-sites
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: biopython>=1.81
Requires-Dist: numpy>=1.21.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: scikit-learn>=0.24.0
Requires-Dist: rdkit>=2021.09.0
Requires-Dist: natsort>=8.0.0
Requires-Dist: rmsd>=1.4.0
Provides-Extra: clustering
Requires-Dist: matplotlib>=3.5; extra == "clustering"
Requires-Dist: plotly>=5.0; extra == "clustering"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: isort>=5.12; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: types-setuptools; extra == "dev"
Requires-Dist: types-requests; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=6.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.2; extra == "docs"
Requires-Dist: myst-parser>=0.19; extra == "docs"
Provides-Extra: examples
Requires-Dist: jupyter>=1.0; extra == "examples"
Requires-Dist: notebook>=6.0; extra == "examples"
Requires-Dist: matplotlib>=3.5; extra == "examples"
Dynamic: license-file

# CSA-3D: 3D Analysis of Enzyme Catalytic Sites

A Python package for extracting, analyzing, and manipulating enzyme catalytic sites in three dimensions from the **Mechanism and Catalytic Site Atlas (M-CSA)** hosted at [EMBL-EBI](https://www.ebi.ac.uk/thornton-srv/m-csa/).

## What is CSA-3D?

CSA-3D enables computational biochemists and structural biologists to:

- **Extract** catalytic site geometries from PDB structures and UniProt sequences
- **Compare** active sites across homologous proteins using RMSD clustering
- **Create** structure templates for enzyme active sites with geometric constraints
- **Analyze** ligand proximity and chemical similarity in active sites
- **Visualize** and export catalytic site information in multiple formats

This package was developed to support research on enzyme mechanisms and is particularly useful for:
- Comparative structural analysis of enzyme families
- Active site template generation for molecular docking
- Catalytic site conservation studies
- Structure-guided annotation of enzyme function

**See also**: [CSA-3D paper](https://www.sciencedirect.com/science/article/pii/S0022283622000912)

## Installation

### Requirements

- Python 3.8 or higher
- ~50 GB of disk space for complete M-CSA dataset (can work with subsets)

### Installation from PyPI

```bash
pip install csa3d
```

### Installation from Source

```bash
git clone https://github.com/your-username/csa3d.git
cd csa3d
pip install -e ".[dev]"
```

### Development Installation

For development with testing and documentation tools:

```bash
pip install -e ".[dev,docs]"
```

## Quick Start

### 1. Configure Data Directory

First, you need to set up the M-CSA data files. You can either:

**Option A: Download automatically (recommended)**
```python
from csa3d import config
config.setup_data("/path/to/csa3d_data")  # Downloads ~50 GB
```

**Option B: Set environment variable**
```bash
export CSA3D_DATA_DIR="/path/to/csa3d_data"
```

**Option C: Set in code**
```python
from csa3d import config
config.set_data_dir("/path/to/csa3d_data")
```

### 2. Load and Inspect Active Sites

```python
from csa3d import Mcsa

# Initialize the database
db = Mcsa()

# Build a specific entry (e.g., M-CSA ID 1)
db.build(entry_ids=1, annotate=True)

# Iterate over entries
for entry in db:
    print(f"Entry {entry.mcsa_id}: {len(entry.pdbsites)} PDB sites")
    
    # Get information
    print(f"  EC Number: {entry.info['ec']}")
    print(f"  Enzyme: {entry.info['enzyme_name']}")
    
    # Inspect active sites
    for site in entry.get_pdbsites(sane_only=True):
        print(f"    PDB: {site.pdb_id}, {len(site.residues)} residues")
        print(f"    Resolution: {site.resolution} Å")
```

### 3. Clustering and Template Creation

```python
# Build multiple entries
db.build(entry_ids=[1, 2, 3], annotate=True)
entry = db.entries[1]

# Calculate RMSD between all active sites
sites = list(entry.get_pdbsites(sane_only=True))
rmsd_matrix = entry.rmsd_matrix(sites)

# Cluster sites by similarity
clusters = entry.clustering(rmsd_matrix, height=1.5)

print(f"Found {len(clusters)} clusters")
for cluster_id, site_ids in clusters.items():
    print(f"  Cluster {cluster_id}: {len(site_ids)} sites")

# Create a template from conserved sites
template = entry.create_template(outdir="./templates")
print(f"Template created: {template.id}")
```

## Data Requirements

CSA-3D requires data from several external sources:

### Core M-CSA Data
- `mcsa/catalytic_residues_homologues.json` - Homologous catalytic residues
- `mcsa/catalytic_residues_references.json` - Reference catalytic residues
- `mcsa/entry_info/mcsa_entry_info.*.json` - Entry metadata

### PDB Data
- `pdbe/assembly_cif/cif/` - PDB assembly structures (mmCIF format)
- `pdbe/pdb_ions.csv` - Ion classification
- `pdbe/pdb_cofactors.csv` - Cofactor information
- `pdbe/crystallization_hets.csv` - Crystallization artifacts

### Sequence/Mapping Data (SIFTS)
- `sifts/uniprot_pdb.csv` - UniProt to PDB mapping
- `sifts/pdb_chain_uniprot.csv` - PDB to UniProt mapping
- `sifts/pdb_chain_enzyme.csv` - PDB to EC number mapping

### Reaction Data
- `kegg/kegg_reaction_components.csv` - KEGG enzyme reactions
- `rhea/rhea_reaction_components.csv` - RHEA reactions
- `pdbe/resolu.idx` - PDB resolution index

### Molecule Data
- `kegg/sdf/` - KEGG small molecules
- `chebi/sdf/` - ChEBI compounds
- `pdbe/het_sdf/` - PDB heteroatom structures

To download all data:
```python
from csa3d.config import setup_data
setup_data("/path/to/csa3d_data")
```

Alternatively, download manually from:
- M-CSA: https://www.ebi.ac.uk/thornton-srv/m-csa/download/
- PDBe: https://www.ebi.ac.uk/pdbe/download/
- SIFTS: https://www.ebi.ac.uk/pdbe/docs/sifts/
- KEGG: https://www.kegg.jp/
- RHEA: https://www.rhea-db.org/

## Usage Examples

### Comparing Two Active Sites

```python
from csa3d import Mcsa

db = Mcsa()
db.build(entry_ids=1)
entry = db.entries[1]

sites = list(entry.get_pdbsites(sane_only=True))
if len(sites) >= 2:
    site1, site2 = sites[0], sites[1]
    
    # Structural alignment
    rotation, translation, rmsd_ca, rmsd_all = site1.fit(site2, weighted=True)
    print(f"RMSD (backbone): {rmsd_ca:.2f} Å")
    print(f"RMSD (all atoms): {rmsd_all:.2f} Å")
```

### Writing Templates for Docking

```python
# Create template with specific parameters
template = entry.create_template(
    ca=False,                    # Use all heavy atoms
    outdir="./templates",
    outfile="myenzyme.template.pdb",
    all_fuzzy=False,            # Use conservative fuzzy matching
    no_alt=False                # Include alternative residue options
)

# Template can be used with docking software like TESS/Jess
```

### Batch Processing

```python
from csa3d import Mcsa

db = Mcsa()

# Build all entries (takes time)
entry_ids = list(db.catalytic_residue_info.keys())
db.build(entry_ids=entry_ids[:10], verbose=True)  # First 10

# Analyze
for entry in db:
    n_sites = len(entry.pdbsites)
    n_clusters = len(entry.clustering(entry.rmsd_matrix(list(entry.get_pdbsites()))))
    print(f"{entry.mcsa_id}: {n_sites} sites, {n_clusters} clusters")
```

## Key Classes

### Mcsa
Main database class. Load and manage M-CSA entries.
```python
db = Mcsa()
db.build(entry_ids=1)  # Build specific entry
entry = db.entries[1]  # Access Entry object
```

### Entry
Represents one M-CSA entry containing PDB and UniProt active sites.
```python
entry.pdbsites           # List of PdbSite objects
entry.unisites           # List of UniSite objects
entry.create_template()  # Generate template
entry.clustering()       # RMSD-based clustering
```

### PdbSite
A catalytic site from a PDB structure.
```python
site.pdb_id              # PDB identifier
site.residues            # Catalytic residues
site.ligands             # Proximal ligands
site.fit(other_site)     # Structural alignment
```

### UniSite
A catalytic site from UniProt sequence.
```python
site.uniprot_id          # UniProt accession
site.residues            # Catalytic residues
```

## Configuration

### Environment Variables

- `CSA3D_DATA_DIR` - Path to M-CSA data directory (default: auto-detect)

### Configuration File

Create `~/.csa3d/config.yml`:
```yaml
data_dir: /path/to/csa3d_data
```

### In Code

```python
from csa3d import config

config.set_data_dir("/path/to/data")
config.validate_config()  # Check if valid
print(config.get_data_dir())
```

## Documentation

- [Architecture Guide](docs/architecture.md) - System design and data flow
- [API Reference](https://csa3d.readthedocs.io) - Full API documentation
- [Examples](examples/) - Jupyter notebooks and scripts

## Testing

Run tests with pytest:
```bash
pytest tests/
```

Run with coverage:
```bash
pytest --cov=csa3d tests/
```

## Performance Considerations

- **First run** is slow (~minutes) as PDB structures are parsed and cached
- **RMSD clustering** on large site sets can be memory-intensive
- **Template creation** involves fitting multiple structures (depends on cluster size)

Tips:
- Use `sane_only=True` to filter low-quality sites
- Process entries in batches
- Use `resolution_cutoff` to filter low-resolution structures
- Cache parsed entries with pickle for reuse

## Citation

If you use CSA-3D in your research, please cite:

```bibtex
@article{Riziotis2022,
    title={CSA-3D: {A} framework to manipulate enzyme catalytic sites in three dimensions},
    author={Riziotis, Ioannis and others},
    journal={Journal of Molecular Biology},
    volume={434},
    number={5},
    pages={167488},
    year={2022},
    issn={0022-2836},
    doi={10.1016/j.jmb.2022.167488},
    url={https://www.sciencedirect.com/science/article/pii/S0022283622000912}
}
```

## Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/my-feature`
3. Make changes and add tests
4. Run quality checks: `make lint`
5. Submit a pull request

## Issues & Support

- **Bug reports**: [GitHub Issues](https://github.com/your-username/csa3d/issues)
- **Questions**: Create a discussion or post an issue
- **Feature requests**: Open an issue with `[FEATURE]` prefix

## License

Apache License 2.0 - see LICENSE file for details

## Contact

- **Author**: Ioannis Riziotis
- **Email**: riziotis@ebi.ac.uk
- **Affiliation**: EMBL-EBI, Wellcome Trust Genome Campus, Cambridge, UK

## Acknowledgments

CSA-3D is built on top of several excellent packages:
- [Biopython](https://biopython.org/) - Biological computation
- [NumPy](https://numpy.org/) - Numerical computing
- [SciPy](https://scipy.org/) - Scientific computing
- [scikit-learn](https://scikit-learn.org/) - Machine learning
- [RDKit](https://www.rdkit.org/) - Cheminformatics

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history and breaking changes.

---

**Questions?** See [docs/faq.md](docs/faq.md) or open an issue.
