# Chameleon
UCSC TABI presents project Chameleon, a pipeline and software package that optimizes plasmids for bacterial transformation efficiency in non-model organisms.
## Description
Chameleon is a software project written for UCSC TABI as a submission for the Best Software award for iGEM 2023. For more information on the Chameleon software project, visit our [team wiki](https://2023.igem.wiki/ucsc/software)
The Chameleon project is based around Stealth which is a bioinformatics tool written by our PI David L. Bernick here a UCSC. Stealth statistically finds and reports underrepresented kmer motifs within a genome. The original version of Stealth can be found [here](https://git.ucsc.edu/dbernick/stealth).
Stealth is included in Chameleon under the sub-module `Stealth` in the `chameleontools` package. The `Stealth` sub-module contains the original Stealth as written by David Bernick with minimal modifications. To see the specific modifications made, see the `README` located in the `Stealth` sub-module located in [`src/chameleontools/Stealth`](https://gitlab.igem.org/2023/software-tools/ucsc/-/tree/main/src/chameleontools/Stealth)
Chameleon is published as a python package to the Python Package Index (PyPI) under the package `chameleontools`. Find the PyPI page for the project [here](https://pypi.org/project/chameleontools/).
## Installation
Installation steps are tailored to Mac/Unix-based operating systems. For instruction for Windows, skip to **Windows OS**
##### MacOS/Linux (Ubuntu 20.04)
Chameleon can be installed under the Python package `chameleontools`. Installation is made simple with the pip python package installer.
The pip installer should be automatically installed with most Python distributions. Check if you have properly installed python and pip installer, the output should look similar
```bash
usr:~$ python --version
Python 3.x.x
usr:~$ python -m pip --version
pip X.Y.Z from /<path>/<to>/<your>/pip (python 3.x.x)
```
If your output looks similar, you can skip to **Installing Chameleon**.
##### Installing Python / pip
Follow this section if your output did not look the same as above.
If you do not have Python, get started by installing Python 3.10 or above from [python.org](https://www.python.org/downloads/), or through a distriubtion such as [anaconda](https://www.anaconda.com/download).
If you do not have a working pip installer, follow steps found [here](https://pip.pypa.io/en/stable/installation/).
Validate you have a working Python / pip installer by running
```bash
usr:~$ python --version
Python 3.x.x
usr:~$ python -m pip --version
pip X.Y.Z from /<path>/<to>/<your>/pip (python 3.x.x)
```
and making sure the output looks similar.
##### Installing Chameleon
Installing Chameleon is simple as running the command
```bash
usr:~$ pip install chameleontools
# OR
usr:~$ python -m pip install chameleontools
```
with a valid pip installer to install the chameleontools package from the Python Package Index (PyPI)
##### Windows Installation
Installation on Windows requires a```Path``` environment variable be set inorder for ```pstealth``` to be run as a CLI tool. Firstly, make sure Python 3.10+ is installed from [python.org](https://www.python.org/downloads/) or other distribution.
Validate that Python and a valid pip installer are installed using the command in the command prompt or Windows powershell
```bat
C:\usr>python --version
Python 3.x.x
C:\usr>python -m pip --version
pip X.Y.Z from C:\<path>\<to>\<your>\pip (python 3.x.x)
```
Install chameleontools with the command
```bat
C:\usr>python -m pip install chameleontools
```
If running `pstealth` gives an output that looks like the following
```bat
C:\usr>pstealth -h
'pstealth' is not recognized as an internal or external command,
operable program or batch file.
C:\usr>
```
continue to the following section. If pstealth runs normally (prints usage information), chameleontools is properly installed and you can ignore the following section.
###### Adding to Path
You must add the Python `Scripts` directory to your `Path` environment variables. This can be done by navigating to your `Scripts` directory where `pstealth.exe` is located. This is most likely under the path `C:\Users\<USER>\AppData\Local\Programs\Python\Python3<x>\Scripts` where `<USER>` is the local Windows user profile and `Python3<x>` represents the version of your Python installation (eg. `Python310`). Once naviagted to your `Scripts` directory, save the filepath.
In the Windows search (hitting the windows button), type and enter `run` and then enter `sysdm.cpl` into the dialog box that pops up. This opens up a new window titled `System Properties`. From there, navigate to the `Advance` tab and select `Environment Variables`. From there, scroll until you see a `Path` variable, select, and click `Edit`. In the `Edit Environment Variable` window, select `New` and paste the filepath you saved into the new text box.
If you do not see a `Path` variable, simply select `New` in the `Environment Variables` window and create a new variable named `Path` with the value of your saved file path.
Once done, `pstealth` should be able to be used from the commandline as intended.
## Usage
#### Plasmid-Stealth (pstealth) CLI tool
Once installed, the pipeline can be easily run with the command `pstealth`
```bash
# usage
pstealth --genome (-g) <genome infile> --plasmid (-p) <plasmid infile> --outfile -o [outfile | default: stdout] -[zPMmrs]
Optional Args:
--zScore (-z) -> [zscore cutoff value | default: -4]
--pseudo (-P) [pseudo-count value | default: 0]
--max (-M) [maximum motif size | default: 8]
--min (-m) [minimum motif size | default: 1]
--palindrome (-r) [Remove RC palindromes only | default: off]
--silent (-s) [Hide report message | default: show]
```
The `pstealth` command takes two required arguments `--plasmid (-p)` and `--genome (-g)`.
`--plasmid` is the annotated plasmid which you wish to Stealth optimize in GenBank record format (.gb/.gbk)
`--genome` is the genomic sequence of the species you wish transform your plasmid into in GenBank record or FastA format (.gb/.gbk || .fasta/.fa)
An example usage is as follows
```bash
usr:~$ pstealth -g M_aeruginosa.gb -p pSPDY.gb -o pSPDY_stealth.gb -r
...
usr:~$ cat pSPDY_stealth.gb | head
LOCUS pSPDY 8825 bp DNA circular UNA 18-AUG-2023
DEFINITION synthetic circular DNA.
ACCESSION
VERSION .
KEYWORDS .
SOURCE synthetic DNA construct
ORGANISM synthetic DNA construct.
FEATURES Location/Qualifiers
misc_feature 1
```
The above example optimizes plasmid `pSPDY.gb` for transformation into species `M_aeruginosa.gb`, removing only reverse-complement palindrome motifs identified with StealthV0. The modifed plasmid is saved to a new file `pSPDY_stealth.gb`, keeping all the same annotations, only changing the plasmid sequence to remove underrepresented motifs in coding regions.
#### chameleontools Module
Development of the Chameleon project and chameleontools started when we wrote software to process the Stealth output of <em>M.aeruginosa</em> and realized we could write a pipeline to automate what was a manual and time consuming process. This software ultimately became what is now the `StealthParser` module.
We recognized the usefulness of having each submodule perform their own specific tasks and have written the chameleontools package in a way that reflects that ideal.
To import chameleontools as a Python module, simply import it as follows
```python
import chameleontools.<submodule>
```
The submodules supported for importing include
```py
import chameleontools.ChromatoSeq # Motif removal from sequence
import chameleontools.CodonAnalyzer # Codon Analysis of CDS
import chameleontools.FastAreader
import chameleontools.ORFfinder # Very basic ORF finder
import chameleontools.SeqParser # Plasmid and Genome input handling
import chameleontools.Stealth # Stealth analysis
import chameleontools.StealthParser # Stealth output parser
```
For detailed documentation on the contents of each module, visit the <b>Documentation</b> on the [software page](https://2023.igem.wiki/ucsc/software) on our team's wiki.
## Contributing
Chameleon is open to any and all contributions.
Chameleon was created for the 2023 iGEM competition and will not be maintained on this repository after the conclusion of this year's iGEM cycle. See the [PyPI](https://pypi.org/project/chameleontools/) page for `chameleontools` to look for future maintenance.
This software is published under the MIT license. Feel free to use any and all code provided by the project in any way and for any purpose.
## Authors and acknowledgment
Stealth is lab software written by our PI David L. Bernick at UC Santa Cruz; who advised the development of the `pstealth` pipeline (contact: dbernick@soe.ucsc.edu)
Chameleon was written and contributed to by
* Tyler Gaw (contact: tagaw@ucsc.edu)
* Allison Jaballas (contact: acjaball@ucsc.edu)
* James Larbaleister (contact: jlarbale@ucsc.edu)
Special thanks to Reto Stamm (contact: rstamm@ucsc.edu | [github](https://github.com/retospect)) for guidance in developing and publishing a packge to the Python Package Index
Raw data
{
"_id": null,
"home_page": "https://gitlab.igem.org/2023/software-tools/ucsc",
"name": "chameleontools",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10,<3.13",
"maintainer_email": "",
"keywords": "",
"author": "Tyler Gaw",
"author_email": "tagaw@ucsc.edu",
"download_url": "https://files.pythonhosted.org/packages/79/be/199b3a0d5cd7d7b6483d689b5b6d20aa3a27228ef83cd637eebab2ee24b6/chameleontools-1.0.1.tar.gz",
"platform": null,
"description": "# Chameleon\n\nUCSC TABI presents project Chameleon, a pipeline and software package that optimizes plasmids for bacterial transformation efficiency in non-model organisms.\n\n\n\n## Description\n\nChameleon is a software project written for UCSC TABI as a submission for the Best Software award for iGEM 2023. For more information on the Chameleon software project, visit our [team wiki](https://2023.igem.wiki/ucsc/software)\n\nThe Chameleon project is based around Stealth which is a bioinformatics tool written by our PI David L. Bernick here a UCSC. Stealth statistically finds and reports underrepresented kmer motifs within a genome. The original version of Stealth can be found [here](https://git.ucsc.edu/dbernick/stealth).\n\nStealth is included in Chameleon under the sub-module `Stealth` in the `chameleontools` package. The `Stealth` sub-module contains the original Stealth as written by David Bernick with minimal modifications. To see the specific modifications made, see the `README` located in the `Stealth` sub-module located in [`src/chameleontools/Stealth`](https://gitlab.igem.org/2023/software-tools/ucsc/-/tree/main/src/chameleontools/Stealth) \n\n\nChameleon is published as a python package to the Python Package Index (PyPI) under the package `chameleontools`. Find the PyPI page for the project [here](https://pypi.org/project/chameleontools/).\n\n\n## Installation\nInstallation steps are tailored to Mac/Unix-based operating systems. For instruction for Windows, skip to **Windows OS**\n\n##### MacOS/Linux (Ubuntu 20.04)\n\nChameleon can be installed under the Python package `chameleontools`. Installation is made simple with the pip python package installer. \n\nThe pip installer should be automatically installed with most Python distributions. Check if you have properly installed python and pip installer, the output should look similar\n```bash\nusr:~$ python --version\nPython 3.x.x\nusr:~$ python -m pip --version\npip X.Y.Z from /<path>/<to>/<your>/pip (python 3.x.x) \n```\nIf your output looks similar, you can skip to **Installing Chameleon**.\n\n##### Installing Python / pip\nFollow this section if your output did not look the same as above.\n\nIf you do not have Python, get started by installing Python 3.10 or above from [python.org](https://www.python.org/downloads/), or through a distriubtion such as [anaconda](https://www.anaconda.com/download).\n\nIf you do not have a working pip installer, follow steps found [here](https://pip.pypa.io/en/stable/installation/).\n\nValidate you have a working Python / pip installer by running \n```bash\nusr:~$ python --version\nPython 3.x.x\nusr:~$ python -m pip --version\npip X.Y.Z from /<path>/<to>/<your>/pip (python 3.x.x) \n```\nand making sure the output looks similar.\n\n##### Installing Chameleon\n\nInstalling Chameleon is simple as running the command\n```bash\nusr:~$ pip install chameleontools\n# OR\nusr:~$ python -m pip install chameleontools\n```\nwith a valid pip installer to install the chameleontools package from the Python Package Index (PyPI)\n\n##### Windows Installation\nInstallation on Windows requires a```Path``` environment variable be set inorder for ```pstealth``` to be run as a CLI tool. Firstly, make sure Python 3.10+ is installed from [python.org](https://www.python.org/downloads/) or other distribution.\n\nValidate that Python and a valid pip installer are installed using the command in the command prompt or Windows powershell\n```bat\nC:\\usr>python --version\nPython 3.x.x\nC:\\usr>python -m pip --version \npip X.Y.Z from C:\\<path>\\<to>\\<your>\\pip (python 3.x.x)\n```\n\nInstall chameleontools with the command\n```bat\nC:\\usr>python -m pip install chameleontools\n```\nIf running `pstealth` gives an output that looks like the following\n```bat\nC:\\usr>pstealth -h\n'pstealth' is not recognized as an internal or external command,\noperable program or batch file.\nC:\\usr>\n```\ncontinue to the following section. If pstealth runs normally (prints usage information), chameleontools is properly installed and you can ignore the following section.\n\n###### Adding to Path \nYou must add the Python `Scripts` directory to your `Path` environment variables. This can be done by navigating to your `Scripts` directory where `pstealth.exe` is located. This is most likely under the path `C:\\Users\\<USER>\\AppData\\Local\\Programs\\Python\\Python3<x>\\Scripts` where `<USER>` is the local Windows user profile and `Python3<x>` represents the version of your Python installation (eg. `Python310`). Once naviagted to your `Scripts` directory, save the filepath.\n\nIn the Windows search (hitting the windows button), type and enter `run` and then enter `sysdm.cpl` into the dialog box that pops up. This opens up a new window titled `System Properties`. From there, navigate to the `Advance` tab and select `Environment Variables`. From there, scroll until you see a `Path` variable, select, and click `Edit`. In the `Edit Environment Variable` window, select `New` and paste the filepath you saved into the new text box.\n\nIf you do not see a `Path` variable, simply select `New` in the `Environment Variables` window and create a new variable named `Path` with the value of your saved file path.\n\nOnce done, `pstealth` should be able to be used from the commandline as intended.\n\n\n\n## Usage\n\n#### Plasmid-Stealth (pstealth) CLI tool\nOnce installed, the pipeline can be easily run with the command `pstealth`\n```bash\n# usage\npstealth --genome (-g) <genome infile> --plasmid (-p) <plasmid infile> --outfile -o [outfile | default: stdout] -[zPMmrs]\n Optional Args:\n --zScore (-z) -> [zscore cutoff value | default: -4]\n --pseudo (-P) [pseudo-count value | default: 0]\n --max (-M) [maximum motif size | default: 8]\n --min (-m) [minimum motif size | default: 1]\n --palindrome (-r) [Remove RC palindromes only | default: off]\n --silent (-s) [Hide report message | default: show]\n```\nThe `pstealth` command takes two required arguments `--plasmid (-p)` and `--genome (-g)`. \n`--plasmid` is the annotated plasmid which you wish to Stealth optimize in GenBank record format (.gb/.gbk)\n`--genome` is the genomic sequence of the species you wish transform your plasmid into in GenBank record or FastA format (.gb/.gbk || .fasta/.fa)\n\nAn example usage is as follows\n```bash\nusr:~$ pstealth -g M_aeruginosa.gb -p pSPDY.gb -o pSPDY_stealth.gb -r \n...\nusr:~$ cat pSPDY_stealth.gb | head\nLOCUS pSPDY 8825 bp DNA circular UNA 18-AUG-2023\nDEFINITION synthetic circular DNA.\nACCESSION\nVERSION .\nKEYWORDS .\nSOURCE synthetic DNA construct\n ORGANISM synthetic DNA construct.\nFEATURES Location/Qualifiers\n misc_feature 1\n```\n\nThe above example optimizes plasmid `pSPDY.gb` for transformation into species `M_aeruginosa.gb`, removing only reverse-complement palindrome motifs identified with StealthV0. The modifed plasmid is saved to a new file `pSPDY_stealth.gb`, keeping all the same annotations, only changing the plasmid sequence to remove underrepresented motifs in coding regions.\n\n#### chameleontools Module\n\nDevelopment of the Chameleon project and chameleontools started when we wrote software to process the Stealth output of <em>M.aeruginosa</em> and realized we could write a pipeline to automate what was a manual and time consuming process. This software ultimately became what is now the `StealthParser` module.\n\nWe recognized the usefulness of having each submodule perform their own specific tasks and have written the chameleontools package in a way that reflects that ideal.\n\nTo import chameleontools as a Python module, simply import it as follows\n```python\nimport chameleontools.<submodule>\n```\nThe submodules supported for importing include \n```py\nimport chameleontools.ChromatoSeq # Motif removal from sequence\nimport chameleontools.CodonAnalyzer # Codon Analysis of CDS\nimport chameleontools.FastAreader \nimport chameleontools.ORFfinder # Very basic ORF finder\nimport chameleontools.SeqParser # Plasmid and Genome input handling\nimport chameleontools.Stealth # Stealth analysis\nimport chameleontools.StealthParser # Stealth output parser\n```\n\nFor detailed documentation on the contents of each module, visit the <b>Documentation</b> on the [software page](https://2023.igem.wiki/ucsc/software) on our team's wiki. \n\n\n## Contributing\n\nChameleon is open to any and all contributions.\n\nChameleon was created for the 2023 iGEM competition and will not be maintained on this repository after the conclusion of this year's iGEM cycle. See the [PyPI](https://pypi.org/project/chameleontools/) page for `chameleontools` to look for future maintenance.\n\nThis software is published under the MIT license. Feel free to use any and all code provided by the project in any way and for any purpose.\n\n## Authors and acknowledgment\nStealth is lab software written by our PI David L. Bernick at UC Santa Cruz; who advised the development of the `pstealth` pipeline (contact: dbernick@soe.ucsc.edu) \n\nChameleon was written and contributed to by \n* Tyler Gaw (contact: tagaw@ucsc.edu)\n* Allison Jaballas (contact: acjaball@ucsc.edu)\n* James Larbaleister (contact: jlarbale@ucsc.edu)\n\nSpecial thanks to Reto Stamm (contact: rstamm@ucsc.edu | [github](https://github.com/retospect)) for guidance in developing and publishing a packge to the Python Package Index",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Stealth-based pipeline that optimizes plasmids for bacterial transformations in non-model organisms.",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://gitlab.igem.org/2023/software-tools/ucsc",
"Repository": "https://gitlab.igem.org/2023/software-tools/ucsc"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cca04cf31d3295be1c81f500f29583f25fe75545f9c8a95ee191dabcc2709ed8",
"md5": "01839e01ad69dfb433acc1f24bd1c58f",
"sha256": "a4f9507dabb9b4ac71eda8ceac4ac01c65cbc306458ebb8e10f116dfad55b15c"
},
"downloads": -1,
"filename": "chameleontools-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "01839e01ad69dfb433acc1f24bd1c58f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<3.13",
"size": 34737,
"upload_time": "2023-10-12T04:23:39",
"upload_time_iso_8601": "2023-10-12T04:23:39.931267Z",
"url": "https://files.pythonhosted.org/packages/cc/a0/4cf31d3295be1c81f500f29583f25fe75545f9c8a95ee191dabcc2709ed8/chameleontools-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "79be199b3a0d5cd7d7b6483d689b5b6d20aa3a27228ef83cd637eebab2ee24b6",
"md5": "9f384f131d6ecbbe2d089966b497abb6",
"sha256": "a7655cd8754a96261845a67eddfbbafb65c5b836b733e1381bdb96107eafc8c5"
},
"downloads": -1,
"filename": "chameleontools-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "9f384f131d6ecbbe2d089966b497abb6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<3.13",
"size": 31903,
"upload_time": "2023-10-12T04:23:41",
"upload_time_iso_8601": "2023-10-12T04:23:41.535800Z",
"url": "https://files.pythonhosted.org/packages/79/be/199b3a0d5cd7d7b6483d689b5b6d20aa3a27228ef83cd637eebab2ee24b6/chameleontools-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-12 04:23:41",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "chameleontools"
}
JSON