GMT.jl translation of the GMT tutorial (session 1)

gmt_tutorial_s1.jl

"""GMT tutorial using GMT.jl

1. In the Julia shell, do `]add GMT`
2. Download GSHHG data: <http://www.soest.hawaii.edu/wessel/gshhg/>
3. Unpack GSHHG data to a predictable directory
4. Create the `.gmt` folder in your HOME directory
5. In the command line shell, run `gmt defaults -Ds > .gmt/gmt.conf`
6. Change the assignment of `DIR_GSHHG` to point to the directory from step 3

"""

"""https://docs.generic-mapping-tools.org/latest/tutorial/session-1.html"""
module Session1

using GMT


"""
    Run GMT tutorial session 1 / # 1

Notes:
- `figsize` can be specified as its own tuple, 
    which can contain either strings or numbers. 
    Numbers specify lengths in PROJ_LENGTH_UNIT units;
    strings allow for any supported units using the default GMT mapping,
    see <https://docs.generic-mapping-tools.org/latest/cookbook/features.html?highlight=units#gmt-units>

"""
function tutorial1()
    basemap(
        region = (10, 70, -3, 8),
        figsize = ("4i", "3i"),
        frame = (annot = :auto, ticks = :auto, fill = :lightred),
        title = "My first plot",
        show = true,
        Vd = 1,
    )

end

"""
    Run GMT tutorial session 1 / # 2

Careful about how you specify the axes,
see <https://github.com/GenericMappingTools/GMT.jl/issues/665>.

Notes:
- `frame` is available for setting overall frame/axis properties
    - `xlabel` and `ylabel` are available for setting the axis labels
    - `axes` is used to specify the axis types, with some caveats,
        see <https://www.generic-mapping-tools.org/GMT.jl/dev/common_opts/#frame>
- `xaxis` and `yaxis` are available for more granular control over individual axes
    - `ticks` sets the axis tick interval, this can have a special meaning for certain plots,
        e.g. [TODO: insert relevant link]
    - `annot` sets the annotation interval;
         default GMT modifiers can be specified if a string value is used,
        see [TODO: insert relevant link]

"""
function tutorial2()
    basemap(
        region = (1, 10000, 1e20, 1e25),
        figsize = ("9il", "6il"),  # No log-log projection yet, see #664.
        frame = (
            axes = (:left_full, :bottom_full),
            xlabel = "Wavelength (m)",
            ylabel = "Power (W)",
        ),
        xaxis = (annot = 2, ticks = :auto),
        yaxis = (annot = "1p", ticks = 3),
        show = true,
        Vd = 1,
    )
end

"""
    Run GMT tutorial session 1 / # 3

Notes
- if `frame` is not set, it defaultts to `(axes = (:left_full, :bottom_full), annot = :auto, ticks = :auto)`
- `proj` is available to set the projection;
    there are convenient symbols to use for most cases,
    see <https://www.generic-mapping-tools.org/GMT.jl/dev/common_opts/#proj>
- `land` is an alias for `-G`; it is available for setting pen/color options

"""
function tutorial3()
    coast(
        region = (-90, -70, 0, 20),
        proj = :Mercator,
        figsize = "6i",
        land = :chocolate,
        show = true,
        Vd = 1,
    )
end

"""
    Run GMT tutorial session 1 / # 4

The GMT -N<n> syntax is for borders, it's well hidden but here you go:
<https://docs.generic-mapping-tools.org/latest/supplements/gshhg/gshhg.html#technical-information>

Notes:
- `shore` is an alias for `-W`; it is available to for setting pen/color options
- `borders` is available to set the `-N` options (see above),
    each border is specified by it's own iterable

"""
function tutorial4()
    coast(
        region = (-130, -70, 24, 52),
        proj = (name = :Albers, center = (-100,  35), parallels = (33, 45)),
        figsize = "6i",
        title = "Conic Projection",
        shore = :thinnest,
        borders = ((type = 1, pen = :thickest), (type = 2, pen = :thinnest)),
        land = :gray,
        show = true,
        Vd = 1,
    )
end

"""
    Run GMT tutorial session 1 / # 5

Notes:
- The `:g` symbol is available to set a global `region` or `frame`
- `area` is available to set the minimum area threshold (`-A`) for map features (km^2),
    see <https://docs.generic-mapping-tools.org/latest/coast.html?highlight=coast#a>
- `ocean` is available for setting pen/color options (`-S`)
- `res` is available for setting the dataset resolution (`-D`)

"""
function tutorial5()
    coast(
        region = :g,  # Would be nice to have :global as an alias here...
        proj = (name = :Orthographic, center = (280, 30)),
        figsize = "6i",
        frame = :g,
        area = 5000,
        res = :crude,
        land = :white,
        ocean = :darkturquoise,
        show = true,
        Vd = 1,
    )
end

"""
    Run GMT tutorial session 1 / # 6

Notes:
- `center` can be a single number, it will be interpreted as a latitude

"""
function tutorial6()
    coast(
        region = :g,
        proj = (name = :EckertVI, center = 180),
        figsize = "9i",
        frame = (axes = :g, annot = :auto),
        area = 5000,
        res = :crude,
        land = :chocolate,
        ocean = :darkturquoise,
        shore = :thinnest,
        show = true,
        Vd = 1,
    )
end

end #Session1