.. note:: This tutorial was generated from an IPython notebook that can be
          downloaded `here <../../notebooks/create_own_regions.ipynb>`_.

.. _create_own_regions:



Create your own region
======================



.. note:: In version 0.5 the ``Regions_cls`` has been renamed to ``Regions`` and it's call signature has changed. All arguments (except ``outlines``) are now optional.

Creating own regions is straightforward. Import regionmask and check the
version:

.. code:: python

    import regionmask
    
    regionmask.__version__




.. parsed-literal::

    '0.5.0+dev'



Import numpy

.. code:: python

    import numpy as np

Assume you have two custom regions in the US, you can easily use these
to create ``Regions``:

.. code:: python

    US1 = np.array([[-100.0, 30], [-100, 40], [-120, 35]])
    US2 = np.array([[-100.0, 30], [-80, 30], [-80, 40], [-100, 40]])
    
    regionmask.Regions([US1, US2])




.. parsed-literal::

    <regionmask.Regions>
    Name:     unnamed
    
    Regions:
     0  r0  Region0
     1  r1  Region1
    
    [2 regions]



If you want to set the ``names`` and ``abbrevs`` yourself you can still
do that:

.. code:: python

    names = ["US_west", "US_east"]
    abbrevs = ["USw", "USe"]
    
    USregions = regionmask.Regions([US1, US2], names=names, abbrevs=abbrevs, name="US")
    USregions




.. parsed-literal::

    <regionmask.Regions>
    Name:     US
    
    Regions:
     0  USw  US_west
     1  USe  US_east
    
    [2 regions]



Again we can plot the outline of the defined regions

.. code:: python

    ax = USregions.plot(label="abbrev")
    
    # load cartopy
    import cartopy.crs as ccrs
    
    # fine tune the extent
    ax.set_extent([225, 300, 25, 45], crs=ccrs.PlateCarree())



.. image:: create_own_regions_files/create_own_regions_13_0.png


and obtain a mask:

.. code:: python

    import numpy as np
    
    # define lat/ lon grid
    lon = np.arange(200.5, 330, 1)
    lat = np.arange(74.5, 15, -1)
    
    # for the plotting
    lon_edges = np.arange(200, 331, 1)
    lat_edges = np.arange(75, 14, -1)
    
    mask = USregions.mask(lon, lat)

.. code:: python

    import matplotlib.pyplot as plt
    
    ax = plt.subplot(111, projection=ccrs.PlateCarree())
    
    # pcolormesh does not handle NaNs, requires masked array
    mask_ma = np.ma.masked_invalid(mask)
    
    h = ax.pcolormesh(
        lon_edges, lat_edges, mask_ma, transform=ccrs.PlateCarree(), cmap="viridis",
    )
    
    ax.coastlines()
    
    # add the outlines of the regions
    USregions.plot_regions(ax=ax, add_label=False)
    
    ax.set_extent([225, 300, 25, 45], crs=ccrs.PlateCarree())



.. image:: create_own_regions_files/create_own_regions_16_0.png


Use shapely Polygon
-------------------

If you have the region defined as a shapely polygon, this also works:

.. code:: python

    from shapely.geometry import Polygon, MultiPolygon
    
    US1_poly = Polygon(US1)
    US2_poly = Polygon(US2)
    
    US1_poly, US2_poly




.. parsed-literal::

    (<shapely.geometry.polygon.Polygon at 0x7fe14df48bd0>,
     <shapely.geometry.polygon.Polygon at 0x7fe14f29ed90>)



.. code:: python

    USregions_poly = regionmask.Regions([US1_poly, US2_poly])
    
    USregions_poly




.. parsed-literal::

    <regionmask.Regions>
    Name:     unnamed
    
    Regions:
     0  r0  Region0
     1  r1  Region1
    
    [2 regions]



Create Regions with MultiPolygon and interiors
----------------------------------------------

Create two discontiguous regions and combine them to one. Add a hole to
one of the regions

.. code:: python

    US1_shifted = US1 - (5, 0)
    US2_hole = np.array([[-98.0, 33], [-92, 33], [-92, 37], [-98, 37], [-98.0, 33]])

Create ``Polygons``, a ``MultiPolygon``, and finally ``Regions``

.. code:: python

    US1_poly = Polygon(US1_shifted)
    US2_poly = Polygon(US2, holes=[US2_hole])
    
    US_multipoly = MultiPolygon([US1_poly, US2_poly])
    
    USregions_poly = regionmask.Regions([US_multipoly])

.. code:: python

    USregions_poly.plot()
    
    # polygon interiors are not yet plotted by default
    plt.plot(*US2_hole.T, color="k", transform=ccrs.PlateCarree());



.. image:: create_own_regions_files/create_own_regions_24_0.png


Create a mask:

.. code:: python

    mask = USregions_poly.mask(lon, lat)

and plot it:

.. code:: python

    ax = plt.subplot(111, projection=ccrs.PlateCarree())
    
    mask.plot(transform=ccrs.PlateCarree(), add_colorbar=False)
    
    ax.coastlines();



.. image:: create_own_regions_files/create_own_regions_28_0.png