The Karmana.jl plotting API

create_page(paper_size, qr_code_link; landscape = automatic, naxes = 1, supertitle = "Title", description = "...", kwargs...)

Creates a figure of the specified size with the specified arguments, themed for XKDR. Applies the appropriate paper size theme (theme_a4, theme_a3, etc.)

Arguments

• paper_size: A symbol representing the desired paper size; can be :a[0/1/2/3/4]. More planned. In the future, you may also be able to pass a tuple.
• qr_code_link: The contents of the QR code shown at the bottom left of the page. Must be a string.

Keyword arguments

• landscape = automatic: Decides whether the figure should be in landscape or portrait mode. If automatic, decides automatically. To set this manually, set landscape = true or landscape = false.
• naxes = 1: The number of axes to create in the central grid. Automatically laid out.
• axistitles = Makie.automatic: The titles for each axis. If set to automatic, they will be the positions of the axes in the layout.
• hideaxisdecorations = true: Whether to hide the decorations (tick labels, tick marks, etc.) for each axis.
• hideaxisspines = true: Whether to hide the spines (frame lines) for each axis.
• supertitle = "Title": The title of the figure, in the "header" gridlayout.
• description = "Placeholder": The description of the figure, in the "footer" gridlayout (page.description_layout[1, 1]).
• padding: The padding around the figure. If a number, sets all sides to the same value. If a tuple, sets the padding to (left, right, top, bottom).
• axisaspect = DataAspect(): Sets the aspect ratio of the axis. You can set this to nothing if you want the default.

Returns

Returns a NamedTuple containing the following items:

• figure: The Figure in which everything is plotted.
• supertitle: The Label which serves as the figure's title.
• axis_layout: The GridLayout in which the axes are placed.
• axes: A Matrix{Union{Axis, Nothing}} which contains the axes which can be placed. If nrows * ncols > naxes, then the remaining positions will be nothing.
• description_layout: The GridLayout in which the description is placed. Has 3 columns and 1 row. The description label is located in description_layout[1, 1], and [1, 3] is reserved for a box representing the QR code. You can plot a legend or colorbar in description_layout[1, 2].
• description_label: The Label which holds the figure's description.

The items can be extracted from the named tuple using standard getproperty syntax, as in the following example:

page = create_page(:a4, "https://xkdr.org")
page.figure
page.axes[i::Int, j::Int]
page.description_layout
page.description_label
...

indiaoutline!(admin_level::Symbol, ids::Vector, vals::Vector{<: Real}; kw_args...)
indiaoutline!(admin_level::Symbol, dataframe::DataFrame, [id_column::Symbol], value_column::Symbol; kw_args...)

Plots an outline of India, merged with the data passed in. This data must fundamentally have two things: a column of IDs, and a column of values. The IDs must match the IDs in the CPHS database, and the values may be either numbers, or explicit colors.

Arguments

admin_level must be one of :State, :HR, or :District.

ids must be a Vector{Union{Int, Missing}} or a Vector{Int}. It and vals must have the same length.

Attributes

One can set the attributes of the various plot elements by setting the values of the corresponding nested Attributes. These are plot.State, plot.HR, plot.District, and plot.River.

For example, to set the stroke width of districts to 0.25, one would do:

plot.District.strokewidth[] = 0.25

The attributes available for State, HR, and District are those of poly; the attributes available for River are those of lines.

Cropping the map to provided data

If the attribute crop_to_data is true, then this crops the map to the bounding box of the provided IDs only, and does not draw any other states/HRs/districts. Otherwise, all available geometries are drawn, but only the provided IDs are colored by their values; the rest of the geometries remain transparent.

Controlling how the data is merged

You can control the column on which data is merged by setting the merge_column and external_merge_column keyword arguments.

• merge_column specifies the key with which to merge of the provided ids to the CPHS database for that admin level.
• external_merge_column specifies the key with which to merge the provided ids with the lower admin level geometries.

For example, if the provided admin_level is :State, then merge_column will control the key for state_df, and external_merge_column will control the key for hr_df and district_df.

To see all available attributes and their defaults, have a look at the extended help section by running ??indiaoutline! in the REPL.

Extended help

Available attributes, and their values

Available attributes and their defaults for Combined{Karmana.indiaoutline} are:

  District               Attributes with 7 entries:
  label => Districts
  names => false
  nan_color => RGBA{Float32}(0.0,0.0,0.0,0.0)
  strokecolor => RGB{N0f8}(0.549,0.549,0.549)
  strokewidth => 0.2
  visible => true
  zlevel => 98
  HR                     Attributes with 7 entries:
  label => HR regions
  names => false
  nan_color => RGBA{Float32}(0.0,0.0,0.0,0.0)
  strokecolor => RGBA{Float32}(0.901961,0.623529,0.0,1.0)
  strokewidth => 0.2
  visible => true
  zlevel => 99
  Legend                 Attributes with 2 entries:
  draw => true
  polypoints => 1
  River                  Attributes with 5 entries:
  color => RGB{N0f8}(0.678,0.847,0.902)
  label => Rivers
  linewidth => 0.2
  visible => true
  zlevel => 97
  State                  Attributes with 7 entries:
  label => States
  names => false
  nan_color => RGBA{Float32}(0.0,0.0,0.0,0.0)
  strokecolor => RGB{N0f8}(0.0,0.0,0.0)
  strokewidth => 0.2
  visible => true
  zlevel => 101
  colormap               :viridis
  colorrange             MakieCore.Automatic()
  crop_to_data           false
  external_merge_column  MakieCore.Automatic()
  highclip               "nothing"
  lowclip                "nothing"
  merge_column           MakieCore.Automatic()

rgb_to_cmyk_pdf(source_file::AbstractString, dest_file::AbstractString)

Runs Ghostscript on source_file to convert its color schema from RGB to CMYK, and stores the result in dest_file.

This works well when preparing a PDF for printing, since many printer drivers don't perform the conversion as well as Ghostscript does. You might see a green tint on black when printing in color; this ameliorates that to a large degree.

maps_db_connection(user = ENV["MAPS_USER"], password = ENV["MAPS_PASSWORD"])::DBInterface.Connection

Returns a connection to the maps database on data.mayin.org, which must be closed by DBInterface.close!.

merge_polys(polys::AbstractVector{<: Union{Polygon, MultiPolygon}})

Merges a vector of polygons into a single MultiPolygon using ArchGDAL.union.

Returns an ArchGDAL geometry.