Metadata-Version: 2.4
Name: AlphaFetcher
Version: 0.2.0
Summary: This package allows interface with the AlphaFold Protein Structure Database. This package allows the download of entries' metadata an AlphaFold files (e.g. mmCIF, PAE, PDB...)
Home-page: https://bitbucket.org/bio2byte/alphafetcher/
Author: Jose Gavalda-Garcia
Author-email: jose.gavalda.garcia@vub.be
Maintainer: Jose Gavalda-Garcia
Maintainer-email: jose.gavalda.garcia@vub.be
License: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
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: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: Development Status :: 5 - Production/Stable
Requires-Python: >=3.6, <3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Requires-Dist: tqdm
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: maintainer
Dynamic: maintainer-email
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# AlphaFetcher

`AlphaFetcher` facilitates fetching and downloading protein metadata and related files from the 
[AlphaFold Protein Structure Database](https://alphafold.ebi.ac.uk/) 
using Uniprot access codes.

---

## 🌟 Features

- **Batch Import**: Input single or multiple Uniprot access codes seamlessly.
  
- **Parallel Processing**: Efficiently fetch metadata using multithreading.
  
- **Flexible Downloads**: Choose among various file types - PDB, CIF, BCIF, PAE image, and PAE data files.
  
- **Optimal Performance**: Easily adjust the number of workers for threaded tasks.

---

## 🔧 Installation

We recommend PyPI installation:

```bash
pip install alphafetcher
```

---

## 💡 Usage

```python
from alphafetcher import AlphaFetcher

# Instantiate the fetcher
# The base_savedir parameter allows you to set a base directory where files will be saved.
# Inside this directory, two separate directories for pdb and cif files will be created.
fetcher = AlphaFetcher(base_savedir="my_savedir")

# Add desired Uniprot access codes
fetcher.add_proteins(["A1KXE4", "H0YL14", "B2RXH2", "A8MVW5"])

# Retrieve metadata
fetcher.fetch_metadata(multithread=True, workers=4)
# Metadata available at fetcher.metadata_dict

# Commence download of specified files
fetcher.download_all_files(pdb=True, cif=True, multithread=True, workers=4)
```

---

## 📜 Documentation

### Initialization

- **`AlphaFetcher(base_savedir: str)`**
  - *Description*: Initialize the fetcher with a base save directory. The `base_savedir` is where the downloaded pdb and cif files will be stored. Inside this directory, two subdirectories will be automatically created: one for pdb files and another for cif files.
  - *Parameters*:
    - `base_savedir`: The base directory where the pdb and cif files will be saved.


### Methods

- **`add_proteins(proteins: Union[str, List[str]])`**
  - *Description*: Add the provided Uniprot access codes for fetching. A single string or a list of strings are 
    accepted. 

- **`fetch_metadata(multithread: bool = False, workers: int = 10)`**
  - *Description*: Extracts metadata corresponding to the supplied Uniprot access codes. This metadata is used to 
    download the relevant files and is stored in ```fetcher.metadata_dict```, assuming the notation of the example
    above is followed.
  
- **`download_all_files(uniprot_access: str, pdb: bool = False, cif: bool = False, bcif: bool = False, 
  pae_image:bool = False, pae_data: bool = False)`**
  - *Description*: Initiates download for the specified file types linked to the given Uniprot codes.
  - Specify the types of files to be downloaded by changing the values of their parameters to True.

*For a comprehensive guide, users are encouraged to view the docstrings incorporated within the source code.*

---

## ⚠️ Limitations

Always respect the AlphaFold Protein Structure Database terms of service, ensuring not to flood it with excessive 
concurrent requests. Consider adjusting the number of workers to reduce the requests density. 

---

## 🙌 Contributing

We welcome your contributions! To collaborate:
1. Fork this repository.
2. Commit your changes.
3. Open a pull request with your updates.

---

## 📖 Authors and Acknowledgment

- **Jose Gavalda-Garcia** - *Author* - [jose.gavalda.garcia@vub.be](mailto:jose.gavalda.garcia@vub.be)
- **Wim Vranken** - *Supervisor* - [wim.vranken@vub.be](mailto:wim.vranken@vub.be)

---

## 📄 License

This project is licensed under the [GNU General Public License v3 (GPLv3)](https://www.gnu.org/licenses/gpl-3.0.en.html).
