# ElliptiC - an automated command line tool for visualizing and measuring ellipticity of cucurbituril host/guest structures
<br />
## How to install
**In a terminal, the command for installation is a simple**
_pip install ElliptiCBn_
**If you would rather not use pip and prefer installing source, the installation of the package can be done by the following:**
* Clone this git repository to your local machine
* In the cloned repository, install the cbn_analysis package through _python -m pip install . vv_
* Next, install the required dependencies by running _pip install -r requirements.txt_
<br />
## How to run the analysis
### The ElliptiC package takes a single command line argument: an xyz file containing atom coordinates, or a folder of xyz files containing atom coordinates
**To run the analysis package on a single file, navigate to the directory with the ElliptiC script and execute it:**
(NOTE: if there are spaces in your file name, you will need quotes around the file name)
**The same convention can be used to execute the package on a folder of xyz files**
<br />
## How the package works
### Below is a diagram of the analysis steps the software completes on any given file
### 1. In a given XYZ file, extract the coordinates of all carbon atoms (and oxygen atoms used later on in the analysis).
### 2. Identify strongly connected components to differentiate between host and guest structures.
### 3. Remove the guest structure since we only care about calculating ellipticity of the host.
### 4. Using proximity to oxygen atoms, remove the top and bottom rings of the hosts for accurate ellipticity calculation.
### 5 & 6. Using a Principal Components Analysis, calculate the variance along both major axes of the host ring. The ellipticity is thus (Vax1-Vax2)/Vax1 where Vax1 is the variance on the longest axis (length) and Vax2 is the variance on the second-longest axis (width).
### 7. Output graphs of both the single ring hosts and the full host-guest structures, as well as a spreadsheet with the calculated ellipticity for each structure.
<br />
<br />
## How to interpret the output
### Each xyz file analyzed with this package will produce at least 3 pieces of data:
* 1 interactive 3D scatter plot with all carbons in the CBn structures visualized
* 1 interactive 3D scatter plot with only the central carbon ring of the CBn structures visualized
* 1 spreadsheet with all of the carbons, their positions, distance to the centroid of the structure, and the measured ellipticity
**In the case of host CBn structures with an internally situated guest structure, an additional 3D graph will be produced with the guests visualized in the structures (see below)**
To see the interactive version of this plot that gets generated from the script, [Click Here](https://plotly.com/~Mshavlik/63/)
**The user can visually see the ellipticity in the structues and compare them to the measured values in the spreadsheets:**
_CB7 structures from above with guests removed_
Calculated ellipticity for each structure on a scale of circular (0) to linear (1)
_CB10 wide structures with guests removed_
Calculated ellipticity for each structure on a scale of circular (0) to linear (1)
Raw data
{
"_id": null,
"home_page": "https://github.com/harmslab/ElliptiC",
"name": "ElliptiCBn",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7.0",
"maintainer_email": "",
"keywords": "CBn; Crystal structure",
"author": "Michael Shavlik",
"author_email": "Michael Shavlik <mshavlik@uoregon.edu>",
"download_url": "https://files.pythonhosted.org/packages/7f/36/bf58b5486b485766bde02ca6425730661c48a0dc656e080d1b3637aba9d1/ElliptiCBn-1.0.9.tar.gz",
"platform": null,
"description": "# ElliptiC - an automated command line tool for visualizing and measuring ellipticity of cucurbituril host/guest structures\r\n\r\n<br />\r\n\r\n\r\n## How to install\r\n**In a terminal, the command for installation is a simple**\r\n\r\n_pip install ElliptiCBn_\r\n\r\n**If you would rather not use pip and prefer installing source, the installation of the package can be done by the following:**\r\n* Clone this git repository to your local machine\r\n* In the cloned repository, install the cbn_analysis package through _python -m pip install . vv_ \r\n* Next, install the required dependencies by running _pip install -r requirements.txt_\r\n\r\n<br />\r\n\r\n## How to run the analysis\r\n### The ElliptiC package takes a single command line argument: an xyz file containing atom coordinates, or a folder of xyz files containing atom coordinates\r\n\r\n**To run the analysis package on a single file, navigate to the directory with the ElliptiC script and execute it:**\r\n(NOTE: if there are spaces in your file name, you will need quotes around the file name)\r\n\r\n\r\n\r\n**The same convention can be used to execute the package on a folder of xyz files**\r\n\r\n \r\n<br />\r\n\r\n## How the package works\r\n### Below is a diagram of the analysis steps the software completes on any given file\r\n\r\n\r\n### 1. In a given XYZ file, extract the coordinates of all carbon atoms (and oxygen atoms used later on in the analysis).\r\n### 2. Identify strongly connected components to differentiate between host and guest structures.\r\n### 3. Remove the guest structure since we only care about calculating ellipticity of the host.\r\n### 4. Using proximity to oxygen atoms, remove the top and bottom rings of the hosts for accurate ellipticity calculation.\r\n### 5 & 6. Using a Principal Components Analysis, calculate the variance along both major axes of the host ring. The ellipticity is thus (Vax1-Vax2)/Vax1 where Vax1 is the variance on the longest axis (length) and Vax2 is the variance on the second-longest axis (width). \r\n### 7. Output graphs of both the single ring hosts and the full host-guest structures, as well as a spreadsheet with the calculated ellipticity for each structure.\r\n\r\n<br />\r\n<br />\r\n\r\n## How to interpret the output\r\n\r\n### Each xyz file analyzed with this package will produce at least 3 pieces of data: \r\n* 1 interactive 3D scatter plot with all carbons in the CBn structures visualized \r\n* 1 interactive 3D scatter plot with only the central carbon ring of the CBn structures visualized\r\n* 1 spreadsheet with all of the carbons, their positions, distance to the centroid of the structure, and the measured ellipticity\r\n\r\n**In the case of host CBn structures with an internally situated guest structure, an additional 3D graph will be produced with the guests visualized in the structures (see below)**\r\n\r\n\r\n\r\nTo see the interactive version of this plot that gets generated from the script, [Click Here](https://plotly.com/~Mshavlik/63/)\r\n\r\n**The user can visually see the ellipticity in the structues and compare them to the measured values in the spreadsheets:** \r\n_CB7 structures from above with guests removed_\r\n\r\n\r\nCalculated ellipticity for each structure on a scale of circular (0) to linear (1) \r\n\r\n\r\n\r\n_CB10 wide structures with guests removed_\r\n\r\n\r\nCalculated ellipticity for each structure on a scale of circular (0) to linear (1) \r\n\r\n\r\n\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python package for analyzing Cucurbituril crystal structures automatically",
"version": "1.0.9",
"project_urls": {
"Homepage": "https://github.com/harmslab/ElliptiC"
},
"split_keywords": [
"cbn;",
"crystal",
"structure"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5ce05dcb288bb7aa398ae7199cdf9bd987b7cf1cd544542497ae5413f3041516",
"md5": "661726dbf3169c7ecb7c4e3a6e10044c",
"sha256": "567d1dd7cbc95ceb128b3978c1dc645ca0d56416b59ce895126e4f09a3158f2c"
},
"downloads": -1,
"filename": "ElliptiCBn-1.0.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "661726dbf3169c7ecb7c4e3a6e10044c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7.0",
"size": 11091,
"upload_time": "2023-07-10T18:24:57",
"upload_time_iso_8601": "2023-07-10T18:24:57.340954Z",
"url": "https://files.pythonhosted.org/packages/5c/e0/5dcb288bb7aa398ae7199cdf9bd987b7cf1cd544542497ae5413f3041516/ElliptiCBn-1.0.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7f36bf58b5486b485766bde02ca6425730661c48a0dc656e080d1b3637aba9d1",
"md5": "c0016d3c626c978c8278d0b6ee001496",
"sha256": "4a7e767d1008d7879afcaac5ec3e2e0dd6595e4d2e14dca582f8c05999c69210"
},
"downloads": -1,
"filename": "ElliptiCBn-1.0.9.tar.gz",
"has_sig": false,
"md5_digest": "c0016d3c626c978c8278d0b6ee001496",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7.0",
"size": 11047,
"upload_time": "2023-07-10T18:24:58",
"upload_time_iso_8601": "2023-07-10T18:24:58.866013Z",
"url": "https://files.pythonhosted.org/packages/7f/36/bf58b5486b485766bde02ca6425730661c48a0dc656e080d1b3637aba9d1/ElliptiCBn-1.0.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-10 18:24:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "harmslab",
"github_project": "ElliptiC",
"github_not_found": true,
"lcname": "ellipticbn"
}
JSON
