Updating documentation for Interpolations.jl v0.14

Hello. I’m the current maintainer of Interpolations.jl. We recently released v0.14.0. I would like to follow up with a point release with a focus on the documentation, and I could use your help.

JuliaHub tells me that there were 9300 new users in the last 30 days.

I’ve started some changes via this pull request #499.

Here is a preview:

If you have a second, feel free to stop by the pull request and provide feedback. This could include

  • What could be improved?
  • Examples you would like to see.
  • Other interpolation packages you would like to list.
  • Spelling or grammatical errors.
  • Badges to add.
9 Likes

You can also leave comments here if you are not familiar with pull requests. Thanks again for everyone who have participated so far.

Thanks for the opportunity to comment on the documentation. I would like to suggest making the documentation more newcomer friendly.

  1. Very early, clarify the difference between regular and irregular grids - and refer to the respective sections.
  2. In the early examples, use the convenience methods with an explicit grid xs, or at least use scale(). Again clarify what to do when xs is irregular.
  3. Put the “Convenience Constructors” before “General”.
  4. In “General” and “Interpolation Algorithms”, mention what the effective assumption about the x grid is (1:N) and give an example on how to work with a different x grid.
9 Likes

I’m trying to figure out how to balance @tim.holy’s suggestion with putting the convenience constructors up front. I think you are getting at the underlying matter. Could you elaborate on how you think we might achieve that balance?

The working version of the index page now includes a convenience constructor example first, and then it breaks it down, including a mention of scale. Do you think I should explain more detail about regular and irregular grids on the index page or should that kind of detail be relegated to deeper sections.

https://juliamath.github.io/Interpolations.jl/previews/PR499/

Your excellent maintenance of this package is greatly appreciated!

One ambitious option might be to reconsider the design of the convenience constructors. There are a couple of things odd about them, for example:

  • The capitalization of LinearInterpolation is a bit non-traditional since there isn’t actually a type of that name
  • LinearInterpolation does not hint that it also sets a choice for extrapolation. Perhaps the default value for extrapolation_bc could be nothing, and in such cases it returns something without an extrapolation wrapper, e.g., a (scaled BSpline) interpolant for uniform grids. If the user chooses something besides nothing, then it could wrap in an extra extrapolation layer.
  • one might consider implementing LinearInterpolation(A) (or whatever new name it gets) to return just the plain (unscaled) BSplineInterpolation.

That might resolve the performance concerns while maintaining the ease of use, and at that point I don’t think I’d have any reservations about emphasizing the convenience constructors.

1 Like

Do you think I should explain more detail about regular and irregular grids on the index page

Yes, I think it should be mentioned together with a pointer to which section to read for the irregular grid.

For some ideas: DataInterpolations.jl has a short but very straightforward README. It really helps users getting started.

1 Like

Hi, thanks for your work on this package. I use it every day =)

  • The new landing page is a lot better than the old one!
    • In addition to Paul’s suggestions, I’d add a small section where you ‘’[…]explain more detail about regular and irregular grids on the index page" and also explain scale.
  • I don’t understand what this means “Note: the current version of Interpolations supports interpolation evaluation using index calls [], but this feature will be deprecated in future.”. Since it’s a holdover from an old version, maybe it’s time to drop this sentence.
1 Like

I created a separate pull request to deprecate ConstantInterpolation, LinearInterpolation,
and CubicSplineInterpolation in favor of constant_interpolation, linear_interpolation, and cubic_spline_interpolation:

1 Like

Previously, we used to support “indexing” into an interpolation object.

julia> itp = interpolate((1:5,),collect(0.1:0.1:0.5), Linear() |> Gridded)
5-element interpolate((::Vector{Int64},), ::Vector{Float64}, Gridded(Linear())) with element type Float64:
 0.1
 0.2
 0.3
 0.4
 0.5

julia> itp(1.5)
0.15000000000000002

julia> itp[1.5]
┌ Warning: `getindex(itp::AbstractInterpolation{T, N}, i::Vararg{Number, N}) where {T, N}` is deprecated, use `itp(i...)` instead.
│   caller = top-level scope at REPL[4]:1
└ @ Core REPL[4]:1
0.15000000000000002

The graphs that show name-by-dim vs time-by-order are some hard to understand at a glance. Using the same font for the dim and the order may not be the best choice, even italicizing one would help. Also consider separating cells or rows or cols by thin yet visible lines (grey?).

1 Like

I also do not know where the code to generate those graphs are at the moment, although I have a vague recollection of asking @tim.holy about it at one point. At the moment, those numbers are likely quite out of date. I would lean towards removing them in favor of focusing on benchmarks of Interpolations.jl itself.

1 Like

I suspect everything is in the perf folder, but it has been quite a while since I looked at this.

1 Like