APA theme and helpers

[davidgohel]

How to help with APA subject

• A theme function or a something() |> as_flextable() ?
• utilities?
• support for rempsyc

@rempsyc @Buedenbender

guidelines and references:

• https://github.com/rempsyc/rempsyc
• https://apastyle.apa.org/style-grammar-guidelines/tables-figures/tables.

[Buedenbender]

Hi in shameless self-promotion, I am quite happy with my format_flextable() function (doc).
If this is desireable we could easily use the code of the function for a improved / better version and include it in flextable. Also the nice_table() function of @rempsyc could be a useful basis.

I think overall a function or template for the APA Style is very useful and would be highly appreciated by a wide community, as there is a whole range of Journals in Social Science and Medicine that explicitly require APA Style. In the APA Publication Manual the Chapter would be "7 Tables and Figures" (pp 195. - 209). There are also examples included, which are also on the apastyle webpage you referenced (examples can be found: here).
Albeit I can not share the respective chapter from the publication manual publicly (due to (C)), I condensed some important information below. Also I could send you parts of my APA Publication manual via Mail if interested.

PS: Just noticed that I did not credit flextable in my function (apologizes, will fix that soon, but included references / credit elsewhere in my package e.g., here); fixed it

List of Details on Formatting (relevant to flextable):

• 7.10 Each table should be enumerated in bold face (e.g. Table 1), followed by
• 7.11 Table heading (in sentence case and in italic
• 7.12 Column Headings, should be centered above their column, use singular
• 7.13 Body: Line spacing can be variable either (single spaced, one-and-a-half spaced, double spaced). Entries longer than one line (0.15 in indent), cell entries flush left alignment, (if entries significantly shorter than their heading its acceptable to center)
• 7.14 Table Note: There are three type of notes general notes, which always start with the word Note. in cursive. general notes qualify, explain and provide further information on the table (e.g. explains abbreviations, or copyright attributions); Specific Notes refer to a particular cell, column, or row and are usualy denoted by superscript lowercase letter; Probability Note describes how asterisks are used to indicate significance for p values. Each type of note should start on a new line

[rempsyc]

Ok. Here's a first attempt.

library(flextable)
theme_apa <- function(x) {
  if (!inherits(x, "flextable")) {
    stop("theme_apa supports only flextable objects.")
  }
  apa.border <- list("width" = 1, color = "black", style = "solid")
  x <- font(x, part = "all", fontname = "Times New Roman")
  x <- line_spacing(x, space = 2, part = "all")
  x <- hline_top(x, part = "head", border = apa.border)
  x <- hline_bottom(x, part = "head", border = apa.border)
  x <- hline_top(x, part = "body", border = apa.border)
  x <- hline_bottom(x, part = "body", border = apa.border)
  x <- align(x, align = "center", part = "all")
  x <- valign(x, valign = "center", part = "all")
  x <- colformat_double(x, digits = 2)
  fix_border_issues(x)
}
head(mtcars*22.22) |>
  flextable() |>
  theme_apa()

^{Created on 2022-07-21 by the reprex package (v2.0.1)}

Discussion

1. Initially, I wrote the function with the native pipe operator |> but realized that you don’t have a Depends section specifying the minimal R version required in your DESCRIPTION file. So I assumed flextable doesn't support the native pipe yet and rewrote the code accordingly.
2. Few things I’ve realized: size 12 and theme_booktabs are default now (has this changed or always was? Had the feeling theme_vanilla was the default before) so not needed so I’ve removed them. Not sure if it’s safer to specify explicitly still, in case defaults change in the future. Following David’s comment, I removed height=0.55 and instead used double space along valign, which allowed me to remove hrule.
3. Not sure about including set_table_properties(layout = "autofit") or not, but I think default is fine since it’s too situational.
4. The caption (“Table 1” on first line, “Description of table” on second line), note, footnotes, etc. would be required for APA style. However, to stay consistent with other templates, I am not sure it should be integrated with the APA template, or whether it should be required in a second step. Technically, we are, after all, writing a theme, not a full-fledged function. So I would tend to go for the basic APA template no caption, and then just maybe add a function to add the double caption (and notes/footnotes) as per @Buedenbender's way, if at all. I would be quite happy with that to start with. Up for discussion of course.
5. The default digit is tricky because it depends on the statistic (p value is 3 digits, r values are 2 digits, descriptive stats are 1 digit) and this is what rempsyc::nice_table deals with, but I think a safe default would be 2 digits. If people really want specific digits, they can manually specify after.
6. David if you’d be interested, perhaps there would be a possibility of some overlap between nice_table and theme_apa for basic statistical formatting (perhaps italics for common statistical symbols, combination of upper and lower bounds of the 95% confidence interval, etc.), however the function is pretty comprehensive, so I don’t know how far you’d like to go into that.

@Buedenbender, anything missing in your opinion? I tried combining both our custom functions. Thanks for setting up all the resources and explanations in your first post!

[Buedenbender]

Very well done. I agree footer and header might not need to be part of the basic theme as this is not a full function.
One possible addition I'd like to suggest could be instead of stoping when not a flextable is provided, the function could try to convert and if this is not possible throw the same message

e.g.,

# Conversion if possible (e.g., for data.frame)
  if (!inherits(x, "flextable")) {
    tryCatch(
      x <- flextable::flextable(x),
      error = function(c) stop("Error could not convert to a flextable object. Stopping - theme_apa() only supports flextable objects.")
    )
  }

I am not quite sure if this is proper behavior for a theme, as it might, should only take flextable objects. Still I believe it would not hurt, to include this one line. E.g., for early data exploration this would enable me to call theme_apa(iris) and it would work fine.

[rempsyc]

@davidgohel would it be useful if I submitted a PR with the new APA theme?

[davidgohel]

(Sorry for the delay; I was in holidays, and then I tested flextable with quarto and since I am working on captions... but it is related to our subjects)

You can prepare a PR, it will be welcome. But we may have to iterate over it, because there is something to enable for captions (with the caption structure table xx/caption/table), it must be made compatible with cross-referencing in bookdown and in quarto if possible. I am not sure if it's easy. (Everything related to caption is crazily time-consuming!)

I am also working on enabling captions formatting as you have suggested. That's almost ready.

[davidgohel]

Sorry again for the delay but I do what I can :)

@rempsyc to answer your questions

1. we don't use pipes because we want user that only have old versions can use the package latest versions. Not sure if it often happens but that's a decision asked by a customer a long time ago so we stick to it :)
2. a problem only occurs with pdf that does not support line height nor height. I am trying to find a solution, I doubt it is possible easily.
3. Agree
4. Agree. Below a suggestion to start...
5. I prefer to not redo your work on these points
6. I may not have enough time. If we can provide the tools you need, it will be a very first good step :)

---

Starting from the PR of @rempsyc and the latest GitHub version of flextable,
here is a function to add the captions as defined in APA rules. Feel free to comment or suggest improvements.

library(officer)
library(flextable)

apa_paragraph_tabnum <- function (z) {
  
  pr <- fp_text_default(font.size = 12, font.family = "Times New Roman", bold = TRUE)
  
  run_str_pre <- as_chunk(z$pre_label, props = pr)
  
  seq_str <- paste0("SEQ ", z$seq_id, " \u005C* Arabic")
  if(!is.null(z$start_at) && is.numeric(z$start_at)){
    seq_str <- paste(seq_str, "\\r", as.integer(z$start_at))
  }
  run_word_field <- as_word_field(x = seq_str, prop = pr)
  
  run_word_styleref_1 <- NULL
  run_word_styleref_2 <- NULL
  if(z$tnd > 0){
    run_word_styleref_1 <- as_word_field(x = paste0("STYLEREF ", z$tnd, " \\r"), prop = pr)
    run_word_styleref_2 <- as_chunk(z$tns, prop = pr)
  }
  
  args <- list(run_str_pre, run_word_styleref_1, run_word_styleref_2, run_word_field)
  args <- Filter(function(z) !is.null(z), args)
  do.call(as_paragraph, args)
}

apa_decorate <- function(x, tab_caption, table_num = NULL) {
  
  table_num_fp <- fp_text_default(font.size = 12, font.family = "Times New Roman", bold = TRUE)
  
  x <- add_header_lines(x, values = c("", ""))
  x <- align(x, i = 1:2, part = "header", align = "left")
  if (is.null(table_num)) {
    z <- flextable:::get_word_autonum(x, tab_props = opts_current_table())
    x <- compose(x, i = 1, j = 1, part = "header", value = apa_paragraph_tabnum(z))
  } else {
    x <- compose(x, i = 1, j = 1, part = "header", value = as_paragraph(as_chunk(table_num, props = table_num_fp)))
  }
  
  x <- compose(
    x = x, i = 2, 
    j = 1, part = "header", 
    value = as_paragraph(
      as_chunk(tab_caption, props = fp_text_default(font.size = 12, font.family = "Times New Roman", italic = TRUE))
    )
  )
  x <- line_spacing(x, i = 2, part = "header", space = 2)
  x <- valign(x, i = 2, part = "header", valign = "center")
  
  x <- border(x = x, i = 1:2, border = fp_border_default(width = 0), part = "header")
  x <- hline(x = x, i = 2, border = fp_border_default(width = 1, color = "black"), part = "header")
  
  x <- font(x, fontname = "Times New Roman", part = "header")
  x <- fontsize(x, size = 12, part = "header")
  
  x
}

theme_apa <- function(x, line_spacing = 2, ...) {
  if (!inherits(x, "flextable")) {
    stop("theme_apa supports only flextable objects.")
  }
  apa.border <- list("width" = 1, color = "black", style = "solid")
  x <- font(x, part = "all", fontname = "Times New Roman")
  x <- fontsize(x, size = 12, part = "all")
  x <- line_spacing(x, space = line_spacing, part = "all")
  x <- hline_top(x, part = "head", border = apa.border)
  x <- hline_bottom(x, part = "head", border = apa.border)
  x <- hline_top(x, part = "body", border = apa.border)
  x <- hline_bottom(x, part = "body", border = apa.border)
  x <- align(x, align = "center", part = "all")
  x <- valign(x, valign = "center", part = "all")
  x <- colformat_double(x, digits = 2)
  fix_border_issues(x)
}

ft_1 <- head(cars) |>
  flextable() |>
  set_caption(autonum = run_autonum(seq_id = "tab", bkm = "mtcars", prop = fp_text_default(bold = TRUE)))|>
  theme_apa()|>
  # apa_decorate(tab_caption = "qsdq qdqsd qdqsd")|>
  apa_decorate(table_num = "Table 1", tab_caption = "qsdq qdqsd qdqsd")|>
  fix_border_issues()

print(ft_1, preview = "docx")
print(ft_1, preview = "html")
print(ft_1, preview = "pptx")
print(ft_1, preview = "pdf", latex_engine = "xelatex")

This solution comes with some limits:

1. not cross-reference-able with bookdown and quarto!
2. PDF line height (2 for the caption) is not possible for now
3. Table numbers will be made by hand, that's not ideal. Maybe a pandoc filter could be used...

[rempsyc]

1. Thanks! Yeah I think I tried different things and tried adding back the label from the other example from the other issue. Works now after removing the label :)

2. Arg, that was it. I was changing the bold in apa_fp_text so it was changing it at both places! I had to create two different ones. Works now! :D

3. Below:

library(officer)
docx_summary(read_docx("flextable test2.docx"))
#>      doc_index content_type    style_name
#> 1            1    paragraph         Title
#> 2            2    paragraph   Source Code
#> 3            3    paragraph   Source Code
#> 4            4    paragraph   Source Code
#> 5            5    paragraph   Source Code
#> 6            6    paragraph Table Caption
#> 1.1          7   table cell          <NA>
#> 1.4          7   table cell          <NA>
#> 1.7          7   table cell          <NA>
#> 1.10         7   table cell          <NA>
#> 1.13         7   table cell          <NA>
#> 2.2          7   table cell          <NA>
#> 2.5          7   table cell          <NA>
#> 2.8          7   table cell          <NA>
#> 2.11         7   table cell          <NA>
#> 2.14         7   table cell          <NA>
#> 3.3          7   table cell          <NA>
#> 3.6          7   table cell          <NA>
#> 3.9          7   table cell          <NA>
#> 3.12         7   table cell          <NA>
#> 3.15         7   table cell          <NA>
#>                                        text level num_id row_id is_header
#> 1                                 APA theme    NA     NA     NA        NA
#> 2                 packageVersion("officer")    NA     NA     NA        NA
#> 3                             [1] '0.4.4.6'    NA     NA     NA        NA
#> 4               packageVersion("flextable")    NA     NA     NA        NA
#> 5                            [1] '0.7.4.17'    NA     NA     NA        NA
#> 6    Table SEQ tab \\* ArabicItalic Caption    NA     NA     NA        NA
#> 1.1                                     mpg    NA     NA      1      TRUE
#> 1.4                                   21.00    NA     NA      2     FALSE
#> 1.7                                   21.00    NA     NA      3     FALSE
#> 1.10                                  22.80    NA     NA      4     FALSE
#> 1.13                                  21.40    NA     NA      5     FALSE
#> 2.2                                     cyl    NA     NA      1      TRUE
#> 2.5                                    6.00    NA     NA      2     FALSE
#> 2.8                                    6.00    NA     NA      3     FALSE
#> 2.11                                   4.00    NA     NA      4     FALSE
#> 2.14                                   6.00    NA     NA      5     FALSE
#> 3.3                                    disp    NA     NA      1      TRUE
#> 3.6                                  160.00    NA     NA      2     FALSE
#> 3.9                                  160.00    NA     NA      3     FALSE
#> 3.12                                 108.00    NA     NA      4     FALSE
#> 3.15                                 258.00    NA     NA      5     FALSE
#>      cell_id col_span row_span
#> 1         NA       NA       NA
#> 2         NA       NA       NA
#> 3         NA       NA       NA
#> 4         NA       NA       NA
#> 5         NA       NA       NA
#> 6         NA       NA       NA
#> 1.1        1        1        1
#> 1.4        1        1        1
#> 1.7        1        1        1
#> 1.10       1        1        1
#> 1.13       1        1        1
#> 2.2        2        1        1
#> 2.5        2        1        1
#> 2.8        2        1        1
#> 2.11       2        1        1
#> 2.14       2        1        1
#> 3.3        3        1        1
#> 3.6        3        1        1
#> 3.9        3        1        1
#> 3.12       3        1        1
#> 3.15       3        1        1

^{Created on 2022-09-07 by the reprex package (v2.0.1)}

I do have a field on the table number, and when I right-click on it, I can update field, etc.

I also have the EndNote integration, so I don't know if that can mess up code fields...

4. Fixed by removing the label also! :)

5. This was actually also caused by the label!

6. Same.

[rempsyc]

Only issue I see is that using the automatic label, it appears in Word but not in HTML, which will be problematic in my vignettes if people cannot see the result (unless saving as images and then loading local image).

[davidgohel]

See the line 6, it's written "Table Caption" in column style_name

For you last/new issue, I still don't have an answer. I suggest to not use HTML and instead use doconv::to_miniature() to prepare images of the Word documents.

[rempsyc]

Thanks and above all congratulations on all this work and accomplishment! 😄

[davidgohel]

Well now, there is much more work to document that 😭 and submit to CRAN. no thanks to you 😉