Comm

Author: joa-quim

documentation/all_docs_ref/all_refs.md

@@ -65,11 +65,11 @@ its use requires resorting to the \myreflink{Monolithic} mode.
 | \myreflink{cubeplot} | \myreflink{coastlinesproj} | \myreflink{cubeslice} | \myreflink{date2doy} | \myreflink{delrows!} | \myreflink{doy2date} | \myreflink{findpeaks} | \myreflink{gadm} |
 | \myreflink{geocoder} | \myreflink{geodetic2enu} | \myreflink{getbyattrib} | \myreflink{gmtread} | \myreflink{gmtwrite} | \myreflink{graticules} | \myreflink{gridit} | \myreflink{gunique} |
 | \myreflink{hampel} | \myreflink{imagesc} | \myreflink{inpolygon} | \myreflink{inwhichpolygon} | \myreflink{image_alpha!} | \myreflink{image_cpt!} | \myreflink{imshow} | \myreflink{ind2rgb} |
-| \myreflink{info} | \myreflink{isnodata} | \myreflink{isoutlier} | \myreflink{lazread} | \myreflink{lazwrite} | \myreflink{lelandshade} | \myreflink{linearfitxy} | \myreflink{magic} |
-| \myreflink{mat2ds} | \myreflink{mat2grid} | \myreflink{mat2img} | \myreflink{mosaic} | \myreflink{ODE2ds} | \myreflink{orbits} | \myreflink{pca} | \myreflink{plotgrid!} |
-| \myreflink{plotyy} | \myreflink{pol2cart} | \myreflink{polygonlevels} | \myreflink{rasterzones!} | \myreflink{regiongeog} | \myreflink{remotegrid} | \myreflink{rescale} | \myreflink{slicecube} |
-| \myreflink{sph2cart} | \myreflink{stackgrids} | \myreflink{ter2cart} | \myreflink{theme} | \myreflink{uniqueind} | \myreflink{vecangles} | \myreflink{whereami} | \myreflink{worldrectgrid} |
-| \myreflink{worldrectcoast} | \myreflink{worldrectangular} | \myreflink{xyzw2cube} | \myreflink{yeardecimal} | \myreflink{zonal_stats} |  |  |  |
+| \myreflink{info} | \myreflink{isnodata} | \myreflink{isoutlier} | \myreflink{lazread} | \myreflink{lazwrite} | \myreflink{leepacific} | \myreflink{lelandshade} | \myreflink{linearfitxy} |
+| \myreflink{magic} | \myreflink{mat2ds} | \myreflink{mat2grid} | \myreflink{mat2img} | \myreflink{mosaic} | \myreflink{ODE2ds} | \myreflink{orbits} | \myreflink{pca} |
+| \myreflink{plotgrid!} | \myreflink{plotyy} | \myreflink{pol2cart} | \myreflink{polygonlevels} | \myreflink{rasterzones!} | \myreflink{regiongeog} | \myreflink{remotegrid} | \myreflink{rescale} |
+| \myreflink{slicecube} | \myreflink{sph2cart} | \myreflink{stackgrids} | \myreflink{ter2cart} | \myreflink{theme} | \myreflink{uniqueind} | \myreflink{vecangles} | \myreflink{whereami} |
+| \myreflink{worldrectgrid} | \myreflink{worldrectcoast} | \myreflink{worldrectangular} | \myreflink{xyzw2cube} | \myreflink{yeardecimal} | \myreflink{zonal_stats} |  |  |
 
 ## Solids functions
 

documentation/modules/coast.md

@@ -41,8 +41,31 @@ painted and no land fill is set then the land-areas will be transparent. A map p
    The resolution drops off by 80% between data sets. The default is **res=:auto**, which chooses
    to automatically select the best resolution given the chosen map scale.
 
-- **E** or **DCW** : -- *DCW=code1,code2,...* **|** *DCW=(country=code, continent=code, pen=pen, fill=fill, file=fname, inside=true, outside=false, adjust_r=??, , adjust_R=??, , adjust_e=??, headers=false)*\
-   Select painting country polygons from the Digital Chart of the World. This is another dataset independent of GSHHG and hence the **area** and **resolution** options do not apply. **DCW="+l"** just list the countries and their codes [plotting takes place] and **DCW="+L"** shows states/territories for Argentina, Australia, Brazil, Canada, and the US. *country* or **name=code(s)**, where **code(s)** is a one or more comma-separated countries using the 2-character ISO 3166-1 alpha-2 convention. To select a state of a country (if available), append .state, e.g, US.TX for Texas. To specify a whole continent, use **continent=code**, with continent codes AF (Africa),AN (Antarctica), AS (Asia), EU (Europe), OC (Oceania), NA (North America), or SA (South America). Use **pen=pen** (see \myreflink{Pen attributes}) to draw polygon outlines and **fill=fill** (see \myreflink{Fill color/pattern}) to fill them [default is no fill]. At least one of these must be specified unless **dump** is in effect, in which case only one **DCW** option can be given. It is also possible to specify the parameters using simple Tuples. For example: **DCW=("PT", (0.5,"red","--"), "blue")** plots the polygon *PT* with a 0.5p red dashed line and filled with blue and **DCW=:PT** uses a default pen of 0.5. **DCW=(:PT, :blue)** fills with blue. You may repeat **DCW** to give different groups of items their own *pen/fill* settings. However, since we cannot repeat a keyword, the solution to setting different groupes is to use a tuple of tuples. An example would be *DCW=((country=:PT, pen=(2,:red), fill=:blue), (country=:ES, pen=(2,:blue)) )*. If neither **proj** nor **dump** are set then we just print the **region**. The **file=fname** is a option to let users select alternative DCW files. Available options by default are: *ODS*, *NE10m* or *NE110m*. For example: `DCW=(country=:CH, file=:ODS)` extracts the Swiss polygon from (small) `ODS.nc` file. The **inside=true** (the default) means that data is ket _inside_ the clipping polygon. Use **outside=true** if want the reverse. **adjust_r=??** adjusts the region boundaries to be multiples of the steps indicated by _inc_ or _xinc/yinc_ or _winc/einc/sinc/ninc_. **adjust_R=??** adjusts the region boundaries adding the amounts specified by _inc_ or _xinc/yinc_ or _winc/einc/sinc/ninc_. **headers=true** place the country code in the segment headers via _-Zcode_ settings (for use with the **dump** option). 
+- **E** or **DCW** : -- *DCW=code1,code2,...* **|** *DCW=(country=code, continent=code, states=code, pen=pen, fill=fill, file=fname, inside=true, outside=false, adjust_r=??, , adjust_R=??, , adjust_e=??, headers=false)*\
+   Select painting country polygons from the Digital Chart of the World. This is another dataset independent
+   of GSHHG and hence the **area** and **resolution** options do not apply. **DCW="+l"** just list the countries
+   and their codes [plotting takes place] and **DCW="+L"** shows states/territories for Argentina (AR), Australia (AU),
+   Brazil (BR), Canada (CA), China (CN), Great Britan (GB), India (IR), Russia (RU), and the US (US).
+   *country* or **name=code(s)**, where **code(s)** is a one or more comma-separated countries using the 2-character
+   ISO 3166-1 alpha-2 convention. To select a state of a country (if available), append .state, e.g, US.TX for Texas.
+   To get all states in a country, use **states=code** or `DCW=+code` (only available for AR, AU, BR, CA, CN, GB, IN,
+   NO, RU, and US).  To specify a whole continent, use **continent=code**,
+   with continent codes AF (Africa), AN (Antarctica), AS (Asia), EU (Europe), OC (Oceania), NA (North America),
+   or SA (South America). Use **pen=pen** (see \myreflink{Pen attributes}) to draw polygon outlines and **fill=fill**
+   (see \myreflink{Fill color/pattern}) to fill them [default is no fill]. At least one of these must be specified
+   unless **dump** is in effect, in which case only one **DCW** option can be given. It is also possible to specify
+   the parameters using simple Tuples. For example: **DCW=("PT", (0.5,"red","--"), "blue")** plots the polygon *PT*
+   with a 0.5p red dashed line and filled with blue and **DCW=:PT** uses a default pen of 0.5. **DCW=(:PT, :blue)**
+   fills with blue. You may repeat **DCW** to give different groups of items their own *pen/fill* settings. However,
+   since we cannot repeat a keyword, the solution to setting different groupes is to use a tuple of tuples. An example
+   would be *DCW=((country=:PT, pen=(2,:red), fill=:blue), (country=:ES, pen=(2,:blue)) )*. If neither **proj** nor
+   **dump** are set then we just print the **region**. The **file=fname** is a option to let users select alternative
+   DCW files. Available options by default are: *ODS*, *NE10m* or *NE110m*. For example: `DCW=(country=:CH, file=:ODS)`
+   extracts the Swiss polygon from (small) `ODS.nc` file. The **inside=true** (the default) means that data is kept
+   _inside_ the clipping polygon. Use **outside=true** if want the reverse. **adjust_r=??** adjusts the region boundaries
+   to be multiples of the steps indicated by _inc_ or _xinc/yinc_ or _winc/einc/sinc/ninc_. **adjust_R=??** adjusts
+   the region boundaries adding the amounts specified by _inc_ or _xinc/yinc_ or _winc/einc/sinc/ninc_. **headers=true**
+   place the country code in the segment headers via _-Zcode_ settings (for use with the **dump** option). 
 
 - **getR** or **getregion** or **get_region** : -- *getR=code1,code2,...*\
    Return the region corresponding to the code/list-of-codes passed in as argument. The code(s) are the same

documentation/utilities/coastlinesproj.md

@@ -1,7 +1,7 @@
 # coastlinesproj
 
 ```julia
-cl = coastlinesproj(proj="?", res="crude", coastlines=nothing)
+cl = coastlinesproj(proj="?", res="crude", coastlines=nothing, limits=Float64[])
 ```
 
 Extract the coastlines from GMT's GSHHG database and project them using PROJ (NOT the GMT projection machinery).
@@ -21,7 +21,7 @@ This allows the use of many of the PROJ projections that are not available from
 Returns
 -------
 
-A Vector of \myreflink{GMTdataset} containing the projected (or not) world GSHHG coastlines at resolution `res`.
+A Vector of \myreflink{GMTdataset} containing the projected world GSHHG coastlines at resolution `res`.
 
 
 Example

documentation/utilities/getbyattrib.md

@@ -23,9 +23,16 @@ NOTE: Instead of ``getbyattrib`` one can use instead ``filter`` (..., `index=fal
   means select all elements from ``Antioquia`` and ``Caldas`` that have the attribute `feature_id` = 0.
 
   A second set of attributes can be used to select elements by region, number of polygon vertices and area.
-  For that, name the keyword with a leading underscore, e.g. `_region`, `_nps`, `_area`. Their values are
+  For that, name the keyword with a leading underscore, e.g. `_region`, `_nps`, `_area`, `_unique`. Their values are
   passed respectively a 4 elements tuple and numbers. E.g. `_region=(-8.0, -7.0, 37.0, 38.0)`, `_nps=100`, `_area=10`.
-  Areas are in square km when input is in geographic coordinates, otherwise squre data unites.
+  Areas are in square km when input is in geographic coordinates, otherwise squre data unites. The `_unique` case is
+  a bit special and is meant to be used when more than one polygon share the same attribute value (_e.g._ countries with islands).
+  In that case, set the value of `_unique` to the name of the attribute that is shared by the polygons (_e.g._ `_unique="NAME"`).
+  By default (_e.g._ `_unique=true`), the attribute name is `Feature_ID` which is the one used by GMT when creating unique
+  IDs for polygons read from OGR formats (.shp, .geojson, etc). If this attrib name is not found, we search for `CODE` which is
+  the one assigned by GMT when extracting polygons from the internal GMT coasts database. If none of these is found,
+  it is users responsibility to provide a valid attribute name. The uniqueness is determined by selecting the polygon
+  with the largest area.
 
 - `attrib` or `att`: (OLD SYNTAX) A NamedTuple with the attribname, attribvalue as in `att=(NAME_2="value",)`.
   Use more elements if wishing to do a composite match. E.g. `att=(NAME_1="val1", NAME_2="val2")` in which

documentation/utilities/polygonlevels.md

@@ -8,8 +8,7 @@ or
 zvals = polygonlevels(D::GDtype, idvals::GMTdataset; kw...) -> Vector{Float64}
 ```
 
-Creates a vector with `zvals` to use in `plot` and where length(zvals) == length(D)
-The elements of `zvals` are made up from the `vals`.
+Creates a vector with `zvals` to use in `plot` when creating choropleth maps and where length(zvals) == length(D).
 
 - `ids`: is a string Vector or Matrix with the ids (attribute names) of the \myreflink{GMTdataset} D.
          If a Matrix (2 columns only) then the `att` bellow must also have the two names (string vector
@@ -27,6 +26,10 @@ The elements of `zvals` are made up from the `vals`.
 - `nocase` or `insensitive`: a keyword from `kw`. Perform a case insensitive comparision between the contents of
          `ids` and the attribute specified with `attrib`. Default compares as case sensistive.
 
+- `starts,ends,contains`: Sometimes the attribute value is only part of the string in `ids`.
+			Use one of these options to specify how to match. E.g. `ends=true` selects all attributes
+			that ends with a match in `ids`. Default is the exact match.
+
 - `repeat`: keyword to replicate the previously known value until it finds a new segment ID for the case
             when a polygon have no attributes (may happen for the islands in a country).
 

documentation/utilities/worldrectangular.md

@@ -1,7 +1,7 @@
 # worldrectangular
 
 ```julia
-GI[,coast] = worldrectangular(GI; proj::String="+proj=vandg", pm=0, latlim=:auto, coast=false)
+GI[,coast] = worldrectangular(fname::String|GI::GItype; proj::String="+proj=vandg", pm=0, latlim=:auto, coast=false)
 ```
 
 Try to create a rectangular map out miscellaneous and not cylindrical projections. We say *try* because
@@ -45,5 +45,5 @@ viz(G)
 See Also
 --------
 
-\myreflink{coastlinesproj}, \myreflink{graticules}, \myreflink{plotgrid!}, \myreflink{worldrectgrid}, \myreflink{worldrectcoast},
+\myreflink{coastlinesproj}, \myreflink{graticules}, \myreflink{leepacific}, \myreflink{plotgrid!}, \myreflink{worldrectgrid}, \myreflink{worldrectcoast},
 \myreflink{Best rectangular world map projection}

tutorials/choropleths/choropleths.md

@@ -2,9 +2,10 @@
 
 ### What color is your State?
 
-This example shows an adaptation of the [Average color of World](https://erdavis.com/2021/06/26/average-colors-of-the-world/) examples.
-It differs slightly for the also shown US case likely due to the different data used. Here we retrieve
-the image data (Sentinel 2) from the [EOX WMS server](https://eox.at/) and use the year 2020.
+This example shows an adaptation of the [Average color of World](https://erdavis.com/2021/06/26/average-colors-of-the-world/)
+examples. It differs slightly for the also shown US case likely due to the different data used. Here we retrieve
+the image data (Sentinel 2) from the [EOX WMS server](https://eox.at/) and use the year 2020. And, as a side note, realize
+how incredibly simpler this example is as comparing to the codes used to generate the figures in that blog.
 
 Note how the sates polygons are read directly from source, without any previous download, uncompressing file format conversions, etc...
 We will also filter the states polygons to use only those inside the US continental zone and limit them by number
@@ -82,3 +83,64 @@ viz(D, region=(-125,-66,24,50), level=zvals, cmap=C, proj=:guess,
     plot=(data=D,lw=0), title="Population (Millions)", colorbar=true)
 ```
 \end{examplefig}
+
+### Choropleths by symbol color
+
+To avoid the perceptual problem of over-enphasize the polygon's are we can alternatively use colored
+symbols (or symbols of different sizes). That can be done with the `bubblechart` program. One issue,
+though, that we have to deal in this case is that a state can have multiple polygons (for example
+Hawaii has many islands, and Michigan has two main landmasses). So, we need to calculate the largest
+polygon of each state and its centroid to place the symbol there.
+
+\begin{examplefig}{}
+```julia
+using GMT   # Hide
+D = gmtread("/vsizip//vsicurl/https://www2.census.gov/geo/tiger/GENZ2024/shp/cb_2024_us_state_500k.zip");  # Hide
+
+Df = filter(D, _region=(-125,-66,24,50), _unique=true);  # Keep only the largest polygon per state
+
+pop = gmtread(TESTSDIR * "assets/uspop.csv");
+zvals = polygonlevels(Df, pop, att="NAME") / 1e6;
+C = makecpt(zvals, auto=:r, reverse =true, cmap=:bamako);
+
+bubblechart(Df, labels="attrib=STUSPS", proj=:guess, zcolor=zvals,
+            cmap=C, colorbar=true, show=true)
+```
+\end{examplefig}
+
+
+In all the examples above we have used the US states polygons from a downloaded file, but we actually no not
+need that as the internal GMT coasts database has the US states polygons. So, we can use the `coast` function
+to get extract the states polygons and use them in the same way as above. Here is an example that would
+produce the exactly same image. But note how attribute names are different now as state names are stored
+under the "CODE" attribute.
+
+```julia
+using GMT   # Hide
+
+D = coast(DCW=(states="US",))   # Or simply D = coast(DCW="+US");
+Df = filter(D, _region=(-125,-66,24,50), _unique=true);
+
+pop = gmtread(TESTSDIR * "assets/uspop.csv");
+zvals = polygonlevels(Df, pop, att="NAME", contains=true) / 1e6;
+C = makecpt(zvals, auto=:r, reverse =true, cmap=:bamako);
+
+bubblechart(Df, labels="attrib=CODE", proj=:guess, zcolor=zvals,
+            cmap=C, colorbar=true, show=true)
+```
+
+Note the `contains=true` option in the `polygonlevels` function call. That is needed because the state
+names in the `Df` dataset are like "Alabama (United States)" while in the `pop` table they are simply
+"Alabama".  So, to do the joining operation, we had to be more relaxed and not impose an quality comparions
+(like the cases above) but to satisfy that the name in `pop` is contained in the name in `Df`.
+
+```
+Df
+
+Attribute table
+┌─────┬──────┬──────────────────────────────────────┐
+│ Row │ CODE │ NAME                                 │
+├─────┼──────┼──────────────────────────────────────┤
+│   1 │ AL   │ Alabama (United States)              │
+│   2 │ AR   │ Arkansas (United States)             │
+```