GH-15677 Fix Match function bug

[maurever]

Issue: #15677

TODO:

• Do not add new parameter indexes, fix the bug in our implementation according to what R::match does. Using the iris dataset and calling match with c(“setosa”, “versicolor”) should generate a new column with value 1 assigned to rows with “setosa” and 2 assigned to rows with “versicolor”). The answer should be the same with all clients. This implies that R and Python should generate the same column values.
• The default for nomatch should be NaN for both R and Python. In addition, only allow NaN or other numerical values for nomatch values. No string is supported.
• Fix the documentation to reflect the changes: nomatch is defaulted to NaN and can only be numerical values. Remove the last sentences for incomparables.
• Add parameter start_index with default value = 1, if a user wants to change indexing from 0 for example
• Fix %in% to works as in base library but in different PR GH-15677 Fix %in% function #15929
• Add better example in doc

[sebhrusen]

Looks good @maurever.
Added some suggestions for doc + concern about sorted numerical values.

[maurever]

@hannah-tillman Could you check the documentation of this feature, please? Thanks!

[hannah-tillman]

made a few docs updates -- good on my end :)

[sebhrusen]

looking good, thanks @maurever
Apparently, you still need to rebase to resolve conflicts, so I will approve next time.

[maurever]

Thanks, @sebhrusen; the PR is updated based on your suggestion and rebased.

[sebhrusen]

tested the Py doc generation with the result rendered in the example, it works nicely!
Also updated the suggestion to use real data from the example.

Maybe same could be done in R.

[maurever]

@hannah-tillman, please check that the documentation is generated correctly. @sebhrusen also suggested adding output into the R example, but I think it will not work in the R. If you have any idea how to improve the R example to be similar to the Python example, please let me know (or feel free to commit this change here). Thanks!

[sebhrusen]

LGTM, thanks @maurever

I took the initiative to commit a small fix in the Py example.
Regarding the R example, looking at R doc, I don't think it's possible to render the results the same way as we can in Py, common practice seems to be using a comment, like:

sample ##--> describe shortly what is expected when this is printed

for example, in this case

sample ##--> `match` column should be made of `1` for `setosa`, `2` for `versicolor` and `NaN` for `virginica`

[hannah-tillman]

@maurever The python docs build fine 👍

For the R documentation, I went through the current R guide to find an example of something adding the output because I didn’t really remember that happening. What I was able to find was a rare case of output being added as a comment, so we could do the same for this? Would look like this:

#' \dontrun{
#' h2o.init()
#' data <- as.h2o(iris)
#' match_col <- h2o.match(data$Species, c("setosa", "versicolor", "setosa"))
#' iris_match <- h2o.cbind(data, match_col)
#' sample <- h2o.splitFrame(iris_match, ratios=0.05, seed=1)[1]
#' sample
#' # [[1]]
#' #   Sepal.Length Sepal.Width Petal.Length Petal.Width    Species C1
#' # 1          5.2         3.5          1.5         0.2     setosa  1
#' # 2          5.0         3.5          1.3         0.3     setosa  1
#' # 3          7.0         3.2          4.7         1.4 versicolor  1
#' # 4          4.9         2.4          3.3         1.0 versicolor  1
#' # 5          5.5         2.4          3.8         1.1 versicolor  1
#' # 6          5.8         2.7          5.1         1.9  virginica  0
#' #
#' # [12 rows x 6 columns] 
#' }

This is the only example I was able to find for output in the R docs, though, so it is currently the only idea i have. Let me know if this is what you want.

[maurever]

Thanks, @seb and @hannah-tillman. The PR is now ready for review.

[sebhrusen]

LG, thank you @maurever !