SummaryTables
Docstrings
SummaryTables.Annotated
— MethodAnnotated(value, annotation; label = AutoNumbering())
Create an Annotated
object which will be given a footnote annotation in the Table
where it is used. If the label
keyword is AutoNumbering()
, annotations will be given number labels from 1 to N in the order of their appearance. If it is nothing
, no label will be shown. Any other label
will be used directly as the footnote label.
Each unique label must be paired with a unique annotation, but the same combination can exist multiple times in a single table.
SummaryTables.Cell
— TypeCell(value, style::CellStyle)
Cell(value; [bold, italic, underline, halign, valign, border_bottom, indent_pt, merge, mergegroup])
Construct a Cell
with value value
and CellStyle
style
, which can also be created implicitly with keyword arguments. For explanations of the styling options, refer to CellStyle
. A cell with value nothing
is displayed as an empty cell (styles might still apply). The type of value
can be anything.
Some types with special behavior are:
Multiline
for content broken over multiple lines in a cell. This object may not be used nested in other values, only as the top-level value.Concat
for stringing together multiple values without having to interpolate them into aString
, which keeps their own special behaviors intact.Superscript
andSubscript
Annotated
for a value with an optional superscript label and a footnote annotation.
SummaryTables.CellStyle
— TypeCellStyle(;
bold::Bool = false,
italic::Bool = false,
underline::Bool = false,
halign::Symbol = :center,
valign::Symbol = :top,
indent_pt::Float64 = 0.0,
border_bottom::Bool = false,
merge::Bool = false,
mergegroup::UInt8 = 0,
)
Create a CellStyle
object which determines the visual appearance of Cell
s.
Keyword arguments:
bold
renders textbold
iftrue
.italic
renders textitalic
iftrue
.underline
underlines text iftrue
.halign
determines the horizontal alignment within the cell, either:left
,:center
or:right
.valign
determines the vertical alignment within the cell, either:top
,:center
or:bottom
.indent_pt
adds left indentation in points to the cell text.border_bottom
adds a bottom border to the cell iftrue
.merge
causes adjacent cells which are==
equal to be rendered as a single merged cell.mergegroup
is a number that can be used to differentiate between two otherwise equal adjacent groups of cells that should not be merged together.
SummaryTables.Concat
— TypeConcat(args...)
Create a Concat
object which can be used to concatenate the representations of multiple values in a single table cell while keeping the conversion semantics of each arg
in args
intact.
Example
Concat(
"Some text and an ",
Annotated("annotated", "Some annotation"),
" value",
)
# will be rendered as "Some text and an annotated¹ value"
SummaryTables.Group
— TypeSpecifies one variable to group over and an associated name for display.
SummaryTables.Multiline
— TypeMultiline(args...)
Create a Multiline
object which renders each arg
on a separate line. A Multiline
value may only be used as the top-level value of a cell, so Cell(Multiline(...))
is allowed but Cell(Concat(Multiline(...), ...))
is not.
SummaryTables.Replace
— TypeReplace(f, with)
Replace(f; with)
This postprocessor replaces all cell values for which f(value) === true
with the value with
. If with <: Function
then the new value will be with(value)
, instead.
Examples
Replace(x -> x isa String, "A string was here")
Replace(x -> x isa String, uppercase)
Replace(x -> x isa Int && iseven(x), "An even Int was here")
SummaryTables.Summary
— TypeStores the index of the grouping variable under which the summaries defined in analyses
should be run. An index of 0
means that one summary block is appended after all columns or rows, an index of 1
means on summary block after each group from the first grouping key of rows or columns, and so on.
SummaryTables.SummaryAnalysis
— TypeSpecifies one function to summarize the raw values of one group with, and an associated name for display.
SummaryTables.Table
— Methodfunction Table(cells;
header = nothing,
footer = nothing,
round_digits = 3,
round_mode = :auto,
trailing_zeros = false,
footnotes = [],
postprocess = [],
rowgaps = Pair{Int,Float64}[],
colgaps = Pair{Int,Float64}[],
)
Create a Table
which can be rendered in multiple formats, such as HTML or LaTeX.
Arguments
cells::Vector{SpannedCell}
: The list ofSpannedCell
s that make up the table. No cells may overlap.
Keyword arguments
header
: The index of the last row of the header,nothing
if no header is specified.footer
: The index of the first row of the footer,nothing
if no footer is specified.footnotes
: A vector of objects printed as footnotes that are not derived fromAnnotated
values and therefore don't get labels with counterparts inside the table.round_digits = 3
: Float values will be rounded to this precision before printing.round_mode = :auto
: How the float values are rounded, options are:auto
,:digits
or:sigdigits
. Ifround_mode === nothing
, no rounding will be applied andround_digits
andtrailing_zeros
will have no effect.trailing_zeros = false
: Controls if float values keep trailing zeros, for example4.0
vs4
.postprocess = []
: A list of post-processors which will be applied left to right to the table. A post-processor can either work element-wise or on the whole table object. See thepostprocess_table
andpostprocess_cell
functions for defining custom postprocessors.rowgaps = Pair{Int,Float64}[]
: A list of pairsindex => gap_pt
. For each pair, a visual gap the size ofgap_pt
is added between the rowsindex
andindex+1
.colgaps = Pair{Int,Float64}[]
: A list of pairsindex => gap_pt
. For each pair, a visual gap the size ofgap_pt
is added between the columnsindex
andindex+1
.
Round mode
Consider the numbers 0.006789
, 23.4567
, 456.789
or 12345.0
.
Here is how these numbers are formatted with the different available rounding modes:
:auto
rounds ton
significant digits but doesn't zero out additional digits before the comma unlike:sigdigits
. For example,round_digits = 3
would result in0.00679
,23.5
,457.0
or12345.0
. Numbers at orders of magnitude >= 6 or <= -5 are displayed in exponential notation as in Julia.:digits
rounds ton
digits after the comma and shows possibly multiple trailing zeros. For example,round_digits = 3
would result in0.007
,23.457
or456.789
or12345.000
. Numbers are never shown with exponential notation.:sigdigits
rounds ton
significant digits and zeros out additional digits before the comma unlike:auto
. For example,round_digits = 3
would result in0.00679
,23.5
,457.0
or12300.0
. Numbers at orders of magnitude >= 6 or <= -5 are displayed in exponential notation as in Julia.
SummaryTables.ReplaceMissing
— MethodReplaceMissing(; with = Annotated("-", "- No value"; label = NoLabel()))
This postprocessor replaces all missing
cell values with the value in with
.
SummaryTables.auto_round
— Methodauto_round(number; target_digits)
Rounds a floating point number to a target number of digits that are not leading zeros. For example, with 3 target digits, desirable numbers would be 123.0, 12.3, 1.23, 0.123, 0.0123 etc. Numbers larger than the number of digits are only rounded to the next integer (compare with round(1234, sigdigits = 3)
which rounds to 1230.0
). Numbers are rounded to target_digits
significant digits when the floored base 10 exponent is -5 and lower or 6 and higher, as these numbers print with e
notation by default in Julia.
auto_round( 1234567, target_digits = 4) = 1.235e6
auto_round( 123456.7, target_digits = 4) = 123457.0
auto_round( 12345.67, target_digits = 4) = 12346.0
auto_round( 1234.567, target_digits = 4) = 1235.0
auto_round( 123.4567, target_digits = 4) = 123.5
auto_round( 12.34567, target_digits = 4) = 12.35
auto_round( 1.234567, target_digits = 4) = 1.235
auto_round( 0.1234567, target_digits = 4) = 0.1235
auto_round( 0.01234567, target_digits = 4) = 0.01235
auto_round( 0.001234567, target_digits = 4) = 0.001235
auto_round( 0.0001234567, target_digits = 4) = 0.0001235
auto_round( 0.00001234567, target_digits = 4) = 1.235e-5
auto_round( 0.000001234567, target_digits = 4) = 1.235e-6
auto_round(0.0000001234567, target_digits = 4) = 1.235e-7
SummaryTables.listingtable
— Methodlistingtable(table, variable;
rows = [],
cols = [],
summarize_rows = [],
summarize_cols = [],
variable_header = true,
celltable_kws...
)
Create a listing table Table
from table
which displays raw values from column variable
.
Arguments
table
: Data source which must be convertible to aDataFrames.DataFrame
.variable
: Determines which variable's raw values are shown. Can either be aSymbol
such as:ColumnA
, or alternatively aPair
where the second element is the display name, such as:ColumnA => "Column A"
.
Keyword arguments
rows = []
: Grouping structure along the rows. Should be aVector
where each element is a grouping variable, specified as aSymbol
such as:Column1
, or aPair
, where the first element is the symbol and the second a display name, such as:Column1 => "Column 1"
. Specifying multiple grouping variables creates nested groups, with the last variable changing the fastest.cols = []
: Grouping structure along the columns. Follows the same structure asrows
.summarize_rows = []
: Specifies functions to summarizevariable
with along the rows. Should be aVector
, where each entry is one separate summary. Each summary can be given as aFunction
such asmean
ormaximum
, in which case the display name is the function's name. Alternatively, a display name can be given using the pair syntax, such asmean => "Average"
. By default, one summary is computed over all groups. You can also passSymbol => [...]
whereSymbol
is a grouping column, to compute one summary for each level of that group.summarize_cols = []
: Specifies functions to summarizevariable
with along the columns. Follows the same structure assummarize_rows
.variable_header = true
: Controls if the cell with the name of the summarizedvariable
is shown.sort = true
: Sort the input table before grouping. Pre-sort as desired and set tofalse
when you want to maintain a specific group order or are using non-sortable objects as group keys.
All other keywords are forwarded to the Table
constructor, refer to its docstring for details.
Example
using Statistics
tbl = [
:Apples => [1, 2, 3, 4, 5, 6, 7, 8],
:Batch => [1, 1, 1, 1, 2, 2, 2, 2],
:Checked => [true, false, true, false, true, false, true, false],
:Delivery => ['a', 'a', 'b', 'b', 'a', 'a', 'b', 'b'],
]
listingtable(
tbl,
:Apples => "Number of apples",
rows = [:Batch, :Checked => "Checked for spots"],
cols = [:Delivery],
summarize_cols = [sum => "overall"],
summarize_rows = :Batch => [mean => "average", sum]
)
SummaryTables.postprocess_cell
— Functionpostprocess_cell
Overload postprocess_cell(c::Cell, postprocessor::YourPostProcessor)
to enable using YourPostProcessor
as a cell postprocessor by passing it to the postprocess
keyword argument of Table
.
The function must always return a Cell
. It will be applied on every cell of the table that is being postprocessed, all other table attributes will be left unmodified.
Use postprocess_table
instead if you need to modify table attributes during postprocessing.
SummaryTables.postprocess_table
— Functionpostprocess_table
Overload postprocess_table(t::Table, postprocessor::YourPostProcessor)
to enable using YourPostProcessor
as a table postprocessor by passing it to the postprocess
keyword argument of Table
.
The function must always return a Table
.
Use postprocess_cell
instead if you do not need to modify table attributes during postprocessing but only individual cells.
SummaryTables.summarytable
— Methodsummarytable(table, variable;
rows = [],
cols = [],
summary = [],
variable_header = true,
celltable_kws...
)
Create a summary table Table
from table
, which summarizes values from column variable
.
Arguments
table
: Data source which must be convertible to aDataFrames.DataFrame
.variable
: Determines which variable fromtable
is summarized. Can either be aSymbol
such as:ColumnA
, or alternatively aPair
where the second element is the display name, such as:ColumnA => "Column A"
.
Keyword arguments
rows = []
: Grouping structure along the rows. Should be aVector
where each element is a grouping variable, specified as aSymbol
such as:Column1
, or aPair
, where the first element is the symbol and the second a display name, such as:Column1 => "Column 1"
. Specifying multiple grouping variables creates nested groups, with the last variable changing the fastest.cols = []
: Grouping structure along the columns. Follows the same structure asrows
.summary = []
: Specifies functions to summarizevariable
with. Should be aVector
, where each entry is one separate summary. Each summary can be given as aFunction
such asmean
ormaximum
, in which case the display name is the function's name. Alternatively, a display name can be given using the pair syntax, such asmean => "Average"
. By default, one summary is computed over all groups. You can also passSymbol => [...]
whereSymbol
is a grouping column, to compute one summary for each level of that group.variable_header = true
: Controls if the cell with the name of the summarizedvariable
is shown.sort = true
: Sort the input table before grouping. Pre-sort as desired and set tofalse
when you want to maintain a specific group order or are using non-sortable objects as group keys.
All other keywords are forwarded to the Table
constructor, refer to its docstring for details.
Example
using Statistics
tbl = [
:Apples => [1, 2, 3, 4, 5, 6, 7, 8],
:Batch => [1, 1, 1, 1, 2, 2, 2, 2],
:Delivery => ['a', 'a', 'b', 'b', 'a', 'a', 'b', 'b'],
]
summarytable(
tbl,
:Apples => "Number of apples",
rows = [:Batch],
cols = [:Delivery],
summary = [length => "N", mean => "average", sum]
)
SummaryTables.table_one
— Methodtable_one(table, analyses; keywords...)
Construct a "Table 1" which summarises the patient baseline characteristics from the provided table
dataset. This table is commonly used in biomedical research papers.
It can handle both continuous and categorical columns in table
and summary statistics and hypothesis testing are able to be customised by the user. Tables can be stratified by one, or more, variables using the groupby
keyword.
Keywords
groupby
: Which columns to stratify the dataset with, as aVector{Symbol}
.nonnormal
: A vector of column names where hypothesis tests for the:nonnormal
type are chosen.minmax
: A vector of column names where hypothesis tests for the:minmax
type are chosen.tests
: aNamedTuple
of hypothesis test types to use forcategorical
,nonnormal
,minmax
, andnormal
variables.combine
: an object fromMultipleTesting
to use when combining p-values.show_overall
: display the "Overall" column summary. Default istrue
.show_n
: Display the number of rows for each group key next to its label.show_pvalues
: display theP-Value
column. Default isfalse
.show_testnames
: display theTest
column. Default isfalse
.show_confints
: display theCI
column. Default isfalse
.sort
: Sort the input table before grouping. Default istrue
. Pre-sort as desired and set tofalse
when you want to maintain a specific group order or are using non-sortable objects as group keys.
All other keywords are forwarded to the Table
constructor, refer to its docstring for details.
SummaryTables.to_docx
— Methodto_docx(ct::Table)
Creates a WriteDocx.Table
node for Table
ct
which can be inserted into a WriteDocx
document.
Note that you also have to insert the styles from SummaryTables.docx_styles()
to the style section of the WriteDocx
document.