GitHub

Public Documentation

Documentation for MakieMaestro's public interface.

Contents

Exporting

MakieMaestro.savefig — Function
savefig(fig, [path], [size]; <keyword arguments>)

Save the figure fig at path with size.

Themes are applied from the :base theme and you can supply any number of overrides, either predefined or you own with the override_theme keyword.

The arguments fig, path and size may be specified in a number of different ways as shown below in Arguments or in the case of path and size be left with their default values (see Themes.width!, Themes.hwratio!, figure_dir! and export_format!). For a clearer picture of how to supply the arguments, see Examples in the documentation, but as a rule of thumb, any sensible way to define the export arguments should work granted that they are in the correct order.

Arguments

  • fig – figure(s) generating function
Info

fig_func::Function, (arg1, arg2,...), () -> fig_func(arg1, arg2,...) or fig_func (if it is possible to call it without any arguments). This is the only argument that is necessary to provide. See all possible signatures at FunctionSpec.

  • path: basename, directory and formats
Info

name, [formats], [dir] or path. For example "protein_density_heatmap", [:svg, :pdf, :pdf_tex], "~/ImporantProject/" or equivalently "~/ImporantProject/protein_density_heatmap.{svg, pdf, pdf_tex}". See all possible signatures at PathSpec.

Tip

If not supplied, the name is inferred from nameof(fig_func), formats are taken from MakieMaestro.get_export_format (see also export_format!) and dir is taken from MakieMaestro.get_figure_dir (see also figure_dir!).

Warning

If PdfTex format is requested, Inkscape is used to convert the SVG file to PDF with text in LaTeX. Due to that incscape must be an executable on your system if you want to use the PdfTex format.

  • size: physical dimensions of the figure
Info

20.5u"cm", 0.6, FigHeight(5u"inch"), 8u"inch", 0.5, 1.5 (relative width, hwratio), HeightLength(0.3), 0.4 (relative height, hwratio). A combination of width, height and/or hwratio, such that the size is completely determined from these and the default values (see Themes.hwratio! and Themes.width!). See all possible signatures at SizeSpec.

Keyword arguments

  • backends=CairoMakie – Backend used for exporting
  • override_theme=Theme() – Theme(s) that will be used to style the figure
  • [update] – (default: determine by the backend)
  • kwargs... – Any additional keyword arguments are supplied to the figure function as keyword arguments.
source
MakieMaestro.export_format! — Function
export_format!(formats)

Set the default formats to export.

julia> export_format!(["pdf", :eps]);

julia> export_format!("pdf", MakieMaestro.Png, :svg);

julia> export_format!(missing);
source
Internals
MakieMaestro.isvectorgraphic — Function
MakieMaestro.isvectorgraphic(x::Format)

Return true if x is a vector graphic format, false otherwise.

Examples

julia> MakieMaestro.isvectorgraphic(MakieMaestro.Pdf)
true

julia> MakieMaestro.isvectorgraphic(MakieMaestro.Png)
false
source
MakieMaestro.skip — Function
MakieMaestro.skip(skips::Vararg{Union{Symbol,Format}})

Return a Set{Format} of allowed formats by excluding specified formats or format groups.

Useful for customizing the output formats when saving figures, allowing you to easily exclude certain format types or groups of formats.

Arguments

  • skips: Variable number of arguments specifying formats or format groups to exclude. Can be individual Format types or symbols :raster or :vector.

Examples

julia> @assert MakieMaestro.skip(:raster) == Set([MakieMaestro.PdfTex, MakieMaestro.Eps, MakieMaestro.Svg, MakieMaestro.Pdf])

julia> @assert MakieMaestro.skip(:vector) == Set([MakieMaestro.Png])

julia> @assert MakieMaestro.skip(MakieMaestro.Pdf, MakieMaestro.Svg) == Set([MakieMaestro.PdfTex, MakieMaestro.Png, MakieMaestro.Eps])
source
MakieMaestro.extension — Function
MakieMaestro.extension(format::Format)

Return the string of the extension from the given format.

Examples

julia> MakieMaestro.extension(MakieMaestro.Png)
".png"

julia> MakieMaestro.extension(MakieMaestro.PdfTex)
".pdf"
source
MakieMaestro.choose_backend — Function
MakieMaestro.choose_backend(backends::Vector{Module}, f::Format)

Select the best backend from backends to export a figure in the format f.

Prefers CairoMakie for most formats unless the format is Png and GLMakie is available.

Examples

julia> MakieMaestro.choose_backend([CairoMakie, GLMakie], MakieMaestro.Svg)
CairoMakie

julia> MakieMaestro.choose_backend([WGLMakie], MakieMaestro.Eps)
ERROR: None of the backends support the format Eps
[...]
source
MakieMaestro.backend_formats — Function
MakieMaestro.backend_formats(backend::Module,...)

Return the set of compatible formats for given backends.

Examples

julia> @assert Set([ MakieMaestro.Png, MakieMaestro.Eps, MakieMaestro.Svg, MakieMaestro.Pdf ]) ⊆ MakieMaestro.backend_formats(CairoMakie) 

julia> @assert MakieMaestro.backend_formats(GLMakie) == Set([MakieMaestro.Png])
source
MakieMaestro.get_figure_dir — Function
MakieMaestro.get_figure_dir()

Get the figure directory

Examples

julia> figure_dir!("/tmp")
"/tmp"

julia> MakieMaestro.get_figure_dir()
"/tmp"
source
MakieMaestro.get_themes — Function
MakieMaestro.get_themes(backend::Module, format::Format)

Get the modification themes associated with the backend and format.

Examples

julia> MakieMaestro.get_themes(CairoMakie, MakieMaestro.PdfTex)
2-element Vector{Symbol}:
 :cairomakie
 :vector

julia> MakieMaestro.get_themes(GLMakie, MakieMaestro.Png)
2-element Vector{Symbol}:
 :glmakie
 :raster
source
MakieMaestro.get_export_theme — Function
MakieMaestro.get_export_theme(backend, format, width, hwratio, override_theme...)

Create the final export theme applied when generating the figure.

Examples

julia> theme = MakieMaestro.get_export_theme(CairoMakie, MakieMaestro.Png, 10u"cm", 0.8,
           Theme(;
               CairoMakie=(;pdf_version=1.1)
           ),
           Theme(;
               Scatter=(;markersize=8)
           )
       );

julia> theme.size[]
(283, 226)
source
MakieMaestro.get_formats — Function
MakieMaestro.get_formats(backends::Vector{Module}, formats::Set{Format})

Return the list (Vector) of formats to generate based on the given backends required formats. Output is in the correct order for export.

Examples

julia> (Sys.which("inkscape") === nothing) || MakieMaestro.Svg ∈ MakieMaestro.get_formats([CairoMakie], Set([MakieMaestro.PdfTex])) # Added Svg so the PdfTex is possible to create
true

julia> MakieMaestro.get_formats([GLMakie], Set([MakieMaestro.Pdf]))
ERROR: ArgumentError: None of the backends Module[GLMakie] support the formats Set(MakieMaestro.Format[MakieMaestro.Pdf])
[...]

julia> MakieMaestro.get_formats([CairoMakie, GLMakie], Set([MakieMaestro.Png, MakieMaestro.Svg]))
2-element Vector{MakieMaestro.Format}:
 Svg::Format = 1
 Png::Format = 0
source
MakieMaestro.get_export_format — Function
MakieMaestro.get_export_format()

Get the default export formats

Examples

julia> export_format!(:pdf)
Set{MakieMaestro.Format} with 1 element:
  MakieMaestro.Pdf

julia> MakieMaestro.get_export_format()
Set{MakieMaestro.Format} with 1 element:
  MakieMaestro.Pdf

julia> export_format!(missing);
source
MakieMaestro.FunctionSpec — Type
FunctionSpec(fig, args)

Specification of the function generating the figure with its arguments.

Can be called with additional keyword arguments. The arguments are passed from the args field.

source
MakieMaestro.uniqueid — Function
uniqueid(fspec::FunctionSpec; kwargs...)

Generate a unique ID for the fspec when called with kwargs.

Useful for caching the figures that do not change their definitions so that they do not have to be re-generated when re-exported.

See also uniqueids.

julia> f(args...; kwargs...) = lines(args...; kwargs...);

julia> fspec1 = FunctionSpec(f, (1:10, 1:10));

julia> fspec2 = FunctionSpec(f, (1:10, 1:10));

julia> fspec3 = FunctionSpec(f, (1:20, 1:20));

julia> @assert uniqueid(fspec1) == uniqueid(fspec2)

julia> @assert uniqueid(fspec1) != uniqueid(fspec1; axis=(;title="Line")) 

julia> @assert uniqueid(fspec1) != uniqueid(fspec3)
source
MakieMaestro.uniqueids — Function
uniqueids(fspec::FunctionSpec; kwargs...)

Returns a named tuple of the unique IDs for the fspec when called with kwargs.

See also uniqueid.

julia> f(args...; kwargs...) = lines(args...; kwargs...);

julia> fspec1 = FunctionSpec(f, (1:10, 1:10));

julia> fspec2 = FunctionSpec(f, (1:10, 1:10));

julia> @assert uniqueids(fspec1).code == uniqueids(fspec2).code

julia> @assert uniqueids(fspec1; axis=(;title="Line")).kwargs != uniqueids(fspec2).kwargs

julia> fspec3 = FunctionSpec(f, (1:20, 1:20));

julia> @assert uniqueids(fspec1).code == uniqueids(fspec3).code

julia> @assert uniqueids(fspec1).args != uniqueids(fspec3).args
source
MakieMaestro.PathSpec — Type
PathSpec(basename, [formats], [dirname])
PathSpec(fullpath, [formats])

Specification of where and which format to use for exporting a figure.

  • basename is internally a function that takes an index integer and returns the name of the figure. The function is created either by a suffix or by parsing the supplied string (see examples below).
  • formats is a set or collection of formats wanted for the export.
  • dirname is the directory where the figure will be saved (checked for existence upon creation).

Examples

```jldoctest; setup=:(using MakieMaestro: PathSpec) julia> PathSpec("somefile.pdf", ".") ./somefile.pdf

julia> PathSpec("somefile.{svg,eps}", "..") ../somefile.{eps,svg}

julia> PathSpec("somefile.png", "nonexistentdir") ERROR: ArgumentError: `nonexistent_dir` is not a valid directory [...]

julia> PathSpec("somefile",["pdf", :svg], "..") ../somefile.{pdf,svg}

source
MakieMaestro.SizeSpec — Type
MakieMaestro.SizeSpec(width::Length, hwratio::Real)

Specification of the physical size of the exported image.

The primary way to represent the size of a figure is it's width and the height to width ratio hwratio. However, any set of two values from {width, hwratio, height} fully determine the size. width and height may be either fixed values of the type Length or relative sizes to their default values by the type Real (RelativeSize). None, one or two of the values may be supplied and the size is determined from these values and the defaults. These defaults may be set with width! and hwratio!.

See also Themes.width!, Themes.get_width, Themes.hwratio!, Themes.get_hwratio

Examples

julia> Themes.width!(Themes.A4_WIDTH), Themes.hwratio!(2/(√(5) + 1));

julia> SizeSpec(0.5, 2)
w×h: 105.0 mm × 210.0 mm [h/w: 2.0]

julia> SizeSpec(10u"cm")
w×h: 10.0 cm × 6.18 cm [h/w: 2/(√5 + 1)]

julia> SizeSpec((15u"cm", 10u"cm"))
w×h: 10.0 cm × 15.0 cm [h/w: 1.5]

julia> SizeSpec((15u"cm", 0.5))
w×h: 105.0 mm × 150.0 mm [h/w: 1.4]

julia> SizeSpec((2, 10u"cm"))
w×h: 10.0 cm × 12.36 cm [h/w: 1.2]
source
MakieMaestro._savefig — Function
_savefig(fig, name, format, backend, dir; update)

Save figure fig with backend and name in dir with format.

Internal function that gets called at the end of the exporting stack with all of the arguments already fully determined and the figure created with the theme activated. update should be true if the Axis is created separately from the plots contained in the axis in order to set the correct viewing limits for the figure.

source
MakieMaestro._savepdftex — Function
_savepdftex(svgpath, outputpath; wait=true)

Run the command for creating a PDFTEX figure using Inkscape.

Internal function to convert SVG figures to PDFTEX (PDF+LaTeX) format assuming that the SVG already exists. If wait then the command in ran as blocking.

source

Logging

Internals
MakieMaestro.create_logger — Function
create_logger(logger, figdir)

Create a logger based on the logger argument and the figure directory figdir.

If logger is true, a default logger is created, if logger is an AbstractString, a TOMLLogger at that path. If logger is false the NullLogger is created.

source
MakieMaestro.add_entry — Method
add_entry(logger::FigureLogger, key::String, data::AbstractDict; update=true, keep=true)

Add the entry data under the key in the log file.

source
MakieMaestro.add_entry — Method
add_entry(logger::TOMLLogger, key::String, data::AbstractDict; update=true, merge=true)

Add the entry data under the key in the log file.

If update is true, the entry under key will be updated if it already exists. If merge is true, the data will be merged with the existing entry.

source

Theming

MakieMaestro.Themes — Module

This module is used to set themes for your figures. It can help you define a consistent theming scheme for your saved figures and for the figures you experiment with interactively.

It intends to solve the problem, where Makie gives you the option of theming, but if you want to change the theme at multiple places with multiple attribute changes and perhaps combine these options differently for your figures, it is necessary that you create the override themes and merge them with the current one which sooner or later becomes tedious and error prone. Especially if you are to create a lot of figures with various theming preferences. This tries to make theming and keeping consistency in your plots a little bit easier by allowing you to define all the connected attributes in one theme, register it with update_theme!(:my_theme, theme) and use these where necessary in your figure creation process and when saving.

source
MakieMaestro.Themes.width! — Function
width!(val::Length)

Set the default width for figures.

julia> width!(177u"mm" * 0.8)
141.6 mm

julia> Themes.get_width()
141.6 mm
source
MakieMaestro.Themes.hwratio! — Function
hwratio!(val)

Set the height-width ratio for saving figures.

julia> hwratio!((1 + √(5))/2)
1.618033988749895

julia> Themes.get_hwratio()
1.618033988749895
source
MakieMaestro.Themes.update_theme — Function
update_theme(key::Symbol, with::ThemeGenerator)

Update a specific theme component identified by key in the global THEME dictionary.

Arguments

  • key::Symbol: The key identifying the theme component to update.
  • with::ThemeGenerator: The new theme or function to update the existing theme with.

See also update_theme! for direct modifications.

Extended help

Specific behaviour for argument types:

  • If the key doesn't exist in THEME, it adds the new theme or function.
  • If the key exists:
    • For an existing Theme:
      • If with is a Function, it merges the result of with with the current theme.
      • If with is a Theme, it merges the current theme with with.
    • For an existing Function:
      • If with is a Theme, it creates a new function that merges with with the result of the current function.
      • If with is a Function, it throws an ArgumentError.

Throws

  • ArgumentError: If attempting to update a generating function with another generating

function.

source
MakieMaestro.Themes.update_theme! — Function
update_theme!(key::Symbol, new::ThemeGenerator)

Update a specific theme component in the global theme.

Arguments

  • key::Symbol: The key representing the theme component to be updated.
  • new::ThemeGenerator: The new theme generator to replace the existing one.

This function modifies the global theme by replacing the theme generator for the specified component with a new one. It directly updates the THEME global variable.

See also update_theme

source
MakieMaestro.Themes.get_theme — Function
get_theme(themes::Vector{Union{ThemeGenerator,Symbol}}; dict = THEME[])
get_theme(A, B, C, ...; dict = THEME[])

Create theme for specified keys and/or generators (including Themes).

Later arguments have precedence similarly to Base.merge(A::Dict, B::Dict).

Arguments

  • keys: A Vector or Vararg of symbols, functions generating themes or themes. Symbols are taken as keys from the dict.

Examples

julia> gap = true
true

julia> theme_props = MakieMaestro.Themes.get_theme([Theme(; figure_padding=2), () -> Theme(; colgap = gap, rowgap = gap), :orange_title]);

julia> @assert theme_props.colgap[] == theme_props.rowgap[] == true
source
MakieMaestro.Themes.theme_keys — Function
theme_keys()

Show the that are defined in the theme dictionary.

julia> theme_keys()[1:3]
3-element Vector{Symbol}:
 :base
 :cairomakie
 :data_aspect
source
Internals
MakieMaestro.Themes.ThemeGenerator — Type
ThemeGenerator == Union{Function,Theme}

A struct used for defining new theme “mixins” that can be inferred from some latent parameters.

Danger

That the function returns a Theme value is not checked. Therefore this type is only to be used internally...

julia> (() -> nothing) isa MakieMaestro.Themes.ThemeGenerator
true
source
MakieMaestro.Themes.merge_generate — Function
merge_generate(theme::ThemeGenerator,...)::Theme

Generate and merge all the theme arguments.

Later input arguments have precedence similarly as in a merge of dictionaries.

See also get_theme, ThemeGenerator

Examples

julia> MakieMaestro.Themes.merge_generate(Theme(; figure_padding=3), () -> Theme(; figure_padding=6))
Attributes with 1 entry:
  figure_padding => 6
source
MakieMaestro.Themes.figsize — Function
figsize(width::Length=get_width(), hw_ratio=get_hwratio())

Calculate the figure size in points (1u"pt" == (1//72)u"inch") based on the given width and height-to-width ratio.

Examples

julia> w,h = Themes.figsize(32u"cm", (1 + √(5))/2)
(907, 1467)
source
MakieMaestro.Themes.ScreenInfo — Type
MakieMaestro.Themes.ScreenInfo

Fields

  • default::Union{Missing,Bool} – X11 default screen
  • index::Int – X11 screen index
  • size::Tuple{Int,Int} – pixel dimensions of the display
  • dimensions::Tuple{Length,Length} – physical dimensions of the display
source
MakieMaestro.Themes.interactive_size! — Function
interactive_size!(size::Tuple{Length,Length})
interactive_size!(ratio::Tuple{Number,Number}; index=nothing)

Set the interactive figure size.

If given a ratio, calculate the size from the screen parameters so that the figure takes up the given width/height ratio of the screen. The optional index specifies the screen to use.

See also screen_parameters, get_interactive_size

source
MakieMaestro.Themes.get_interactive_size — Function
get_interactive_size()

Retrieve the current interactive size setting for figures.

This function checks the global INTERACTIVE_SIZE variable and returns its value. If INTERACTIVE_SIZE is not set (i.e., it's missing), it attempts to set a default size of 80% of the screen dimensions using interactive_size!((0.8, 0.8)).

See also interactive_size!

Throws

  • ErrorException: If INTERACTIVE_SIZE is not set and the function fails to set a default value.
source
MakieMaestro.Themes.screen_parameters — Function
screen_parameters()

Retrieve information about available screens (Vector{ScreenInfo}) using the xdpyinfo command.

This function parses the output of xdpyinfo to extract details about each screen, including its index, dimensions in pixels and millimeters, and whether it's the default screen.

Examples

screens = screen_parameters()
for screen in screens
    println("Screen $(screen.index): $(screen.size) pixels, $(screen.dimensions) physical size")
end
# Screen 0: (4080, 1920) pixels, (1072 mm, 504 mm) physical size

See also ScreenInfo

Extended help

  • This function relies on the xdpyinfo command and is therefore only compatible with systems where this command is available (typically Unix-like systems with X11).
  • The function may return an empty vector if no screens are detected or if parsing fails.
  • Requires the Unitful.jl package for handling millimeter units.
source

Paper Sizes

ISO 216 standard

The standard under ISO 216 is to define the paper size of {A/B/C}{1-X} paper to be the size when the paper with an index one lower is folded in half. This means that with an increasing index we alternate between the width > height and width < height, or, loosely speaking, "landscape" and "portrait" orientation. If you truly want to use the standard, then the constants {A/B/C}{1-X}_{WIDTH/HEIGHT}_TRUE are the ones that you should use. If like any other sane person, you view the width as the left to right span of the paper, when oriented vertically you should use the constants {A/B/C}{1-X}_{WIDTH/HEIGHT} instead.

using MakieMaestro.Themes
@assert Themes.A0_WIDTH == Themes.A1_HEIGHT
@assert Themes.A2_HEIGHT_TRUE == Themes.A1_WIDTH_TRUE # weird
Paper Size Constants

Plotting

Overrides

MakieMaestro.Recipes.image! — Function
Recipes.image!(args...; decorations=false, interpolate=false, axis=(; aspect=DataAspect()), colormap=:viridis, kwargs...)

Modified image! recipe that enables the user to set axis attributes even with the mutating function and has different defaults.

  • decorations – hide the axis decorations if set to false
source
MakieMaestro.Recipes.image — Function
Recipes.image(f)

Helper for setting the prefered options (interpolate, ax.aspect, decorations) for the image recipe.

source

Utility / QOL functions

MakieMaestro.L — Function
L(s::String)

Shortcut for latexstring(raw"\text{" * s * "}").

This is useful when you want to have LaTeX axis labels, but do not want to use the theme_latexfonts() theme.

source
MakieMaestro.fftvis — Function
fftvis(fft_img)

Apply a logarithmic scaling to visualize the absolute value of the Fourier image.

Extended help

This function takes the absolute value of the input img (typically the result of an FFT), adds 1 to avoid log(0), and then applies a base-2 logarithm. This scaling helps to visualize the wide dynamic range typically present in Fourier transforms of images.

Examples

using FFTW
img = rand(100, 100)
fft_img = fft(img)
heatmap(fftvis(fftshift(fft_img)))
source