Options for `print.latexMatrix` too hard to use

[friendly]

In my book, I'm generating matrices for SST, SSH and SSE for an MLM using crossprod() from Y, fitted and residuals,
but I don't want the row/col names automatically generated by crossprod(). I had to do the following:

# Ugh! rownames/colnames if present are used by default. Need to make them null to avoid them.
rownames(SST) <- rownames(SSH) <- rownames(SSE) <- NULL
colnames(SST) <- colnames(SSH) <- colnames(SSE) <- NULL
Eqn(latexMatrix(SST), "=", latexMatrix(SSH), "+", latexMatrix(SSE))

The default for display.labels used by print.latexMatrix() is now TRUE by default, and I can't figure out how to change it, because I don't understand the syntax for assigning to an option which is a list of such nested labels.

> options("print.latexMatrix")
$print.latexMatrix
NULL

> options(print.latexMatrix[["display.labels"]] = FALSE)
Error: unexpected '=' in "options(print.latexMatrix[["display.labels"]] ="
> options(print.latexMatrix$display.labels = FALSE)
Error: unexpected '=' in "options(print.latexMatrix$display.labels ="

I understand that this developed as a result of adding more features.

But, at the least we should document (in @details for print.latexMatrix()) how to change the default.

Or, maybe something like how knitr::opts$set() works?

[john-d-fox]

From ?latexMatrix:

display.labels: whether or not to display row and column labels (if they exist); the default is taken from the "display.labels" element of the "print.latexMatrix" option, and if the option isn't set, the default is TRUE.

So either use the display.labels argument to print() or set the "display.labels" element of the option, which is a list.

For example:

X <- latexMatrix(rownames=c("a", "b", "z"), 
                 colnames=c("A", "B", "Z"))
X
print(X, display.labels=FALSE)
options(print.latexMatrix=list(display.labels=FALSE))
X

All of the "print.latexMatrix" 'sub-options' work like this -- i.e., they're list elements. Apparently, that's unclear from the documentation, so please feel free to improve it.

The approach taken is simpler than in knitr; if you look at the code for print.latexMatrix(), you'll see (in addition to the default for the display.labels argument, which will be NULL if the option or sub-option in unset) the command

if (is.null(display.labels) || is.na(display.labels)) 
    display.labels <- TRUE

[friendly]

Thanks for clarifying this John. I'll revise the documentation to make this explicit.

I know that the defaults are all set in the code, so trying to interrogate them gives NULL:

> options("print.latexMatrix")
$print.latexMatrix
NULL

I wonder if it would be better/more transparent to assign them in the package?

Part of the difficulty was that I was trying to use this within Eqn(), so print(latexMatrix(), display.labels=FALSE) was unnecessarily verbose.

I'm also thinking that the default should be display.labels=FALSE, because that would be more typical use, and the row/col labels can get messy. What do you think?

[friendly]

Also, looking at ?latexMatrix makes me think that it would be clearer to document print.latexMatrix() separately, because there are so many options that apply only to the print method, and now they're all interspersed among the others.

I think this could be done with a separate @Rdname tag. What do you think?

[john-d-fox]

With respect to your penultimate comment: An alternative to the current approach is to set the default print.latexMatrix() option list (and other options -- I don't recall whether there are any) at package start-up. I think this is what you're suggesting; if not, can you clarify?

I don't like that approach for a couple of reasons: (1) Changing an option is much more complicated; you have to change the corresponding list element and then re-assign the whole list to the option via options(); that's sufficiently complicated for the user probably to warrant creating a setMatlibOptions() function to facilitate making small changes. So everything gets more complicated. (2) I'd rather avoid changing the session state when the package loads.

That said, if you really want to do this, please feel free to go ahead.

I'd prefer not to change the default to display.labels=FALSE, figuring that if users take the trouble to define labels, they probably want to see them. Also, although you're likely currently the main (and maybe only) user of this feature, it's helpful IMO to think about it more generally. That said, I don't strongly object to making this change.

With respect to your last comment: Yes, please feel free to create a separate help page for the print() method, linking to it from the latexMatrix help page. Dividing up the examples may prove awkward, but maybe not.

[friendly]

OK, I can see the difficulty of setting options at startup, something I haven't seen elsewhere in package code.

Re: the default for display.labels, it's not so much that I took any trouble to define them, but rather than many matrix functions, like crossprod() create them. But now that I understand how to change the default, I can live with this for now.

I finished working on the documentation for latexMatrix(), all in place for now, and clearer in a number of ways. Take a look when I've committed the latest changes.

[john-d-fox]

I may have conveyed the wrong impression: It's not hard to set options at startup, just not, I think, a good idea here. To do it, you'd define a .onLoad() function along the lines (not tested!)

.onLoad <- function(libname, pkgname){
  if (is.null(getOption("print.latexMatrix") {
    options(print.latexMatrix = list(display.labels=FALSE, etc.))
  }
   etc.
}