# SADIC v2: A Modern Implementation of the Simple Atom Depth Index Calculator
[](https://opensource.org/licenses/MIT)
[](https://badge.fury.io/py/sadic)
[](https://pepy.tech/project/sadic)
This repository contains the source code for the SADIC v2 package, a modern implementation of the Simple Atom Depth Index Calculator, used to compute the SADIC depth index, a measure of atom depth in protein molecules.
The package is designed to be easy to use and to provide a fast and efficient implementation of the algorithm.
It is built to be used as a command line tool or as a Python library.
The package exposes functions to all the single steps of the algorithm, allowing the user to have full control over the computation, as well as a high-level function to compute the SADIC indices with a single line of python code.
**Authors**
- Giacomo Nunziati
- Alessia Lucia Prete
- Sara Marziali
<!-- ### Table of Contents
- **[Install](#install)**
- **[Install from PyPI](#install-from-pypi)**
- **[Install from source](#install-from-source)**
- **[Requirements](#requirements)**
- **[Usage](#usage)**
- **[Command Line Interface (CLI)](#command-line-interface-cli)**
- **[Python interface](#python-interface)**
- **[Simple usage](#simple-usage)**
- **[Filter and aggregations](#filter-and-aggregations)**
- **[Software](#software)**
- **[Main algorithm](#main-algorithm)**
- **[Architecture](#architecture)**
- **[Functionalities](#functionalities)**
<!-- - **[Citing](#citing)**
- **[License](#license)** -->
## Install
### Install from PyPI
```bash
pip install sadic
```
### Install from source
```bash
git clone https://github.com/nunziati/sadic.git
cd sadic
pip install .
```
### Requirements
SADIC v2 requires the packages **numpy**, **scipy**, **biopandas** and **biopython**.
The requirements are automatically downloaded while installing this package.
To in stall the requirements separately, run the following command:
```bash
pip install -U -r requirements.txt
```
## Usage
The algorithm processes a protein structure and computes the depth index for each atom in the structure.
The protein structure can be provided as a PDB code or as a path to a PDB file.
The package is integrated with BioPython and BioPandas, so the input can also be provided as a BioPython Structure object or a BioPandas PDB Entity object.
### Command Line Interface (CLI)
Simplified interface for the command line usage of the package.
The CLI interface only allows to specify the input as a PDB code or a path to a PDB file. The output is returned as a PDB file.
```bash
sadic <input> --output <output> [--config <config_file>]
```
Input can be:
- a PDB code of a protein structure
- a path to a PDB file (.pdb or .tar.gz)
Output must be a path of a PDB file (.pdb or .tar.gz)
Config file is optional and, if specified, must be a path to a python file (.py) containing two dictionaries:
- sadic_config: a dictionary containing the configuration parameters for the SADIC algorithm
- output_config: a dictionary containing the configuration parameters for the output file
---
### Python interface
#### Simple usage
```python
import sadic
# Input protein
pdb_code = "1GWD"
# Run the pipeline
result = sadic.sadic(pdb_code)
# (optional) Useful to retrieve the depth indices from the result object
output = result.get_depth_index()
# Save the output to a file
result.save_pdb("1gwd_sadic.pdb")
```
#### Filter and aggregations
Note: filters, atom aggregations and model aggregations are optional and independent from each other.<br>
They can be used in any combination.
```python
import sadic
# Input protein
pdb_code = "1GWD"
# Define the filter options
# Only return the SADIC indices for the atoms composing the alanine and glycine residues
filter_arg = {"residue_name": ["ALA", "GLY"]}
# Define the atom aggregation options
# Compute the depth index for each residue by averaging the depth indices of the atoms composing it
group_by = "residue_number"
aggregation_function = "mean"
atom_aggregation_arg = (group_by, aggregation_function)
# Define the model aggregation options
# If the pdb file contains multiple models, they can be aggregated
# In this case, the depth indices of corresponding atoms in different models are averaged
model_aggregation_arg = "mean"
# Run the pipeline
# Filter by residue name
result = sadic.sadic(pdb_code, filter_by = filter_arg)
# (optional) Useful to retrieve the depth indices from the result object
# Aggregate the depth indices of the atoms of the same residue
output = result.get_depth_index(atom_aggregation = atom_aggregation_arg)
# Save the output to a file
# Aggregate the depth indices of the different models
result.save_pdb("1gwd_sadic.pdb", model_aggregation = model_aggregation_arg)
```
## Software
Our approach involves modeling each protein as a solid object composed of spheres centered on single atoms.
SADIC simulates the probing of the protein computing the largest sphere inscribed in its molecular structure.
Let $r$ be the radius of such sphere and $V_{r_{max}}$ its volume.
During the simulation, the reference sphere is iteratively centered on each atom $i$, and the exposed volume $V_{r,i}$ is calculated.
The evaluation of the atom depth index $D_{i,r}$ for the $i$-th atom is determined by the formula:
$$ D_{i,r} = \frac{2V_{r,i}}{V_{r_{max}}} $$
The exposed volume $V_{r,i}$ indicates the volume of the portion of the reference sphere centered on the $i$-th atom that does not intersect the solid representation of the protein.
### Main algorithm
#### The execution of the SADIC v2 algorithm is articulated in multiple stages:
- Loading of protein data;
- Creation of the structured PDB entity;
- For each model found in the PDB file:
- Creation of the continuous-space model of the protein under analysis;
- Voxelization and definition of the discrete-space model approximating the protein solid;
- Filling of the internal cavities of the protein;
- Computation of the reference radius, that will be used for the depth index calculation;
- Computation of the depth indexes for the atoms selected by the user.
<!--  -->
<!-- For a more comprehensive understanding of the implementation and analysis of the SADIC v2 algorithm's main pipeline, additional details are available in WAITING FOR CITATION, that presents a deeper exploration and analysis of the algorithm's execution stages. -->
---
### Architecture
The software architecture of SADIC v2 is organized into distinct sub-packages:
- **pdb** for organizing the data of the input protein and managing the result of the execution of the algorithms;
- **solid** for modeling and manipulating the continuous-space and discrete-space solids representing the molecule;
- **algorithm** where the core algorithms are defined
The main **sadic** package exposes an API with a single function for executing the depth index computation pipeline.
<!--  -->
---
### Functionalities
#### Different types of input are supported:
- PDB code
- PDB file (raw *.pdb* or compressed *.tar.gz*)
- BioPython Structure object
- BioPandas PDB Entity object
#### The user can specify different options:
- Reference sphere radius
- Van Der Waals radii for the atoms
- Grid resolution for the discretization of the protein
- Protein models to consider (in case of multiple models)
- Atom filters, to select only a subset of atoms
- Atom aggregations, to compute the depth index for groups of atoms
- Model aggregations, to obtain a single depth index for each atom (in case of multiple models)
#### The output can be obtained in different forms:
- Python list
- Numpy array
- Save to a .txt file
- Save to a .npy file (NumPy)
- PDB file (raw *.pdb* or compressed *.tar.gz*)
<!-- ## Citing
**_Waiting for submission/preprint/pubblication_** -->
## License
This project is [MIT](https://choosealicense.com/licenses/mit/) licensed.
Raw data
{
"_id": null,
"home_page": "https://github.com/nunziati/sadic",
"name": "sadic",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "protein atom depth",
"author": "Giacomo Nunziati",
"author_email": "giacomo.nunziati.0@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/82/51/b41874f9770a2f40bc837413c427c683456ca10d7fdea53f4f365c2e8741/sadic-2.0.0.tar.gz",
"platform": null,
"description": "# SADIC v2: A Modern Implementation of the Simple Atom Depth Index Calculator\n\n[](https://opensource.org/licenses/MIT)\n[](https://badge.fury.io/py/sadic)\n[](https://pepy.tech/project/sadic)\n\nThis repository contains the source code for the SADIC v2 package, a modern implementation of the Simple Atom Depth Index Calculator, used to compute the SADIC depth index, a measure of atom depth in protein molecules.\n\nThe package is designed to be easy to use and to provide a fast and efficient implementation of the algorithm.\n\nIt is built to be used as a command line tool or as a Python library.\nThe package exposes functions to all the single steps of the algorithm, allowing the user to have full control over the computation, as well as a high-level function to compute the SADIC indices with a single line of python code.\n\n**Authors**\n- Giacomo Nunziati\n- Alessia Lucia Prete\n- Sara Marziali\n\n<!-- ### Table of Contents\n- **[Install](#install)**\n - **[Install from PyPI](#install-from-pypi)**\n - **[Install from source](#install-from-source)**\n - **[Requirements](#requirements)**\n- **[Usage](#usage)**\n - **[Command Line Interface (CLI)](#command-line-interface-cli)**\n - **[Python interface](#python-interface)**\n - **[Simple usage](#simple-usage)**\n - **[Filter and aggregations](#filter-and-aggregations)**\n- **[Software](#software)**\n - **[Main algorithm](#main-algorithm)**\n - **[Architecture](#architecture)**\n - **[Functionalities](#functionalities)**\n<!-- - **[Citing](#citing)**\n- **[License](#license)** -->\n\n## Install\n### Install from PyPI\n```bash\n pip install sadic\n```\n\n### Install from source\n```bash\n git clone https://github.com/nunziati/sadic.git\n cd sadic\n pip install .\n```\n\n### Requirements\nSADIC v2 requires the packages **numpy**, **scipy**, **biopandas** and **biopython**.\n\nThe requirements are automatically downloaded while installing this package.\n\nTo in stall the requirements separately, run the following command:\n\n```bash\n pip install -U -r requirements.txt\n```\n\n## Usage\nThe algorithm processes a protein structure and computes the depth index for each atom in the structure. \nThe protein structure can be provided as a PDB code or as a path to a PDB file.\nThe package is integrated with BioPython and BioPandas, so the input can also be provided as a BioPython Structure object or a BioPandas PDB Entity object.\n\n### Command Line Interface (CLI)\nSimplified interface for the command line usage of the package. \nThe CLI interface only allows to specify the input as a PDB code or a path to a PDB file. The output is returned as a PDB file.\n```bash\n sadic <input> --output\u00a0<output> [--config <config_file>]\n```\n\nInput can be:\n- a PDB code of a protein structure\n- a path to a PDB file (.pdb or .tar.gz)\n\nOutput must be a path of a PDB file (.pdb or .tar.gz)\n\nConfig file is optional and, if specified, must be a path to a python file (.py) containing two dictionaries:\n- sadic_config: a dictionary containing the configuration parameters for the SADIC algorithm\n- output_config: a dictionary containing the configuration parameters for the output file\n\n---\n\n### Python interface\n#### Simple usage\n```python\n import sadic\n\n # Input protein\n pdb_code = \"1GWD\" \n\n # Run the pipeline\n result = sadic.sadic(pdb_code)\n\n # (optional) Useful to retrieve the depth indices from the result object\n output = result.get_depth_index()\n\n # Save the output to a file\n result.save_pdb(\"1gwd_sadic.pdb\")\n```\n\n#### Filter and aggregations\nNote: filters, atom aggregations and model aggregations are optional and independent from each other.<br>\nThey can be used in any combination.\n```python\n import sadic\n\n # Input protein\n pdb_code = \"1GWD\" \n\n # Define the filter options\n # Only return the SADIC indices for the atoms composing the alanine and glycine residues\n filter_arg = {\"residue_name\": [\"ALA\", \"GLY\"]}\n\n # Define the atom aggregation options\n # Compute the depth index for each residue by averaging the depth indices of the atoms composing it\n group_by = \"residue_number\"\n aggregation_function = \"mean\"\n atom_aggregation_arg = (group_by, aggregation_function)\n\n # Define the model aggregation options\n # If the pdb file contains multiple models, they can be aggregated\n # In this case, the depth indices of corresponding atoms in different models are averaged\n model_aggregation_arg = \"mean\"\n\n # Run the pipeline\n # Filter by residue name\n result = sadic.sadic(pdb_code, filter_by = filter_arg)\n\n # (optional) Useful to retrieve the depth indices from the result object\n # Aggregate the depth indices of the atoms of the same residue\n output = result.get_depth_index(atom_aggregation = atom_aggregation_arg)\n\n # Save the output to a file\n # Aggregate the depth indices of the different models\n result.save_pdb(\"1gwd_sadic.pdb\", model_aggregation = model_aggregation_arg)\n```\n\n## Software\nOur approach involves modeling each protein as a solid object composed of spheres centered on single atoms. \nSADIC simulates the probing of the protein computing the largest sphere inscribed in its molecular structure. \nLet $r$ be the radius of such sphere and $V_{r_{max}}$ its volume. \nDuring the simulation, the reference sphere is iteratively centered on each atom $i$, and the exposed volume $V_{r,i}$ is calculated. \nThe evaluation of the atom depth index $D_{i,r}$ for the $i$-th atom is determined by the formula:\n$$ D_{i,r} = \\frac{2V_{r,i}}{V_{r_{max}}} $$\nThe exposed volume $V_{r,i}$ indicates the volume of the portion of the reference sphere centered on the $i$-th atom that does not intersect the solid representation of the protein.\n\n### Main algorithm\n#### The execution of the SADIC v2 algorithm is articulated in multiple stages:\n- Loading of protein data;\n- Creation of the structured PDB entity;\n- For each model found in the PDB file:\n - Creation of the continuous-space model of the protein under analysis;\n - Voxelization and definition of the discrete-space model approximating the protein solid;\n - Filling of the internal cavities of the protein;\n - Computation of the reference radius, that will be used for the depth index calculation;\n - Computation of the depth indexes for the atoms selected by the user.\n\n<!--  -->\n\n<!-- For a more comprehensive understanding of the implementation and analysis of the SADIC v2 algorithm's main pipeline, additional details are available in WAITING FOR CITATION, that presents a deeper exploration and analysis of the algorithm's execution stages. -->\n\n---\n\n### Architecture \nThe software architecture of SADIC v2 is organized into distinct sub-packages:\n- **pdb** for organizing the data of the input protein and managing the result of the execution of the algorithms;\n- **solid** for modeling and manipulating the continuous-space and discrete-space solids representing the molecule;\n- **algorithm** where the core algorithms are defined\n\nThe main **sadic** package exposes an API with a single function for executing the depth index computation pipeline.\n\n<!--  -->\n\n---\n\n### Functionalities\n#### Different types of input are supported:\n- PDB code\n- PDB file (raw *.pdb* or compressed *.tar.gz*)\n- BioPython Structure object\n- BioPandas PDB Entity object\n\n\n#### The user can specify different options:\n- Reference sphere radius\n- Van Der Waals radii for the atoms\n- Grid resolution for the discretization of the protein\n- Protein models to consider (in case of multiple models)\n- Atom filters, to select only a subset of atoms\n- Atom aggregations, to compute the depth index for groups of atoms\n- Model aggregations, to obtain a single depth index for each atom (in case of multiple models)\n\n#### The output can be obtained in different forms:\n- Python list\n- Numpy array\n- Save to a .txt file\n- Save to a .npy file (NumPy)\n- PDB file (raw *.pdb* or compressed *.tar.gz*)\n\n<!-- ## Citing\n**_Waiting for submission/preprint/pubblication_** -->\n\n## License\nThis project is [MIT](https://choosealicense.com/licenses/mit/) licensed.\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Reimplementation as a python package of the software for Simple Atom Depth Index Calculator (SADIC)",
"version": "2.0.0",
"project_urls": {
"Homepage": "https://github.com/nunziati/sadic"
},
"split_keywords": [
"protein",
"atom",
"depth"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9af99b46fcd2bef495db4ceaf28a0c5052c5fd61ba1169b07fccf90ee3fdf662",
"md5": "02eb9520b0cb6625259968be3d818ac3",
"sha256": "c147f78b7a6b26a478175d2bab6919ed6199cbfbc69eea7069a8b70a6632599a"
},
"downloads": -1,
"filename": "sadic-2.0.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "02eb9520b0cb6625259968be3d818ac3",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 37527,
"upload_time": "2024-03-25T14:12:49",
"upload_time_iso_8601": "2024-03-25T14:12:49.151083Z",
"url": "https://files.pythonhosted.org/packages/9a/f9/9b46fcd2bef495db4ceaf28a0c5052c5fd61ba1169b07fccf90ee3fdf662/sadic-2.0.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8251b41874f9770a2f40bc837413c427c683456ca10d7fdea53f4f365c2e8741",
"md5": "19650d05bb6e9fec53f7cade5c7aaecf",
"sha256": "fe62ee28b0d3279d29d7c758bd44d0d8ea53e591ec5a287128154911f921808d"
},
"downloads": -1,
"filename": "sadic-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "19650d05bb6e9fec53f7cade5c7aaecf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 33955,
"upload_time": "2024-03-25T14:12:51",
"upload_time_iso_8601": "2024-03-25T14:12:51.285731Z",
"url": "https://files.pythonhosted.org/packages/82/51/b41874f9770a2f40bc837413c427c683456ca10d7fdea53f4f365c2e8741/sadic-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-25 14:12:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nunziati",
"github_project": "sadic",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "sadic"
}
JSON
