# 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/)
Raw data
{
"_id": null,
"home_page": null,
"name": "af3jobs",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "AlphaFold, bioinformatics, molecular biology, protein modeling",
"author": null,
"author_email": "Karl Gruber <gammaturn@gmail.com>, Gregor Wirnsberger <gregor.wirnsberger@uni-graz.at>",
"download_url": null,
"platform": null,
"description": "# af3jobs\n\n`af3jobs` is a Python package designed to streamline the process of creating JSON input files for AlphaFold 3.\nIt provides data structures and tools for defining molecular components, modifications, and job\nconfigurations compatible with both the [AlphaFold server](https://alphafoldserver.com/welcome) and the [standalone version](https://github.com/google-deepmind/alphafold3).\n\n## Features\n\n- Define **protein**, **DNA**, and **RNA chains** with sequence modifications (e.g., PTMs, nucleotide modifications).\n- Add **ligands**, **ions**, and other small molecules with CCD codes or SMILES strings.\n- Extract multiple sequence alignments and templates from JSON files generated by AF3 and attach them to a protein\nor RNA chain.\n- Read an MSA from A3M formatted alignment files.\n\n## Installation\n\nYou can install `af3jobs` using `pip`:\n\n```bash\npip install af3jobs\n```\n\nAlternatively, clone the repository and install the package using `pip`:\n\n```bash\ngit clone https://github.com/your_username/af3jobs.git\ncd af3jobs\npip install .\n```\n\nOr install the package directly from GitHub:\n\n```bash\npip install git+https://github.com/ugSUBMARINE/af3jobs.git\n```\n\n## Usage\n\nThe `Job` class is the main container for combining protein and nucleotide chains, ligands/ions, and modifications\nthat can be converted to JSON as input for AlphaFold 3.\n\n```python\nfrom af3jobs import Job\n\n# Create a new job\njob = Job(name=\"Sample AlphaFold Job\", model_seeds=[42])\n\n# Add a protein chain with modifications\n# The method returns the chain object, which can be used to add modifications, alignments, etc.\nprotein_chain = job.add_protein_chain(sequence=\"MVLSEGEWQLVLHVWAKVEA\", count=2)\n\n# Add MSA and templates from the output JSON file of a previous job\n# MSAs could also be read from A3M files using 'protein_chain.add_msa_from_a3m(\"msa.a3m\")'\nprotein_chain.add_msa_from_json(\"some_job_data.json\")\nprotein_chain.add_templates_from_json(\"some_job_data.json\")\n\n# Add a DNA chain with modifications\ndna_chain = job.add_dna_chain(sequence=\"GATTACA\", ids=\"C\")\ndna_chain.add_modification(mod_type=\"6OG\", position=1)\n\n# Add a bonded atom pair\njob.add_bonded_atom_pair(id_1=\"A\", resi_1=1, name_1=\"N\", id_2=\"B\", resi_2=2, name_2=\"C\")\n\n# Add two heme cofactors\njob.add_ligand(ccd_codes=\"HEM\", ids=[\"X\", \"Y\"])\n\n# Export to JSON\njob.write_af3_json(\"standalone_job.json\", indent=4)\n```\n\n### Server Job Example\n\nThe `ServerJob` class can be used in a similar way to prepare jobs for the [AlphaFold server](https://alphafoldserver.com/welcome).\n(The two types of JSON input files are not interchangeable!)\n\n```python\nimport json\nfrom af3jobs import ServerJob\n\n# Create a new job\njob = ServerJob(name=\"Sample AlphaFold Server Job\")\n\n# Add a protein chain with glycans and modifications, set a maximum date for the used template\nprotein_chain = job.add_protein_chain(sequence=\"PREACHINGS\", count=1, max_template_date=\"2018-01-20\")\nprotein_chain.add_glycan(residues=\"NAG(NAG)(BMA)\", position=8)\nprotein_chain.add_glycan(residues=\"BMA\", position=10)\nprotein_chain.add_modification(mod_type=\"CCD_HY3\", position=1)\nprotein_chain.add_modification(mod_type=\"CCD_P1L\", position=5)\n\n# Add a protein chain for which the structure templates should not be used\nprotein_chain_no_templates = job.add_protein_chain(sequence=\"REACHER\", count=1, use_structure_template=False)\n\n# Add a DNA chain with modifications\ndna_chain = job.add_dna_chain(sequence=\"GATTACA\", count=1)\ndna_chain.add_modification(mod_type=\"CCD_6OG\", position=1)\ndna_chain.add_modification(mod_type=\"CCD_6MA\", position=2)\n\n# Add an RNA chain with modifications\nrna_chain = job.add_rna_chain(sequence=\"GUAC\", count=1)\nrna_chain.add_modification(mod_type=\"CCD_2MG\", position=1)\n\n# Add a ligand and an ion\njob.add_ligand(ligand_type=\"CCD_ATP\", count=1)\njob.add_ion(ion_type=\"MG\", count=2)\n\n# Convert the job to a dictionary and print it\njob_dict = job.to_dict()\nprint(\"Job as dictionary:\", job_dict)\n\n# Save the job as a JSON file\nwith open(\"job_request.json\", \"w\") as json_file:\n json.dump([job_dict], json_file, indent=4)\n```\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n## References\n\n- [AlphaFold3 input file format](https://github.com/google-deepmind/alphafold3/blob/main/docs/input.md)\n- [AlphaFold Server Documentation](https://github.com/google-deepmind/alphafold/blob/main/server/README.md)\n- [CCD Ligand Dictionary](https://www.ebi.ac.uk/pdbe-srv/pdbechem/)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Module for defining molecular components, modifications, and job configurations for AlphaFold 3",
"version": "0.3.0",
"project_urls": {
"Homepage": "https://github.com/ugSUBMARINE/af3jobs",
"Source": "https://github.com/ugSUBMARINE/af3jobs",
"Tracker": "https://github.com/ugSUBMARINE/af3jobs/issues"
},
"split_keywords": [
"alphafold",
" bioinformatics",
" molecular biology",
" protein modeling"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "081cec9463ffebb9b676674012e5fe7862814a1269e661dcaf3dcf7f83740357",
"md5": "ffc37bfe833fa8b63323d1af81772e11",
"sha256": "c9a657538b24616cd7cd4d6f5d1adbf0767b9335722c6a4de99d159a13ff2805"
},
"downloads": -1,
"filename": "af3jobs-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ffc37bfe833fa8b63323d1af81772e11",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 13638,
"upload_time": "2025-10-10T19:46:34",
"upload_time_iso_8601": "2025-10-10T19:46:34.251423Z",
"url": "https://files.pythonhosted.org/packages/08/1c/ec9463ffebb9b676674012e5fe7862814a1269e661dcaf3dcf7f83740357/af3jobs-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-10 19:46:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ugSUBMARINE",
"github_project": "af3jobs",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "af3jobs"
}
JSON
