Changes to function reference

[peterdesmet]

This is a suggested update to the function reference:

• Remove section "Manipulate radar scans" (currently a bit of a mixed bag) and list:
  • integrate_to_ppi() under "Integrate vertical profiles", as it expresses vertically integrated reflectivity (VIR) and requires a vp file (imo less suitable to list under the ppi section then)
  • calculate_param() under "Inspect scans and parameters", right under get_param()
  • apply_mistnet() under "Read radar data" after nexrad_to_odim(), as it is a pvol manipulation
• Just as scan and param are treated together, also treat vp and vpts together, in 2 sections:
  • "Read vertical profile data", with e.g. read_vpfiles() and read_vpts()
  • "Inspect vertical profiles"
• Move get_quantity() to "Access profile metadata" (the description mentions "data" as well)
• Use active verbs "Read", not "Reading"
• No functions are repeated
• List example (e.g. example_scan) after other functions in that section

@adokter @bart1 @CeciliaNilsson709 suggestions?

Rendering:

[adokter]

This is a suggested update to the function reference:

* Remove section "Manipulate radar scans" (currently a bit of a mixed bag) and list:

I liked this section honestly, it are those functions that generate new spatial quantities (either as ppi or scan). And Mistnet acts on scans just as much as on polar volumes. I expect more manipulating functions to be added in the future, so good to have this section.

  * `integrate_to_ppi()` under "Integrate vertical profiles", as it expresses vertically integrated reflectivity (VIR) and requires a vp file (imo less suitable to list under the ppi section then)

The core functionality of this function is much more towards generating a PPI than that it is integrating vertical profiles. It could be under "Project scans and parameters", but I prefer the "manipulate radars scans" because new quantities are being generated.

  * `calculate_param()` under "Inspect scans and parameters", right under `get_param()`

My vote is against this, as the function generates new scan parameters, not inspecting/plotting existing data

  * `apply_mistnet()` under "Read radar data" after `nexrad_to_odim()`, as it is a pvol manipulation

Also voting against this one, the function is segmenting out rain from biology, "reading radar data" doesn't capture that.

* Just as `scan` and `param` are treated together, also treat `vp` and `vpts` together, in 2 sections:
  
  * "Read vertical profile data", with e.g. `read_vpfiles()` and `read_vpts()`
  * "Inspect vertical profiles"

Ok, but in that case rename "Inspect vertical profiles" to "inspect and manipulate vertical profiles", because regularize_vpts(), filter_vpts() and bind_vpts() have little to do with inspection.

* Move `get_quantity()` to "Access profile metadata" (the description mentions "data" as well)

I think we should keep a strict distinction between actual data and metadata. get_quantity() accesses data while all the other functions are higher level thresholding attributes. Suggest moving it to "inspect and manipulate vertical profiles"

* Use active verbs "Read", not "Reading"

ok

* No functions are repeated

ok

* List example (e.g. `example_scan`) after other functions in that section

ok

[bart1]

Hi, I must say I'm not a daily user of this bit of documentation so I'm not sure how valuable it is but I tend to agree with @adokter that some topic on manipulating makes sense as these might be operations people are looking for. It might make sense to also include polar volumes in the title.

I also noticed the topic project scans and parameters now contains a lot that is more about visualizing then projecting (eg, download_basemap, plot, [). For me projecting is quite a specific operation thus maybe this heading should be more generic.

Now the headings seem to be mixture of both the type of object and the type of operation. Would a two level grouping make more sense? Or reporting functions in multiple places where it makes sense (e.g functions that convert from one type to an other)?