<img align="left" width="100" height="100" src="https://github.com/cusp-london/vizent/raw/main/docs/_static/vizent_logo_thumbnail.png">
# vizent
<br/>
> A python library for visualising bivariate data using glyphs and node-link diagrams with matplotlib
This library allows the user to create scatter plots and node-link diagrams using Visual Entropy Glyphs[1] and network edges [2]. Vizent glyphs and network edges are designed to help when you need to add an extra variable to a scatter plot, map, or graph.
Vizent glyphs are bivariate, that is they allow you to represent two variables at each point on your plot. A central colored disc is able to represent a continuous variable, an enclosing shape can represent a continuous interval or categorical variable using increasing levels of visual entropy (shape complexity).
Vizent network edges enable additional bivariate data representation and can be used in combination with the glyphs. The edges represent data via colored edges and a visual entropy component on top of the colored edge capable of representing ordered data.
Applications for the Vizent glyphs include:
* when you need represent uncertainty at a point or edge, eg a mean and a standard deviation
* when you need to represent derivatives at a point or edge, eg a rate and an acceleration
* any other pair of values at a point on a plot or on a network edge.
The vizent library provides an interface to matplotlib axes and figures that supports the drawing of vizent glyphs and network edges. The matplotlib artists, figures and axes objects are returned for further editing using the broader matplotlib library if required.
The library also provides functionality to plot vizent glyphs and networks edges with a map background (requires [Cartopy](https://scitools.org.uk/cartopy/docs/latest/)) or using an image provided by the user (requires [pillow](https://pillow.readthedocs.io/en/stable/)).
The [gallery](docs/_build/gallery.html) gives example plots demonstrating the library capability. A more detailed tutorial is also available [here](https://medium.com/nightingale/rising-or-falling-visualizing-the-trends-in-the-daily-covid-19-situation-e5ae3044fcef).
## Installation
vizent can be installed using [pip](https://pip.pypa.io/en/stable/)
```sh
pip install vizent
```
[vizent on PyPI](https://pypi.org/project/vizent)
Dependencies:
* matplotlib
* numpy
* scipy
Optional dependencies:
* pillow (for image backgrounds)
* cartopy (for map backgrounds)
## Using vizent
Library documentation is available at at: https://cusplondon.ac.uk/vizent
## Glyph Designs
The available glyph shape designs are shown here in full. Value increases with frequency from left (lowest) to right (highest).
### sine
### saw
### reverse_saw
### square
### triangular
### concave
### star
## Edge Designs
Default sample lines for a variety of frequency values are shown below. The left-most line is used when the data contains numpy.nan (i.e. for missing data).
## Examples
### Create a basic scatterplot:
```python
from vizent import vizent_plot
x_values = [1,2,3,4,5,6,7]
y_values = [6,3,7,1,4,2,5]
color_values = [0,3,6,9,12,15,18]
shape_values= [0,1,2,3,4,5,6]
size_values = [30,60,30,45,60,30,45]
extent = [0, 9, 0, 9]
fig = vizent_plot(x_values, y_values, color_values, shape_values, size_values,
color_label="color", shape_label="shape", glyph_legend_title='Legend',
extent=extent)
fig.axes[1].set_xlabel('x')
fig.axes[1].set_ylabel('y')
```
### Create a vizent plot with edges:
```python
import numpy as np
from vizent import vizent_plot
x_values = [0, 0, 1, 1, 0.5]
y_values = [0, 1, 0, 1, 0.5]
color_values = [-100, -10, 0.01, 100, 1000]
shape_values = [2, 1, 0, -2, -1]
edge_color_values = [-10, -5, -3, 1, 2, 4]
edge_freq_values = range(6)
color_values = [-100, -10, 0.01, 100, 1000]
shape_values = [2, 1, 0, -2, -1]
# Build a sample network based on these points
x_start = []
x_end = []
y_start = []
y_end = []
for x1,y1 in zip(x_values, y_values):
for x2,y2 in zip(x_values, y_values):
if x1 <= x2 and y1 <= y2:
line_distance = np.sqrt((x1 - x2)**2 + (y1 - y2)**2)
if line_distance <= 1 and line_distance > 10e-5:
x_start.append(x1)
y_start.append(y1)
x_end.append(x2)
y_end.append(y2)
fig = vizent_plot(x_values=x_values,
y_values=y_values,
colour_values=color_values,
shape_values=shape_values,
size_values=[20 for i in range(len(x_values))],
edge_start_points=[(x,y) for x,y in zip(x_start, y_start)],
edge_end_points=[(x,y) for x,y in zip(x_end, y_end)],
edge_colors=edge_color_values,
edge_frequencies=edge_freq_values,
edge_widths=[5 for i in range(len(x_start))],
edge_color_n=4,
scale_x=15)
```
Other examples, including those using background maps for geospatial data can be found at https://cusplondon.ac.uk/vizent/gallery.
## Release History
* 1.0 First release 24/02/2021
* 1.1 Added vizent network edges 13/09/2023
## Meta
[vizent on github](https://github.com/cusp-london/vizent)
[vizent on PyPI](https://pypi.org/project/vizent)
Distributed under the MIT license. See ``LICENSE`` for more information.
Acknowledgments: The Alan Turing Institute for funding the Newcastle Seedcorn project "Automating visualization", under the EPSRC grant EP/N510129/1 and for Nick Holliman's Turing Fellowship 2018-2024. For supporting Lucy McLaughlin's PhD, the EPSRC Centre for Doctoral Training in Cloud Computing for Big Data EP/L015358/1. For Osman Akbulut's PhD support the Turkish Government. CUSP London, the Department of Informatics and the Faculty of NMES at King's College for supporting Dr Peter Baudains' time. A Department of Informatics Impact Acceleration Award for summer 2023 funding to develop new Vizent test cases for Kabir Chhabra.
[1] "Visual Entropy and the Visualization of Uncertainty", Holliman et al, arXiv:1907.12879
[2] "Visualising ordered bivariate data on node-link diagrams", O Akbulut, L McLaughlin, T Xin et al. Visual Informatics (2023) [doi:10.1016/j.visinf.2023.06.003](https://doi.org/10.1016/j.visinf.2023.06.003)
Raw data
{
"_id": null,
"home_page": "https://github.com/cusp-london/vizent",
"name": "vizent",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "visualization,plot,bivariate,glyphs,scatterplot,dataviz,networks,uncertainty",
"author": "CUSP London and Lucy McLaughlin",
"author_email": "lucy.mclaughlin@ncl.ac.uk",
"download_url": "https://files.pythonhosted.org/packages/3b/23/b1b9106c24d526f94331de05ba706475fa3f9163496ea287bf7396575142/vizent-1.1.0.tar.gz",
"platform": null,
"description": "<img align=\"left\" width=\"100\" height=\"100\" src=\"https://github.com/cusp-london/vizent/raw/main/docs/_static/vizent_logo_thumbnail.png\">\n\n# vizent\n\n<br/> \n \n\n\n> A python library for visualising bivariate data using glyphs and node-link diagrams with matplotlib\n\nThis library allows the user to create scatter plots and node-link diagrams using Visual Entropy Glyphs[1] and network edges [2]. Vizent glyphs and network edges are designed to help when you need to add an extra variable to a scatter plot, map, or graph.\n\nVizent glyphs are bivariate, that is they allow you to represent two variables at each point on your plot. A central colored disc is able to represent a continuous variable, an enclosing shape can represent a continuous interval or categorical variable using increasing levels of visual entropy (shape complexity). \n\nVizent network edges enable additional bivariate data representation and can be used in combination with the glyphs. The edges represent data via colored edges and a visual entropy component on top of the colored edge capable of representing ordered data.\n\nApplications for the Vizent glyphs include: \n* when you need represent uncertainty at a point or edge, eg a mean and a standard deviation\n* when you need to represent derivatives at a point or edge, eg a rate and an acceleration\n* any other pair of values at a point on a plot or on a network edge.\n\nThe vizent library provides an interface to matplotlib axes and figures that supports the drawing of vizent glyphs and network edges. The matplotlib artists, figures and axes objects are returned for further editing using the broader matplotlib library if required.\n\nThe library also provides functionality to plot vizent glyphs and networks edges with a map background (requires [Cartopy](https://scitools.org.uk/cartopy/docs/latest/)) or using an image provided by the user (requires [pillow](https://pillow.readthedocs.io/en/stable/)).\n\nThe [gallery](docs/_build/gallery.html) gives example plots demonstrating the library capability. A more detailed tutorial is also available [here](https://medium.com/nightingale/rising-or-falling-visualizing-the-trends-in-the-daily-covid-19-situation-e5ae3044fcef).\n\n\n## Installation\n\nvizent can be installed using [pip](https://pip.pypa.io/en/stable/)\n\n```sh\npip install vizent\n```\n[vizent on PyPI](https://pypi.org/project/vizent)\n\nDependencies:\n* matplotlib\n* numpy\n* scipy\n\nOptional dependencies:\n* pillow (for image backgrounds)\n* cartopy (for map backgrounds)\n\n\n## Using vizent\n\nLibrary documentation is available at at: https://cusplondon.ac.uk/vizent\n\n## Glyph Designs\n\nThe available glyph shape designs are shown here in full. Value increases with frequency from left (lowest) to right (highest).\n\n### sine\n![sine glyphs](https://github.com/cusp-london/vizent/raw/main/docs/_static/glyphs/sine.png \"sine glyphs\")\n### saw\n![saw glyphs](https://github.com/cusp-london/vizent/raw/main/docs/_static/glyphs/saw.png \"saw glyphs\")\n### reverse_saw\n![reverse_saw glyphs](https://github.com/cusp-london/vizent/raw/main/docs/_static/glyphs/reverse_saw.png \"reverse_saw glyphs\")\n### square\n![square glyphs](https://github.com/cusp-london/vizent/raw/main/docs/_static/glyphs/square.png \"square glyphs\")\n### triangular\n![triangular glyphs](https://github.com/cusp-london/vizent/raw/main/docs/_static/glyphs/triangular.png \"triangular glyphs\")\n### concave\n![concave glyphs](https://github.com/cusp-london/vizent/raw/main/docs/_static/glyphs/concave.png \"concave glyphs\")\n### star\n![star glyphs](https://github.com/cusp-london/vizent/raw/main/docs/_static/glyphs/star.png \"star glyphs\")\n\n## Edge Designs\n\nDefault sample lines for a variety of frequency values are shown below. The left-most line is used when the data contains numpy.nan (i.e. for missing data).\n\n\n\n\n## Examples\n\n### Create a basic scatterplot:\n\n```python\nfrom vizent import vizent_plot\n\nx_values = [1,2,3,4,5,6,7]\ny_values = [6,3,7,1,4,2,5]\ncolor_values = [0,3,6,9,12,15,18]\nshape_values= [0,1,2,3,4,5,6]\nsize_values = [30,60,30,45,60,30,45]\n\nextent = [0, 9, 0, 9]\n\nfig = vizent_plot(x_values, y_values, color_values, shape_values, size_values,\n color_label=\"color\", shape_label=\"shape\", glyph_legend_title='Legend',\n extent=extent)\n\nfig.axes[1].set_xlabel('x')\nfig.axes[1].set_ylabel('y')\n```\n![scatterplot image](https://github.com/cusp-london/vizent/raw/main/docs/_build/_images/gallery-basic-scatterplot_1_1.png \"scatterplot image\")\n\n\n### Create a vizent plot with edges:\n\n```python\nimport numpy as np\nfrom vizent import vizent_plot\n\nx_values = [0, 0, 1, 1, 0.5]\ny_values = [0, 1, 0, 1, 0.5]\n\ncolor_values = [-100, -10, 0.01, 100, 1000]\nshape_values = [2, 1, 0, -2, -1]\n\nedge_color_values = [-10, -5, -3, 1, 2, 4]\nedge_freq_values = range(6)\ncolor_values = [-100, -10, 0.01, 100, 1000]\nshape_values = [2, 1, 0, -2, -1]\n\n# Build a sample network based on these points\nx_start = []\nx_end = []\ny_start = []\ny_end = []\nfor x1,y1 in zip(x_values, y_values):\n for x2,y2 in zip(x_values, y_values):\n if x1 <= x2 and y1 <= y2:\n line_distance = np.sqrt((x1 - x2)**2 + (y1 - y2)**2)\n if line_distance <= 1 and line_distance > 10e-5:\n x_start.append(x1)\n y_start.append(y1)\n x_end.append(x2)\n y_end.append(y2)\n\nfig = vizent_plot(x_values=x_values,\n y_values=y_values,\n colour_values=color_values,\n shape_values=shape_values,\n size_values=[20 for i in range(len(x_values))],\n edge_start_points=[(x,y) for x,y in zip(x_start, y_start)],\n edge_end_points=[(x,y) for x,y in zip(x_end, y_end)],\n edge_colors=edge_color_values,\n edge_frequencies=edge_freq_values,\n edge_widths=[5 for i in range(len(x_start))],\n edge_color_n=4,\n scale_x=15)\n```\n![vizent plot](https://github.com/cusp-london/vizent/raw/main/docs/_build/_images/vizent_plot_with_edges_test.png \"vizent plot\")\n\n\nOther examples, including those using background maps for geospatial data can be found at https://cusplondon.ac.uk/vizent/gallery.\n\n## Release History\n\n* 1.0 First release 24/02/2021\n* 1.1 Added vizent network edges 13/09/2023\n\n## Meta\n\n[vizent on github](https://github.com/cusp-london/vizent)\n\n[vizent on PyPI](https://pypi.org/project/vizent)\n\nDistributed under the MIT license. See ``LICENSE`` for more information.\n\nAcknowledgments: The Alan Turing Institute for funding the Newcastle Seedcorn project \"Automating visualization\", under the EPSRC grant EP/N510129/1 and for Nick Holliman's Turing Fellowship 2018-2024. For supporting Lucy McLaughlin's PhD, the EPSRC Centre for Doctoral Training in Cloud Computing for Big Data EP/L015358/1. For Osman Akbulut's PhD support the Turkish Government. CUSP London, the Department of Informatics and the Faculty of NMES at King's College for supporting Dr Peter Baudains' time. A Department of Informatics Impact Acceleration Award for summer 2023 funding to develop new Vizent test cases for Kabir Chhabra.\n\n[1] \"Visual Entropy and the Visualization of Uncertainty\", Holliman et al, arXiv:1907.12879\n\n[2] \"Visualising ordered bivariate data on node-link diagrams\", O Akbulut, L McLaughlin, T Xin et al. Visual Informatics (2023) [doi:10.1016/j.visinf.2023.06.003](https://doi.org/10.1016/j.visinf.2023.06.003)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A python library for visualising bivariate data using glyphs and node-link diagrams with matplotlib.",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://github.com/cusp-london/vizent"
},
"split_keywords": [
"visualization",
"plot",
"bivariate",
"glyphs",
"scatterplot",
"dataviz",
"networks",
"uncertainty"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b0096e2fb05ceef350f6319bc37a315792f25bb1c6ccf8df28956b0f64afcf75",
"md5": "23d850f13c9032f48ebc8d587b4d0e99",
"sha256": "434fdce738338084172379e7fc0246ecb1659fd0dba928862e54cd69ec54ff26"
},
"downloads": -1,
"filename": "vizent-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "23d850f13c9032f48ebc8d587b4d0e99",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 46296609,
"upload_time": "2023-10-26T11:22:44",
"upload_time_iso_8601": "2023-10-26T11:22:44.558603Z",
"url": "https://files.pythonhosted.org/packages/b0/09/6e2fb05ceef350f6319bc37a315792f25bb1c6ccf8df28956b0f64afcf75/vizent-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3b23b1b9106c24d526f94331de05ba706475fa3f9163496ea287bf7396575142",
"md5": "5fd2b8c2c4f9432ae0bfe5f10548364f",
"sha256": "ae3bebf94ced22a045f7c87cdae377c33f25e1e161395c70d85760968f12f339"
},
"downloads": -1,
"filename": "vizent-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "5fd2b8c2c4f9432ae0bfe5f10548364f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 46301702,
"upload_time": "2023-10-26T11:23:52",
"upload_time_iso_8601": "2023-10-26T11:23:52.416622Z",
"url": "https://files.pythonhosted.org/packages/3b/23/b1b9106c24d526f94331de05ba706475fa3f9163496ea287bf7396575142/vizent-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-26 11:23:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cusp-london",
"github_project": "vizent",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "vizent"
}
JSON
