Recipe for General TopoPlots

At the core of TopoPlots.jl is the topoplot recipe, which takes an array of measurements and an array of positions, which then creates a heatmap like plot which interpolates between the measurements from the positions.

TopoPlots.topoplot — Function
topoplot(data::Vector{<:Real}, positions::Vector{<: Point2})

Creates an irregular interpolation for each data[i] point at positions[i].

Attributes

  • colormap = Reverse(:RdBu)

  • colorrange = automatic

  • labels::Vector{<:String} = nothing: names for each data point

  • interpolation::Interpolator = ClaughTochter(): Applicable interpolators are TopoPlots.ClaughTochter, TopoPlots.DelaunayMesh, TopoPlots.NullInterpolator, TopoPlots.SplineInterpolator

  • extrapolation = GeomExtrapolation(): Extrapolation method for adding additional points to get less border artifacts

  • bounding_geometry = Circle: A geometry that defines what to mask and the x/y extend of the interpolation. E.g. Rect(0, 0, 100, 200), will create a heatmap(0..100, 0..200, ...). By default, a circle enclosing the positions points will be used.

  • enlarge = 1.2, enlarges the area that is being drawn. E.g., ifbounding_geometryisCircle`, a circle will be fitted to the points and the interpolation area that gets drawn will be 1.2x that bounding circle.

  • resolution = (512, 512): resolution of the interpolation

  • label_text = false:

    • true: add text plot for each position from labels
    • NamedTuple: Attributes get passed to the Makie.text! call.

  • label_scatter = false:

    • true: add point for each position with default attributes
    • NamedTuple: Attributes get passed to the Makie.scatter! call.

  • markersize = 5: size of the points defined by positions, shortcut for label_scatter=(markersize=5,)

  • contours = false:

    • true: add scatter point for each position
    • NamedTuple: Attributes get passed to the Makie.contour! call.

Example

using TopoPlots, CairoMakie
topoplot(rand(10), rand(Point2f, 10); contours=(color=:red, linewidth=2))

Interpolation

The recipe supports different interpolation methods, namely:

TopoPlots.DelaunayMesh — Type
DelaunayMesh()

Creates a delaunay triangulation of the points and linearly interpolates between the vertices of the triangle. Really fast interpolation that happens on the GPU (for GLMakie), so optimal for exploring larger timeseries.

Warning

DelaunayMesh won't allow you to add a contour plot to the topoplot.

TopoPlots.NullInterpolator — Type
NullInterpolator()

Interpolator that returns "0", which is useful to display only the electrode locations + labels

One can define your own interpolation by subtyping:

TopoPlots.Interpolator — Type

Interface for all types <: Interpolator:

interpolator = Interpolator(; kw_specific_to_interpolator)
interpolator(xrange::LinRange, yrange::LinRange, positions::Vector{Point2}, data::Vector{<: Real})::Matrix{<: Real}

The different interpolation schemes look quite different:

using TopoPlots, CairoMakie

data, positions = TopoPlots.example_data()

f = Figure(resolution=(1000, 1000))

interpolators = [
    DelaunayMesh() ClaughTochter();
    SplineInterpolator() NullInterpolator()]

data_slice = data[:, 360, 1]

for idx in CartesianIndices(interpolators)
    interpolation = interpolators[idx]
    TopoPlots.topoplot(
        f[Tuple(idx)...], data_slice, positions;
        contours=true,
        interpolation=interpolation,
        labels = string.(1:length(positions)), colorrange=(-1, 1),
        label_scatter=(markersize=10,),
        axis=(type=Axis, title="$(typeof(interpolation))()",aspect=DataAspect(),))
end
f

Extrapolation

There are currently just two extrapolations: None (NullExtrapolation()) and a geometry based one:

TopoPlots.GeomExtrapolation — Type
GeomExtrapolation(
    method = Shepard(), # extrapolation method
    geometry = Rect, # the geometry to fit around the points
    enlarge = 3.0 # the amount to grow the bounding geometry for adding the extra points
)

Takes positions and data, and returns points and additional datapoints on an enlarged bounding geometry:

extra = GeomExtrapolation()
extra_positions, extra_data, bounding_geometry, bounding_geometry_enlarged = extra(positions, data)

The extrapolations in action:

data, positions = TopoPlots.example_data()
titles = ["No Extrapolation", "Rect", "Circle"]
data_slice = data[:, 340, 1]
f = Figure(resolution=(900, 300))
for (i, extra) in enumerate([NullExtrapolation(), GeomExtrapolation(enlarge=3.0), GeomExtrapolation(enlarge=3.0, geometry=Circle)])
    pos_extra, data_extra, rect_extended, rect = extra(positions, data_slice)
    geom = extra isa NullExtrapolation ? Rect : extra.geometry
    # Note, that enlarge doesn't match (the default), the additional points won't be seen and masked by `bounding_geometry` and `enlarge`.
    enlarge = extra isa NullExtrapolation ? 1.0 : extra.enlarge
    ax, p = topoplot(f[1, i], data_slice, positions; extrapolation=extra, bounding_geometry=geom, enlarge=enlarge, axis=(aspect=DataAspect(), title=titles[i]))
    scatter!(ax, pos_extra, color=data_extra, markersize=10, strokewidth=0.5, strokecolor=:white, colormap = p.colormap, colorrange = p.colorrange)
    lines!(ax, rect_extended, color=:black, linewidth=4)
    lines!(ax, rect, color=:red, linewidth=1)
end
resize_to_layout!(f)
f

Interactive exploration

DelaunayMesh is best suited for interactive data exploration, which can be done quite easily with Makie's native UI and observable framework:

f = Figure(resolution=(1000, 1000))
s = Slider(f[:, 1], range=1:size(data, 2), startvalue=351)
data_obs = map(s.value) do idx
    data[:, idx, 1]
end
TopoPlots.topoplot(
    f[2, 1],
    data_obs, positions,
    interpolation=DelaunayMesh(),
    labels = string.(1:length(positions)),
    colorrange=(-1, 1),
    colormap=:viridis,
    axis=(title="delaunay mesh",aspect=DataAspect(),))
f

Different geometry

The bounding geometry pads the input data with more points in the form of the geometry. So e.g. for maps, one can use Rect as the bounding geometry:

TopoPlots.topoplot(
    rand(10), rand(Point2f, 10),
    axis=(; aspect=DataAspect()),
    colorrange=(-1, 1),
    bounding_geometry = Rect,
    label_scatter=(; strokewidth=2),
    contours=(linewidth=2, color=:white))