Fix reference to missing example in FAQ

Solves GitHub issue #592.

Author: molinav

CHANGELOG.md

@@ -24,6 +24,9 @@ https://semver.org/spec/v2.0.0.html
   @YilongWang).
 - Fix `antialiased` argument being ignored in `Basemap.drawcounties` and
   `Basemap.readshapefile` (solves issue [#501], thanks to @TheFizzWare).
+- Fix wrong reference to `ireland.py` example in FAQ, which should be
+  `hires.py` instead, and fix wrong use of locals and invalid syntax
+  in this example (solves issue [#592], thanks to @timcoote).
 
 ## [1.3.8] - 2023-08-18
 
@@ -991,6 +994,8 @@ https://semver.org/spec/v2.0.0.html
 - Fix glitches in drawing of parallels and meridians.
 
 
+[#592]:
+https://github.com/matplotlib/basemap/issues/592
 [#589]:
 https://github.com/matplotlib/basemap/issues/589
 [#583]:

FAQ

@@ -1,33 +1,33 @@
-Q: It takes a long time to make a plot with the 'intermediate' or 'high' 
+Q: It takes a long time to make a plot with the 'intermediate' or 'high'
 resolution coastlines, how can I speed it up?
 
-A: There is a overhead in processing boundary datasets when a Basemap 
-class in created, and this overhead can be significant for the higher 
-resolution boundaries.  If you are makeing many maps for the same region, 
-you only need to create you Basemap class instance once, then re-use it 
-for each plot.  If the plots are being created by different scripts, you 
-can save the Basemap class instance to a Pickle on disk, then read it in 
-whatever script needs it (it's much faster to read a pickle from disk than 
-it is to create the Basemap instance originally). The ireland.py example 
+A: There is a overhead in processing boundary datasets when a Basemap
+class in created, and this overhead can be significant for the higher
+resolution boundaries.  If you are makeing many maps for the same region,
+you only need to create you Basemap class instance once, then re-use it
+for each plot.  If the plots are being created by different scripts, you
+can save the Basemap class instance to a Pickle on disk, then read it in
+whatever script needs it (it's much faster to read a pickle from disk than
+it is to create the Basemap instance originally). The hires.py example
 illustrates how to do this.
 
-Q: I have my own boundary dataset that I would like to use, how do I use 
+Q: I have my own boundary dataset that I would like to use, how do I use
 it in place of (or in addition to) the built-in basemap boundary datasets?
 
-A: If your dataset is in ESRI shapefile format, this is relatively easy. 
-Just create your Basemap class instance, then call the 'readshapefile' 
-method on that instance to import your data.  Setting 'drawbounds=True' 
-will draw the boundaries in the shapefile.  The fillstates.py example 
+A: If your dataset is in ESRI shapefile format, this is relatively easy.
+Just create your Basemap class instance, then call the 'readshapefile'
+method on that instance to import your data.  Setting 'drawbounds=True'
+will draw the boundaries in the shapefile.  The fillstates.py example
 shows how to do this.
 
-Q: How do I specify the map projection region if I don't know what the 
+Q: How do I specify the map projection region if I don't know what the
 latitude and longitudes of the corners are?
 
-A: As an alternative to specifying the lat/lon values for the upper-right 
-and lower-left corners of the projection domain (using the llcrnrlat, 
-llcrnrlon, urcrnrlat and urcrnrlon keywords) you can specify the center of 
-the map projection domain (using the lat_0 and lon_0 keywords) and the 
-width and height of the domain in map projection coordinates (meters) 
-using the width and height keywords.  Basemap will then calculate the 
-corresponging values of llcrnrlat, llcrnrlon, urcrnrlat and urcrnrlon. 
+A: As an alternative to specifying the lat/lon values for the upper-right
+and lower-left corners of the projection domain (using the llcrnrlat,
+llcrnrlon, urcrnrlat and urcrnrlon keywords) you can specify the center of
+the map projection domain (using the lat_0 and lon_0 keywords) and the
+width and height of the domain in map projection coordinates (meters)
+using the width and height keywords.  Basemap will then calculate the
+corresponging values of llcrnrlat, llcrnrlon, urcrnrlat and urcrnrlon.
 Examples of this are given in the garp.py and setwh.py examples.

examples/hires.py

@@ -1,49 +1,51 @@
-from __future__ import (absolute_import, division, print_function)
+from __future__ import print_function
+
+import time
+import pickle
 
-from mpl_toolkits.basemap import Basemap
 import numpy as np
 import matplotlib.pyplot as plt
-import pickle, time
+from mpl_toolkits.basemap import Basemap
+
 
-# create figure with aqua background (will be oceans)
+# Create figure.
 fig = plt.figure()
 
-# create Basemap instance. Use 'high' resolution coastlines.
-t1 = time.clock()
-#m = Basemap(llcrnrlon=-10.5,llcrnrlat=49.5,urcrnrlon=3.5,urcrnrlat=59.5,
-#            resolution='h',projection='tmerc',lon_0=-4,lat_0=0)
-m = Basemap(width=920000,height=1100000,
-            resolution='f',projection='tmerc',lon_0=-4.2,lat_0=54.6)
-# make sure countries and rivers are loaded
-m.drawcountries()
-m.drawrivers()
-print(time.clock()-t1,' secs to create original Basemap instance')
-
-# pickle the class instance.
-pickle.dump(m,open('map.pickle','wb'),-1)
-
-# clear the figure
+# Create Basemap instance:
+# - Use 'full' resolution coastlines.
+# - Make sure that countries and rivers are loaded.
+t0 = time.time()
+bmap1 = Basemap(width=920000, height=1100000, resolution="f",
+                projection="tmerc", lon_0=-4.2, lat_0=54.6)
+bmap1.drawcountries()
+bmap1.drawrivers()
+t1 = time.time()
+print("{0:.3f} secs to plot with a Basemap instance created at runtime".format(t1 - t0))
+
+# Clear the figure.
 plt.clf()
-# read pickle back in and plot it again (should be much faster).
-t1 = time.clock()
-m2 = pickle.load(open('map.pickle','rb'))
-# draw coastlines and fill continents.
-m.drawcoastlines()
-# fill continents and lakes
-m.fillcontinents(color='coral',lake_color='aqua')
-# draw political boundaries.
-m.drawcountries(linewidth=1)
-# fill map projection region light blue (this will
-# paint ocean areas same color as lakes).
-m.drawmapboundary(fill_color='aqua')
-# draw major rivers.
-m.drawrivers(color='b')
-print(time.clock()-t1,' secs to plot using using a pickled Basemap instance')
-# draw parallels
-circles = np.arange(48,65,2).tolist()
-m.drawparallels(circles,labels=[1,1,0,0])
-# draw meridians
-meridians = np.arange(-12,13,2)
-m.drawmeridians(meridians,labels=[0,0,1,1])
-plt.title("High-Res British Isles",y=1.04)
+
+# Pickle the class instance.
+with open("map.pickle", "wb") as fd:
+    pickle.dump(bmap1, fd, protocol=-1)
+
+# Read pickle back in and plot it again (should be much faster):
+# - Draw coastlines and fill continents and lakes.
+# - Draw political boundaries and rivers.
+# - Draw parallels and meridians.
+# - Draw map boundary and fill map background.
+t0 = time.time()
+with open("map.pickle", "rb") as fd:
+    bmap2 = pickle.load(fd)
+bmap2.drawcoastlines()
+bmap2.fillcontinents(color="coral", lake_color="aqua")
+bmap2.drawcountries(linewidth=1)
+bmap2.drawrivers(color="b")
+bmap2.drawparallels(np.arange(48, 65, 2), labels=[1, 1, 0, 0])
+bmap2.drawmeridians(np.arange(-12, 13, 2), labels=[0, 0, 1, 1])
+bmap2.drawmapboundary(fill_color="aqua")
+t1 = time.time()
+print("{0:.3f} secs to plot with a pickled Basemap instance".format(t1 - t0))
+
+plt.title("High-Res British Isles", y=1.04)
 plt.show()