Rename ak.choose and ak.cross.

[jpivarski]

This is for #199, and I think I'm going to go with

• choose → combinations
• diagonal → replacement
• cross → product

for the sake of following itertools as much as possible. cartesian is also a good word for the last one, but I think if we're going to follow itertools for one, we should follow it for both. (These two functions are related; rules for one should apply to the other.) Besides, someone might not know who Descartes is.

[jpivarski]

Something to consider:

• rpad → padna

It can't just be "pad" because of np.pad. We (with @ianna) added an "r" because the None values go on the right, not the left. But really, unequal length lists always align left like this—it has to do with the fact that the leftmost objects can be identified with each other while the rightmost cannot. Putting "r" for "right" in the name is (1) a little obscure; I wouldn't guess "right", and (2) begs the question, "why not left?" I don't want to entertain that question.

So instead of saying which side should get padded, since this function isn't actually different in that regard, let's use the disambiguator to say what it should be padded with. NumPy's pad fills with zeros; Pandas's pd.Series.str.pad pads with spaces. The fact that Awkward fills with None is a bit unusual—the other libraries don't have the opportunity to do that.

So maybe this or

• rpad → pad_none and
• fillna → fill_none

This would be more in keeping with the use of snake_case and whole words, which was a request from many people (scikit-hep/awkward-0.x#240). @nsmith- suggested fillna for agreement with Pandas, but that's a method on DataFrame, not a free function like ours, and the "na" comes from R, which doesn't really have an equivalent in Python.

[jpivarski]

Ach! But ak.Array must have a method named isna or else it can't be a Pandas column!

Okay, so there's a difference between free functions and methods:

• function ak.pad_none
• function ak.fill_none
• function ak.is_none (no function ak.not_none; that's gratuitous)
• function ak.to_list
• method ak.Array.isna because Pandas requires it
• method ak.Array.dropna might be required for performance in Pandas
• method ak.Array.fillna might be required for performance in Pandas
• method ak.Array.tolist to be like NumPy; it's just natural to type
• method ak.Array.tojson for symmetry

If the People ask for it, synonyms ak.tolist → ak.to_list and ak.tojson → ak.to_json can be later added, but only if it's a true desire path.

To do:

• Document the ak.Array methods that exist only for Pandas compatibility.

[jpivarski]

Hmm. NumPy has an np.product, but it's going to be deprecated. That could count as an argument against it—a NumPy function of that name technically exists—but it could count as an argument for it—NumPy will never use that name again, for fear of conflicts with old code.

[jpivarski]

• ak.covar is not quite the same thing as np.cov (both do correlations)
• ak.corr is not quite the same thing as np.corrcoef (both do correlations)

As long as they're not quite the same, I'll keep their different names. That, at least, will prevent misidentification by accident. The NumPy functions seem to be designed for a single large matrix, while the Awkward functions are reducer-like, which favors computing many small covariances and correlations (e.g. tracking or vertex-finding or something).

Also, the ak.covar name has symmetry with ak.var, and they are much closer in behavior than np.cov is to np.var.

[jpivarski]

Manually document

• ak.numba.register
• ak.pandas.register
• ak.pandas.df
• ak.pandas.dfs
• ak.numexpr.evaluate
• ak.numexpr.re_evaluate
• ak.autograd.elementwise_grad

[jpivarski]

Final names:

old	new
ak.choose	ak.combinations
ak.diagonal	ak.replacement
ak.cross	ak.cartesian
ak.rpad	ak.pad_none
ak.fillna	ak.fill_none
ak.isna	ak.is_none
ak.notna	gone!
ak.Array.to_list	ak.Array.tolist
ak.Array.to_json	ak.Array.tojson

ak.covar and ak.corr are unchanged, as are the methods that are required for Pandas.