Modin 电子表格 API#

入门指南#

使用 pip 安装 Modin-spreadsheet：

pip install "modin[spreadsheet]"

以下代码片段使用FiveThirtyEight数据集创建了一个关于大学专业劳动力信息的电子表格（遵循CC BY 4.0许可）：

import modin.pandas as pd
import modin.experimental.spreadsheet as mss
df = pd.read_csv('https://raw.githubusercontent.com/fivethirtyeight/data/master/college-majors/all-ages.csv')
spreadsheet = mss.from_dataframe(df)
spreadsheet
../../_images/modin_spreadsheets_installation.png

通过用户界面的基本操作#

Spreadsheet API 允许用户通过简单的图形控件对 DataFrame 进行排序、过滤和编辑操作。

Here are the instructions for each operation:

  • 排序: 点击要排序的列的表头。

  • 过滤器: 点击列标题上的过滤器按钮，并对该列应用所需的过滤器。过滤器下拉菜单会根据列的类型而变化。多个过滤器会自动组合。

  • 编辑单元格: 双击单元格并输入新值。

  • 添加行: 点击工具栏中的“添加行”按钮以复制DataFrame中的最后一行。复制的值提供了方便的默认值，可以根据需要进行编辑。

  • 删除行: 选择行并点击“删除行”按钮。通过单击选择单行。可以使用Cmd+单击（Windows：Ctrl+单击）选择多行，或使用Shift+单击指定行范围。

其中一些操作也可以通过电子表格的程序接口完成。排序和过滤器可以使用工具栏按钮重置。编辑和添加/删除行只能手动撤销。

虚拟渲染#

电子表格将仅根据用户的视口渲染数据。这允许即使在非常大的DataFrames上也能快速渲染，因为在任何给定时间只加载少量行。因此，滚动和查看您的数据是流畅且响应迅速的。

转换历史与代码导出#

电子表格上的所有操作都会被记录，并且可以轻松导出为代码以便分享或重现。 每当显示电子表格小部件时，此历史记录会自动显示在历史记录单元格中，该单元格在电子表格下方生成。 默认情况下会显示历史记录单元格，但可以关闭。Modin Spreadsheet API 提供了几种与历史记录交互的方法：

  • SpreadsheetWidget.get_history(): 以可重复代码的形式检索转换历史。

  • SpreadsheetWidget.filter_relevant_history(persist=True): 返回仅包含与电子表格最终状态相关的代码的转换历史记录。persist 参数决定是否也过滤内部状态和显示的历史记录。

  • SpreadsheetWidget.reset_history(): 清除转换历史。

可定制界面#

电子表格小部件提供了许多选项，允许用户更改电子表格的外观和交互性。选项包括：

  • 行高/列宽

  • 防止对整个电子表格或每列进行编辑、排序或过滤

  • 隐藏工具栏和历史记录单元格

  • 浮点数精度

  • 单元格和行的高亮显示

  • 视口大小

将电子表格转换为数据框及从数据框转换#

modin.experimental.spreadsheet.general.from_dataframe(dataframe, show_toolbar=None, show_history=None, precision=None, grid_options=None, column_options=None, column_definitions=None, row_edit_callback=None)

将DataFrame或Series渲染为交互式电子表格，由SpreadsheetWidget类的实例表示。SpreadsheetWidget实例是使用传递给此函数的选项构造的。此函数的dataframe参数用作调用SpreadsheetWidget构造函数时的df关键字参数，其余参数按原样传递。

如果 dataframe 参数是一个 Series，它将在传递给 SpreadsheetWidget 构造函数之前被转换为 DataFrame，作为 df 关键字参数。

Return type:

SpreadsheetWidget

Parameters:

  • dataframe (DataFrame) – 该SpreadsheetWidget实例将显示的DataFrame。

  • grid_options (dict) – 创建SlickGrid控件（即交互式网格）时要使用的选项。有关可用选项的更多信息，请参阅下面的注释部分，以及此小部件使用的默认选项。

  • precision (整数) – 浮点数值显示的小数位数。如果未设置，则使用pandas.get_option(‘display.precision’)的值。

  • show_toolbar (bool) – 是否显示带有添加/删除行选项的工具栏。 添加/删除行是一个实验性功能，仅适用于具有整数索引的DataFrames。

  • show_history (bool) – 是否显示包含电子表格转换历史的单元格。

  • column_options (dict) – 应用于每一列的列选项。有关可用选项的更多信息，请参阅下面的注释部分，以及此小部件使用的默认选项。

  • column_definitions (dict) – 应用于单个列的列选项。字典的键应为列名，每个值应为特定列的列选项，表示为字典。每列可用的选项与通过column_options参数为所有列设置的选项相同。有关这些选项的更多信息，请参阅下面的注释部分。

  • row_edit_callback (callable) – 一个可调用对象，用于确定特定行是否应可编辑。其签名应为 callable(row)，其中 row 是一个字典，包含特定行的值，按列名键控。如果提供的行应可编辑，则回调应返回 True，否则返回 False。

注释

如果没有明确提供，以下字典将用于 grid_options：

{
    # SlickGrid options
    'fullWidthRows': True,
    'syncColumnCellResize': True,
    'forceFitColumns': False,
    'defaultColumnWidth': 150,
    'rowHeight': 28,
    'enableColumnReorder': False,
    'enableTextSelectionOnCells': True,
    'editable': True,
    'autoEdit': False,
    'explicitInitialization': True,

    # Modin-spreadsheet options
    'maxVisibleRows': 15,
    'minVisibleRows': 8,
    'sortable': True,
    'filterable': True,
    'highlightSelectedCell': False,
    'highlightSelectedRow': True
}

第一组选项是SlickGrid的“网格选项”，这些选项在SlickGrid文档中有详细描述。

第二组选项是专门为modin-spreadsheet添加的选项，因此未在SlickGrid文档中记录。以下要点描述了这些选项。

  • maxVisibleRows modin-spreadsheet 将显示的最大行数。

  • minVisibleRows modin-spreadsheet 将显示的最小行数

  • sortable 是否允许用户通过点击列标题来对modin-spreadsheet实例中的列进行排序。当此选项设置为False时，用户点击列标题将不会发生任何操作。

  • filterable 是否允许用户对modin-spreadsheet实例进行过滤。当设置为False时，任何列的过滤图标都不会显示。

  • highlightSelectedCell 如果你将此设置为True，选中的单元格将会有一个浅蓝色的边框。

  • highlightSelectedRow 如果你将此设置为False，默认情况下为选中行显示的浅蓝色背景将被隐藏。

如果没有明确提供，以下字典将用于 column_options：

{
    # SlickGrid column options
    'defaultSortAsc': True,
    'maxWidth': None,
    'minWidth': 30,
    'resizable': True,
    'sortable': True,
    'toolTip': "",
    'width': None

    # Modin-spreadsheet column options
    'editable': True,
}

第一组选项是SlickGrid的“列选项”，这些选项在SlickGrid文档中有详细描述。

editable 选项是专门为 modin-spreadsheet 添加的，因此在 SlickGrid 文档中没有记录。此选项指定列是否应可编辑。

另请参阅

set_defaults

永久设置show_grid参数的全局默认值，除了dataframe和column_definitions参数，因为这些参数取决于实例显示的特定数据集，因此不是我们希望为所有SpreadsheetWidget实例设置的参数。

set_grid_option

永久设置单个网格选项的全局默认值。通过更改show_grid方法用于grid_options参数的默认值来实现。

SpreadsheetWidget

此方法实例化并返回的小部件类。

modin.experimental.spreadsheet.general.to_dataframe(spreadsheet)

获取一个反映spreadsheet SpreadsheetWidget实例UI当前状态的DataFrame副本。 这包括任何排序或过滤更改，以及通过双击单元格进行的编辑。

Return type:

DataFrame

Parameters:

电子表格 (SpreadsheetWidget) – SpreadsheetWidget 实例，该实例将显示 DataFrame 的 SpreadsheetWidget。

更多API文档#

class modin_spreadsheet.grid.SpreadsheetWidget(**kwargs: Any)

由show_grid方法实例化的小部件类。这个类可以直接构造，但不推荐这样做，因为那样必须明确指定默认选项（因为默认选项通常由show_grid方法提供）。

此类的构造函数接受与 show_grid 相同的所有参数，只有一个例外，即必需的 data_frame 参数被替换为一个名为 df 的可选关键字参数。

另请参阅

show_grid

应该用于构造SpreadsheetWidget实例的方法，因为它为所有modin-spreadsheet选项提供了合理的默认值。

df

获取/设置当前实例显示的DataFrame。 此DataFrame将不会反映通过UI进行的任何排序/过滤/编辑 更改。要获取反映排序/过滤/编辑更改的DataFrame副本，请使用 get_changed_df() 方法。

Type:

DataFrame

grid_options

获取/设置当前实例使用的网格选项。

Type:

字典

precision

获取/设置当前实例使用的精度选项。

Type:

整数

show_toolbar

获取/设置当前实例使用的show_toolbar选项。

Type:

布尔

show_history

获取/设置当前实例使用的show_history选项。

Type:

布尔

column_options

获取/设置当前实例正在使用的列选项。

Type:

布尔

column_definitions

获取/设置当前实例正在使用的列定义（列特定选项）。

Type:

布尔

add_row(row=None)

在DataFrame的末尾添加一行。新行的值可以通过row参数提供，该参数对于具有整数索引的DataFrame是可选的，否则是必需的。如果未提供row参数，则将复制最后一行，并且新行的索引将是最后一行的索引加一。

Parameters:

row (list (默认值: None)) – 一个由(列名, 列值)组成的2元组列表，用于指定新行的值。

另请参阅

SpreadsheetWidget.remove_rows

删除一行（或多行）的方法。

change_grid_option(option_name, option_value)

更改SlickGrid网格选项而不重建整个网格小部件。目前并非所有选项都受支持，因此此方法应被视为实验性的。

Parameters:

  • option_name (str) – 要更改的网格选项的名称。

  • option_value (str) – 网格选项的新值。

change_selection(rows=[])

在用户界面中选择一行（或多行）。要选择的行的索引通过可选的 rows 参数提供。

Parameters:

rows (list (默认: [])) – 要选择的行索引列表。对于多索引的DataFrame，列表中的每个索引应该是一个元组，每个元组中的每个值对应于MultiIndex的一个级别。[]的默认值会导致没有行被选择（即清除选择）。

edit_cell(index, column, value)

编辑网格中的一个单元格，给定要编辑的单元格的索引和列，以及单元格的新值。结果会触发一个cell_edited事件。

Parameters:

  • index (object) – 包含要编辑的单元格的行的索引。

  • column (str) – 包含要编辑的单元格的列的名称。

  • value (object) – 单元格的新值。

get_changed_df()

获取用于创建当前SpreadsheetWidget实例的DataFrame副本，该副本反映了UI的当前状态。这包括任何排序或过滤更改，以及通过双击单元格进行的编辑。

Return type:

DataFrame

get_selected_df()

获取一个反映UI当前状态的DataFrame，并且只包含当前选中的行。内部调用get_changed_df()，然后使用iloc过滤到选中的行。

Return type:

DataFrame

get_selected_rows()

获取当前选中的行。

Return type:

整数列表

off(names, handler)

移除一个使用当前实例的on方法注册的modin-spreadsheet事件处理程序。

Parameters:

  • names (list, str, All (默认: All)) – 应卸载指定处理程序的事件名称。如果 names 是 All，则从所有事件对应的通知程序列表中卸载指定的处理程序。

  • handler (callable) – 一个可调用对象，之前已通过当前实例的 on 方法注册。

另请参阅

SpreadsheetWidget.on

用于连接实例级处理程序的方法，此off方法可以移除。

on(names, handler)

设置一个处理程序，当用户与当前实例交互时调用。

Parameters:

  • names (list, str, All) – 如果 names 是 All，处理程序将应用于所有事件。如果是一个字符串列表，处理程序将应用于列表中命名的所有事件。如果是一个字符串，处理程序将仅应用于具有该名称的事件。

  • handler (callable) – 当事件发生时调用的可调用对象。其签名应为 handler(event, spreadsheet_widget)，其中 event 是一个字典，spreadsheet_widget 是触发事件的 SpreadsheetWidget 实例。event 字典至少包含一个 name 键，该键指定发生的事件的名称。

注释

以下是您可以通过on方法在SpreadsheetWidget实例上监听的事件列表：

[
    'cell_edited',
    'selection_changed',
    'viewport_changed',
    'row_added',
    'row_removed',
    'filter_dropdown_shown',
    'filter_changed',
    'sort_changed',
    'text_filter_viewport_changed',
    'json_updated'
]

以下要点更详细地描述了上面列出的事件。每个事件要点后面都有子要点，这些子要点描述了每个事件的event字典中将包含的键。

  • cell_edited 用户更改了网格中单元格的值。

    • index 包含已编辑单元格的行的索引。

    • column 包含已编辑单元格的列的名称。

    • old 单元格的先前值。

    • new 单元格的新值。

  • filter_changed 用户更改了列的筛选设置。

    • column 更改筛选设置的列的名称。

  • filter_dropdown_shown 用户通过点击列标题中的过滤器图标显示了列的过滤器控件。

    • column 显示过滤器控件的列的名称。

  • json_updated 用户操作导致 SpreadsheetWidget 将数据行（以 json 格式）发送到浏览器。这是某些操作（如滚动、排序和过滤）的副作用。

    • triggered_by 导致数据行被发送到浏览器的事件名称。可能的值是 change_viewport, change_filter, change_sort, add_row, remove_row, 和 edit_cell。

    • range 一个元组，指定已发送到浏览器的行范围。

  • row_added 用户使用网格工具栏中的“添加行”按钮添加了一新行。

    • index 新添加行的索引。

    • source 此事件的来源。可能的值是 api（API方法调用）和 gui（网格界面）。

  • row_removed 用户使用网格工具栏中的“移除行”按钮移除了一行或多行。

    • indices 被移除行的索引，指定为一个整数数组。

    • source 此事件的来源。可能的值是 api（API方法调用）和 gui（网格界面）。

  • selection_changed 用户更改了网格中高亮显示的行。

    • old 一个数组，指定之前选中的行的索引。

    • new 当前选中的行的索引，同样以数组形式指定。

    • source 此事件的来源。可能的值是 api（API方法调用）和 gui（网格界面）。

  • sort_changed 用户更改了网格的排序设置。

    • old 网格之前的排序设置，指定为一个包含以下键的字典：

      • column 网格之前排序的列名

      • ascending 布尔值，表示升序/降序

    • new 网格的新排序设置，指定为一个包含以下键的字典：

      • column 网格当前排序的列名

      • ascending 布尔值，表示升序/降序

  • text_filter_viewport_changed 用户滚动新行以在文本字段的筛选下拉列表中查看。

    • column 筛选下拉列表可见的列的名称

    • old 一个元组，指定筛选下拉列表中先前可见行的范围。

    • new 一个元组，指定筛选下拉列表中现在可见行的范围。

  • viewport_changed 用户将新行滚动到网格视图中。

    • old 一个元组，指定之前可见行的范围。

    • new 一个元组，指定现在可见行的范围。

每种类型事件的event字典都会包含一个name键，用于指定发生的事件的名称。为了避免冗余，该键已从上述键列表中排除。

另请参阅

on

与实例级别的 on 方法相同，不同之处在于它监听所有实例上的事件，而不是单个 SpreadsheetWidget 实例上的事件。

SpreadsheetWidget.off

解除使用实例级on方法挂接的处理程序。

remove_row(rows=None)

remove_rows 的别名，为了方便而提供，因为这是该方法之前的名称。

remove_rows(rows=None)

从DataFrame中移除一行（或多行）。可以通过可选的rows参数提供要移除的行的索引。如果未提供rows参数，则将移除当前在UI中选择的行（或多行）。

Parameters:

rows (list (默认值: None)) – 要从DataFrame中移除的行的索引列表。对于多索引的DataFrame，列表中的每个索引应该是一个元组，元组中的每个值对应于MultiIndex的一个级别。

另请参阅

SpreadsheetWidget.add_row

添加行的方法。

SpreadsheetWidget.remove_row

此方法的别名。

toggle_editable()

更改网格是否可编辑，而无需重建整个网格小部件。

On this page
Show Source