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.
Thanks for the opportunity to comment on the documentation. I would like to suggest making the documentation more newcomer friendly.
Very early, clarify the difference between regular and irregular grids - and refer to the respective sections.
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.
Put the “Convenience Constructors” before “General”.
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.
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.
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.
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.
I created a separate pull request to deprecate ConstantInterpolation, LinearInterpolation,
and CubicSplineInterpolation in favor of constant_interpolation, linear_interpolation, and cubic_spline_interpolation:
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?).
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.
I’m new to this package and am having a hard time understanding the documentation, which is a major deterrent to using it.
The Home page of the documentation starts with “Example Usage”. This part I get, though I think it should just be “Example.” There are lots of other places with unnecessary words.
The next section is " Performant Example Usage" and it loses me. Because it starts using undefined terms/functions/types. It says “The above use of LinearInterpolation is actually a short hand for a composition of interpolate , scale , and extrapolate .” But “LinearInterpolation” doesn’t appear above. And I don’t know what interpolate , scale , and extrapolate are exactly in the context. For example, what’s being scaled–the domain or the range of the interpolation? Then there’s an example line, “extrapolate(scale(interpolate(A, BSpline(Linear())), xs))”. I get the idea, but there’s a lot of complexity here, and it’s unexplained. Why isn’t it Linear(BSpline()), for example? What are the other possible iterations on this construct? It’s surprising to be so lost so early in the documentation.
To try to figure out what all this means, I search for “scale” in the docs. I go to the top hit, Scaling. It says “If the knots are not unit spaced or start at a distinct value other than 1 , then the scale function can be used.” That still doesn’t tell me what the scale function is nor how it is used.
But it then it says “See Scaled BSplines for further information.” So I try that. I read first that “BSplines assume your data is uniformly spaced…”. But I don’t know what BSplines is. It says “However, if A is a collection of ranges or linspaces, you can use scaled BSplines.” Which still doesn’t tell me what the scale function is, nor how to use scaled BSplines.
So I try looking at the example in this section. I hit another complex and unexplained expression, “interpolate(A, BSpline(Cubic(Line(OnGrid())))).” Again I don’t know what exactly all these terms mean.
Giving up on that, I go to the API, which is hard to find because it is under “Library.” The first entry is about chain rules… I search through for things about scaling and BSplines, but get lost again.
The documentation for Linear says it is a type. But the terse example is “Linear()” which confuses me because that looks like a function call. Int64 is a type, but I can’t do Int64(). So Linear is both a type and a method? I don’t understand what the example “Linear()” is showing/doing.
And so on.
My strongest suggestion is to impose an iron rule on the non-API documentation: do not use a term or function or type before defining it. Define the elements one by one, building up the concepts, giving runnable examples of each new idea. I wish I could help, but of course it’s hard to document what one doesn’t understand.