Metadata-Version: 2.0
Name: convert2geojson
Version: 0.0.2
Summary: Tools for converting dataframes to GeoJSON format.
Home-page: https://github.com/computational-antiquity/convert2geojson/
Author: Malte Vogl
Author-email: mvogl@mpiwg-berlin.mpg.de
License: GPLv3
Project-URL: Home, https://github.com/computational-antiquity/convert2geojson/
Project-URL: Tracker, https://github.com/computational-antiquity/convert2geojson/issues
Project-URL: Download, https://github.com/computational-antiquity/convert2geojson/archive/0.0.2.tar.gz
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Text Processing :: General
Classifier: Topic :: Text Processing :: Indexing
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3
Requires-Dist: pandas
Requires-Dist: xlrd
Requires-Dist: citableclass
Requires-Dist: ipyleaflet
Requires-Dist: ipywidgets
Requires-Dist: jinja2
Requires-Dist: ipython

convert2geojson
===============

Convert databases to geojson, useful for displaying datasets on maps.

A FeatureCollection is generated from those dataframe rows containing
values for latitude and longitude.

*Note:* To limit the size of the GeoJSON file, lookup tables are
generated automatically for fields with a limited number of values (<20)
and saved as a top-level 'properties' key in the JSON file. This is not
part of the GeoJSON standard and can lead to problems with linters, e.g.
`GeoJSONLint <http://geojsonlint.com/>`__.

Content
-------

1. `Installation <#installation>`__
2. `Basics <#basic-usage>`__

-  `Loading data <#loading-data>`__
-  `Generating geojson <#generating-geojson>`__
-  `Plotting <#plotting>`__

3. `Examples <#examples>`__

Installation
------------

The package can be installed by

::

    pip install convert2geojson

The latest development version of the package can be installed from
GitHub by running

::

      pip install git+https://github.com/computational-antiquity/convert2geojson.git

This installs the most recent version of the master branch.

If the plotting on maps in JupyterLab is not yielding results, there
might be problems with your `ipyleaflet
installtion <https://github.com/jupyter-widgets/ipyleaflet#installation>`__
or `ipywidgets
installtion <https://ipywidgets.readthedocs.io/en/stable/user_install.html#installing-the-jupyterlab-extension>`__.

Basic usage
-----------

Import the package with

.. code:: python

    from convert2geojson import Convert2GeoJson

Loading data
~~~~~~~~~~~~

The package is instantiated by providing a dataframe containing the
geodata ,e.g. ``dataframe=df``, a list of columns of the dataframe,
which should be shown as information for every geo feature, e.g.
``properties=df.columns`` to show everything, and the column titles for
longitudal and latitudal data (standard parameter names are
``lat='latitude'`` and ``lon='longitude'``).

.. code:: python

    data = Convert2GeoJson(
              df,
              df.columns,
              lat='latitude',
              lon='longitude'
           )

The geo data is expected to be gievn as float numbers. Rows with empty
longitudal or latitudel data, or marked as ``NaN`` are droped from the
supplied dataframe.

The original dataframe can however still be accessed as ``data.rawDF``.

Generate geoJson
~~~~~~~~~~~~~~~~

To generate the geoJSON simple run

.. code:: python

    data.convert()

This generates a geoJSON formated dictionary which is available at

.. code:: python

    data.geojson()

To save the geoJSON to a file, run

.. code:: python

    data.save()

You can provide parameters for the name and path, standards are
``name='data.geojson'`` and ``path='.'``.

Plotting
~~~~~~~~

For plotting the package is leveraging the `ipyleaflet
package <https://github.com/jupyter-widgets/ipyleaflet>`__ which is also
available as a JupyterLab extension.

For a first overview use

.. code:: python

    data.display()

This plots the geoJSON features as a layer on a basemap.

The basic plotting can be changed by parameters for the map layout
(``mapLayout=dict()``), and the basemap data (``basemap=dict()``).

To use a custom basemap, you can provide a dictionary of the format

.. code:: python

    customBasemap = {
              'url': 'https://{s}.URL_to_mapdata/{z}/{x}/{y}.png',
              'max_zoom': 'max available zoom level',
              'attribution': 'Attribution',
              'name': 'Name for layer control'
              }

Screenshot
''''''''''

.. figure:: example/mapExample.png
   :alt: Screenshot of generated map

   Screenshot of generated map

Grouped Plotting
^^^^^^^^^^^^^^^^

For densely distributed geographical data, to styling options are
available.

By choosing ``style='grouped'`` ipyleaflets MarkerCluster is used to
show groups of markers depending on the zoom level. By clicking on a
cluster, the map zooms to the level, which contains the selected markers
in the cluster .

Additionally, since markers are now single entities, by clicking on any
marker a popup shows the information of the dataframe belonging to the
geographical point.

Screenshot
''''''''''

.. figure:: example/clusterMap.png
   :alt: Screenshot of generated cluster map

   Screenshot of generated cluster map

Categorical plotting as pie chart distribution
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

By choosing ``style='pie'`` and providing a category found in the
dataframe columns, by setting ``groupBy='Category'``, the package
generates a standalone map showing the clustered markers as pie charts
separated into sub-groups by the chosen category.

Screenshot
''''''''''

.. figure:: example/pieChartMap.png
   :alt: Screenshot of generated pie chart map

   Screenshot of generated pie charts map

Examples
--------

Have a look at the `Loading datasets </example/Loading_dataset.ipynb>`__
or the `Advanced Plotting </example/Advanced_plotting.ipynb>`__
notebooks in the ``/example`` folder


