feat: added option to define cities manually in ozcities (#21)

* feat: added option to define cities manually in ozcities

* test: added manual city test

Author: jlerat

hydrodiy/gis/oz.py

@@ -159,7 +159,8 @@ def plotit(x, y, recs):
     return lines
 
 
-def ozcities(ax, filter_regex=None, \
+def ozcities(ax, cities=None, \
+                filter_regex=None, \
                 fixed_lim=True, plot_kwargs={}, \
                 text_kwargs={}, proj=None):
     """ plot Australian capital cities.
@@ -168,10 +169,33 @@ def ozcities(ax, filter_regex=None, \
     -----------
     ax : matplotlib.axes
         Axe to draw data on
-       Shapefile field to filter on.
+        Shapefile field to filter on.
+    cities : dict
+        Dictionnary containing cities and their coordinates:
+        { city_name: [x, y] }
     fiter_regex : str
-        Regular expression to filter cities.
+        Regular expression to filter city name.
+    plot_kwargs : dict
+        Argument passed to plot the point representing a city.
+    text_kwargs : dict
+        Argument passed to write the city name.
+        This can be used to adjust label placement. For example,
+        the following can be used to add shadow (path effect) and
+        offset the labels:
+
+        text_kwargs = dict(
+            path_effects=[pe.withStroke(linewidth=3, foreground="w")], \
+            textcoords="offset pixels",\
+            fontsize=12, \
+            xytext=(20, 8)
+        )
+    proj : pyproj.CRS
+        Projec coordinates.
+
     """
+    if cities is None:
+        cities = CAPITAL_CITIES
+
     # Plot options
     plot_kwargs["marker"] = plot_kwargs.get("marker", "s")
     plot_kwargs["mfc"] = plot_kwargs.get("mfc", "tab:orange")
@@ -187,7 +211,7 @@ def ozcities(ax, filter_regex=None, \
     xlim, ylim = ax.get_xlim(), ax.get_ylim()
 
     elements = {}
-    for icity, (city, xy) in enumerate(CAPITAL_CITIES.items()):
+    for icity, (city, xy) in enumerate(cities.items()):
         # Skip if filtered
         if not filter_regex is None:
             if not re.search(filter_regex, city):

hydrodiy/gis/tests/test_hygis_oz.py

@@ -2,7 +2,7 @@
 from pathlib import Path
 import pytest
 
-from hydrodiy.gis.oz import REGIONS, HAS_PYSHP, ozlayer, ozcities
+from hydrodiy.gis.oz import REGIONS, HAS_PYSHP, ozlayer, ozcities, CAPITAL_CITIES
 from hydrodiy.plot import putils
 
 import numpy as np
@@ -80,7 +80,7 @@ def test_ozlayer_proj():
     plt.savefig(fp)
 
 
-def test_ozcities():
+def test_ozcities_kw():
     """ Test plotting oz cities """
     plt.close("all")
     fig, ax = plt.subplots()
@@ -141,6 +141,39 @@ def test_ozcities_proj():
     plt.savefig(fp)
 
 
+def test_ozcities_manual():
+    """ Test plotting oz cities using filter """
+    plt.close("all")
+    fig, ax = plt.subplots()
+    lines = ozlayer(ax, "ozcoast50m",  \
+                color="k", lw=0.5, fixed_lim=False)
+
+    cities = dict(
+        Sydney=[-33.86785, 151.20732], \
+        Melbourne=[	-37.814, 144.96332], \
+        Brisbane=[-27.46794, 153.02809], \
+        Perth=[-31.95224, 115.8614], \
+        Adelaide=[-34.92866, 138.59863], \
+        Canberra=[-35.28346, 149.12807], \
+        Newcastle=[-32.92953, 151.7801], \
+        Wollongong=[-34.424, 150.89345], \
+        Geelong=[-38.14711, 144.36069], \
+        Hobart=[-42.87936, 147.32941], \
+        Townsville=[-19.26639, 146.80569], \
+        Cairns=[-16.92366, 145.76613], \
+        Ballarat=[-37.56622, 143.84957], \
+        Toowoomba=[-27.56056, 151.95386], \
+        Darwin=[-12.46113, 130.84185], \
+        Mandurah=[-32.5269, 115.7217], \
+        Mackay=[-21.15345, 149.16554], \
+        Bundaberg=[-24.86621, 152.3479]
+    )
+    c = {n: (cc[1], cc[0]) for n, cc in cities.items()}
+    elems = ozcities(ax, cities=c)
+
+    fp = FIMG / "ozcities_manual.png"
+    plt.savefig(fp)
+