FastTable

Introduction

FastTable widget in Supervisely allows for displaying and manipulating data of various dataset statistics and processing it on the server side.

The FastTable widget allows searching, sorting by column and order, and the ability to customize data. It also allows updating table data in real-time through Python code.

😲 The main feature of FastTable in that all information is processed on the server side and transmitted in the size of the active page of the table to the client, thus making its operation more efficient.

Function signature

Data structure example

fast_table = FastTable(
    data=data,
    columns=columns,
    columns_options=columns_options,
    project_meta=project_meta,
    fixed_columns=1,
    page_size=10,
    sort_column_idx=1,
    sort_order="desc",
    width="auto",
    widget_id=None,
)

Parameters

Parameters	Type	Description
data	Optional[Union[list, pd.DataFrame]]	Table data
columns	Optional[list]	Table columns
columns_options	Optional[list[dict]]	Columns options
project_meta	Optional[Union[ProjectMeta, dict]]	Project metadata
fixed_columns	Optional[Literal[1]]	Number of the first fixed columns
page_size	Optional[int]	Table page size in number of rows
sort_column_idx	int	Index of the column by which sorting works
sort_order	Optional[Literal["asc", "desc"]]	Sort order
width	Optional[str]	Width of table
widget_id	Optional[str]	ID of the widget
show_header	Bool	If True header (column names) is displayed at the top of the table. When set to False, the table will show only the data rows without column headers.
is_radio	Bool	Enables radio button selection mode for single row selection. When set to True, users can select only one row at a time using radio buttons.
is_selectable	Bool	If True, users can select multiple rows using checkboxes.
header_left_content	Optional[Widget]	Allows to add a custom widget to the left side of the table header area.
header_right_content	Optional[Widget]	Allows to add a custom widget to the right side of the table header area.
max_selected_rows	Optional[int]	Sets the maximum number of rows that can be selected when is_selectable is True. If not specified, there's no limit on the number of selected rows.
search_position	Optional[Literal["left", "right"]]	Determines the position of the search input field in the table interface. Can be positioned on either the "left" or "right" side of the table header. If not specified, defaults to "left".

data

Table data in different formats:

type: Optional[Union[list, pd.DataFrame]]

default value: None

1. Python list with structure:

   data_list = [
       [
           ["apple", "21"],
           ["banana", "15"],
       ],
   ]
   
   fast_table = FastTable(data=data_list)

   Where:

   • data_list - list with rows

2. Pandas DataFrame:

   dataframe = pd.DataFrame(data=data, columns=columns)
   fast_table = FastTable(data=dataframe)

   Where:

   • columns - list of column names

   • data - list with rows

     • row - list with values, requires len(row) == len(columns)

columns

Column names.

💡 If data in DataFrame type is passed, specifying columns will overwrite it in DataFrame

type: Optional[list]

default value: None

fast_table = FastTable(data=dataframe, columns=columns)

columns_options

List of dictionaries with column options. len(columns_options) must equal len(columns) to properly add options. If the column has no options, just pass an empty dictionary {}

Each dictionary may contain:

• type - with value of type str, determines special column type, depending on which styles will be applied, now supports only class as special type, you don't need to specify a type for the regular ones

• subtitle - with value of type str, provide additional clarification, specify units of measurement, offer context, and enhance overall understanding of the data

• maxValue - with value of type int, determines the maximum value for the column and activates special bars that visualize how close the value is to the maximum value

• postfix - with value of type str, is substituted after each value to denote dimensionality

• tooltip - with value of type str, tooltip with description for a column

type: Optional[list[dict]]

default value: None

fast_table = FastTable(data=data_list, columns=columns_list)

project_meta

Project metadata with classes used to apply special styles for columns with type:class

type: Optional[Union[ProjectMeta, dict]]

default value: None

meta_json = api.project.get_meta(id=project_id)
fast_table = FastTable(data=data_dict, project_meta=meta_json)

# or

meta = sly.ProjectMeta.from_json(data=meta_json)
fast_table = FastTable(data=data_dict, project_meta=meta)

fixed_columns

Number of the first fixed columns if the table has horizontal scrolling.

💡 Currently supports only 1 or None as value.

type: Optional[Literal[1]]

default value: None

fast_table = FastTable(data=dataframe, fixed_columns=1)

page_size

Table page size in number of rows

type: int

default value: 10

fast_table = FastTable(data=dataframe, page_size=15)

sort_column_idx

Index of the column by which sorting works.

💡 Cannot be used without sort_order, if one of parameters is not set - the sorting will follow the original data structure.

type: int

default value: None

fast_table = FastTable(data=dataframe, sort_column_idx=0, sort_order='asc')

sort_order

Sort order.

💡 Cannot be used without sort_column_idx, if one of parameters is not set - the sorting will follow the original data structure.

type: Optional[Literal["asc", "desc"]]

default value: None

fast_table = FastTable(data=dataframe, sort_column_idx=1, sort_order='desc')

width

Width of table.

type: Optional[str]

default value: auto

fast_table = FastTable(data=data_dict, width="50%")

widget_id

ID of the widget.

type: str

default value: None

show_header

If True header (column names) is displayed at the top of the table. When set to False, the table will show only the data rows without column headers.

type: bool

default value: True

is_radio

Enables radio button selection mode for single row selection. When set to True, users can select only one row at a time using radio buttons.

type: bool

default value: False

is_selectable

If True, users can select multiple rows using checkboxes.

type: bool

default value: False

header_left_content

Allows to add a custom widget to the left side of the table header area.

type: Optional[Widget]

default value: None

header_right_content

Allows to add a custom widget to the right side of the table header area.

type: Optional[Widget]

default value: None

max_selected_rows

Sets the maximum number of rows that can be selected when is_selectable is True. If not specified, there's no limit on the number of selected rows.

type: Optional[int]

default value: None

search_position

Determines the position of the search input field in the table interface. Can be positioned on either the "left" or "right" side of the table header. If not specified, defaults to "left".

type: Optional[Literal["left", "right"]]

default value: None

Methods and attributes

Attributes and Methods	Description
fixed_columns_num	Get or set number of fixed columns (left to right) property.
project_meta	Get or set number project meta property.
page_size	Get or set table page size property.
read_json(data: dict, meta: dict = None)	Read and set table data from JSON format.
read_pandas(data: pd.DataFrame)	Read and set table data from DataFrame.
to_json(active_page = False)	Convert table data to JSON format. Full table or active page only.
to_pandas(active_page = False)	Convert table data to pandas DataFrame. Full table or active page only.
clear_selection()	Deselect a table cell.
get_selected_row()	Get selected table row info.
get_selected_cell()	Get selected table cell info.
insert_row(row: List, index=-1)	Insert new row in table by index.
pop_row(index=-1)	Remove row from table by index.
search(search_value)	Search source data for search_value and return results as DataFrame.
sort(column_id: int, order: Optional[Literal["asc", "desc"]])	Sort table rows by given column ID and/or order direction.
@row_click	Decorator function is handled when table row is clicked.
@cell_click	Decorator function is handled when table cell is clicked.
update_cell_value(row_index: int, column_index: int, value)	Update cell value in table by row and column indexes.
filter	Applies a filter to the table data using the specified filter value.
@selection_changed	Decorator for function that handles selection change event.
select_row	Selects single row in the table by row indice.
select_rows	Selects multiple rows in the table by their row indices.
select_row_by_value	Selects a single row by finding a specific value in a given column.
select_rows_by_value	Selects multiple rows by finding rows that contain any of the specified values in a given column.

read_json()

The data structure must correspond to the dictionary given in the example below 👇

Structure:

• columns - list of column names

• data - list with rows

  • row - list with values, requires len(row) == len(columns)

• columnsOptions - list of dictionaries in which settings for each column are stored

  • type - determines special type of column, depending on which styles will be applied, now supports only class as special type, you don't need to specify a type for regular

  • subtitle - provide additional clarification, specify units of measurement, offer context, and enhance overall understanding of the data

  • maxValue - determines the maximum value for the column and activates special bars that visualize how close the value is to the maximum value

  • postfix - is substituted after each value to denote dimensionality

  • tooltip - tooltip with description for a column

• options - dict with table options

  • fixColumns - number of first fixed table columns. ℹ️ Currently, only the first column is supported

  • sort - dict with applied sorting options

    • columnIndex - index of the column, by the values of which the data should be sorted

    • order - sort order

  • pageSize - how many rows will be displayed on the table page

Here is an example of the described structure: json_data_example

This data is under MIT license. Source

An example of a table built from this JSON can be seen on the datasets' page on Dataset Ninja.

Mini App Example

You can find this example in our Github repository:

ui-widgets-demos/tables/006_fast_table/src/main.py

Import libraries

import os
import json
import pandas as pd
import random

import supervisely as sly
from supervisely.app.widgets import (
    Card,
    Container,
    FastTable,
)

Prepare data and meta that will be used to create example table

data = [
    ["apple", "21"],
    ["banana", "15"]
  ]

columns = ["Class", "Items"]

dataframe = pd.DataFrame(data=data, columns=columns)

columns_options = [
    { "type": "class"},
    { "maxValue": 21, "postfix": "pcs", "tooltip": "description text", "subtitle": "boxes" }
  ]

meta_path = "meta.json"  # define file path
with open(meta_path, "r") as json_file:
    meta = json.load(json_file)

Initialize FastTable widget

fast_table = FastTable(
    data=dataframe,
    project_meta=meta,
    columns_options=columns_options,
)

Create app layout

Prepare a layout for app using Card widget with the content parameter and place widget that we've just created in the Container widget.

card = Card(
    title="Fast Table",
    content=fast_table,
)
layout = Container(widgets=[card])

Create app using layout

Create an app object with layout parameter.

app = sly.Application(layout=layout)

Add functions to control widget from python code

@fast_table.row_click
def handle_table_row(clicked_row: sly.app.widgets.FastTable.ClickedRow):
    sly.app.show_dialog(
        f"{clicked_row.row[0]}",
        f"You clicked table row with idx={clicked_row.row_index} in source data",
    )

or

@fast_table.cell_click
def handle_table_cell(cell: sly.app.widgets.FastTable.ClickedCell):
    new_value = str(random.randint(0, 100))
    fast_table.update_cell_value(cell.row_index, cell.column_index, new_value)