Repository: geopandas/geopandas

Issue:
DOC: add page on how to construct GeoDataFrame from existing DataFrame
Eg if you have 

- two columns with x, y
- a column with the WKT format


Discussion:
Sounds good, should it be an example gallery or a subsection ?
Hmm, not sure, maybe a gallery example is fine. Unless you see a good place to fit it in the user guides.

If there are any of the other ideas here: https://github.com/geopandas/geopandas/issues/529 that you would be familiar with, that's also welcome (or any other typical example workflow that you are using yourself).

General improvement of docstrings (adding examples, more explanation) is also very useful: https://github.com/geopandas/geopandas/issues/107

Resolving patch:
diff --git a/examples/create_geopandas_from_pandas.py b/examples/create_geopandas_from_pandas.py
new file mode 100644
--- /dev/null
+++ b/examples/create_geopandas_from_pandas.py
@@ -0,0 +1,89 @@
+"""
+Creating a GeoDataFrame from a DataFrame with coordinates
+---------------------------------------------------------
+
+This example shows how to create a ``GeoDataFrame`` when starting from
+a *regular* ``DataFrame`` that has coordinates either WKT
+(`well-known text <https://en.wikipedia.org/wiki/Well-known_text>`_)
+format, or in
+two columns.
+
+"""
+import matplotlib.pyplot as plt
+import pandas as pd
+import geopandas as gpd
+from shapely.geometry import Point
+
+###############################################################################
+# From longitudes and latitudes
+# =============================
+#
+# First, let's consider a ``DataFrame`` containing cities and their respective
+# longitudes and latitudes.
+
+df = pd.DataFrame(
+    {'City': ['Buenos Aires', 'Brasilia', 'Santiago', 'Bogota', 'Caracas'],
+     'Country': ['Argentina', 'Brazil', 'Chile', 'Colombia', 'Venezuela'],
+     'Latitude': [-34.58, -15.78, -33.45, 4.60, 10.48],
+     'Longitude': [-58.66, -47.91, -70.66, -74.08, -66.86]})
+
+###############################################################################
+# A ``GeoDataFrame`` needs a ``shapely`` object, so we create a new column
+# **Coordinates** as a tuple of **Longitude** and **Latitude** :
+
+df['Coordinates']  = list(zip(df.Longitude, df.Latitude))
+
+###############################################################################
+# Then, we transform tuples to ``Point`` :
+
+df['Coordinates'] = df['Coordinates'].apply(Point)
+
+###############################################################################
+# Now, we can create the ``GeoDataFrame`` by setting ``geometry`` with the
+# coordinates created previously.
+
+gdf = gpd.GeoDataFrame(df, geometry='Coordinates')
+
+###############################################################################
+# ``gdf`` looks like this :
+
+print(gdf.head())
+
+###############################################################################
+# Finally, we plot the coordinates over a country-level map.
+
+world = gpd.read_file(gpd.datasets.get_path('naturalearth_lowres'))
+
+# We restrict to South America.
+ax = world[world.continent == 'South America'].plot(
+    color='white', edgecolor='black')
+
+# We can now plot our GeoDataFrame.
+gdf.plot(ax=ax, color='red')
+
+plt.show()
+
+###############################################################################
+# From WKT format
+# ===============
+# Here, we consider a ``DataFrame`` having coordinates in WKT format.
+
+df = pd.DataFrame(
+    {'City': ['Buenos Aires', 'Brasilia', 'Santiago', 'Bogota', 'Caracas'],
+     'Country': ['Argentina', 'Brazil', 'Chile', 'Colombia', 'Venezuela'],
+     'Coordinates': ['POINT(-34.58 -58.66)', 'POINT(-15.78 -47.91)',
+                     'POINT(-33.45 -70.66)', 'POINT(4.60 -74.08)',
+                     'POINT(10.48 -66.86)']})
+
+###############################################################################
+# We use ``shapely.wkt`` sub-module to parse wkt format:
+from shapely import wkt
+
+df['Coordinates'] = df['Coordinates'].apply(wkt.loads)
+
+###############################################################################
+#  The ``GeoDataFrame`` is constructed as follows :
+
+gdf = gpd.GeoDataFrame(df, geometry='Coordinates')
+
+print(gdf.head())


Test patch: