Rename more functions

[GegznaV]

There are several functions (especially plot-related) that names do not comply with the Tidyverse style. I think plot-related functions shouldn't start with the prefix spc as spc should be reserved for functions that modify @data$spc (cbeleites/hyperSpec#208 (comment)). Otherwise, the prefixes will be confusing. In series of issues, I'll mention the functions and give suggestions on how to rename them.

• Rename spc.label.wlonly() → format_label_wl_only(), etc. #39
• Rename spc.identify() → identify_spc() #40
• Rename stacked.offsets() → calculate_offsets() | calculate_stacked_offsets() #41
• Rename trellis.factor.key() → trellis_factor_key() #42
• Rename mark.dendrogram() → mark_groups_in_dendrogram() #43
• Rename markpeak() → mark_peak() #44
• Rename sel.poly() → plot_and_get_polygon_coordinates(), etc. #45
• Rename spc.point.*() → locate_spc_point_*() #46
• Rename fitraster() → raster_fit(), makeraster → raster_make #47
• Rename plot*() → plot_*() #48
• Rename as.*() → as_*() #49
• Rename normalize01() → normalize_01() #50
• Rename pooled.cov() → cov_pooled() #51

[GegznaV]

I opened separate issues for each portion of functions I suggest renaming. All these functions are exported functions. So we should decide if and how to rename them.

[GegznaV]

@sangttruong, @bryanhanson, @cbeleites, please, add comments in each issue.

[bryanhanson]

I support the renaming in general, subject to CB fine-tuning the names. I think we need to start thinking about adding something additional to .onAttach warning users that the changes are extensive ("extensive" is just my word for now, we probably need several sentences to give a sense of the sweep of changes).

[GegznaV]

I think we need to start thinking about adding something additional to .onAttach warning users that the changes are extensive

I think we need:

1. a new vignette or several sections in current vignettes on that;
2. a section in README on that.

[bryanhanson]

A new vignette, dedicated to the changes, would be a good idea. It would be really great if we could create it by reading the deprecated *.R files and having the vignette create itself, e.g. by writing a table of old and new function names. Personally I would want such a thing in printable form, probably pdf. This would be a great kindness to users.

The audience for such a vignette are existing users, but in the face of problems with old scripts I'm not sure their first move would be to look for a vignette; they might go to the README. Nor is it very pleasant to run an old script dozens of times, each time fixing the re-named or deprecated function that is named in the messages. That's why I think having a printable cheat sheet of changes would be nice -- users could work through their scripts using it.

If we create such a vignette, I would put a message in .onAttach saying to check the vignette and telling them how to view it. Something like:

"Existing users of hyperSpec will find that many functions have been renamed in favor of more consistent names. To help you update your workflows, there is a cheat sheet available as a vignette"

If you really want to be nice, we would write a function to read their scripts and point out what needs to be changed.

[bryanhanson]

Suggest moving the conversation about user experience here.

[GegznaV]

I'm starting the procedures to rename the functions as this summer, in general, there was an agreement on doing this.