# Updating documentation for Interpolations.jl v0.14

**URL:** <https://discourse.julialang.org/t/updating-documentation-for-interpolations-jl-v0-14/84082>\
**Category:** Community\
**Tags:** package, documentation, interpolations\
**Created:** [July 12, 2022, 4:45am UTC](https://discourse.julialang.org/t/updating-documentation-for-interpolations-jl-v0-14/84082 "2022-07-12T04:45:26Z")\
**Posts on this page:** 14\
**Page:** 1

<div class="post-metadata">

**Author:** ![mkitti](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mkitti/32/12459_2.png) [@mkitti](https://discourse.julialang.org/u/mkitti)\
**Post date:** [July 12, 2022, 4:45am UTC](https://discourse.julialang.org/t/updating-documentation-for-interpolations-jl-v0-14/84082/1 "2022-07-12T04:45:26Z")

</div>

Hello. I’m the current maintainer of [Interpolations.jl](https://github.com/JuliaMath/Interpolations.jl). We recently released [v0.14.0](https://github.com/JuliaMath/Interpolations.jl/releases/tag/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.](https://juliahub.com/ui/Packages/Interpolations/VpKVx/0.14.0)

I’ve started some changes via this [pull request #499](https://github.com/JuliaMath/Interpolations.jl/pull/499).

Here is a preview:

- Documentation: [Home · Interpolations.jl](https://juliamath.github.io/Interpolations.jl/previews/PR499/)
- README.md: [Interpolations.jl/README.md at mkitti/update\_docs · JuliaMath/Interpolations.jl · GitHub](https://github.com/JuliaMath/Interpolations.jl/blob/mkitti/update_docs/README.md)
- NEWS.md: [Interpolations.jl/NEWS.md at mkitti/update\_docs · JuliaMath/Interpolations.jl · GitHub](https://github.com/JuliaMath/Interpolations.jl/blob/mkitti/update_docs/NEWS.md)

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.

---

<div class="post-metadata">

**Author:** ![mkitti](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mkitti/32/12459_2.png) [@mkitti](https://discourse.julialang.org/u/mkitti)\
**Post date:** [July 12, 2022, 5:54am UTC](https://discourse.julialang.org/t/updating-documentation-for-interpolations-jl-v0-14/84082/2 "2022-07-12T05:54:59Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![Paul\_Soderlind](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/paul_soderlind/32/1753_2.png) [@Paul\_Soderlind](https://discourse.julialang.org/u/Paul_Soderlind)\
**Post date:** [July 12, 2022, 9:20am UTC](https://discourse.julialang.org/t/updating-documentation-for-interpolations-jl-v0-14/84082/3 "2022-07-12T09:20:24Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![mkitti](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mkitti/32/12459_2.png) [@mkitti](https://discourse.julialang.org/u/mkitti)\
**Post date:** [July 14, 2022, 8:42am UTC](https://discourse.julialang.org/t/updating-documentation-for-interpolations-jl-v0-14/84082/4 "2022-07-14T08:42:35Z")

</div>

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/](https://juliamath.github.io/Interpolations.jl/previews/PR499/)

---

<div class="post-metadata">

**Author:** ![tim.holy](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tim.holy/32/52_2.png) [@tim.holy](https://discourse.julialang.org/u/tim.holy)\
**Post date:** [July 14, 2022, 9:54am UTC](https://discourse.julialang.org/t/updating-documentation-for-interpolations-jl-v0-14/84082/5 "2022-07-14T09:54:38Z")

</div>

Your excellent maintenance of this package is greatly appreciated!

> [@mkitti](#):
>
> 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?

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.

---

<div class="post-metadata">

**Author:** ![Paul\_Soderlind](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/paul_soderlind/32/1753_2.png) [@Paul\_Soderlind](https://discourse.julialang.org/u/Paul_Soderlind)\
**Post date:** [July 14, 2022, 11:45am UTC](https://discourse.julialang.org/t/updating-documentation-for-interpolations-jl-v0-14/84082/6 "2022-07-14T11:45:55Z")

</div>

> 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](https://github.com/PumasAI/DataInterpolations.jl) has a short but very straightforward README. It really helps users getting started.

---

<div class="post-metadata">

**Author:** ![eirikeb](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/eirikeb/32/11674_2.png) [@eirikeb](https://discourse.julialang.org/u/eirikeb)\
**Post date:** [July 14, 2022, 1:10pm UTC](https://discourse.julialang.org/t/updating-documentation-for-interpolations-jl-v0-14/84082/7 "2022-07-14T13:10:56Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![mkitti](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mkitti/32/12459_2.png) [@mkitti](https://discourse.julialang.org/u/mkitti)\
**Post date:** [July 14, 2022, 2:45pm UTC](https://discourse.julialang.org/t/updating-documentation-for-interpolations-jl-v0-14/84082/8 "2022-07-14T14:45:40Z")

</div>

> [@tim.holy](#):
>
> - The capitalization of `LinearInterpolation` is a bit non-traditional since there isn’t actually a type of that name

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

> <https://github.com/JuliaMath/Interpolations.jl/pull/501>
>
> Specifically, deprecate \`LinearInterpolation\`, \`ConstantInterpolation\`,
> and \`Cu…bicSplineInterpolation\` in favor of \`linear\_interpolation\`,
> \`constant\_interpolation\`, and \`cubic\_spline\_interpolation\`, respectively
> since these are merely functions and not types.
> 
> Put another way:
> 
> \`\`\`
> julia\> Dict(\[
> :ConstantInterpolation =\> :constant\_interpolation,
> :LinearInterpolation =\> :linear\_interpolation,
> :CubicSplineInterpolation =\> :cubic\_spline\_interpolation
> \])
> Dict{Symbol, Symbol} with 3 entries:
> :CubicSplineInterpolation =\> :cubic\_spline\_interpolation
> :LinearInterpolation =\> :linear\_interpolation
> :ConstantInterpolation =\> :constant\_interpolation
> \`\`\`

---

<div class="post-metadata">

**Author:** ![mkitti](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mkitti/32/12459_2.png) [@mkitti](https://discourse.julialang.org/u/mkitti)\
**Post date:** [July 14, 2022, 2:53pm UTC](https://discourse.julialang.org/t/updating-documentation-for-interpolations-jl-v0-14/84082/9 "2022-07-14T14:53:46Z")

</div>

> [@eirikeb](#):
>
> 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.

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

```julia
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

```

---

<div class="post-metadata">

**Author:** ![JeffreySarnoff](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jeffreysarnoff/32/1980_2.png) [@JeffreySarnoff](https://discourse.julialang.org/u/JeffreySarnoff)\
**Post date:** [July 14, 2022, 4:51pm UTC](https://discourse.julialang.org/t/updating-documentation-for-interpolations-jl-v0-14/84082/10 "2022-07-14T16:51:11Z")

</div>

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?).

---

<div class="post-metadata">

**Author:** ![mkitti](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mkitti/32/12459_2.png) [@mkitti](https://discourse.julialang.org/u/mkitti)\
**Post date:** [July 14, 2022, 8:14pm UTC](https://discourse.julialang.org/t/updating-documentation-for-interpolations-jl-v0-14/84082/11 "2022-07-14T20:14:59Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![tim.holy](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tim.holy/32/52_2.png) [@tim.holy](https://discourse.julialang.org/u/tim.holy)\
**Post date:** [July 15, 2022, 5:13pm UTC](https://discourse.julialang.org/t/updating-documentation-for-interpolations-jl-v0-14/84082/12 "2022-07-15T17:13:08Z")

</div>

> [@mkitti](#):
>
> 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.

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

---

<div class="post-metadata">

**Author:** ![droodman](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/droodman/32/26652_2.png) [@droodman](https://discourse.julialang.org/u/droodman)\
**Post date:** [June 6, 2023, 1:27am UTC](https://discourse.julialang.org/t/updating-documentation-for-interpolations-jl-v0-14/84082/13 "2023-06-06T01:27:21Z")

</div>

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](http://juliamath.github.io/Interpolations.jl/stable/#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](http://juliamath.github.io/Interpolations.jl/stable/control/#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.

---

<div class="post-metadata">

**Author:** ![mkitti](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mkitti/32/12459_2.png) [@mkitti](https://discourse.julialang.org/u/mkitti)\
**Post date:** [June 15, 2023, 6:22pm UTC](https://discourse.julialang.org/t/updating-documentation-for-interpolations-jl-v0-14/84082/14 "2023-06-15T18:22:32Z")

</div>

@droodman Could you make this into an issue or issues at [Issues · JuliaMath/Interpolations.jl · GitHub](https://github.com/JuliaMath/Interpolations.jl/issues) to help me keep track of this? Also, pull requests are welcome there.