Remove clip

CHANGELOG.md

@@ -6,10 +6,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+* Deprecate clip function from earthpy given it's moved to geopandas now (@nkorinek, #510)
 * Fix clip vignette. Cant plot w empty geoms (@lwasser, #475)
 
 ## [0.8]
-* JOSS paper and pyopensci review completed release! 
+* JOSS paper and pyopensci review completed release!
 
 ## [0.7.6]
 * no significant changes but pyopensci approval and badge added.

CONTRIBUTING.rst

@@ -290,5 +290,5 @@ copies of that data object are required by multiple tests, we can use
 create and tear down those objects independently for each test.
 See `earthpy/tests/conftest.py <https://github.com/earthlab/earthpy/blob/master/earthpy/tests/conftest.py>`_
 for fixture definitions, and
-`earthpy/tests/test_clip.py <https://github.com/earthlab/earthpy/blob/master/earthpy/tests/test_crop_image.py>`_
+`earthpy/tests/test_crop_image.py <https://github.com/earthlab/earthpy/blob/master/earthpy/tests/test_crop_image.py>`_
 for example usage of fixtures in tests.

README.md

@@ -30,7 +30,6 @@ code needed to:
 * [Create discrete (categorical) legends](https://earthpy.readthedocs.io/en/latest/gallery_vignettes/plot_draw_legend_docs.html)
 * [Calculate vegetation indices such as Normalized Difference Vegetation Index (`normalized_diff()`)](https://earthpy.readthedocs.io/en/latest/gallery_vignettes/plot_calculate_classify_ndvi.html)
 * [Create hillshade from a DEM](https://earthpy.readthedocs.io/en/latest/gallery_vignettes/plot_dem_hillshade.html)
-* [Clip point, line, and polygon geometries](https://earthpy.readthedocs.io/en/latest/gallery_vignettes/plot_clip.html)
 
 EarthPy also has an `io` module that allows users to
 
@@ -69,8 +68,8 @@ $ conda install earthpy
 
 ### Install via Pip
 
-EarthPy uses the rtree package for some of its operations which depends upon `libspatialindex`. This package can be
-challenging to install using pip whereas it will automagically be installed if you use conda.
+We strongly suggest that you install EarthPy using conda-forge given pip can be more prone to 
+spatial library dependency conflicts. However, you can install earthpy using pip.
 
 To install EarthPy via `pip` use:
 

dev-requirements.txt

@@ -1,14 +1,14 @@
-codecov==2.0.15
+codecov==2.0.22
 bumpversion==0.5.3
 pre-commit==1.21.0
 m2r==0.2.1
 importlib-metadata==1.3.0
-pytest==5.3.5
+pytest==5.4.1
 pytest-vcr==1.0.2
 pytest-cov==2.7.1
 sphinx==2.4.0
 sphinx-autobuild==0.7.1
 sphinx_gallery==0.5.0
 sphinx_rtd_theme==0.4.3
-tox==3.14.2
+tox==3.14.6
 pip>=19.0

docs/api/earthpy.rst

@@ -11,7 +11,6 @@ Submodules
 
 .. toctree::
 
-   earthpy.clip
    earthpy.io
    earthpy.mask
    earthpy.plot

docs/get-started.rst

@@ -8,11 +8,10 @@ Earth Lab earth analytics courses and any user with a url and a zip file.
 EarthPy Module and Function Documentation
 -----------------------------------------
 
-All functions are included in the 5 earthpy modules:
+All functions are included in the 4 earthpy modules:
 
 - spatial
 - plot
-- clip
 - mask
 - io
 
@@ -42,7 +41,6 @@ You can also chose to import any of the individual modules as follows:
 
     >>> import earthpy.spatial as es
     >>> import earthpy.plot as ep
-    >>> import earthpy.clip as ec
     >>> import earthpy.mask as em
 
 Data

earthpy/clip.py

@@ -10,220 +10,66 @@
 import geopandas as gpd
 
 
+# @deprecate
 def _clip_points(shp, clip_obj):
-    """Clip point geometry to the clip_obj GeoDataFrame extent.
+    """This function has been deprecated from earthpy.
 
-    Clip an input point GeoDataFrame to the polygon extent of the clip_obj
-    parameter. Points that intersect the clip_obj geometry are extracted with
-    associated attributes and returned.
-
-    Parameters
-    ----------
-    shp : GeoDataFrame
-        Composed of point geometry that is clipped to clip_obj.
-
-    clip_obj : GeoDataFrame
-        Reference polygon for clipping.
-
-    Returns
-    -------
-    GeoDataFrame
-        The returned GeoDataFrame is a subset of shp that intersects
-        with clip_obj.
+    Please use the _clip_points() function in GeoPandas instead.
     """
-    poly = clip_obj.geometry.unary_union
-    return shp[shp.geometry.intersects(poly)]
+    raise Warning(
+        "_clip_points is deprecated. Use the _clip_points() function in "
+        "GeoPandas. Exiting..."
+    )
+    sys.exit()
 
 
+# @deprecate
 def _clip_multi_point(shp, clip_obj):
-    """Clip multi point features to the clip_obj GeoDataFrame extent.
-
-    Clip an input multi point to the polygon extent of the clip_obj
-    parameter. Points that intersect the clip_obj geometry are
-    extracted with associated attributes returned.
-
-    Parameters
-    ----------
-    shp : GeoDataFrame
-        multipoint geometry that is clipped to clip_obj.
-
-    clip_obj : GeoDataFrame
-        Reference polygon for clipping.
+    """This function has been deprecated from earthpy.
 
-    Returns
-    -------
-    GeoDataFrame
-        The returned GeoDataFrame is a clipped subset of shp
-        containing multi-point and point features.
+    Please use the _clip_points() function in GeoPandas instead.
     """
-
-    # Explode multi-point features when clipping then recreate geom
-    clipped = _clip_points(shp.explode().reset_index(level=[1]), clip_obj)
-    clipped = clipped.dissolve(by=[clipped.index]).drop(columns="level_1")[
-        shp.columns.tolist()
-    ]
-
-    return clipped
+    raise Warning(
+        "_clip_multi_point is deprecated. Use the _clip_points() function in "
+        "GeoPandas. Exiting..."
+    )
+    sys.exit()
 
 
+# @deprecate
 def _clip_line_poly(shp, clip_obj):
-    """Clip line and polygon geometry to the clip_obj GeoDataFrame extent.
-
-    Clip an input line or polygon to the polygon extent of the clip_obj
-    parameter. Lines or Polygons that intersect the clip_obj geometry are
-    extracted with associated attributes and returned.
-
-    Parameters
-    ----------
-    shp : GeoDataFrame
-        Line or polygon geometry that is clipped to clip_obj.
-
-    clip_obj : GeoDataFrame
-        Reference polygon for clipping.
+    """This function has been deprecated from earthpy.
 
-    Returns
-    -------
-    GeoDataFrame
-        The returned GeoDataFrame is a clipped subset of shp
-        that intersects with clip_obj.
+    Please use the _clip_line_poly() function in GeoPandas instead.
     """
-    # Create a single polygon object for clipping
-    poly = clip_obj.geometry.unary_union
-    spatial_index = shp.sindex
-
-    # Create a box for the initial intersection
-    bbox = poly.bounds
-    # Get a list of id's for each object that overlaps the bounding box and
-    # subset the data to just those lines
-    sidx = list(spatial_index.intersection(bbox))
-    shp_sub = shp.iloc[sidx]
-
-    # Clip the data - with these data
-    clipped = shp_sub.copy()
-    clipped["geometry"] = shp_sub.intersection(poly)
-
-    # Return the clipped layer with no null geometry values
-    return clipped[clipped.geometry.notnull()]
+    raise Warning(
+        "_clip_line_poly is deprecated. Use the _clip_line_poly() function in "
+        "GeoPandas. Exiting..."
+    )
+    sys.exit()
 
 
+# @deprecate
 def _clip_multi_poly_line(shp, clip_obj):
-    """Clip multi lines and polygons to the clip_obj GeoDataFrame extent.
-
-    Clip an input multi line or polygon to the polygon extent of the clip_obj
-    parameter. Lines or Polygons that intersect the clip_obj geometry are
-    extracted with associated attributes and returned.
-
-    Parameters
-    ----------
-    shp : GeoDataFrame
-        multiLine or multipolygon geometry that is clipped to clip_obj.
-
-    clip_obj : GeoDataFrame
-        Reference polygon for clipping.
+    """This function has been deprecated from earthpy.
 
-    Returns
-    -------
-    GeoDataFrame
-        The returned GeoDataFrame is a clipped subset of shp
-        that intersects with clip_obj.
+    Please use the _clip_line_poly() function in GeoPandas instead.
     """
-
-    # Clip multi polygons
-    clipped = _clip_line_poly(shp.explode().reset_index(level=[1]), clip_obj)
-
-    lines = clipped[
-        (clipped.geometry.type == "MultiLineString")
-        | (clipped.geometry.type == "LineString")
-    ]
-    line_diss = lines.dissolve(by=[lines.index]).drop(columns="level_1")
-
-    polys = clipped[clipped.geometry.type == "Polygon"]
-    poly_diss = polys.dissolve(by=[polys.index]).drop(columns="level_1")
-
-    return gpd.GeoDataFrame(
-        pd.concat([poly_diss, line_diss], ignore_index=True)
+    raise Warning(
+        "_clip_multi_poly_line is deprecated. Use the _clip_line_poly() "
+        "function in GeoPandas. Exiting..."
     )
+    sys.exit()
 
 
+# @deprecate
 def clip_shp(shp, clip_obj):
-    """Clip points, lines, or polygon geometries to the clip_obj extent.
-
-    Both layers must be in the same Coordinate Reference System (CRS) and will
-    be clipped to the full extent of the clip object.
-
-    If there are multiple polygons in clip_obj,
-    data from shp will be clipped to the total boundary of
-    all polygons in clip_obj.
-
-    Parameters
-    ----------
-    shp : GeoDataFrame
-          Vector layer (point, line, polygon) to be clipped to clip_obj.
-    clip_obj : GeoDataFrame
-          Polygon vector layer used to clip shp.
-          The clip_obj's geometry is dissolved into one geometric feature
-          and intersected with shp.
-
-    Returns
-    -------
-    GeoDataFrame
-         Vector data (points, lines, polygons) from shp clipped to
-         polygon boundary from clip_obj.
-
-    Examples
-    --------
-    Clipping points (glacier locations in the state of Colorado) with
-    a polygon (the boundary of Rocky Mountain National Park):
-
-        >>> import geopandas as gpd
-        >>> import earthpy.clip as cl
-        >>> from earthpy.io import path_to_example
-        >>> rmnp = gpd.read_file(path_to_example('rmnp.shp'))
-        >>> glaciers = gpd.read_file(path_to_example('colorado-glaciers.geojson'))
-        >>> glaciers.shape
-        (134, 2)
-        >>> rmnp_glaciers = cl.clip_shp(glaciers, rmnp)
-        >>> rmnp_glaciers.shape
-        (36, 2)
-
-    Clipping a line (the Continental Divide Trail) with a
-    polygon (the boundary of Rocky Mountain National Park):
-
-        >>> cdt = gpd.read_file(path_to_example('continental-div-trail.geojson'))
-        >>> rmnp_cdt_section = cl.clip_shp(cdt, rmnp)
-        >>> cdt['geometry'].length > rmnp_cdt_section['geometry'].length
-        0    True
-        dtype: bool
-
-    Clipping a polygon (Colorado counties) with another polygon
-    (the boundary of Rocky Mountain National Park):
-
-        >>> counties = gpd.read_file(path_to_example('colorado-counties.geojson'))
-        >>> counties.shape
-        (64, 13)
-        >>> rmnp_counties = cl.clip_shp(counties, rmnp)
-        >>> rmnp_counties.shape
-        (4, 13)
+    """This function has been deprecated from earthpy.
+
+    Please use the clip() function in GeoPandas instead.
     """
-    try:
-        shp.geometry
-        clip_obj.geometry
-    except AttributeError:
-        raise AttributeError(
-            "Please make sure that your input and clip GeoDataFrames have a"
-            " valid geometry column"
-        )
-
-    if not any(shp.intersects(clip_obj.unary_union)):
-        raise ValueError("Shape and crop extent do not overlap.")
-
-    if any(shp.geometry.type == "MultiPoint"):
-        return _clip_multi_point(shp, clip_obj)
-    elif any(shp.geometry.type == "Point"):
-        return _clip_points(shp, clip_obj)
-    elif any(shp.geometry.type == "MultiPolygon") or any(
-        shp.geometry.type == "MultiLineString"
-    ):
-        return _clip_multi_poly_line(shp, clip_obj)
-    else:
-        return _clip_line_poly(shp, clip_obj)
+    raise Warning(
+        "clip_shp is deprecated. Use the clip() function in "
+        "GeoPandas. Exiting..."
+    )
+    sys.exit()