API Reference

Creating and interacting with the Mito Spreadsheet component in Dash.

The Spreadsheet Component

To display a Mito spreadsheet in a Dash application, use the following code:

from mitosheet.mito_dash.v1 import Spreadsheet, activate_mito
from dash import Dash, html
import pandas as pd

app = Dash(__name__)
activate_mito(app)

df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/gapminder2007.csv')

app.layout = html.Div([
    html.H1('Empty Mito Spreadsheet'),
    Spreadsheet(df, id={'type': 'spreadsheet', 'id': 'sheet'})
])

if __name__ == '__main__':
    app.run_server(debug=True)

Activate Mito

After creating a Dash app instance, you need to activate Mito. This activation step simply sets up communication between the Mito frontend and the backend, and ensures that Mito works like a proper spreadsheet.

from mitosheet.mito_dash.v1 import activate_mito, Spreadsheet
from dash import Dash

app = Dash(__name__)
activate_mito(app)

Spreadsheet Component API

After you have activated Mito, you can now create a Spreadsheet component. It has the following API:

from mitosheet.mito_dash.v1 import activate_mito, Spreadsheet

Spreadsheet(
    *args: Union[pd.Dataframe, str, None],
    id: str,
    import_folder: Optional[str]=None,
    df_names: Optional[List[str]]=None,
    sheet_functions: Optional[List[Callable]]=None, 
    importers: Optional[List[Callable]]=None,
    code_options: Optional[CodeOptions]=None,
    track_selection: Optional[bool]=False
) -> Tuple[Dict[str, pd.DataFrame], str]

Argument Name	Type	Explanation
*args	Union[pd.DataFrame, str, None]	Pass any number of Pandas dataframes or paths to CSV files that will be displayed by in the Mito spreadsheet.
id	{ type: "spreadsheet", id: str }	An necessary key that uniquely identifies this component as a spreadsheet with a unique ID. Must be a dictonary the the keys type and id, where type: spreadsheet and id is a unique string.
import_folder	Optional[str]	A file path to a folder where users can import data from. Any subfolders will be available for navigation and importing within the Mito file browser. See more here.
df_names	Optional[List[str]]	if you pass Pandas dataframes through the args, then optionally include the names of these dataframes in this list. This makes Mito generated code more correct.
sheet_functions	Optional[List[Callable]]	Pass functions that are available as spreadsheet functions in the Mito spreadsheet. See more here. (Mito Enterprise)
importers	Optional[List[Callable]]	Pass custom data importers that get an auto-generated UI. See more here. (Mito Enterprise)
editors	Optional[List[Callable]]	Pass Python functions that edit a dataframe to get an auto-generated Ui. See more here. (Mito Enterprise)
code_options	Optional[CodeOptions]	Pass a CodeOptions object to specify how the code should be generated. See more here. (Mito Enterprise)
track_selection	Optional[bool]	If you want to register callbacks based on selection changes in the sheet, set this to True. Has a performance impact on scrolling through your data.

Callback Props and Types

Like any other Dash component, the Spreadsheet component allows you to make your Dash app interactive by registering callback functions. However, to give you a better callback experience, Mito works slighly differently than default dash callbacks.

A simple interactive example

Mito works differently in that it requires you to use the @mito_callback decorator when you're subscribing to Input or State changes from a Mito spreadsheet.

A simple example:

from mitosheet.mito_dash.v1 import Spreadsheet, mito_callback, activate_mito
from dash import Dash, html, Input, Output, State
import pandas as pd

app = Dash(__name__)
activate_mito(app)

df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/gapminder2007.csv')

app.layout = html.Div([
    html.H1('Simple Mito Example'),
    Spreadsheet(df, id={'type': 'spreadsheet', 'id': 'sheet'}),
    html.Div(id='output')
])

@mito_callback(
    Output('output', 'children'),
    Input({'type': 'spreadsheet', 'id': 'sheet'}, 'spreadsheet_result'),
)
def update_output(spreadsheet_result):
    return html.Div([
        html.H3('Spreadsheet Result'),
        html.Code(f'Code: {spreadsheet_result.code()}', style={'whiteSpace': 'pre-wrap'}),
        html.Div(f'Selection: {spreadsheet_result.selection()}'),
        html.Div(f'Dataframes: {spreadsheet_result.dfs()}')
    ])

if __name__ == '__main__':
    app.run_server(debug=True)

How is @mito_callback different?

1. Only two valid props you can subscribe to for the Mito component are:

   1. spreadsheet_result: returns the SpreadsheetResult class defined below.

   2. spreadsheet_selection: returns the data that is currently selected in the Mito spreadsheet.

2. Both of these properties do not return JSON that you need to parse. Rather, they return the actual objects you want to use - resulting in a much better developer experience than having to parse various types of JSON.

The SpreadsheetResult object

The SpreadsheetResult object gives you access to:

• dfs: The dataframes generated by the analysis

• code: The code generated by the analysis

• selection: The currently selected cells in the mitosheet

• analysis: A RunnableAnalysis object to help rerun the analysis on new data. To learn more, see the RunnableAnalysis documentation.

from typing import List
import pandas as pd
from mitosheet.mito_dash.v1 import mito_callback, SpreadsheetResult, activate_mito

@mito_callback(
    Output('output', 'children'),
    Input({'type': 'spreadsheet', 'id': 'sheet'}, 'spreadsheet_result'),
)
def update_output(spreadsheet_result: SpreadsheetResult):

    # The code that corresponds to the 
    code: str = spreadsheet_result.code()
    
    # The current dataframes in the mitosheet
    dfs: List[pd.DataFrame] = spreadsheet_result.dfs()
    
    # The currently selected data in the Mito sheet
    selection: Optional[Union[pd.DataFrame, pd.Series]] = spreadsheet_result.selection()

Examples

Below are examples of common uses of the Mito spreadsheet component in a Dash application.

Empty Mito Spreadsheet

from mitosheet.mito_dash.v1 import Spreadsheet, activate_mito
from dash import Dash, html
import pandas as pd

app = Dash(__name__)
activate_mito(app)

app.layout = html.Div([
    html.H1('Empty Mito Spreadsheet'),
    Spreadsheet(id={'type': 'spreadsheet', 'id': 'sheet'})
])

if __name__ == '__main__':
    app.run_server(debug=True)

Display a Dataframe for Editing

from mitosheet.mito_dash.v1 import Spreadsheet, mito_callback, activate_mito
from dash import Dash, html, Input, Output, State
import pandas as pd

app = Dash(__name__)
activate_mito(app)

df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/gapminder2007.csv')

app.layout = html.Div([
    html.H1('Simple Dataframe Editing Example'),
    Spreadsheet(df, id={'type': 'spreadsheet', 'id': 'sheet'}),
    html.Div(id='output')
])

@mito_callback(
    Output('output', 'children'),
    Input({'type': 'spreadsheet', 'id': 'sheet'}, 'spreadsheet_result'),
)
def update_output(spreadsheet_result):
    return html.Div([
        html.H3('Edited Dataframes'),
        html.Div(f'Dataframes: {spreadsheet_result.dfs()}')
    ])

if __name__ == '__main__':
    app.run_server(debug=True)

Display a CSV file for Editing

from mitosheet.mito_dash.v1 import Spreadsheet, mito_callback, activate_mito
from dash import Dash, html, Input, Output, State
import pandas as pd

app = Dash(__name__)
activate_mito(app)

app.layout = html.Div([
    html.H1('Simple CSV Editing Example'),
    Spreadsheet('https://raw.githubusercontent.com/plotly/datasets/master/gapminder2007.csv', id={'type': 'spreadsheet', 'id': 'sheet'}),
    html.Div(id='output')
])

@mito_callback(
    Output('output', 'children'),
    Input({'type': 'spreadsheet', 'id': 'sheet'}, 'spreadsheet_result'),
)
def update_output(spreadsheet_result):
    return html.Div([
        html.H3('Edited Dataframes'),
        html.Div(f'Dataframes: {spreadsheet_result.dfs()}')
    ])

if __name__ == '__main__':
    app.run_server(debug=True)

Displaying Mito generated code

from mitosheet.mito_dash.v1 import Spreadsheet, mito_callback, activate_mito
from dash import Dash, html, Input, Output, State
import pandas as pd

app = Dash(__name__)
activate_mito(app)

df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/gapminder2007.csv')

app.layout = html.Div([
    html.H1('Simple Dataframe Editing Example'),
    Spreadsheet(df, id={'type': 'spreadsheet', 'id': 'sheet'}),
    html.Div(id='output')
])

@mito_callback(
    Output('output', 'children'),
    Input({'type': 'spreadsheet', 'id': 'sheet'}, 'spreadsheet_result'),
)
def update_output(spreadsheet_result):
    return html.Div([
        html.H3('Mito Generated Code'),
        html.Code(spreadsheet_result.code(), style={'whiteSpace': 'pre-wrap'}),
    ])

if __name__ == '__main__':
    app.run_server(debug=True)