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(;
+ 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 Cells.
Keyword arguments:
boldrenders textboldiftrue.italicrenders textitaliciftrue.underlineunderlines text iftrue.haligndetermines the horizontal alignment within the cell, either:left,:centeror:right.valigndetermines the vertical alignment within the cell, either:top,:centeror:bottom.indent_ptadds left indentation in points to the cell text.border_bottomadds a bottom border to the cell iftrue.mergecauses adjacent cells which are==equal to be rendered as a single merged cell.mergegroupis 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 — TypeGroupKeyHolds 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_valuepairs.
SummaryTables.ListingPageMetadata — TypeListingPageMetadataDescribes 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 aPaginationargument 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}}: EachPageholds a table and metadata of typeMwhich 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 ofCells that make up the table.
Keyword arguments
header: The index of the last row of the header,nothingif no header is specified.footer: The index of the first row of the footer,nothingif no footer is specified.footnotes: A vector of objects printed as footnotes that are not derived fromAnnotatedvalues 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,:digitsor:sigdigits. Ifround_mode === nothing, no rounding will be applied andround_digitsandtrailing_zeroswill have no effect.trailing_zeros = false: Controls if float values keep trailing zeros, for example4.0vs4.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_tableandpostprocess_cellfunctions for defining custom postprocessors.rowgaps = Pair{Int,Float64}[]: A list of pairsindex => gap_pt. For each pair, a visual gap the size ofgap_ptis added between the rowsindexandindex+1.colgaps = Pair{Int,Float64}[]: A list of pairsindex => gap_pt. For each pair, a visual gap the size ofgap_ptis added between the columnsindexandindex+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:
:autorounds tonsignificant digits but doesn't zero out additional digits before the comma unlike:sigdigits. For example,round_digits = 3would result in0.00679,23.5,457.0or12345.0. Numbers at orders of magnitude >= 6 or <= -5 are displayed in exponential notation as in Julia.:digitsrounds tondigits after the comma and shows possibly multiple trailing zeros. For example,round_digits = 3would result in0.007,23.457or456.789or12345.000. Numbers are never shown with exponential notation.:sigdigitsrounds tonsignificant digits and zeros out additional digits before the comma unlike:auto. For example,round_digits = 3would result in0.00679,23.5,457.0or12300.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-7SummaryTables.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 aSymbolsuch as:ColumnA, or alternatively aPairwhere 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. ThePaginationobject may be created with keywordsrowsand/orcols. These must be set toInts 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_rowsorsummarize_colsis empty or unset, each group along that side is its own section. Ifsummarize_rowsorsummarize_colshas a group passed via thecolumn => ...syntax, the group sections along that side are determined bycolumn. If no suchcolumnis 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 aVectorwhere each element is a grouping variable, specified as aSymbolsuch 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 summarizevariablewith along the rows. Should be aVector, where each entry is one separate summary. Each summary can be given as aFunctionsuch asmeanormaximum, 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 => [...]whereSymbolis a grouping column, to compute one summary for each level of that group.summarize_cols = []: Specifies functions to summarizevariablewith along the columns. Follows the same structure assummarize_rows.variable_header = true: Controls if the cell with the name of the summarizedvariableis shown.sort = true: Sort the input table before grouping. Pre-sort as desired and set tofalsewhen 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_cellOverload 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_tableOverload 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 fromtableis summarized. Can either be aSymbolsuch as:ColumnA, or alternatively aPairwhere the second element is the display name, such as:ColumnA => "Column A".
Keyword arguments
rows = []: Grouping structure along the rows. Should be aVectorwhere each element is a grouping variable, specified as aSymbolsuch 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 summarizevariablewith. Should be aVector, where each entry is one separate summary. Each summary can be given as aFunctionsuch asmeanormaximum, 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 => [...]whereSymbolis 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 summarizedvariableis shown.sort = true: Sort the input table before grouping. Pre-sort as desired and set tofalsewhen 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: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.
![](\"./../assets/icon_pdf.png\"){kind=icon}
","category":"page"},{"location":"output/#docx","page":"Output","title":"docx","text":"","category":"section"},{"location":"output/","page":"Output","title":"Output","text":"To get docx output, you need to use the WriteDocx.jl package because this format is not plain-text like LaTeX or HTML. The table node you get out of the to_docx function can be placed into sections on the same level as paragraphs.","category":"page"},{"location":"output/","page":"Output","title":"Output","text":"using SummaryTables\nusing DataFrames\nimport WriteDocx as W\n\n\nmkpath(joinpath(@__DIR__, \"outputs\"))\n\ndata = DataFrame(\n sex = [\"m\", \"m\", \"m\", \"m\", \"f\", \"f\", \"f\", \"f\", \"f\", \"f\"],\n age = [27, 45, 34, 85, 55, 44, 24, 29, 37, 76],\n blood_type = [\"A\", \"0\", \"B\", \"B\", \"B\", \"A\", \"0\", \"A\", \"A\", \"B\"],\n smoker = [true, false, false, false, true, true, true, false, false, false],\n)\n\ntbl = table_one(\n data,\n [:age => \"Age (years)\", :blood_type => \"Blood type\", :smoker => \"Smoker\"],\n groupby = :sex => \"Sex\",\n show_n = true\n)\n\ndoc = W.Document(\n W.Body([\n W.Section([\n SummaryTables.to_docx(tbl)\n ])\n ])\n )\n\nW.save(joinpath(@__DIR__, \"outputs\", \"example.docx\"), doc)\n\nnothing # hide","category":"page"},{"location":"output/","page":"Output","title":"Output","text":"Download example.docx:","category":"page"},{"location":"output/","page":"Output","title":"Output","text":"![](\"./../assets/icon_docx.png\"){kind=icon}
","category":"page"},{"location":"output/#Typst","page":"Output","title":"Typst","text":"","category":"section"},{"location":"output/","page":"Output","title":"Output","text":"You can print Typst table code to any IO via show(io, MIME\"text/typst\", table). From SummaryTables v2.0 on, the Typst backend is using the native table functionality in Typst v0.11. Previous versions used the tablex package.","category":"page"},{"location":"output/","page":"Output","title":"Output","text":"using SummaryTables\nusing DataFrames\nusing Typst_jll\n\n\nmkpath(joinpath(@__DIR__, \"outputs\"))\n\ndata = DataFrame(\n sex = [\"m\", \"m\", \"m\", \"m\", \"f\", \"f\", \"f\", \"f\", \"f\", \"f\"],\n age = [27, 45, 34, 85, 55, 44, 24, 29, 37, 76],\n blood_type = [\"A\", \"0\", \"B\", \"B\", \"B\", \"A\", \"0\", \"A\", \"A\", \"B\"],\n smoker = [true, false, false, false, true, true, true, false, false, false],\n)\n\ntbl = table_one(\n data,\n [:age => \"Age (years)\", :blood_type => \"Blood type\", :smoker => \"Smoker\"],\n groupby = :sex => \"Sex\",\n show_n = true\n)\n\n# render latex in a temp directory\nmktempdir() do dir\n typfile = joinpath(dir, \"example.typ\")\n\n open(typfile, \"w\") do io\n # print the table as latex code\n show(io, MIME\"text/typst\"(), tbl)\n end\n\n # render the tex file to pdf\n Typst_jll.typst() do bin\n run(`$bin compile $typfile`)\n end\n\n cp(joinpath(dir, \"example.pdf\"), joinpath(@__DIR__, \"outputs\", \"example_typst.pdf\"))\nend\n\nnothing # hide","category":"page"},{"location":"output/","page":"Output","title":"Output","text":"Download example_typst.pdf:","category":"page"},{"location":"output/","page":"Output","title":"Output","text":"