af3jobs 0.3.0
Module for defining molecular components, modifications, and job configurations for AlphaFold 3
License: MIT
Requires Python: >=3.11
Keywords: AlphaFold, bioinformatics, molecular biology, protein modeling

# af3jobs

`af3jobs` is a Python package designed to streamline the process of creating JSON input files for AlphaFold 3.
It provides data structures and tools for defining molecular components, modifications, and job
configurations compatible with both the [AlphaFold server](https://alphafoldserver.com/welcome) and the [standalone version](https://github.com/google-deepmind/alphafold3).

## Features

- Define **protein**, **DNA**, and **RNA chains** with sequence modifications (e.g., PTMs, nucleotide modifications).
- Add **ligands**, **ions**, and other small molecules with CCD codes or SMILES strings.
- Extract multiple sequence alignments and templates from JSON files generated by AF3 and attach them to a protein
or RNA chain.
- Read an MSA from A3M formatted alignment files.

## Installation

You can install `af3jobs` using `pip`:

```bash
pip install af3jobs
```

Alternatively, clone the repository and install the package using `pip`:

```bash
git clone https://github.com/your_username/af3jobs.git
cd af3jobs
pip install .
```

Or install the package directly from GitHub:

```bash
pip install git+https://github.com/ugSUBMARINE/af3jobs.git
```

## Usage

The `Job` class is the main container for combining protein and nucleotide chains, ligands/ions, and modifications
that can be converted to JSON as input for AlphaFold 3.

```python
from af3jobs import Job

# Create a new job
job = Job(name="Sample AlphaFold Job", model_seeds=[42])

# Add a protein chain with modifications
# The method returns the chain object, which can be used to add modifications, alignments, etc.
protein_chain = job.add_protein_chain(sequence="MVLSEGEWQLVLHVWAKVEA", count=2)

# Add MSA and templates from the output JSON file of a previous job
# MSAs could also be read from A3M files using 'protein_chain.add_msa_from_a3m("msa.a3m")'
protein_chain.add_msa_from_json("some_job_data.json")
protein_chain.add_templates_from_json("some_job_data.json")

# Add a DNA chain with modifications
dna_chain = job.add_dna_chain(sequence="GATTACA", ids="C")
dna_chain.add_modification(mod_type="6OG", position=1)

# Add a bonded atom pair
job.add_bonded_atom_pair(id_1="A", resi_1=1, name_1="N", id_2="B", resi_2=2, name_2="C")

# Add two heme cofactors
job.add_ligand(ccd_codes="HEM", ids=["X", "Y"])

# Export to JSON
job.write_af3_json("standalone_job.json", indent=4)
```

### Server Job Example

The `ServerJob` class can be used in a similar way to prepare jobs for the [AlphaFold server](https://alphafoldserver.com/welcome).
(The two types of JSON input files are not interchangeable!)

```python
import json
from af3jobs import ServerJob

# Create a new job
job = ServerJob(name="Sample AlphaFold Server Job")

# Add a protein chain with glycans and modifications, set a maximum date for the used template
protein_chain = job.add_protein_chain(sequence="PREACHINGS", count=1, max_template_date="2018-01-20")
protein_chain.add_glycan(residues="NAG(NAG)(BMA)", position=8)
protein_chain.add_glycan(residues="BMA", position=10)
protein_chain.add_modification(mod_type="CCD_HY3", position=1)
protein_chain.add_modification(mod_type="CCD_P1L", position=5)

# Add a protein chain for which the structure templates should not be used
protein_chain_no_templates = job.add_protein_chain(sequence="REACHER", count=1, use_structure_template=False)

# Add a DNA chain with modifications
dna_chain = job.add_dna_chain(sequence="GATTACA", count=1)
dna_chain.add_modification(mod_type="CCD_6OG", position=1)
dna_chain.add_modification(mod_type="CCD_6MA", position=2)

# Add an RNA chain with modifications
rna_chain = job.add_rna_chain(sequence="GUAC", count=1)
rna_chain.add_modification(mod_type="CCD_2MG", position=1)

# Add a ligand and an ion
job.add_ligand(ligand_type="CCD_ATP", count=1)
job.add_ion(ion_type="MG", count=2)

# Convert the job to a dictionary and print it
job_dict = job.to_dict()
print("Job as dictionary:", job_dict)

# Save the job as a JSON file
with open("job_request.json", "w") as json_file:
    json.dump([job_dict], json_file, indent=4)
```

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

## References

- [AlphaFold3 input file format](https://github.com/google-deepmind/alphafold3/blob/main/docs/input.md)
- [AlphaFold Server Documentation](https://github.com/google-deepmind/alphafold/blob/main/server/README.md)
- [CCD Ligand Dictionary](https://www.ebi.ac.uk/pdbe-srv/pdbechem/)