Updating documentation for Interpolations.jl v0.14

Community
, ,
13

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.

6 Likes