Design decision on the output tables

[lf-araujo]

Dear Tim,

Perhaps is too late on the design of this package. It is great that it displays results in markdown directly, however I think that by adding ## Titles you are missing an opportunity (or I completely misunderstand how to use rmarkdown, either of the two).

So if I allow a chunk to print out the resulting output as is, with results = "asis" the symbol ## may include the text in the wrong section level, if for example it is supposed to be printed in part of the text that already is in the second level and the table is meant to be within the section, not in a separate section.

Have you ever considered adding a legend line instead of a section marker, like in the pandoc documentation.

The default looks like this (also note the lack of spacing btw the table and the following section):

## Common Factor paths


|                |    A|   C|    E|
|:---------------|----:|---:|----:|
|Common.factor.1 | 0.55| 0.7| 0.49|
## Loading of each trait on the Common Factors


|         |   CP1|
|:--------|-----:|
|parcontt | -0.04|
|parincot | -0.52|
|parmonit | -0.24|
|parnegct | -0.37|
|parwarmt |  0.08|
|peragre  |  0.07|
|percons  |  0.05|
|perneur  | -0.18|
|perextr  |  0.08|
|peropen  |  0.22|

My suggestion is that perhaps it would play nicer with rmarkdown chunks if they were:

|                |    A|   C|    E|
|:---------------|----:|---:|----:|
|Common.factor.1 | 0.55| 0.7| 0.49|
: Common Factor paths

Here is how code like the above is presented in LaTEX, these are supported in other pandoc writers too:

[mcneale]

One thing I would suggest as a default is to include the standard errors or CIs in the table.

I would also expand the table title to say what the numbers are, e.g., Parameter estimates from a two-factor model. A: additive genetic; C: common environment; E: unique environment.

[tbates]

hI @lf-araujo
Thanks for the thoughtful comments.

Markdown output in umx was designed some years ago with the goals of being easy to read in the terminal and easy to paste into a markdown doc. The "##" for table captions was just to make these easy to find in the console and it's always niggled me that captions look more like they belong to the table above than the one below…

So... yes: definitely scope for improvements now with kable extras and rmarkdown/pandoc etc. to build on. I see pandoc supports the Table: caption styling... Seems like low-hanging fruit to get started on. I'll have a look at that when I get time and try and approach this systematically.

PS: Have a play with ?tmx_show() - I've been working on making more colourful, styled, and interactive table-output there and would be interested in your thoughts.

[tbates]

I modified umxSummary for umxCP umxACE and umxRAM. Captions work in the online pandoc converter to generate latex code with table captions.

If you have devtools:install_github("tbates/umx"), let me how it behaves for you.

example output from RAM model (nb: GitHub markdown doesn't grok the captions)

require(umx)
data(demoOneFactor)
manifests = names(demoOneFactor)
m2 = umxRAM("One Factor", data = demoOneFactor, type = "cov",
	umxPath("G", to = manifests),
	umxPath(var = manifests),
	umxPath(var = "G", fixedAt = 1)
)
umxSummary(m2, digits=3)
?umxSummary std=T|F', digits, report= 'html', filter= 'NS' & more

name	Estimate	SE
G_to_x1	0.397	0.016
G_to_x2	0.503	0.018
G_to_x3	0.577	0.02
G_to_x4	0.702	0.024
G_to_x5	0.795	0.027
x1_with_x1	0.041	0.003
x2_with_x2	0.038	0.003
x3_with_x3	0.041	0.003
x4_with_x4	0.039	0.003
x5_with_x5	0.036	0.004
G_with_G	1.000	0
Table: Model Parameter loadings

Model Fit: χ²(5) = 7.39, p = 0.193; CFI = 0.999; TLI = 0.999; RMSEA = 0.031

[tbates]

As shown above, @mcneale umxSummary displays SEs for umxRAM models. For other models, it prints CIs if they have been requested and run in the model. See also #95

[tbates]

Now using the caption = facility of knitr::kable

Table: Standardized parameter estimates from a 1-factor Cholesky ACE model. A: additive genetic; C: common environment; E: unique environment.

	a1	c1	e1
ht	0.93	0.08	0.36

Table: Means and (raw) betas from model$top$intercept and model$top$meansBetas

	ht1	ht2
intercept	16.446	16.446
age	-0.005	-0.005

[tbates]

• IMPROVED: umxCompare generate compliant and more informative captions, and inline help is more compatible (cat instead of message)

[tbates]

I think is mostly up-to-spec now. re-open if there are more opportunities to improve