Mechanism for specifying facet-aware formats in `analyze`

[gmbecker]

We have standard templates which need different formatting depending on where in the row faceting structure they are. As mentioned in insightsengineering/tern#1439 the most common standard case of this is splitting on PARAMCD and then analyzing AVAL.

While we can (and currently do) build specialized afuns which bake in this logic, we feel the framework as a whole would benefit if there were a mechanism for doing this while using otherwise "off the shelf" afuns, such as those provided by tern.

What this ultimately boils down to is the formats depending on the split context (or, as we will see below, the row data).

Currently if you give analyze's format argument a function, that is taken as a formatting function, so we cannot give what might be called a "format deriving function" there without breaking existing and used behavior.

Also note that analyze's format argument is superseded by any formatting the afun applies, which is why we need the suggested change to tern linked above.

We have two forms of this functionality we are currently thinking about and haven't decided which we like more yet:

format deriving functions

A new argument (name tbd) to analyze that accepts a function which will be called with the split context and the generated RowsVerticalSection and be expected to determine formats within the tabulation process (after afun calling), e.g. possibly somewhere around

rtables/R/tt_dotabulation.R

Lines 414 to 420 in 79a256b

	rfootnotes <- rep(list(list(), length(rv1col)))
	nms <- value_names(rv1col)
	rfootnotes <- row_footnotes(rv1col)
	imods <- indent_mod(rv1col) ## rv1col@indent_mods
	unwrapped_vals <- lapply(rawvals, as, Class = "list", strict = TRUE)

ie where other aspects of what will be rows are figured out based on the RowsVerticalSection the afun created.

This gives full flexibility but puts the onus on those writing format deriving functions to figure out how to handle everything, and thus we'd likely need helper functions

format column

A new argument format_var (or format_col) which names a (list) column in the data which specifies format(s) that have been precalculated.

The logic required to ultimately use this is essentially the same as above, minus the interacting with the split column stuff, as it would be done during the preprocessing step.

Things To Figure Out

In both cases, we will need some way of specifying which formats go to which cells/rows. This is handled in in_rows and widely by afuns via .formats, but currently .formats isn't handled specially by the actual tabulation machinery (it is specified in extra_args and passed unmodified to afuns like all other extra arguments). We might need to change that, which would make its place in extra_args not really correct (but not something we can change without breaking tons of code, so we wouldn't). Even leaving it in extra_args but modifying it in certain cases before passing it along would technically be a breaking change but not one that would break any existing code in practice.

@iaugusty and I will prepare a PR but are happy to discuss design decisions beforehand either here, in meetings or both.