<img src="docs/assets/ninetysix_1.png" alt="logo" width="250"/>
# ninetysix
A general package for annotating, processing, and visualizing 96-well* plate data.
(*_n_-well, really.)
## Purpose
`ninetysix` provides a method of combining well-value data pairs and efficiently adding additional information (e.g., controls, well conditions) and processing and visualizing the results.
This primarily works via the `Plate` class, but visualization tools are available for `pandas DataFrame` objects as well through `ninetysix.viz`.
Visit the [`ninetysix` GitHub Pages site](https://palmhjell.github.io/ninetysix/) for detailed and interactive examples.
## Install
```
pip install ninetysix
```
Although `jupyter lab` is not a strict dependency for `ninetysix`, much of the visualization functionality benefits from being run in a notebook. If your `jupyter lab` and other packages are up to date, the above `pip` install should suffice. If you have issues, the following conda environment should work:
```
# Create the environment with python and jupyterlab installed
conda create -n ns_env python jupyterlab
# Activate the environment
conda activate ns_env
# Install ninetysix and its dependencies
pip install ninetysix
# Open jupyter lab
jupyter lab
```
## Features
### `ninetysix.Plate`
The heart of this package, a `Plate` object contains three major groups to describe a well:
`locations`, `annotations`, and `values`,
which are always arrayed in that order.
#### `Plate` performs value-oriented operations
The 'most important' (or perhaps 'most relevant') `value` is set as the right-most column in the data, which is automatically used in downstream processing and visualization unless explicitly overwritten, thus saving time needing to specify what data to use during exploratory data analysis.
New columns are assumed to be generic `annotations`, but can be moved to `locations` or `values` as desired to streamline your processing and analysis (see **Examples** below).
#### `Plate` uses the flexibility of the `pandas DataFrame`
`Plate` objects have nearly all methods available to a `DataFrame` (e.g., `merge`), but will return a `Plate` object when possible.
```python
>>> import ninetysix as ns
>>> import pandas as pd
>>> # Create Plate
>>> plate = ns.Plate('example_data.csv')
>>> # Create DataFrame with only row A and column 'plate'
>>> df = pd.DataFrame({
... 'well': [f'A{i}' for i in range(1, 13)],
... 'plate': 1
... })
>>> # Call `pd.merge` from Plate
>>> merged_plate = plate.merge(df)
>>> # Returned object is a Plate
>>> type(merged_plate)
ninetysix.plate.Plate
```
This new plate object will retain the same `locations`, `annotations`, and `values` attributes.
### `ninetysix.parsers.well_regex`
Dictionaries with key-value pairs that represent a single well and information about it are a powerful way to add information to a plate, but writing 96 key-value pairs is cumbersome. To alleviate this, `ninetysix` provides `well_regex` in the `parsers` module, which accepts well keys written in a simple regex form and expands them.
```python
>>> from ninetysix.parsers import well_regex
>>> well_info = {
... '[A-C]10': 'control',
... '[A,H][1,12]': 'empty',
... }
>>> well_regex(well_info)
{'A10': 'control',
'B10': 'control',
'C10': 'control',
'A1': 'empty',
'A12': 'empty',
'H1': 'empty',
'H12': 'empty'}
```
### `ninetysix.viz`
Quick access to scatter charts, plate heatmaps, and aggregated charts are available for both `Plate` and `DataFrame` objects, leveraging the information encoded in these objects to generate annotated visualizations.
These plots are based on the `holoviews` (http://holoviews.org/) package with the `bokeh` backend. The chart outputs of `viz` can be further tuned using the tools provided in these packages.
Plotting functions are available directly as `Plate` methods for an efficient workflow:
<img src="docs/assets/full_workup.png" alt="ex0" width="600"/>
Raw data
{
"_id": null,
"home_page": "https://palmhjell.github.io/ninetysix/",
"name": "ninetysix",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Patrick Almhjell",
"author_email": "palmhjell@caltech.edu",
"download_url": "https://files.pythonhosted.org/packages/59/44/36db8372708afc5040bb5442838e7c77689e90ddfa3cc91387fc16f971cb/ninetysix-0.0.5.tar.gz",
"platform": "",
"description": "<img src=\"docs/assets/ninetysix_1.png\" alt=\"logo\" width=\"250\"/>\n\n# ninetysix\nA general package for annotating, processing, and visualizing 96-well* plate data.\n\n(*_n_-well, really.)\n\n## Purpose\n`ninetysix` provides a method of combining well-value data pairs and efficiently adding additional information (e.g., controls, well conditions) and processing and visualizing the results.\n\nThis primarily works via the `Plate` class, but visualization tools are available for `pandas DataFrame` objects as well through `ninetysix.viz`.\n\nVisit the [`ninetysix` GitHub Pages site](https://palmhjell.github.io/ninetysix/) for detailed and interactive examples.\n\n## Install\n```\npip install ninetysix\n```\nAlthough `jupyter lab` is not a strict dependency for `ninetysix`, much of the visualization functionality benefits from being run in a notebook. If your `jupyter lab` and other packages are up to date, the above `pip` install should suffice. If you have issues, the following conda environment should work:\n```\n# Create the environment with python and jupyterlab installed\nconda create -n ns_env python jupyterlab\n\n# Activate the environment\nconda activate ns_env\n\n# Install ninetysix and its dependencies\npip install ninetysix\n\n# Open jupyter lab\njupyter lab\n```\n\n## Features\n### `ninetysix.Plate`\nThe heart of this package, a `Plate` object contains three major groups to describe a well:\n\n`locations`, `annotations`, and `values`,\n\nwhich are always arrayed in that order.\n\n#### `Plate` performs value-oriented operations\nThe 'most important' (or perhaps 'most relevant') `value` is set as the right-most column in the data, which is automatically used in downstream processing and visualization unless explicitly overwritten, thus saving time needing to specify what data to use during exploratory data analysis.\n\nNew columns are assumed to be generic `annotations`, but can be moved to `locations` or `values` as desired to streamline your processing and analysis (see **Examples** below).\n\n#### `Plate` uses the flexibility of the `pandas DataFrame`\n`Plate` objects have nearly all methods available to a `DataFrame` (e.g., `merge`), but will return a `Plate` object when possible.\n\n```python\n>>> import ninetysix as ns\n>>> import pandas as pd\n\n>>> # Create Plate\n>>> plate = ns.Plate('example_data.csv')\n\n>>> # Create DataFrame with only row A and column 'plate'\n>>> df = pd.DataFrame({\n... 'well': [f'A{i}' for i in range(1, 13)],\n... 'plate': 1\n... })\n\n>>> # Call `pd.merge` from Plate\n>>> merged_plate = plate.merge(df)\n\n>>> # Returned object is a Plate\n>>> type(merged_plate)\n\nninetysix.plate.Plate\n```\nThis new plate object will retain the same `locations`, `annotations`, and `values` attributes.\n\n### `ninetysix.parsers.well_regex`\nDictionaries with key-value pairs that represent a single well and information about it are a powerful way to add information to a plate, but writing 96 key-value pairs is cumbersome. To alleviate this, `ninetysix` provides `well_regex` in the `parsers` module, which accepts well keys written in a simple regex form and expands them.\n\n```python\n>>> from ninetysix.parsers import well_regex\n\n>>> well_info = {\n... '[A-C]10': 'control',\n... '[A,H][1,12]': 'empty',\n... }\n\n>>> well_regex(well_info)\n\n{'A10': 'control',\n 'B10': 'control',\n 'C10': 'control',\n 'A1': 'empty',\n 'A12': 'empty',\n 'H1': 'empty',\n 'H12': 'empty'}\n```\n\n### `ninetysix.viz`\nQuick access to scatter charts, plate heatmaps, and aggregated charts are available for both `Plate` and `DataFrame` objects, leveraging the information encoded in these objects to generate annotated visualizations.\n\nThese plots are based on the `holoviews` (http://holoviews.org/) package with the `bokeh` backend. The chart outputs of `viz` can be further tuned using the tools provided in these packages.\n\nPlotting functions are available directly as `Plate` methods for an efficient workflow:\n\n<img src=\"docs/assets/full_workup.png\" alt=\"ex0\" width=\"600\"/>\n\n",
"bugtrack_url": null,
"license": "",
"summary": "A general package for tidying, annotating, and analyzing 96-well plate data.",
"version": "0.0.5",
"project_urls": {
"Homepage": "https://palmhjell.github.io/ninetysix/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c0a35a3727ef07968abf5050625a0320fad29f37fdb30d0091d6c4e51d912d15",
"md5": "632031a9c34ce7960df65dbdffedf573",
"sha256": "c5c3d216c7b60605bfc67ded817e36741dafe2f8d73bbd6faf22c140617db25a"
},
"downloads": -1,
"filename": "ninetysix-0.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "632031a9c34ce7960df65dbdffedf573",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 29893,
"upload_time": "2021-07-22T19:20:39",
"upload_time_iso_8601": "2021-07-22T19:20:39.710809Z",
"url": "https://files.pythonhosted.org/packages/c0/a3/5a3727ef07968abf5050625a0320fad29f37fdb30d0091d6c4e51d912d15/ninetysix-0.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "594436db8372708afc5040bb5442838e7c77689e90ddfa3cc91387fc16f971cb",
"md5": "e6da6d6217e8dbc530cbe6f9fd4f46e8",
"sha256": "d08196f781f0641ca69c9e8015082faae636ac50a813b97f17a2228cad224baf"
},
"downloads": -1,
"filename": "ninetysix-0.0.5.tar.gz",
"has_sig": false,
"md5_digest": "e6da6d6217e8dbc530cbe6f9fd4f46e8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 28028,
"upload_time": "2021-07-22T19:20:41",
"upload_time_iso_8601": "2021-07-22T19:20:41.923167Z",
"url": "https://files.pythonhosted.org/packages/59/44/36db8372708afc5040bb5442838e7c77689e90ddfa3cc91387fc16f971cb/ninetysix-0.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-07-22 19:20:41",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "ninetysix"
}
JSON