# chiLife
chiLife (or χLife) is a python package for modeling non-canonical amino acid side chain ensembles, primarily site
directed spin labels (SDSLs), and using those ensembles to predict experimental results. The goal of chiLife is to provide a
simple, flexible and interoperable python interface to protein side chain ensemble modeling, allowing for rapid
development of custom analysis and modeling pipelines. This is facilitated by the use of `RotamerEnsemble` and
`SpinLabel` objects with standard interfaces for all supported side chain types, side chain modeling methods and
protein modeling methods. Flexibility is achieved by allowing users to create and use custom `RotamerEnsemble` and
`SpinLabel` objects as well as custom side chain modeling methods. Interoperability sought by interactions with other
Python-based molecular modeling packages. This enables the use of experimental data, like double electron-electron
resonance (DEER), in other standalone protein modeling applications that allow user defined restraints, such as
pyrosetta and NIH-Xplor.
## Getting Started
Stable distributions of chiLife can be installed using `pip`.
```bash
pip install chiLife
```
Alternatively the development version can be installed by downloading and unpacking the GitHub repository, or using
`git clone` followed by a standard python setuptools installation.
```bash
git clone https://github.com/mtessmer/chiLife.git
cd chiLife
pip install -e . # Install as editable and update using `git pull origin main`
```
***
## chiLife Module
The primary feature of chiLife is the `SpinLabel` object, which inherits from the more abstract `RotamerEnsemble`
object. While most people will primarily use `SpinLabel` objects, be aware that most properties and functions
discussed are also functional on `RotamerLibrary` objects as well. `SpinLabel` objects can be created and "attached" to
protein models easily and quickly, allowing for on the fly simulation of distance distributions while modeling, or
scriptable analysis. Notably, attaching a `SpinLabel` to a protein does not alter the protein in any way, allowing the
protein model to retain the native amino acid.
### Simple rotamer-library based SpinLabel modeling
```python
import numpy as np
import matplotlib.pyplot as plt
import chilife as xl
# Download protein structure from PDB
MBP = xl.fetch('1omp', save=True)
# Create Spin lables
SL1 = xl.SpinLabel('R1M', site=20, chain='A', protein=MBP)
SL2 = xl.SpinLabel('R1M', site=238, chain='A', protein=MBP)
# Calculate distribution
r = np.linspace(0, 100, 256)
P = xl.distance_distribution(SL1, SL2, r=r)
# Plot distribution
fig, ax = plt.subplots(figsize=(6, 3))
ax.plot(r, P)
ax.set_yticks([])
ax.set_xlabel('Distance ($\AA$)')
for spine in ['left', 'top', 'right']:
ax.spines[spine].set_visible(False)
plt.show()
```
The side chain ensembles can then be saved using a simple `save` function that accepts an arbitrary number of `
RotamerEnsemble`, `SpinLabel`, `MDAnalyisis.Universe` and `MDAnalyiss.AtomGroup` objects. Because
`RotamerEnsemble`/`SpinLabel` objects do not mutate the underlying protein, they are saved as separate multi-state
objects and can be visualized with applications like pymol. If you do wish to permanently alter the underlying protein
structure you can use the [`mutate`](#mutating-protein-structures) function described below.
```
# Save structure
xl.save('MBP_L20R1_S238R1.pdb', SL1, SL2, MBP)
```
### Mimicking MMM and MTSSLWizard
In addition to its own features, chiLife offers spin label modeling methods that mimic the popular MMM and MTSSLWizard
modeling applications.
```python
import chilife as xl
MBP = xl.fetch('1omp')
SLmmm = xl.SpinLabel.from_mmm('R1M', site=238, protein=MBP)
SLWiz = xl.SpinLabel.from_wizard('R1M', site=238, protein=MBP,
to_find=50, to_try=1000, # Equivalent to 'quick' search, default is 'thorough'
vdw=3.4, clashes=0, # MTSSLWizard 'tight' setting, default is 'loose'
)
```
### Off-rotamer sampling and local repacking
One of the benefits of chiLife is the variety and customizable nature of spin label modeling methods. This includes
methods to sample side chain conformations that deviate from canonical dihedral angles and fixed rotamer libraries
(Off-rotamer sampling) and methods to repack a `SpinLabel` and it's neighboring amino acids, and to
```python
import chilife as xl
MBP = xl.fetch('1omp')
# Create a SpinLabel object using the MTSSLWizard 'Accessible Volume' Approach
SL1 = xl.SpinLabel.from_wizard('R1M', site=20, chain='A', protein=MBP)
# Create a SpinLabel object by sampling off-rotamer dihedral conformations using the rotamer library as a prior
SL2 = xl.SpinLabel('R1M', site=238, chain='A', sample=2000, protein=MBP)
# Create a SpinLabel object from a ProEPR.repack trajectory
traj, de = xl.repack(SL1, SL2, protein=MBP)
```
The repack function will perform a Markov chain Monte Carlo sampling repack of the spin labels, `SL1` and `SL2` and
neighboring side chains, returning an `MDAnalysis.Universe` object containing all accepted structures of the MCMC
trajectory, the energy function changes at each acceptance step and new SpinLabel objects attached to the lowest energy
structure of the trajectory.
SpinLabel objects and neighboring side chains can be repacked using off-rotamer sampling by using the `off_rotamer=True`
option. In the event off rotamer sampling is being used for repacking, it is likely that the desired SpinLabel object is
not the default rotamer ensembles attached to the lowest energy structure, but instead the ensemble of side chains
created in the MCMC sampling trajectory. This can be done using the `from_trajectory` class method.
```python
# Create a SpinLabel object from a xl.repack trajectory with off-rotamer sampling
traj, de = xl.repack(SL1, SL2, protein=MBP, off_rotamer=True)
SL1 = xl.SpinLabel.from_trajectory(traj, site=238)
```
Off rotamer sampling can be controlled on a per dihedral basis when repacking with chiLife by passing a list of bools to
the off_rotamer variable. For example, passing `off_rotamer = [False, False, False, True, True]` will allow for off
rotamer sampling of only χ<sub>4</sub> and χ<sub>5</sub>.
### Mutating protein structures
Sometimes you don't want a whole rotamer ensembles, you just want a protein structure mutated at a particular site with
the most probable spin label conformer. This can be done easily with the `mutate` function.
```python
import chilife as xl
MBP = xl.fetch('1omp')
SL = xl.SpinLabel('R1M', 238, protein=MBP)
MBP_S238R1 = xl.mutate(MBP, SL)
xl.save('MBP_S238R1.pdb', MBP_S238R1)
```
chiLife can actually mutate several sites at once, and can mutate canonical amino acids as well.
```python
SL1 = xl.SpinLabel('R1M', 20, protein=MBP)
SL2 = xl.SpinLabel('R1M', 238, protein=MBP)
L284V = xl.RotamerEnsemble('VAL', 284, protein=MBP)
```
Mtating adjacent sites is best done with the `repack` function to avoid clashes between SpinLabels/RotamerEnsembles.
This will return a trajectory which can be used to pick the last or lowest energy frame as your mutated protein.
```python
MBP_L284V_L20R1_S238R1, _, _ = xl.repack(SL1, SL2, L284V, protein=MBP)
```
### Adding user defined spin labels
Site directed spin labels, and other non-canonical amino acids, are constantly being developed. Additionally, rotamer
libraries for existing labels continuously undergo incremental improvements or modification to suit particular needs,
e.g. a rotamer library specifically for transmembrane residues. In fact chiLife iteself may be being used to develop
new and improved, or application specific rotamer libraries. To this end chiLife makes it easy to create user defined
spin labels and custom rotamer libraries. To create a custom rotamer library, all that is needed is (1) a pdb file of
the spin label (2) A list of the rotatable dihedral bonds, and (3) a list of the atoms where the spin is.
```python
xl.create_library(name='TRT_1.0',
resname='TRT',
pdb='test_data/trt.pdb',
dihedral_atoms=[['N', 'CA', 'CB', 'SG'],
['CA', 'CB', 'SG', 'SD'],
['CB', 'SG', 'SD', 'CAD'],
['SG', 'SD', 'CAD', 'CAE'],
['SD', 'CAD', 'CAE', 'OAC']],
spin_atoms='CAQ')
```
This function will create a portable `TRT_1.0_rotlib.npz` file that can be called specified by the `SpinLabel`
constructor.
```python
xl.SpinLabel('TRT', site=238, protein=MBP, rotlib='TRT_1.0', sample=5000)
```
Thus, the file can be easily shared with coworkers, collaborators or with other chiLife users via email or a
forthcoming chiLife rotamer library repository.
> NOTE: In the above example the `rotlib` keyword is only used for demonstration purposes. chiLife always searches the
> current working directory for rotamer library files first. If there is a `XYZ_rotlib.npz` in the working directory
> and you specify `xl.SpinLabel('XYZ', ...)`, chiLife will assume you want to use the `XYZ_rotlib.npz` rotamer library.
User defined labels can be constructed from a single state pdb file or a multi-state PDB file. If constructed from a
single state pdb file a list of dihedral angles and weights can be passed via the `dihedrals` and `weigts` keyword
arguments. For each set of dihedral angles, chiLife create a rotamer and store the whole library using the specified
name. Alternatively using a multi-state PDB file can add some additional information, such as isomeric heterogeneity of
the rotamer library, which will be maintained by chiLife.
For more information on how to use chiLife as a python module, see [examples](https://stolllab.github.io/chiLife/examples.html)
Raw data
{
"_id": null,
"home_page": "https://github.com/StollLab/chiLife",
"name": "chilife",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "Spin label,EPR,DEER,PELDOR,Side chain",
"author": "Maxx Tessmer",
"author_email": "mhtessmer@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/6e/cc/eb0943905893dfb86132bc3b7cb0bbf3623353d843ce4b3cb1f9485648d9/chilife-0.1.10.post2.tar.gz",
"platform": null,
"description": "# chiLife\r\nchiLife (or \u03c7Life) is a python package for modeling non-canonical amino acid side chain ensembles, primarily site \r\ndirected spin labels (SDSLs), and using those ensembles to predict experimental results. The goal of chiLife is to provide a \r\nsimple, flexible and interoperable python interface to protein side chain ensemble modeling, allowing for rapid \r\ndevelopment of custom analysis and modeling pipelines. This is facilitated by the use of `RotamerEnsemble` and \r\n`SpinLabel` objects with standard interfaces for all supported side chain types, side chain modeling methods and \r\nprotein modeling methods. Flexibility is achieved by allowing users to create and use custom `RotamerEnsemble` and \r\n`SpinLabel` objects as well as custom side chain modeling methods. Interoperability sought by interactions with other \r\nPython-based molecular modeling packages. This enables the use of experimental data, like double electron-electron \r\nresonance (DEER), in other standalone protein modeling applications that allow user defined restraints, such as \r\npyrosetta and NIH-Xplor.\r\n \r\n## Getting Started\r\nStable distributions of chiLife can be installed using `pip`. \r\n```bash\r\npip install chiLife\r\n```\r\n\r\nAlternatively the development version can be installed by downloading and unpacking the GitHub repository, or using \r\n`git clone` followed by a standard python setuptools installation.\r\n```bash\r\ngit clone https://github.com/mtessmer/chiLife.git\r\ncd chiLife\r\npip install -e . # Install as editable and update using `git pull origin main`\r\n``` \r\n***\r\n## chiLife Module\r\nThe primary feature of chiLife is the `SpinLabel` object, which inherits from the more abstract `RotamerEnsemble` \r\nobject. While most people will primarily use `SpinLabel` objects, be aware that most properties and functions \r\ndiscussed are also functional on `RotamerLibrary` objects as well. `SpinLabel` objects can be created and \"attached\" to \r\nprotein models easily and quickly, allowing for on the fly simulation of distance distributions while modeling, or \r\nscriptable analysis. Notably, attaching a `SpinLabel` to a protein does not alter the protein in any way, allowing the \r\nprotein model to retain the native amino acid.\r\n\r\n### Simple rotamer-library based SpinLabel modeling\r\n\r\n```python\r\nimport numpy as np\r\nimport matplotlib.pyplot as plt\r\nimport chilife as xl\r\n\r\n# Download protein structure from PDB\r\nMBP = xl.fetch('1omp', save=True)\r\n\r\n# Create Spin lables\r\nSL1 = xl.SpinLabel('R1M', site=20, chain='A', protein=MBP)\r\nSL2 = xl.SpinLabel('R1M', site=238, chain='A', protein=MBP)\r\n\r\n# Calculate distribution\r\nr = np.linspace(0, 100, 256)\r\nP = xl.distance_distribution(SL1, SL2, r=r)\r\n\r\n# Plot distribution\r\nfig, ax = plt.subplots(figsize=(6, 3))\r\nax.plot(r, P)\r\nax.set_yticks([])\r\nax.set_xlabel('Distance ($\\AA$)')\r\nfor spine in ['left', 'top', 'right']:\r\n ax.spines[spine].set_visible(False)\r\nplt.show()\r\n```\r\n\r\n\r\n\r\nThe side chain ensembles can then be saved using a simple `save` function that accepts an arbitrary number of `\r\nRotamerEnsemble`, `SpinLabel`, `MDAnalyisis.Universe` and `MDAnalyiss.AtomGroup` objects. Because \r\n`RotamerEnsemble`/`SpinLabel` objects do not mutate the underlying protein, they are saved as separate multi-state \r\nobjects and can be visualized with applications like pymol. If you do wish to permanently alter the underlying protein\r\nstructure you can use the [`mutate`](#mutating-protein-structures) function described below.\r\n\r\n```\r\n# Save structure\r\nxl.save('MBP_L20R1_S238R1.pdb', SL1, SL2, MBP)\r\n```\r\n\r\n\r\n\r\n\r\n### Mimicking MMM and MTSSLWizard\r\nIn addition to its own features, chiLife offers spin label modeling methods that mimic the popular MMM and MTSSLWizard \r\nmodeling applications.\r\n\r\n```python\r\nimport chilife as xl\r\n\r\nMBP = xl.fetch('1omp')\r\nSLmmm = xl.SpinLabel.from_mmm('R1M', site=238, protein=MBP)\r\nSLWiz = xl.SpinLabel.from_wizard('R1M', site=238, protein=MBP,\r\n to_find=50, to_try=1000, # Equivalent to 'quick' search, default is 'thorough' \r\n vdw=3.4, clashes=0, # MTSSLWizard 'tight' setting, default is 'loose' \r\n )\r\n```\r\n\r\n### Off-rotamer sampling and local repacking \r\nOne of the benefits of chiLife is the variety and customizable nature of spin label modeling methods. This includes \r\nmethods to sample side chain conformations that deviate from canonical dihedral angles and fixed rotamer libraries \r\n(Off-rotamer sampling) and methods to repack a `SpinLabel` and it's neighboring amino acids, and to \r\n\r\n```python\r\nimport chilife as xl\r\n\r\nMBP = xl.fetch('1omp')\r\n\r\n# Create a SpinLabel object using the MTSSLWizard 'Accessible Volume' Approach\r\nSL1 = xl.SpinLabel.from_wizard('R1M', site=20, chain='A', protein=MBP)\r\n\r\n# Create a SpinLabel object by sampling off-rotamer dihedral conformations using the rotamer library as a prior \r\nSL2 = xl.SpinLabel('R1M', site=238, chain='A', sample=2000, protein=MBP)\r\n\r\n# Create a SpinLabel object from a ProEPR.repack trajectory\r\ntraj, de = xl.repack(SL1, SL2, protein=MBP)\r\n```\r\n\r\nThe repack function will perform a Markov chain Monte Carlo sampling repack of the spin labels, `SL1` and `SL2` and \r\nneighboring side chains, returning an `MDAnalysis.Universe` object containing all accepted structures of the MCMC \r\ntrajectory, the energy function changes at each acceptance step and new SpinLabel objects attached to the lowest energy \r\nstructure of the trajectory.\r\n\r\nSpinLabel objects and neighboring side chains can be repacked using off-rotamer sampling by using the `off_rotamer=True`\r\noption. In the event off rotamer sampling is being used for repacking, it is likely that the desired SpinLabel object is \r\nnot the default rotamer ensembles attached to the lowest energy structure, but instead the ensemble of side chains \r\ncreated in the MCMC sampling trajectory. This can be done using the `from_trajectory` class method. \r\n\r\n```python\r\n# Create a SpinLabel object from a xl.repack trajectory with off-rotamer sampling\r\ntraj, de = xl.repack(SL1, SL2, protein=MBP, off_rotamer=True) \r\nSL1 = xl.SpinLabel.from_trajectory(traj, site=238)\r\n```\r\n\r\nOff rotamer sampling can be controlled on a per dihedral basis when repacking with chiLife by passing a list of bools to \r\nthe off_rotamer variable. For example, passing `off_rotamer = [False, False, False, True, True]` will allow for off \r\nrotamer sampling of only χ<sub>4</sub> and χ<sub>5</sub>.\r\n\r\n\r\n### Mutating protein structures\r\nSometimes you don't want a whole rotamer ensembles, you just want a protein structure mutated at a particular site with \r\nthe most probable spin label conformer. This can be done easily with the `mutate` function.\r\n\r\n```python\r\nimport chilife as xl\r\n\r\nMBP = xl.fetch('1omp')\r\nSL = xl.SpinLabel('R1M', 238, protein=MBP)\r\nMBP_S238R1 = xl.mutate(MBP, SL)\r\nxl.save('MBP_S238R1.pdb', MBP_S238R1)\r\n```\r\n\r\nchiLife can actually mutate several sites at once, and can mutate canonical amino acids as well.\r\n\r\n```python\r\nSL1 = xl.SpinLabel('R1M', 20, protein=MBP)\r\nSL2 = xl.SpinLabel('R1M', 238, protein=MBP)\r\nL284V = xl.RotamerEnsemble('VAL', 284, protein=MBP)\r\n```\r\n\r\n Mtating adjacent sites is best done with the `repack` function to avoid clashes between SpinLabels/RotamerEnsembles. \r\nThis will return a trajectory which can be used to pick the last or lowest energy frame as your mutated protein.\r\n\r\n```python\r\nMBP_L284V_L20R1_S238R1, _, _ = xl.repack(SL1, SL2, L284V, protein=MBP)\r\n```\r\n\r\n### Adding user defined spin labels\r\nSite directed spin labels, and other non-canonical amino acids, are constantly being developed. Additionally, rotamer \r\nlibraries for existing labels continuously undergo incremental improvements or modification to suit particular needs, \r\ne.g. a rotamer library specifically for transmembrane residues. In fact chiLife iteself may be being used to develop \r\nnew and improved, or application specific rotamer libraries. To this end chiLife makes it easy to create user defined \r\nspin labels and custom rotamer libraries. To create a custom rotamer library, all that is needed is (1) a pdb file of \r\nthe spin label (2) A list of the rotatable dihedral bonds, and (3) a list of the atoms where the spin is.\r\n\r\n```python\r\nxl.create_library(name='TRT_1.0',\r\n resname='TRT',\r\n pdb='test_data/trt.pdb',\r\n dihedral_atoms=[['N', 'CA', 'CB', 'SG'],\r\n ['CA', 'CB', 'SG', 'SD'],\r\n ['CB', 'SG', 'SD', 'CAD'],\r\n ['SG', 'SD', 'CAD', 'CAE'],\r\n ['SD', 'CAD', 'CAE', 'OAC']],\r\n spin_atoms='CAQ')\r\n```\r\n\r\nThis function will create a portable `TRT_1.0_rotlib.npz` file that can be called specified by the `SpinLabel` \r\nconstructor.\r\n\r\n```python\r\nxl.SpinLabel('TRT', site=238, protein=MBP, rotlib='TRT_1.0', sample=5000)\r\n```\r\n\r\nThus, the file can be easily shared with coworkers, collaborators or with other chiLife users via email or a \r\nforthcoming chiLife rotamer library repository. \r\n\r\n> NOTE: In the above example the `rotlib` keyword is only used for demonstration purposes. chiLife always searches the \r\n> current working directory for rotamer library files first. If there is a `XYZ_rotlib.npz` in the working directory \r\n> and you specify `xl.SpinLabel('XYZ', ...)`, chiLife will assume you want to use the `XYZ_rotlib.npz` rotamer library.\r\n\r\nUser defined labels can be constructed from a single state pdb file or a multi-state PDB file. If constructed from a \r\nsingle state pdb file a list of dihedral angles and weights can be passed via the `dihedrals` and `weigts` keyword\r\narguments. For each set of dihedral angles, chiLife create a rotamer and store the whole library using the specified \r\nname. Alternatively using a multi-state PDB file can add some additional information, such as isomeric heterogeneity of \r\nthe rotamer library, which will be maintained by chiLife.\r\n\r\nFor more information on how to use chiLife as a python module, see [examples](https://stolllab.github.io/chiLife/examples.html)\r\n",
"bugtrack_url": null,
"license": "GNU GPLv3",
"summary": "A package for modeling non-canonical amino acid side chain ensembles.",
"version": "0.1.10.post2",
"project_urls": {
"Homepage": "https://github.com/StollLab/chiLife",
"Source": "https://github.com/StollLab/chiLife"
},
"split_keywords": [
"spin label",
"epr",
"deer",
"peldor",
"side chain"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6ecceb0943905893dfb86132bc3b7cb0bbf3623353d843ce4b3cb1f9485648d9",
"md5": "10ee9e1a40fa8dcdb6777a28211de270",
"sha256": "8a5fc43ec4caf549ff68563dc9d90359a386a79d7d7ba74e0b24a65c62483074"
},
"downloads": -1,
"filename": "chilife-0.1.10.post2.tar.gz",
"has_sig": false,
"md5_digest": "10ee9e1a40fa8dcdb6777a28211de270",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 17737903,
"upload_time": "2023-08-01T20:54:59",
"upload_time_iso_8601": "2023-08-01T20:54:59.849777Z",
"url": "https://files.pythonhosted.org/packages/6e/cc/eb0943905893dfb86132bc3b7cb0bbf3623353d843ce4b3cb1f9485648d9/chilife-0.1.10.post2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-01 20:54:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "StollLab",
"github_project": "chiLife",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "chilife"
}
JSON
