|ciconda| |cipip|
|GitHub license| |joss-status|
.. image:: https://img.shields.io/pypi/v/geohexviz
:alt: PyPI
.. |GitHub license| image:: https://img.shields.io/github/license/mrempel/geohexviz.svg
:target: https://github.com/mrempel/geohexviz/blob/master/LICENSE
.. image:: https://img.shields.io/pypi/pyversions/geohexviz
:alt: PyPI - Python Version
.. image:: img_files/geohexviz-logo-med.png
:align: right
:width: 300
:alt: GeoHexViz logo
Welcome to GeoHexViz!
Geospatial visualization is often used in military operations research to convey analyses to both analysts and decision makers.
For example, it has been used to help commanders coordinate units within a geographic region [feibush2000a]_, to depict how terrain impacts vehicle performance [laskey2010a]_, and inform training decisions in order to meet mission requirements [goodrich2019a]_.
When such analyses include a large amount of point-like data, combining geospatial visualization and binning -
in particular, hexagonal binning given its properties such as having the same number of neighbours as sides, the centre of each hexagon being equidistant from the centres of its neighbours, and that hexagons tile densely on curves surfaces [carr1992a]_ [sinha2019a]_ -
is an effective way to summarize and communicate the data.
Recent examples in the military and public safety domains include assessing the impact of infrastructure on Arctic operations [hunter2021a]_ and communicating the spatial distribution COVID-19 cases [shaito2021a]_ respectively.
However, creating such visualizations may be difficult for many since it requires in-depth knowledge of both Geographic Information Systems and analytical techniques, not to mention access to software that may require a paid license, training, and in some cases knowledge of a programming language such as Python or JavaScript. To help reduce these barriers, GeoHexViz - which produces publication-quality geospatial visualizations with hexagonal binning - is a Python package that provides a simple interface, requires minimal in-depth knowledge, and either limited or no programming. The result is an analyst being able to spend more time doing analysis and less time producing visualizations.
For more information of the design of GeoHexViz, see [abouzeidan2021a]_.
Example Usage
#############
GeoHexViz allows a user to generate hexagonally binned geospatial visualizations with two different methods.
Method 1 concerns using the GeoHexSimple package's script to run a file containing plot structure.
Method 2 concerns using Python code to interact with the functions within the package.
Method 2 method has two categories:
a) Using the functions that the GeoHexSimple script uses \
b) Using the PlotBuilder object from the GeoHexViz package
Please refer to the `examples directory <https://github.com/mrempel/geohexviz/blob/master/examples>`_ for additional examples that go into great depth (for both methods). Note that each example must be executed in its respective directory.
Method 1 Example Usage
**********************
The GeoHexViz distribution includes a module that can allow the reading
of JSON files for quick and easy plots.
.. code-block:: json
{
"hexbin_layer": {
"data": "<sample csv file>",
"hex_resolution": 4
},
"output": {
"filepath": "<sample filepath>",
"width": 600,
"height": 400
},
"display": true
}
Running the JSON script will allow you to input a JSON file via command-line.
The GeoHexSimple command-line script was created using argparse and is very robust.
Running the help command provides the following:
.. code-block::
>geohexsimple --help
usage: geohexsimple [options]
Input plot property files to make hexagonally binned plots.
optional arguments:
-h, --help show this help message and exit
-p PATH, --path PATH path to json file or directory containing json files (required if no gui is used)
-g, --gui enable command-line gui (set to true if no path is provided)
-nf, --nofeedback turn off feedback while plotting
-v, --verbose whether to raise all errors or not
Running your plot properties file may look something like:
.. code-block::
>geohexsimple --path <path to file>
exit
Or something like:
.. code-block::
>geohexsimple
✨=================GeoHexSimple================✨
A script for the simple creation of
hexagonally binned geospatial visualizations.
✨=============================================✨
✨Main Menu✨
Please input the location of your parameterized
builder file (JSON, YAML) or a directory containing
builder files.
Options: file path, help, exit.
<path to file>
Method 2
********
As previously mentioned there are two ways to use the GeoHexViz library in Python code.
Method 2a concerns using the functions that the GeoHexSimple script uses to create plots from pre-existing plot parameter files.
Method 2b concerns using the functions from the GeoHexViz package to create plots.
Method 2a Example Usage
_______________________
You can use the functions that the GeoHexSimple script uses to create a plot from a pre-existing plot parameter file.
A simple example of this method is given below.
.. code:: python
from geohexviz.utils.file import run_json
run_json("<filepath here>")
Method 2b Example Usage
_______________________
You can use the functions and objects within GeoHexViz to create a plot from scratch.
A simple example of this method is given below.
.. code:: python
from pandas import DataFrame
from geohexviz.builder import PlotBuilder
# Creating an example dataset
inputdf = DataFrame(dict(
latitude=[17.57, 17.57, 17.57, 19.98, 19.98, 46.75],
longitude=[10.11, 10.11, 10.12, 50.55, 50.55, 31.17],
value=[120, 120, 120, 400, 400, 700]
))
# Instantiating builder
builder = PlotBuilder()
builder.set_hexbin(inputdf, hexbin_info=dict(binning_fn='sum', binning_field='value'))
builder.finalize(raise_errors=False)
builder.display(clear_figure=True)
# A mapbox map
builder.set_mapbox('<ACCESS TOKEN>')
builder.finalize()
builder.display(clear_figure=True)
Behind the Scenes
*****************
When the hexbin layer is set, the data is processed
in the following steps:
Data:
+-------+-------+-------+-------+
| index | lats | lons | value |
+=======+=======+=======+=======+
| 0 | 17.57 | 10.11 | 120 |
+-------+-------+-------+-------+
| 1 | 17.57 | 10.11 | 120 |
+-------+-------+-------+-------+
| 2 | 17.57 | 10.12 | 120 |
+-------+-------+-------+-------+
| 3 | 19.98 | 50.55 | 400 |
+-------+-------+-------+-------+
| 4 | 19.98 | 50.55 | 400 |
+-------+-------+-------+-------+
| 5 | 46.75 | 31.17 | 700 |
+-------+-------+-------+-------+
1) Coordinate columns are converted into geometry (if applicable)
+-------+-------+---------------------+
| index | value | geometry |
+=======+=======+=====================+
| 0 | 120 | POINT(17.57, 10.11) |
+-------+-------+---------------------+
| 1 | 120 | POINT(17.57, 10.11) |
+-------+-------+---------------------+
| 2 | 120 | POINT(17.57, 10.12) |
+-------+-------+---------------------+
| 3 | 400 | POINT(19.98, 50.55) |
+-------+-------+---------------------+
| 4 | 400 | POINT(19.98, 50.55) |
+-------+-------+---------------------+
| 5 | 700 | POINT(46.75, 31.17) |
+-------+-------+---------------------+
2) Hex cells are then placed over the data
+-----------------+-------+---------------------+
| hex | value | geometry |
+=================+=======+=====================+
| 83595afffffffff | 120 | POINT(17.57, 10.11) |
+-----------------+-------+---------------------+
| 83595afffffffff | 120 | POINT(17.57, 10.11) |
+-----------------+-------+---------------------+
| 83595afffffffff | 120 | POINT(17.57, 10.11) |
+-----------------+-------+---------------------+
| 835262fffffffff | 400 | POINT(19.98, 50.55) |
+-----------------+-------+---------------------+
| 835262fffffffff | 400 | POINT(19.98, 50.55) |
+-----------------+-------+---------------------+
| 831e5dfffffffff | 700 | POINT(46.75, 31.17) |
+-----------------+-------+---------------------+
(hex resolution = 3)
3) The data is grouped together by hex, and hex geometry is added
+-----------------+---------------+-------------+---------------------------------------------------+
| hex | items | value_field | geometry |
+=================+===============+=============+===================================================+
| 83595afffffffff | (120,120,120) | 360 | POLYGON ((30.57051 46.80615, 30.47843 46.19931... |
+-----------------+---------------+-------------+---------------------------------------------------+
| 835262fffffffff | (400, 400) | 800 | POLYGON ((49.90903 20.19437, 49.74835 19.60088... |
+-----------------+---------------+-------------+---------------------------------------------------+
| 831e5dfffffffff | (700) | 700 | POLYGON ((9.44614 17.39197, 9.49704 16.75205, ... |
+-----------------+---------------+-------------+---------------------------------------------------+
(binning function = sum of grouped values)
When the data is eventually plotted, a GeoJSON format of the data is
passed alongside plotly properties are passed to the Plotly graphing
library.
Installation
############
GeoHexViz requires the installation of GeoPandas, and this is most easily done
through the use of Anaconda. Thus, to install GeoHexViz there are two options.
Option 1: Install from PyPI
***************************
This option requires the manual creation of a conda environment, installation of GeoPandas (GeoHexViz was developed with version 0.8.1 (build py_0)), and the installation of GeoHexViz from PyPI.
.. code-block::
conda env create --name geohexviz python<=3.8
conda activate geohexviz
conda install -c conda-forge geopandas
pip install geohexviz
Option 2: Install from GitHub
*****************************
This option requires that GeoHexViz be cloned from GitHub. Doing so will enable all dependencies, including GeoPandas, to be installed automatically.
.. code-block::
git clone https://github.com/mrempel/geohexviz.git
cd geohexviz
conda env create -f environment.yml
conda activate geohexviz
python setup.py install
Further Documentation
#####################
The official documentation for GeoHexViz can be found at `this page <https://github.com/mrempel/geohexviz/blob/master/docs>`_, in particular the `API documentation <https://github.com/mrempel/geohexviz/blob/master/docs/api_reference-v1.0.0.pdf>`_ for Python users.
A Defence Research and Development Canada `reference document <https://cradpdf.drdc-rddc.gc.ca/PDFS/unc381/p814091_A1b.pdf>`_ has also been published alongside this package.
Limitations
###########
This package uses GeoJSON format to plot data sets. With GeoJSON comes
difficulties when geometries cross the 180th meridian . The issue
appears to cause a color that bleeds through the entire plot and leaves
a hexagon empty. In the final plot, this issue may or may not appear as
it only occurs at certain angles of rotation. In this package a simple
solution to the problem is implemented, in the future it would be best
to provide a more robust solution. The solution that is used works
generally, however, when hexagons containing either the north or south
pole are present, the solution to the 180th meridian issue persists.
This pole issue can be seen below.
There also exists some issues with the generation of discrete color
scales under rare circumstances. These circumstances include generating
discrete color scales with not enough hues to fill the scale, and
generating diverging discrete colorscales with the center hue in a weird
position. These issues have been noted and will be fixed in the near
future.
There exists issues with the positioning and height of the color bar
with respect to the plot area of the figure. Although the user is
capable of altering the dimensions and positioning of the color bar,
this should be done automatically as it is a common feature of
publication quality choropleth maps.
Contributing
############
For major changes, please open an issue first to discuss what you would like to change. For more details, `click here <https://github.com/mrempel/geohexviz/blob/master/CONTRIBUTING.md>`_.
Citing
######
If you use geohexviz in your work, please cite our Defence Research and Development Canada report:
Abou Zeidan, T. & Rempel, M. (2021). GeoHezViz---Geospatial visualization using hexagonal binning software: Design reference and instruction manual. *Defence Research and Development Canada, DRDC-RDDC-2021-D183*. https://cradpdf.drdc-rddc.gc.ca/PDFS/unc381/p814091_A1b.pdf
Acknowledgements
################
Thank you to Nicholi Shiell for his input in testing, and providing
advice for the development of this package.
Contact
#######
For any questions, feedback, bug reports, feature requests, etc. please
first present your thoughts via GitHub issues. For further assistance
please contact mark.rempel@forces.gc.ca.
README References
#################
.. [abouzeidan2021a] Abou Zeidan, M. & Rempel, M. (2021). GeoHezViz---Geospatial visualization using hexagonal binning software: Design reference and instruction manual. *Defence Research and Development Canada, DRDC-RDDC-2021-D183*. https://cradpdf.drdc-rddc.gc.ca/PDFS/unc381/p814091_A1b.pdf
.. [feibush2000a] Feibush, E., Gagvani, N., & Williams, D. (2000). Visualization for situational awareness. *IEEE Computer Graphics and Applications, 20* (5), 38–45. https://doi.org/10.1109/38.865878
.. [laskey2010a] Laskey, K. B., Wright, E. J., & da Costa, P. C. G. (2010). Envisioning uncertainty in geospatial information. *International Journal of Approximate Reasoning, 51* (2), 209–223. https://doi.org/10.1016/j.ijar.2009.05.011
.. [goodrich2019a] Goodrich, D. C., Heilman, P., Guertin, D., Levick, L. R., Burns, I., Armendariz, G., & Wei, H. (2019). *Automated geospatial watershed assessment (AGWA) to aid in sustaining military mission and training*. USDA-ARS Southwest Watershed Research Center (SWRC) Tucson United States. https://apps.dtic.mil/sti/citations/AD1092333
.. [carr1992a] Carr, D. B., Olsen, A. R., & White, D. (1992). Hexagon mosaic maps for display of univariate and bivariate geographical data. *Cartography and Geographic Information Systems, 19* (4), 228–236. https://doi.org/10.1559/152304092783721231
.. [sinha2019a] Sinha, A. (2019). *Spatial modelling tidbits: Honeycomb or fishnets?* Towards Data Science. https://towardsdatascience.com/spatial-modelling-tidbits-honeycomb-or-fishnets-7f0b19273aab
.. [hunter2021a] Hunter, G., Chan, J., & Rempel, M. (2021). *Assessing the impact of infrastructure on arctic operations* (Scientific Report DRDC-RDDC-2021-R024). Defence Research and Development Canada. https://cradpdf.drdc-rddc.gc.ca/PDFS/unc356/p812844_A1b.pdf
.. [shaito2021a] Shaito, M., & Elmasri, R. (2021). Map visualization using spatial and spatio-temporal data: Application to COVID-19 data. *The 14th Pervasive Technologies Related to Assistive Environments Conference*, 284--291. https://doi.org/10.1145/3453892.3461336
Copyright and License
#####################
Copyright (c) His Majesty the King in Right of Canada, as represented
by the Minister of National Defence, 2022.
.. |ciconda| image:: https://github.com/mrempel/geohexviz/actions/workflows/geohexviz-automated-tests-conda.yml/badge.svg
:target: https://github.com/mrempel/geohexviz/actions/workflows/geohexviz-automated-tests-conda.yml
.. |cipip| image:: https://github.com/mrempel/geohexviz/actions/workflows/geohexviz-automated-tests-pip.yml/badge.svg
:target: https://github.com/mrempel/geohexviz/actions/workflows/geohexviz-automated-tests-pip.yml
.. |pythonver| image:: https://img.shields.io/badge/python-3.7,_3.8-blue.svg
.. |geohexvizver| image:: https://img.shields.io/badge/geohexviz-v1.0.0-blue.svg
.. |license| image:: https://img.shields.io/badge/License-BSD%203.0-blue.svg
:target: https://github.com/mrempel/geohexviz/blob/master/LICENSE
.. |joss-status| image:: https://joss.theoj.org/papers/c051df96dac973486cc312452575e804/status.svg
:target: https://joss.theoj.org/papers/c051df96dac973486cc312452575e804
Raw data
{
"_id": null,
"home_page": "",
"name": "geohexviz",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "visualization,geospatial,hexagonal binning",
"author": "Tony Marco Abou Zeidan, Mark Rempel",
"author_email": "Tony Abou Zeidan <tony.azp25@gmail.com>, Mark Rempel <mark.rempel@forces.gc.ca>",
"download_url": "https://files.pythonhosted.org/packages/43/ae/8b3cef94b085edd2428492012c23cb0332ceafb8153076e6d381613d1664/geohexviz-1.0.2.tar.gz",
"platform": null,
"description": "|ciconda| |cipip| \r\n|GitHub license| |joss-status|\r\n\r\n.. image:: https://img.shields.io/pypi/v/geohexviz\r\n :alt: PyPI\r\n\r\n.. |GitHub license| image:: https://img.shields.io/github/license/mrempel/geohexviz.svg\r\n :target: https://github.com/mrempel/geohexviz/blob/master/LICENSE\r\n\r\n.. image:: https://img.shields.io/pypi/pyversions/geohexviz\r\n :alt: PyPI - Python Version\r\n\r\n.. image:: img_files/geohexviz-logo-med.png\r\n :align: right\r\n :width: 300\r\n :alt: GeoHexViz logo\r\n\r\nWelcome to GeoHexViz!\r\n\r\nGeospatial visualization is often used in military operations research to convey analyses to both analysts and decision makers.\r\nFor example, it has been used to help commanders coordinate units within a geographic region [feibush2000a]_, to depict how terrain impacts vehicle performance [laskey2010a]_, and inform training decisions in order to meet mission requirements [goodrich2019a]_.\r\nWhen such analyses include a large amount of point-like data, combining geospatial visualization and binning -\r\nin particular, hexagonal binning given its properties such as having the same number of neighbours as sides, the centre of each hexagon being equidistant from the centres of its neighbours, and that hexagons tile densely on curves surfaces [carr1992a]_ [sinha2019a]_ -\r\nis an effective way to summarize and communicate the data.\r\nRecent examples in the military and public safety domains include assessing the impact of infrastructure on Arctic operations [hunter2021a]_ and communicating the spatial distribution COVID-19 cases [shaito2021a]_ respectively.\r\n\r\nHowever, creating such visualizations may be difficult for many since it requires in-depth knowledge of both Geographic Information Systems and analytical techniques, not to mention access to software that may require a paid license, training, and in some cases knowledge of a programming language such as Python or JavaScript. To help reduce these barriers, GeoHexViz - which produces publication-quality geospatial visualizations with hexagonal binning - is a Python package that provides a simple interface, requires minimal in-depth knowledge, and either limited or no programming. The result is an analyst being able to spend more time doing analysis and less time producing visualizations.\r\n\r\nFor more information of the design of GeoHexViz, see [abouzeidan2021a]_.\r\n\r\nExample Usage\r\n#############\r\nGeoHexViz allows a user to generate hexagonally binned geospatial visualizations with two different methods.\r\nMethod 1 concerns using the GeoHexSimple package's script to run a file containing plot structure.\r\nMethod 2 concerns using Python code to interact with the functions within the package.\r\nMethod 2 method has two categories:\r\n\r\na) Using the functions that the GeoHexSimple script uses \\\r\nb) Using the PlotBuilder object from the GeoHexViz package\r\n\r\nPlease refer to the `examples directory <https://github.com/mrempel/geohexviz/blob/master/examples>`_ for additional examples that go into great depth (for both methods). Note that each example must be executed in its respective directory.\r\n\r\nMethod 1 Example Usage\r\n**********************\r\n\r\nThe GeoHexViz distribution includes a module that can allow the reading\r\nof JSON files for quick and easy plots.\r\n\r\n.. code-block:: json\r\n\r\n {\r\n \"hexbin_layer\": {\r\n \"data\": \"<sample csv file>\",\r\n \"hex_resolution\": 4\r\n },\r\n \"output\": {\r\n \"filepath\": \"<sample filepath>\",\r\n \"width\": 600,\r\n \"height\": 400\r\n },\r\n \"display\": true\r\n }\r\n\r\nRunning the JSON script will allow you to input a JSON file via command-line.\r\nThe GeoHexSimple command-line script was created using argparse and is very robust.\r\nRunning the help command provides the following:\r\n\r\n.. code-block::\r\n\r\n >geohexsimple --help\r\n usage: geohexsimple [options]\r\n\r\n Input plot property files to make hexagonally binned plots.\r\n\r\n optional arguments:\r\n -h, --help show this help message and exit\r\n -p PATH, --path PATH path to json file or directory containing json files (required if no gui is used)\r\n -g, --gui enable command-line gui (set to true if no path is provided)\r\n -nf, --nofeedback turn off feedback while plotting\r\n -v, --verbose whether to raise all errors or not\r\n\r\n\r\nRunning your plot properties file may look something like:\r\n\r\n.. code-block::\r\n\r\n >geohexsimple --path <path to file>\r\n exit\r\n\r\nOr something like:\r\n\r\n.. code-block::\r\n\r\n >geohexsimple\r\n\r\n \u2728=================GeoHexSimple================\u2728\r\n A script for the simple creation of\r\n hexagonally binned geospatial visualizations.\r\n \u2728=============================================\u2728\r\n \u2728Main Menu\u2728\r\n Please input the location of your parameterized\r\n builder file (JSON, YAML) or a directory containing\r\n builder files.\r\n Options: file path, help, exit.\r\n <path to file>\r\n\r\nMethod 2\r\n********\r\nAs previously mentioned there are two ways to use the GeoHexViz library in Python code.\r\nMethod 2a concerns using the functions that the GeoHexSimple script uses to create plots from pre-existing plot parameter files.\r\nMethod 2b concerns using the functions from the GeoHexViz package to create plots.\r\n\r\nMethod 2a Example Usage\r\n_______________________\r\nYou can use the functions that the GeoHexSimple script uses to create a plot from a pre-existing plot parameter file.\r\nA simple example of this method is given below.\r\n\r\n.. code:: python\r\n\r\n from geohexviz.utils.file import run_json\r\n\r\n run_json(\"<filepath here>\")\r\n\r\nMethod 2b Example Usage\r\n_______________________\r\nYou can use the functions and objects within GeoHexViz to create a plot from scratch.\r\nA simple example of this method is given below.\r\n\r\n.. code:: python\r\n\r\n from pandas import DataFrame\r\n from geohexviz.builder import PlotBuilder\r\n\r\n # Creating an example dataset\r\n inputdf = DataFrame(dict(\r\n latitude=[17.57, 17.57, 17.57, 19.98, 19.98, 46.75],\r\n longitude=[10.11, 10.11, 10.12, 50.55, 50.55, 31.17],\r\n value=[120, 120, 120, 400, 400, 700]\r\n ))\r\n\r\n # Instantiating builder\r\n builder = PlotBuilder()\r\n builder.set_hexbin(inputdf, hexbin_info=dict(binning_fn='sum', binning_field='value'))\r\n\r\n builder.finalize(raise_errors=False)\r\n builder.display(clear_figure=True)\r\n\r\n # A mapbox map\r\n builder.set_mapbox('<ACCESS TOKEN>')\r\n builder.finalize()\r\n builder.display(clear_figure=True)\r\n\r\n\r\nBehind the Scenes\r\n*****************\r\nWhen the hexbin layer is set, the data is processed\r\nin the following steps:\r\n\r\nData:\r\n\r\n+-------+-------+-------+-------+\r\n| index | lats | lons | value |\r\n+=======+=======+=======+=======+\r\n| 0 | 17.57 | 10.11 | 120 |\r\n+-------+-------+-------+-------+\r\n| 1 | 17.57 | 10.11 | 120 |\r\n+-------+-------+-------+-------+\r\n| 2 | 17.57 | 10.12 | 120 |\r\n+-------+-------+-------+-------+\r\n| 3 | 19.98 | 50.55 | 400 |\r\n+-------+-------+-------+-------+\r\n| 4 | 19.98 | 50.55 | 400 |\r\n+-------+-------+-------+-------+\r\n| 5 | 46.75 | 31.17 | 700 |\r\n+-------+-------+-------+-------+\r\n\r\n1) Coordinate columns are converted into geometry (if applicable)\r\n\r\n+-------+-------+---------------------+\r\n| index | value | geometry |\r\n+=======+=======+=====================+\r\n| 0 | 120 | POINT(17.57, 10.11) |\r\n+-------+-------+---------------------+\r\n| 1 | 120 | POINT(17.57, 10.11) |\r\n+-------+-------+---------------------+\r\n| 2 | 120 | POINT(17.57, 10.12) |\r\n+-------+-------+---------------------+\r\n| 3 | 400 | POINT(19.98, 50.55) |\r\n+-------+-------+---------------------+\r\n| 4 | 400 | POINT(19.98, 50.55) |\r\n+-------+-------+---------------------+\r\n| 5 | 700 | POINT(46.75, 31.17) |\r\n+-------+-------+---------------------+\r\n\r\n2) Hex cells are then placed over the data\r\n\r\n+-----------------+-------+---------------------+\r\n| hex | value | geometry |\r\n+=================+=======+=====================+\r\n| 83595afffffffff | 120 | POINT(17.57, 10.11) |\r\n+-----------------+-------+---------------------+\r\n| 83595afffffffff | 120 | POINT(17.57, 10.11) |\r\n+-----------------+-------+---------------------+\r\n| 83595afffffffff | 120 | POINT(17.57, 10.11) |\r\n+-----------------+-------+---------------------+\r\n| 835262fffffffff | 400 | POINT(19.98, 50.55) |\r\n+-----------------+-------+---------------------+\r\n| 835262fffffffff | 400 | POINT(19.98, 50.55) |\r\n+-----------------+-------+---------------------+\r\n| 831e5dfffffffff | 700 | POINT(46.75, 31.17) |\r\n+-----------------+-------+---------------------+\r\n\r\n(hex resolution = 3)\r\n\r\n3) The data is grouped together by hex, and hex geometry is added\r\n\r\n+-----------------+---------------+-------------+---------------------------------------------------+\r\n| hex | items | value_field | geometry |\r\n+=================+===============+=============+===================================================+\r\n| 83595afffffffff | (120,120,120) | 360 | POLYGON ((30.57051 46.80615, 30.47843 46.19931... |\r\n+-----------------+---------------+-------------+---------------------------------------------------+\r\n| 835262fffffffff | (400, 400) | 800 | POLYGON ((49.90903 20.19437, 49.74835 19.60088... |\r\n+-----------------+---------------+-------------+---------------------------------------------------+\r\n| 831e5dfffffffff | (700) | 700 | POLYGON ((9.44614 17.39197, 9.49704 16.75205, ... |\r\n+-----------------+---------------+-------------+---------------------------------------------------+\r\n\r\n(binning function = sum of grouped values)\r\n\r\nWhen the data is eventually plotted, a GeoJSON format of the data is\r\npassed alongside plotly properties are passed to the Plotly graphing\r\nlibrary.\r\n\r\nInstallation\r\n############\r\n\r\nGeoHexViz requires the installation of GeoPandas, and this is most easily done\r\nthrough the use of Anaconda. Thus, to install GeoHexViz there are two options.\r\n\r\nOption 1: Install from PyPI\r\n***************************\r\nThis option requires the manual creation of a conda environment, installation of GeoPandas (GeoHexViz was developed with version 0.8.1 (build py_0)), and the installation of GeoHexViz from PyPI.\r\n\r\n.. code-block::\r\n\r\n conda env create --name geohexviz python<=3.8\r\n conda activate geohexviz\r\n conda install -c conda-forge geopandas\r\n pip install geohexviz\r\n\r\nOption 2: Install from GitHub\r\n*****************************\r\nThis option requires that GeoHexViz be cloned from GitHub. Doing so will enable all dependencies, including GeoPandas, to be installed automatically.\r\n\r\n.. code-block::\r\n\r\n git clone https://github.com/mrempel/geohexviz.git\r\n cd geohexviz\r\n conda env create -f environment.yml\r\n conda activate geohexviz\r\n python setup.py install\r\n\r\n\r\nFurther Documentation\r\n#####################\r\n\r\nThe official documentation for GeoHexViz can be found at `this page <https://github.com/mrempel/geohexviz/blob/master/docs>`_, in particular the `API documentation <https://github.com/mrempel/geohexviz/blob/master/docs/api_reference-v1.0.0.pdf>`_ for Python users.\r\nA Defence Research and Development Canada `reference document <https://cradpdf.drdc-rddc.gc.ca/PDFS/unc381/p814091_A1b.pdf>`_ has also been published alongside this package.\r\n\r\nLimitations\r\n###########\r\n\r\nThis package uses GeoJSON format to plot data sets. With GeoJSON comes\r\ndifficulties when geometries cross the 180th meridian . The issue\r\nappears to cause a color that bleeds through the entire plot and leaves\r\na hexagon empty. In the final plot, this issue may or may not appear as\r\nit only occurs at certain angles of rotation. In this package a simple\r\nsolution to the problem is implemented, in the future it would be best\r\nto provide a more robust solution. The solution that is used works\r\ngenerally, however, when hexagons containing either the north or south\r\npole are present, the solution to the 180th meridian issue persists.\r\nThis pole issue can be seen below.\r\n\r\nThere also exists some issues with the generation of discrete color\r\nscales under rare circumstances. These circumstances include generating\r\ndiscrete color scales with not enough hues to fill the scale, and\r\ngenerating diverging discrete colorscales with the center hue in a weird\r\nposition. These issues have been noted and will be fixed in the near\r\nfuture.\r\n\r\nThere exists issues with the positioning and height of the color bar\r\nwith respect to the plot area of the figure. Although the user is\r\ncapable of altering the dimensions and positioning of the color bar,\r\nthis should be done automatically as it is a common feature of\r\npublication quality choropleth maps.\r\n\r\nContributing\r\n############\r\n\r\nFor major changes, please open an issue first to discuss what you would like to change. For more details, `click here <https://github.com/mrempel/geohexviz/blob/master/CONTRIBUTING.md>`_.\r\n\r\nCiting\r\n######\r\n\r\nIf you use geohexviz in your work, please cite our Defence Research and Development Canada report:\r\n\r\nAbou Zeidan, T. & Rempel, M. (2021). GeoHezViz---Geospatial visualization using hexagonal binning software: Design reference and instruction manual. *Defence Research and Development Canada, DRDC-RDDC-2021-D183*. https://cradpdf.drdc-rddc.gc.ca/PDFS/unc381/p814091_A1b.pdf\r\n\r\nAcknowledgements\r\n################\r\n\r\nThank you to Nicholi Shiell for his input in testing, and providing\r\nadvice for the development of this package.\r\n\r\nContact\r\n#######\r\n\r\nFor any questions, feedback, bug reports, feature requests, etc. please\r\nfirst present your thoughts via GitHub issues. For further assistance\r\nplease contact mark.rempel@forces.gc.ca.\r\n\r\nREADME References\r\n#################\r\n\r\n.. [abouzeidan2021a] Abou Zeidan, M. & Rempel, M. (2021). GeoHezViz---Geospatial visualization using hexagonal binning software: Design reference and instruction manual. *Defence Research and Development Canada, DRDC-RDDC-2021-D183*. https://cradpdf.drdc-rddc.gc.ca/PDFS/unc381/p814091_A1b.pdf\r\n.. [feibush2000a] Feibush, E., Gagvani, N., & Williams, D. (2000). Visualization for situational awareness. *IEEE Computer Graphics and Applications, 20* (5), 38\u201345. https://doi.org/10.1109/38.865878\r\n.. [laskey2010a] Laskey, K. B., Wright, E. J., & da Costa, P. C. G. (2010). Envisioning uncertainty in geospatial information. *International Journal of Approximate Reasoning, 51* (2), 209\u2013223. https://doi.org/10.1016/j.ijar.2009.05.011\r\n.. [goodrich2019a] Goodrich, D. C., Heilman, P., Guertin, D., Levick, L. R., Burns, I., Armendariz, G., & Wei, H. (2019). *Automated geospatial watershed assessment (AGWA) to aid in sustaining military mission and training*. USDA-ARS Southwest Watershed Research Center (SWRC) Tucson United States. https://apps.dtic.mil/sti/citations/AD1092333\r\n.. [carr1992a] Carr, D. B., Olsen, A. R., & White, D. (1992). Hexagon mosaic maps for display of univariate and bivariate geographical data. *Cartography and Geographic Information Systems, 19* (4), 228\u2013236. https://doi.org/10.1559/152304092783721231\r\n.. [sinha2019a] Sinha, A. (2019). *Spatial modelling tidbits: Honeycomb or fishnets?* Towards Data Science. https://towardsdatascience.com/spatial-modelling-tidbits-honeycomb-or-fishnets-7f0b19273aab\r\n.. [hunter2021a] Hunter, G., Chan, J., & Rempel, M. (2021). *Assessing the impact of infrastructure on arctic operations* (Scientific Report DRDC-RDDC-2021-R024). Defence Research and Development Canada. https://cradpdf.drdc-rddc.gc.ca/PDFS/unc356/p812844_A1b.pdf\r\n.. [shaito2021a] Shaito, M., & Elmasri, R. (2021). Map visualization using spatial and spatio-temporal data: Application to COVID-19 data. *The 14th Pervasive Technologies Related to Assistive Environments Conference*, 284--291. https://doi.org/10.1145/3453892.3461336\r\n\r\n\r\nCopyright and License\r\n#####################\r\n\r\nCopyright (c) His Majesty the King in Right of Canada, as represented\r\nby the Minister of National Defence, 2022.\r\n\r\n.. |ciconda| image:: https://github.com/mrempel/geohexviz/actions/workflows/geohexviz-automated-tests-conda.yml/badge.svg\r\n :target: https://github.com/mrempel/geohexviz/actions/workflows/geohexviz-automated-tests-conda.yml\r\n.. |cipip| image:: https://github.com/mrempel/geohexviz/actions/workflows/geohexviz-automated-tests-pip.yml/badge.svg\r\n :target: https://github.com/mrempel/geohexviz/actions/workflows/geohexviz-automated-tests-pip.yml\r\n.. |pythonver| image:: https://img.shields.io/badge/python-3.7,_3.8-blue.svg\r\n.. |geohexvizver| image:: https://img.shields.io/badge/geohexviz-v1.0.0-blue.svg\r\n.. |license| image:: https://img.shields.io/badge/License-BSD%203.0-blue.svg\r\n :target: https://github.com/mrempel/geohexviz/blob/master/LICENSE\r\n\r\n.. |joss-status| image:: https://joss.theoj.org/papers/c051df96dac973486cc312452575e804/status.svg\r\n :target: https://joss.theoj.org/papers/c051df96dac973486cc312452575e804\r\n\r\n\r\n\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A library for the visualization of hexagonally binned data sets.",
"version": "1.0.2",
"split_keywords": [
"visualization",
"geospatial",
"hexagonal binning"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "13627d5317f48fd296ec095e8193586779d7dd9ff42f760af42f725b682164ef",
"md5": "eb99b64e173eadb052298c423cd1a8c2",
"sha256": "13fa7bff1eb431037455e27856c2f0a2a300bcdb29bac12f7d4afb5793aa4e2d"
},
"downloads": -1,
"filename": "geohexviz-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "eb99b64e173eadb052298c423cd1a8c2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 55250,
"upload_time": "2023-02-06T20:19:29",
"upload_time_iso_8601": "2023-02-06T20:19:29.419035Z",
"url": "https://files.pythonhosted.org/packages/13/62/7d5317f48fd296ec095e8193586779d7dd9ff42f760af42f725b682164ef/geohexviz-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "43ae8b3cef94b085edd2428492012c23cb0332ceafb8153076e6d381613d1664",
"md5": "ea3a8090c9ceb692377e4178e7618d7f",
"sha256": "ea074fee272861bb6da901a4b796ab0ae48ec4eb0e2a302f0a80b2e5eeef4a80"
},
"downloads": -1,
"filename": "geohexviz-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "ea3a8090c9ceb692377e4178e7618d7f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 56683,
"upload_time": "2023-02-06T20:19:31",
"upload_time_iso_8601": "2023-02-06T20:19:31.634349Z",
"url": "https://files.pythonhosted.org/packages/43/ae/8b3cef94b085edd2428492012c23cb0332ceafb8153076e6d381613d1664/geohexviz-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-06 20:19:31",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "geohexviz"
}
JSON