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.GroupKey
— TypeGroupKey
Holds the group column names and values for one group of a dataset. This struct has only one field:
entries::Vector{Pair{Symbol,Any}}
: A vector ofcolumn_name => group_value
pairs.
SummaryTables.ListingPageMetadata
— TypeListingPageMetadata
Describes which row and column group sections of a full listing table are included in a given page. There are two fields:
rows::Vector{GroupKey}
cols::Vector{GroupKey}
Each Vector{GroupKey}
holds all group keys that were relevant for pagination along that side of the listing table. A vector is empty if the table was not paginated along that side.
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.Page
— TypePage{M}
Represents one page of a PaginatedTable
.
It has two public fields:
table::Table
: A part of the full table, created according to the chosenPagination
.metadata::M
: Information about which part of the full table this page contains. This is different for each table function that takes aPagination
argument because each such function may use its own logic for how to split pages.
SummaryTables.PaginatedTable
— TypePaginatedTable{M}
The return type for all table functions that take a Pagination
argument to split the table into pages according to table-specific pagination rules.
This type only has one field:
pages::Vector{Page{M}}
: EachPage
holds a table and metadata of typeM
which depends on the table function that creates thePaginatedTable
.
To get the table of page 2, for a PaginatedTable
stored in variable p
, access p.pages[2].table
.
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}[],
linebreak_footnotes = true,
)
Create a Table
which can be rendered in multiple formats, such as HTML or LaTeX.
Arguments
cells::AbstractMatrix{<:Cell}
: The matrix ofCell
s that make up the table.
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 before displaying 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
.linebreak_footnotes = true
: Iftrue
, each footnote and annotation starts on a separate line.
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
— Functionlistingtable(table, variable, [pagination];
rows = [],
cols = [],
summarize_rows = [],
summarize_cols = [],
variable_header = true,
table_kwargs...
)
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"
.pagination::Pagination
: If a pagination object is passed, the return type changes toPaginatedTable
. ThePagination
object may be created with keywordsrows
and/orcols
. These must be set toInt
s that determine how many group sections along each side are included in one page. These group sections are determined by the summary structure, because pagination never splits a listing table within rows or columns that are being summarized together. Ifsummarize_rows
orsummarize_cols
is empty or unset, each group along that side is its own section. Ifsummarize_rows
orsummarize_cols
has a group passed via thecolumn => ...
syntax, the group sections along that side are determined bycolumn
. If no suchcolumn
is passed (i.e., the summary along that side applies to the all groups) there is only one section along that side, which means that this side cannot be paginated into more than one page.
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 => "total"],
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_total
: Display the total column summary. Default istrue
.group_totals
: A groupSymbol
or vector of symbols specifying for which group levels totals should be added. Any group levels but the topmost can be chosen (the topmost being already handled by theshow_total
option). Default isSymbol[]
.total_name
: The name for all total columns. Default is"Total"
.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.
Deprecated keywords
show_overall
: Useshow_total
instead
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.