Doc plots with Makie

[icweaver]

Closes #36

Depends on:

• Documentation for color laws #43: informs the y-axis label units used
• Support for Unitful.Gain in axis recipes? MakieOrg/Makie.jl#4801: Include Gain unit support in Makie upstream

Preview

• New plotting section
• Color laws
• Dust Maps. I also switched to Cividis here. I think it is a better colormap for accessibility, but can change it back if folks want

Exploration notebook

Motivation

DustExtinction.jl currently uses Plots.jl to generate a bunch of static plot images that are then added to the docs. A while back, Miles had the idea to streamline this process by making the plot creation part of the doc creation process, assisted by plot recipes. Although the original idea was to try and implement this with Plots.jl's recipe system, Makie.jl has since come on the scene as a mature, pure Julia alternative.

Noteable examples in JuliaAstro-adjacent ecosystems also exploring and/or already making the switch include DimensionalData.jl –- which backs the underlying data in AstroImages.jl, PairPlots.jl, and SkyImages.jl.

Major changes

• Replaces Plots.jl with Makie.jl
• Instead of generating plots in a separate script and importing the images into the docs, this generates the plots directly in the docstrings
• This is made more ergonomic with Makie.jl's recipe system
• Additionally, Julia's new package extension system is used to conditionally load the recipes only if the user has Makie.jl installed on their system. More info here.

TODO

• Implement package extension
• Generate parameter average and dust map plots
• Add remaining models to docs
• Cleanup
• Add more text to docs
• Bump oldest Julia version to at least v1.9 to use package extensions. Does this sound reasonable? Doc plots with Makie #58 (comment)
• Tests
  • Makie.PointLike (lines, scatter, etc.)
  • Makie.CellGrid (heatmaps)

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 99.65%. Comparing base (23dad1d) to head (bf78aa2).

Additional details and impacted files

@@            Coverage Diff             @@
##           master      #58      +/-   ##
==========================================
+ Coverage   99.62%   99.65%   +0.02%     
==========================================
  Files          10       11       +1     
  Lines         267      287      +20     
==========================================
+ Hits          266      286      +20     
  Misses          1        1              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[icweaver]

Sweeeet, just saw this too JuliaPhysics/Measurements.jl#174

"Oh yea, it's all coming together.jpeg"

[cgarling]

Great start, thanks! 👍

You intend to export the plotting recipes to users through the package extension? Originally I thought the vision was to define the plotting recipes just for the docs so the plotting dependencies could go into the documentation project and not affect the main project.

Typically I find that plotting recipes are useful when you want to make the same plot many times, as we do in the documentation, but I rarely use them otherwise because they cover one use case that usually doesn't match what I want. For example, the plotting recipe shows the reddening law over the full wavelength range with x in inverse microns (which is good for in the documentation!), but a situation in which I more commonly find myself (as a user) is wanting to plot the reddening law over a small wavelength range (say, the wavelength coverage of HST/ACS) with x in angstroms or nanometers.

This is to say that I don't think I would ever call these plotting recipes as a user myself and so my preference would be to isolate them to the documentation build so that the dependencies of the main code do not need to be changed. This would also allow us to continue iterating on improvements to the docs / plots without worrying how it would affect the main package. This is a weak preference and I'm happy to be persuaded 😄

[icweaver]

Thanks for your feedback, I think those are very fair points

What if we restrict the recipe plots (lplot, mplot, dplot, and friends) to the docs (final names TBD), but still keep the building blocks exposed via the package extension? That way users could still make their own custom plots with Makie's primitives (lines, scatter, etc.) if they want, like for the HST/ACS wavelength coverage example you mentioned, while keeping our original API unchanged

This would also greatly reduce the scope of the full recipe plots that I would need to consider 😅

[cgarling]

The building blocks being the Makie.convert_arguments definitions and Makie.plottype? That sounds good!

As extensions are optional, something I've done in the past is add extensions while keeping compatibility with older Julia versions (i.e., not bumping julia compat). The extensions will just be ignored if you use the package on an older version, but at least you can still use the latest version of the base package. I think it's nice to keep long back compatibility for foundational packages like this and I'm not sure it's worth jumping from Julia 1.6 -> 1.9 compatibility for a few plotting definitions (are the building blocks for the plotting really just 7 lines? pretty cool). What do you think about this solution?

Alternatively if you really want the makie extension to be available everywhere you could fall back to using Requires.jl on older Julia versions (see, e.g., here), but I think it's probably not worth the hassle. Actually now that I think about it, using the Requires.jl trick would be worse from a maintenance perspective than just bumping the julia compat so disregard this paragraph

[icweaver]

Exactly!

Sounds good. I made the following broad changes:

• Moved the doc-specific plotting functions to their own file: plotting.jl
• Call this file from the relevant markdown files via @setup
• Run the plotting code from named @example blocks, and hide the input via # hide comments

I'll keep adding to the documentation, but the overall organization scheme should be ready now for a first pass at reviewing whenever you have the time. I'm still learning the ins-and-outs of Documenter.jl, so if anything looks wonky that was probably a mistake. Thanks!

[icweaver]

Also happy to split the doc writing bits out into its own PR if that is preferred 👍🏾

[icweaver]

Ok, I think things should be in a pretty good place for a review now. Thanks for all the preliminary comments!

[icweaver]

Also, opened #59 to keep track of this comment in case we happen to find more reasons to potentially modernize things

I think it's nice to keep long back compatibility for foundational packages like this and I'm not sure it's worth jumping from Julia 1.6 -> 1.9 compatibility for a few plotting definitions