API
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:
Multilinefor content broken over multiple lines in a cell. This object may not be used nested in other values, only as the top-level value.Concatfor stringing together multiple values without having to interpolate them into aString, which keeps their own special behaviors intact.SuperscriptandSubscriptAnnotatedfor a value with an optional superscript label and a footnote annotation.
SummaryTables.CellStyle — TypeCellStyle(;
+API · SummaryTables.jl API
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.
sourceSummaryTables.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 a String, which keeps their own special behaviors intact.Superscript and SubscriptAnnotated for a value with an optional superscript label and a footnote annotation.
sourceSummaryTables.CellStyle — TypeCellStyle(;
bold::Bool = false,
italic::Bool = false,
underline::Bool = false,
@@ -10,15 +10,15 @@
border_bottom::Bool = false,
merge::Bool = false,
mergegroup::UInt8 = 0,
-)
Create a CellStyle object which determines the visual appearance of Cells.
Keyword arguments:
bold renders text bold if true.italic renders text italic if true.underline underlines text if true.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 if true.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.
sourceSummaryTables.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(
+)
Create a CellStyle object which determines the visual appearance of Cells.
Keyword arguments:
bold renders text bold if true.italic renders text italic if true.underline underlines text if true.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 if true.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.
sourceSummaryTables.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"
sourceSummaryTables.Group — TypeSpecifies one variable to group over and an associated name for display.
sourceSummaryTables.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 of column_name => group_value pairs.
sourceSummaryTables.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.
sourceSummaryTables.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.
sourceSummaryTables.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 chosen Pagination.metadata::M: Information about which part of the full table this page contains. This is different for each table function that takes a Pagination argument because each such function may use its own logic for how to split pages.
sourceSummaryTables.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}}: Each Page holds a table and metadata of type M which depends on the table function that creates the PaginatedTable.
To get the table of page 2, for a PaginatedTable stored in variable p, access p.pages[2].table.
sourceSummaryTables.Replace — TypeReplace(f, with)
+# will be rendered as "Some text and an annotated¹ value"
sourceSummaryTables.Group — TypeSpecifies one variable to group over and an associated name for display.
sourceSummaryTables.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 of column_name => group_value pairs.
sourceSummaryTables.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.
sourceSummaryTables.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.
sourceSummaryTables.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 chosen Pagination.metadata::M: Information about which part of the full table this page contains. This is different for each table function that takes a Pagination argument because each such function may use its own logic for how to split pages.
sourceSummaryTables.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}}: Each Page holds a table and metadata of type M which depends on the table function that creates the PaginatedTable.
To get the table of page 2, for a PaginatedTable stored in variable p, access p.pages[2].table.
sourceSummaryTables.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")
sourceSummaryTables.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.
sourceSummaryTables.SummaryAnalysis — TypeSpecifies one function to summarize the raw values of one group with, and an associated name for display.
sourceSummaryTables.Table — Methodfunction Table(cells;
+Replace(x -> x isa Int && iseven(x), "An even Int was here")
sourceSummaryTables.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.
sourceSummaryTables.SummaryAnalysis — TypeSpecifies one function to summarize the raw values of one group with, and an associated name for display.
sourceSummaryTables.Table — Methodfunction Table(cells;
header = nothing,
footer = nothing,
round_digits = 3,
@@ -29,7 +29,7 @@
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 of Cells 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 from Annotated 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. If round_mode === nothing, no rounding will be applied and round_digits and trailing_zeros will have no effect.trailing_zeros = false: Controls if float values keep trailing zeros, for example 4.0 vs 4.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 the postprocess_table and postprocess_cell functions for defining custom postprocessors.rowgaps = Pair{Int,Float64}[]: A list of pairs index => gap_pt. For each pair, a visual gap the size of gap_pt is added between the rows index and index+1.colgaps = Pair{Int,Float64}[]: A list of pairs index => gap_pt. For each pair, a visual gap the size of gap_pt is added between the columns index and index+1.linebreak_footnotes = true: If true, 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 to n significant digits but doesn't zero out additional digits before the comma unlike :sigdigits. For example, round_digits = 3 would result in 0.00679, 23.5, 457.0 or 12345.0. Numbers at orders of magnitude >= 6 or <= -5 are displayed in exponential notation as in Julia.:digits rounds to n digits after the comma and shows possibly multiple trailing zeros. For example, round_digits = 3 would result in 0.007, 23.457 or 456.789 or 12345.000. Numbers are never shown with exponential notation.:sigdigits rounds to n significant digits and zeros out additional digits before the comma unlike :auto. For example, round_digits = 3 would result in 0.00679, 23.5, 457.0 or 12300.0. Numbers at orders of magnitude >= 6 or <= -5 are displayed in exponential notation as in Julia.
sourceSummaryTables.ReplaceMissing — MethodReplaceMissing(; with = Annotated("-", "- No value"; label = NoLabel()))
This postprocessor replaces all missing cell values with the value in with.
sourceSummaryTables.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
+)
Create a Table which can be rendered in multiple formats, such as HTML or LaTeX.
Arguments
cells::AbstractMatrix{<:Cell}: The matrix of Cells 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 from Annotated 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. If round_mode === nothing, no rounding will be applied and round_digits and trailing_zeros will have no effect.trailing_zeros = false: Controls if float values keep trailing zeros, for example 4.0 vs 4.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 the postprocess_table and postprocess_cell functions for defining custom postprocessors.rowgaps = Pair{Int,Float64}[]: A list of pairs index => gap_pt. For each pair, a visual gap the size of gap_pt is added between the rows index and index+1.colgaps = Pair{Int,Float64}[]: A list of pairs index => gap_pt. For each pair, a visual gap the size of gap_pt is added between the columns index and index+1.linebreak_footnotes = true: If true, 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 to n significant digits but doesn't zero out additional digits before the comma unlike :sigdigits. For example, round_digits = 3 would result in 0.00679, 23.5, 457.0 or 12345.0. Numbers at orders of magnitude >= 6 or <= -5 are displayed in exponential notation as in Julia.:digits rounds to n digits after the comma and shows possibly multiple trailing zeros. For example, round_digits = 3 would result in 0.007, 23.457 or 456.789 or 12345.000. Numbers are never shown with exponential notation.:sigdigits rounds to n significant digits and zeros out additional digits before the comma unlike :auto. For example, round_digits = 3 would result in 0.00679, 23.5, 457.0 or 12300.0. Numbers at orders of magnitude >= 6 or <= -5 are displayed in exponential notation as in Julia.
sourceSummaryTables.ReplaceMissing — MethodReplaceMissing(; with = Annotated("-", "- No value"; label = NoLabel()))
This postprocessor replaces all missing cell values with the value in with.
sourceSummaryTables.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
@@ -42,7 +42,7 @@
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
sourceSummaryTables.listingtable — Functionlistingtable(table, variable, [pagination];
+auto_round(0.0000001234567, target_digits = 4) = 1.235e-7
sourceSummaryTables.listingtable — Functionlistingtable(table, variable, [pagination];
rows = [],
cols = [],
summarize_rows = [],
@@ -65,7 +65,7 @@
cols = [:Delivery],
summarize_cols = [sum => "total"],
summarize_rows = :Batch => [mean => "average", sum]
-)
sourceSummaryTables.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.
sourceSummaryTables.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.
sourceSummaryTables.summarytable — Methodsummarytable(table, variable;
+)
sourceSummaryTables.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.
sourceSummaryTables.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.
sourceSummaryTables.summarytable — Methodsummarytable(table, variable;
rows = [],
cols = [],
summary = [],
@@ -85,4 +85,4 @@
rows = [:Batch],
cols = [:Delivery],
summary = [length => "N", mean => "average", sum]
-)
sourceSummaryTables.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 a Vector{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: A NamedTuple of hypothesis test types to use for categorical, nonnormal, minmax, and normal variables.combine: An object from MultipleTesting to use when combining p-values.show_total: Display the total column summary. Default is true.group_totals: A group Symbol 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 the show_total option). Default is Symbol[].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 the P-Value column. Default is false.show_testnames: Display the Test column. Default is false.show_confints: Display the CI column. Default is false.sort: Sort the input table before grouping. Default is true. Pre-sort as desired and set to false when you want to maintain a specific group order or are using non-sortable objects as group keys.
Deprecated keywords
show_overall: Use show_total instead
All other keywords are forwarded to the Table constructor, refer to its docstring for details.
sourceSummaryTables.to_docx — Methodto_docx(ct::Table)
Creates a WriteDocx.Table node for Table ct which can be inserted into a WriteDocx document.
sourceSettings
This document was generated with Documenter.jl version 1.7.0 on Monday 23 September 2024. Using Julia version 1.10.5.
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:nonnormaltype are chosen.minmax: A vector of column names where hypothesis tests for the:minmaxtype are chosen.tests: ANamedTupleof hypothesis test types to use forcategorical,nonnormal,minmax, andnormalvariables.combine: An object fromMultipleTestingto use when combining p-values.show_total: Display the total column summary. Default istrue.group_totals: A groupSymbolor 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_totaloption). 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-Valuecolumn. Default isfalse.show_testnames: Display theTestcolumn. Default isfalse.show_confints: Display theCIcolumn. Default isfalse.sort: Sort the input table before grouping. Default istrue. Pre-sort as desired and set tofalsewhen you want to maintain a specific group order or are using non-sortable objects as group keys.
Deprecated keywords
show_overall: Useshow_totalinstead
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.