sadic


Namesadic JSON
Version 2.0.0 PyPI version JSON
download
home_pagehttps://github.com/nunziati/sadic
SummaryReimplementation as a python package of the software for Simple Atom Depth Index Calculator (SADIC)
upload_time2024-03-25 14:12:51
maintainerNone
docs_urlNone
authorGiacomo Nunziati
requires_pythonNone
licenseMIT License
keywords protein atom depth
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # SADIC v2: A Modern Implementation of the Simple Atom Depth Index Calculator

[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![PyPI version](https://badge.fury.io/py/sadic.svg)](https://badge.fury.io/py/sadic)
[![Downloads](https://pepy.tech/badge/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.

<!-- ![Main SADIC algorithm](path/to/image.png) -->

<!-- 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.

<!-- ![SADIC v2 package architecture](path/to/image.png) -->

---

### 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[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![PyPI version](https://badge.fury.io/py/sadic.svg)](https://badge.fury.io/py/sadic)\n[![Downloads](https://pepy.tech/badge/sadic)](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<!-- ![Main SADIC algorithm](path/to/image.png) -->\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<!-- ![SADIC v2 package architecture](path/to/image.png) -->\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"
}
        
Elapsed time: 0.28574s