diff --git a/docs/configuration.md b/docs/configuration.md index c05e155..4688561 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -110,27 +110,27 @@ parameters. The following table shows the parameter alternatives between these t of given function. For example, instead of values `yes` and `no`, the functions usually use Boolean values `True` and `False`. -| `config.ini` key | CLI argument | Function argument | Description | -|---------------------------|-----------------------------|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `toc` | `--toc ` | _N/A_ | Include table of contents. It is included only when there are any headings. Allowed values: `yes`, `no`. | -| `align-tables` | `--align-tables` | `align` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Horizontal alignment of tables. Allowed values: `left`, `center`, `right`. | -| `table-captions-position` | `--table-captions-position` | `caption_position` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Caption position. Allowed values: `top`, `bottom`. | -| `numbered-tables` | `--numbered-tables` | `numbered` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Whether to number tables. Allowed values: `yes`, `no`. | -| `tables-display-option` | `--tables-display-option` | `display_option` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | How to display table. This option is useful for long tables, which should not be displayed fully. Allowed values are: `full` (show the full table), `scrolling` (show the table in scrolling mode on y-axis), `paging` (show the table in paging mode). | -| `tables-paging-sizes` | `--tables-paging-sizes` | `paging_sizes` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | The paging sizes that can be selected. Ignored when `tables-display-option` is not `paging`. Allowed values are integers and string `all` (no matter the case of letters), written as a non-empty comma-separated list. | -| `tables-scroll-y-height` | `--tables-scroll-y-height` | `scroll_y_height` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Height of the tables when `tables-display-option` is set to `scrolling`. Any string compatible with CSS sizing can be used, e.g. `300px`, `20em`, etc. | -| `tables-scroll-x` | `--tables-scroll-x` | `scroll_x` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Whether to allow scrolling on the x-axis. If turned off, a wide table is allowed to overflow the main container. It is recommended to turn this on, especially with `tables-display-option` set to `scrolling`, because otherwise the table header won't interact properly when scrolling horizontally. Allowed values: `yes`, `no`. | -| `sortable-tables` | `--sortable-tables` | `sortable` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Whether to make columns in tables sortable. Allowed values: `yes`, `no`. | -| `tables-search-box` | `--tables-search-box` | `show_search_box` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Whether to show the search box for the tables. Allowed values: `yes`, `no`. | -| `tables-datatables-style` | `--tables-datatables-style` | `datatables_style` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Datatables class(es) that affect the tables styling. If multiple classes are provided, separate them either with commas or spaces. See [DataTables documentation](https://datatables.net/manual/styling/classes) with the possible values. | -| `align-plots` | `--align-plots` | `align` in [`plot_graph()`](../api/pyreball_html/#pyreball.html.plot_graph) | Horizontal alignment of plots. Allowed values: `left`, `center`, `right`. | -| `plot-captions-position` | `--plot-captions-position` | `caption_position` in [`plot_graph()`](../api/pyreball_html/#pyreball.html.plot_graph) | Caption position. Allowed values: `top`, `bottom`. | -| `numbered-plots` | `--numbered-plots` | `numbered` in [`plot_graph()`](../api/pyreball_html/#pyreball.html.plot_graph) | Whether to number plots. Allowed values: `yes`, `no`. | -| `matplotlib-format` | `--matplotlib-format` | `matplotlib_format` in [`plot_graph()`](../api/pyreball_html/#pyreball.html.plot_graph) | Format of matplotlib (and thus also seaborn) plots. Allowed values: `png`, `svg`. | -| `matplotlib-embedded` | `--matplotlib-embedded` | `embedded` in [`plot_graph()`](../api/pyreball_html/#pyreball.html.plot_graph) | Whether to embedded matplotlib (and thus also seaborn) plots directly into HTML. Only for svg format. Allowed values: `yes`, `no`. | -| `numbered-headings` | `--numbered-headings` | _N/A_ | Whether to number headings. Allowed values: `yes`, `no`. | -| `page-width` | `--page-width` | _N/A_ | Width of the page container in percentage. Allowed values: An integer in the range 40..100. | -| `keep-stdout` | `--keep-stdout` | _N/A_ | Whether to print the output to stdout too: `yes`, `no`. | +| `config.ini` key | CLI argument | Function argument | Description | +|---------------------------|-----------------------------|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `toc` | `--toc ` | _N/A_ | Include table of contents. It is included only when there are any headings. Allowed values: `yes`, `no`. | +| `align-tables` | `--align-tables` | `align` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Horizontal alignment of tables. Allowed values: `left`, `center`, `right`. | +| `table-captions-position` | `--table-captions-position` | `caption_position` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Caption position. Allowed values: `top`, `bottom`. | +| `numbered-tables` | `--numbered-tables` | `numbered` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Whether to number tables. Allowed values: `yes`, `no`. | +| `tables-display-option` | `--tables-display-option` | `display_option` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | How to display table. This option is useful for long tables, which should not be displayed fully. Allowed values are: `full` (show the full table), `scrolling` (show the table in scrolling mode on y-axis), `paging` (show the table in paging mode). | +| `tables-paging-sizes` | `--tables-paging-sizes` | `paging_sizes` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | The paging sizes that can be selected. Ignored when `tables-display-option` is not `paging`. Allowed values are integers and string `all` (no matter the case of letters), written as a non-empty comma-separated list. | +| `tables-scroll-y-height` | `--tables-scroll-y-height` | `scroll_y_height` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Height of the tables when `tables-display-option` is set to `scrolling`. Any string compatible with CSS sizing can be used, e.g. `300px`, `20em`, etc. | +| `tables-scroll-x` | `--tables-scroll-x` | `scroll_x` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Whether to allow scrolling on the x-axis. If turned off, a wide table is allowed to overflow the main container. It is recommended to turn this on. Allowed values: `yes`, `no`. | +| `sortable-tables` | `--sortable-tables` | `sortable` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Whether to make columns in tables sortable. Allowed values: `yes`, `no`. | +| `tables-search-box` | `--tables-search-box` | `show_search_box` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Whether to show the search box for the tables. Allowed values: `yes`, `no`. | +| `tables-datatables-style` | `--tables-datatables-style` | `datatables_style` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Datatables class(es) that affect the tables styling. If multiple classes are provided, separate them either with commas or spaces. See [DataTables documentation](https://datatables.net/manual/styling/classes) with the possible values. | +| `align-plots` | `--align-plots` | `align` in [`plot_graph()`](../api/pyreball_html/#pyreball.html.plot_graph) | Horizontal alignment of plots. Allowed values: `left`, `center`, `right`. | +| `plot-captions-position` | `--plot-captions-position` | `caption_position` in [`plot_graph()`](../api/pyreball_html/#pyreball.html.plot_graph) | Caption position. Allowed values: `top`, `bottom`. | +| `numbered-plots` | `--numbered-plots` | `numbered` in [`plot_graph()`](../api/pyreball_html/#pyreball.html.plot_graph) | Whether to number plots. Allowed values: `yes`, `no`. | +| `matplotlib-format` | `--matplotlib-format` | `matplotlib_format` in [`plot_graph()`](../api/pyreball_html/#pyreball.html.plot_graph) | Format of matplotlib (and thus also seaborn) plots. Allowed values: `png`, `svg`. | +| `matplotlib-embedded` | `--matplotlib-embedded` | `embedded` in [`plot_graph()`](../api/pyreball_html/#pyreball.html.plot_graph) | Whether to embedded matplotlib (and thus also seaborn) plots directly into HTML. Only for svg format. Allowed values: `yes`, `no`. | +| `numbered-headings` | `--numbered-headings` | _N/A_ | Whether to number headings. Allowed values: `yes`, `no`. | +| `page-width` | `--page-width` | _N/A_ | Width of the page container in percentage. Allowed values: An integer in the range 40..100. | +| `keep-stdout` | `--keep-stdout` | _N/A_ | Whether to print the output to stdout too: `yes`, `no`. | The reason for having multiple options for setting these values is to allow the user to set some properties globally, while others locally as needed for particular scripts. diff --git a/docs/examples/references.py b/docs/examples/references.py index b79ad87..168b87e 100644 --- a/docs/examples/references.py +++ b/docs/examples/references.py @@ -14,7 +14,7 @@ N = 10 np.random.seed(1) df = pd.DataFrame({"x": np.arange(1, N + 1), "y": np.random.random(N) * 4 + 3}) -pb.print_table(df, caption="A data table.") +pb.print_table(df, caption="A data table.", index=False) img_reference = pb.Reference() table_ref = pb.Reference() @@ -28,11 +28,18 @@ f"For example, here is a link to {img_reference('Scatterplot')}." ) pb.print_table( - df, caption="A sortable table with a reference", reference=table_ref, sortable=True + df, + caption="A sortable table with a reference", + reference=table_ref, + sortable=True, + index=False, ) pb.print_table( - df, caption="A table sorted by y column", sorting_definition=("y", "asc") + df, + caption="A table sorted by y column", + sorting_definition=[(df.columns.get_loc("y"), "asc")], + index=False, ) pb.print_h1("Charts") diff --git a/docs/examples/table_captions.py b/docs/examples/table_captions.py index 2b3b9b2..3b7442a 100644 --- a/docs/examples/table_captions.py +++ b/docs/examples/table_captions.py @@ -10,7 +10,4 @@ pb.print_table(df, caption="People with their age.") pb.print_table(df, caption="People with their age.", numbered=False) pb.print_table(df, numbered=False) -pb.print_table( - df, - caption="The table with numbering again. But much bigger caption.", -) +pb.print_table(df, caption="The table with numbering again.") diff --git a/docs/examples/table_datatables_definition.py b/docs/examples/table_datatables_definition.py new file mode 100644 index 0000000..3233af5 --- /dev/null +++ b/docs/examples/table_datatables_definition.py @@ -0,0 +1,19 @@ +import pandas as pd +import pyreball as pb + +df = pd.DataFrame( + [[row * 20 + col for col in range(20)] for row in range(40)], + columns=[f"col_{i}" for i in range(20)], +) +datatables_definition = { + "paging": False, + "scrollCollapse": True, + "scrollY": "400px", + "searching": False, + "order": [(1, "desc")], +} +pb.print_table( + df, + caption="Larger table with custom config.", + datatables_definition=datatables_definition, +) diff --git a/docs/examples/table_paging.py b/docs/examples/table_paging.py new file mode 100644 index 0000000..f88fa87 --- /dev/null +++ b/docs/examples/table_paging.py @@ -0,0 +1,13 @@ +import pandas as pd +import pyreball as pb + +df = pd.DataFrame( + [[row * 20 + col for col in range(20)] for row in range(40)], + columns=[f"col_{i}" for i in range(20)], +) +pb.print_table( + df, + caption="Larger table with paging.", + display_option="paging", + paging_sizes=[5, 10, "All"], +) diff --git a/docs/examples/table_scrolling.py b/docs/examples/table_scrolling.py new file mode 100644 index 0000000..0bed5bc --- /dev/null +++ b/docs/examples/table_scrolling.py @@ -0,0 +1,13 @@ +import pandas as pd +import pyreball as pb + +df = pd.DataFrame( + [[row * 20 + col for col in range(20)] for row in range(40)], + columns=[f"col_{i}" for i in range(20)], +) +pb.print_table( + df, + caption="Larger table with scrolling.", + display_option="scrolling", + scroll_y_height="500px", +) diff --git a/docs/examples/table_searching.py b/docs/examples/table_searching.py new file mode 100644 index 0000000..67e1642 --- /dev/null +++ b/docs/examples/table_searching.py @@ -0,0 +1,14 @@ +import pandas as pd +import pyreball as pb + +df = pd.DataFrame( + { + "name": ["Bob", "Carol", "Alice", "Dave"], + "age": [23, 5, 22, 54], + } +) +pb.print_table( + df, + caption="Table with a search box.", + show_search_box=True, +) diff --git a/docs/examples/table_sorting.py b/docs/examples/table_sorting.py index 6ad5219..b7a679c 100644 --- a/docs/examples/table_sorting.py +++ b/docs/examples/table_sorting.py @@ -18,3 +18,9 @@ caption="Table sorted by name (ASC) and age (DESC).", sorting_definition=[(1, "asc"), (2, "desc")], ) +pb.print_table( + df, + caption="The same table, but without the index.", + index=False, + sorting_definition=[(0, "asc"), (1, "desc")], +) diff --git a/docs/examples/table_styling.py b/docs/examples/table_styling.py new file mode 100644 index 0000000..c937b5e --- /dev/null +++ b/docs/examples/table_styling.py @@ -0,0 +1,19 @@ +import pandas as pd +import pyreball as pb + +df = pd.DataFrame( + { + "name": ["Bob", "Carol", "Alice", "Dave"], + "age": [23, 5, 22, 54], + } +) +pb.print_table( + df, + caption="Style set to 'compact'.", + datatables_style="compact", +) +pb.print_table( + df, + caption="Style set to 'compact' and 'display'.", + datatables_style=["compact", "display"], +) diff --git a/docs/tables.md b/docs/tables.md index ed30a63..1e35ec3 100644 --- a/docs/tables.md +++ b/docs/tables.md @@ -1,11 +1,12 @@ # Tables Pyreball allows printing [pandas DataFrame](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html) objects -into HTML tables by using [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) function. +into HTML tables with [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) function. +Moreover, Pyreball uses [DataTables](https://datatables.net/) library to add styling and interactivity to the tables. ## Basic Usage -The simplest usage is to provide just the `DataFrame` object: +The simplest usage is to provide just a `DataFrame` object: {{ inline_source("docs/examples/table_simplest.py") }} @@ -14,18 +15,21 @@ The simplest usage is to provide just the `DataFrame` object: ## Captions All tables are numbered by default, which causes creation of `Table 1.` table caption above. -It is possible to provide custom caption via `caption` parameter, as well as to control the numbering of form `Table k.` -via `numbered` parameter. +It is possible to provide custom caption text via `caption` parameter. +To control whether `Table k.` prefix should be displayed, one can use `numbered` Boolean parameter. {{ inline_source("docs/examples/table_captions.py") }} -Note that internally all tables are numbered, even though the numbering might be turned off. +!!! note + + All tables are internally numbered, even though the numbering might be turned off for specific tables, as shown + in the previous example. ## Caption Position -By default, the caption is positioned at the top of the table. +By default, the caption is positioned above the table. The position can be controlled by `caption_position` parameter, which can be set either to `top` or `bottom`., {{ inline_source("docs/examples/table_caption_position.py") }} @@ -54,21 +58,69 @@ The following snippet shows the usage of both parameters. !!! note Although the columns in `sorting_definition` are indexed from 0, it is necessary to take into account - also the index when it is displayed. To hide the index, set `index` parameter + also the table index when it is displayed. To hide the index, set `index` parameter of [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) method to `False`. - `index` parameter is one of the `kwargs` that are passed to pandas `to_html()` method. + `index` parameter is one of the `kwargs` parameters that are passed to pandas `to_html()` method. {{ inline_source("docs/examples/table_sorting.py") }} - + ## Dealing with Large Tables -TBD +Each table is fully displayed by default. This is caused by `display_option` parameter's default value `full`. +However, this might not be practical for large tables. + +One solution is to allow vertical scrolling of the table by setting `display_option` to `scrolling`. +To change the default height of the table, set also `scroll_y_height` parameter. + +{{ inline_source("docs/examples/table_scrolling.py") }} + + + +!!! note + + By default, Pyreball turns on horizontall scrolling on each table as can be seen in the previous example. + You can turn it off by setting, `scroll_x` parameter to `False`, which might cause the table to overflow + the container. + +Another option is to set `display_option` to `paging`. This option can be further customized by providing custom page +sizes through `paging_sizes` parameter. Currently, `paging_sizes` takes a list of integers mixed with string `All` (the +case of the letters does nto matter, so it can be `all` or `ALL` as well). When `All` is used, Pyreball interprets it as +showing all entries on a single page. + +{{ inline_source("docs/examples/table_paging.py") }} + + + +## Searching + +To allow searching within a table, just set `show_search_box` to `True`. + +{{ inline_source("docs/examples/table_searching.py") }} + + ## Styling -TBD +Tables are also styled with the help of [DataTables](https://datatables.net/) library. +The default styling class used is `display`. +To change the styling, use parameter `datatables_style`, which takes either a single string with a class name, +or a list of class names. +Usable class names are listed in the styling reference +of [Datatables documentation](https://datatables.net/manual/styling/classes). + +{{ inline_source("docs/examples/table_styling.py") }} + + + +## Custom DataTables Configuration + +Most of the parameters in the previous sections were just setting up the parameters of `DataTable` JavaScript object +in some predefined manner. +It is possible to completely override such parameters by providing custom dictionary via `datatables_definition` +parameter. This dictionary is then serialized into JSON and passed to the `DataTable` JavaScript object. + +{{ inline_source("docs/examples/table_datatables_definition.py") }} -For more options, see the styling reference -in [Datatables documentation](https://datatables.net/manual/styling/classes). \ No newline at end of file + diff --git a/examples/longer_report.html b/examples/longer_report.html index 31fc9bf..d8ac44c 100644 --- a/examples/longer_report.html +++ b/examples/longer_report.html @@ -188,13 +188,7 @@
inline code formatting
.