schrodinger.ui.qt.mapperwidgets.plptable module¶

Framework to simplify creating Qt tables based on parameters.ParamListParam (PLP). A PLP is a type of list param where each element is itself a compound param. These can be naturally represented as tables where each item in the list is a row in the table, and individual subparams (fields) of the item are shown as cells in the row. See scripts/examples/models/plptable_gui.py for an example.

To create a plptable, you first need a model object with a ParamListParam that contains the source data. Each item in the list corresponds to a row in the table, and the cells in that row are based on the fields in that item. For example:

class Contact(parameters.CompoundParam):
    name: str
    phone_number: str
    email: str

class Model(parameters.CompoundParam):
    contacts = parameters.ParamListParam(item_class=Contact)

In the simplest case, a PLPTableWidget can be instantiated with autospec=True, resulting in a very basic table with one column for each field in the PLP item class:

model = Model()
table = plptable.PLPTableWidget(plp=model.contacts, autospec=True)

Typically, it is desirable to customize the column contents and how the data in the list item is used to populate the columns. This is accomplished by sub- classing the TableSpec class to create a table specification. A table spec defines the columns in a table and provides the data methods used to populate the cells in each column.

In the example above, we might want to split the name into separate first and last name columns and turn the email into a hyperlink. This could be done with the following table spec:

class ContactTableSpec(plptable.TableSpec):
    @plptable.FieldColumn(Contact.name)
    def first_name(self, field):
        return field.split()[0]

    @plptable.FieldColumn(Contact.name)
    def last_name(self, field):
        return field.split()[-1]

    phone_number = plptable.FieldColumn(Contact.phone_number)

    @plptable.FieldColumn(Contact.email)
    def email(self, field):
        return f'<a href = "mailto: {field}">{field}</a>'

Notice that there are two ways to declare a column - either with a class attribute or a decorated data method.

Once a spec is defined, it can be applied to a PLPTableWidget using the setSpec method.

For more information, see TableSpec as well as the various column classes.

class schrodinger.ui.qt.mapperwidgets.plptable.FieldColumn(*args, **kwargs)¶

Bases: schrodinger.ui.qt.mapperwidgets.plptable._BaseColumn

A FieldColumn is a column in which each cell receives the data from a single subparam (i.e. field) of one item in the PLP.:

@FieldColumn(ItemClass.subparam)
def my_data_method(self, field)
    field: the value of the param field associated with this row

__init__(field, **kwargs)¶

Parameters: field (parameters.Param) – An abstract param representing the field this column represents or uses.

setData(all_rows, this_row, data, role=ItemDataRole.EditRole)¶

class schrodinger.ui.qt.mapperwidgets.plptable.ParamColumn(*args, **kwargs)¶

Bases: schrodinger.ui.qt.mapperwidgets.plptable._BaseColumn

A ParamColumn is a column in which each cell receives one entire item from the PLP. It’s up to the data method to decide how to convert the item into something that can be used by the cell.

@ParamColumn()
def my_data_method(self, this_row)
    this_row: the model object for this row.

class schrodinger.ui.qt.mapperwidgets.plptable.PLPColumn(*args, **kwargs)¶

Bases: schrodinger.ui.qt.mapperwidgets.plptable._BaseColumn

A PLPColumn is a column in which each cell receives the entire PLP (i.e. the entire table’s data). This allows each cell’s contents to account for data in other rows in the table. It’s up to the data method to decide how to use the entire table data in each individual cell.

@PLPColumn()
def my_data_method(self, all_rows, this_row):
    all_rows: a list where each element is the model object for one row
    this_row: the model object for this row

class schrodinger.ui.qt.mapperwidgets.plptable.ColumnSeries(*args, **kwargs)¶

Bases: schrodinger.ui.qt.mapperwidgets.plptable.PLPColumn

getNumColumns(all_rows)¶

Call the column_count method to see how many columns make up the series.

Parameters: all_rows (list(parameters.CompoundParam)) – A list of the rows that make up the table.
Returns: The number of columns in the series
Return type: int

column_count(*args)¶: Decorator to designate a function to calculate the number of columns in the series.

data(col_idx, all_rows, this_row, role=ItemDataRole.DisplayRole)¶: Get the corresponding data for the column for the specified role.

setData(all_rows, this_row, data, role=ItemDataRole.EditRole)¶

headerData(col_idx, all_rows, role=ItemDataRole.DisplayRole)¶

class schrodinger.ui.qt.mapperwidgets.plptable.TableSpec(*args, _param_type=<object object>, **kwargs)¶

Bases: schrodinger.models.parameters.CompoundParam

A class that represents the specification of a PLPTable. The spec’s role is to specify what columns to display, in what order, and with what data.

To create a table spec, subclass TableSpec and add columns and data methods to define the behavior of the table.

Abstract columns are used to specify the order and existence of columns in the table. They are class attributes (e.g. AtomWeightsSpec.atom_number).

The default set of abstract columns on a spec is given by inheritance from the TableSpec base class. This may be customized with the corresponding getter and setter, e.g.:

cols = spec.getAbstractColumns()
cols.remove(spec.atom_number)
spec.setAbstractColumns(cols)

Concrete columns (or simply “columns”, without “abstract”) are a ListParam defined on TableSpec instances. The list of concrete columns is read-only, but attributes of individual column objects may be mutated on a table instance.

__init__()¶

columns: list¶

A Param to represent lists. Values of this param will have a mutated signal that will be emitted whenever any mutation method is called.

The constructor optionally takes a item_class keyword argument to specify what type of class the items in the list will be. This information will be used for jsonifying the list if specified.

getColumns()¶

Returns the concrete columns, according to their current ordering.

Returns: List of concrete columns according to the spec’s current column ordering.
Return type: list(_BaseColumn)

getAbstractColumns()¶

Getter method for column ordering.

Returns: List of abstract columns according to the spec’s current column ordering.
Return type: list(_BaseColumn)

setAbstractColumns(new_order: list(_BaseColumn)) → None¶

Setter method for column ordering.

Parameters: new_order (list(_BaseColumn)) – List of abstract columns in the new desired column order.

classmethod makeAutoSpec(plp: schrodinger.models.parameters.ParamListParam) → schrodinger.ui.qt.mapperwidgets.plptable.TableSpec¶

Make a TableSpec instance from a PLP (from a table’s model.)

Parameters: plp (parameters.ParamListParam) – a ParamListParam to use as the domain model for this table

headerData(col_idx, all_rows, role)¶

data(col_idx, all_rows, this_row, role)¶

setData(col_idx, all_rows, this_row, value, role=ItemDataRole.EditRole)¶

getColumn(col_idx, all_rows)¶

getNumColumns(all_rows)¶

getColumnIndex(column, all_rows)¶

Note that for column of type ColumnSeries we return the index of the 0th column in the series.

Parameters

column (Subclass instance of _BaseColumn) – Column to return the index for.
all_rows (parameters.ParamListParam) – All rows of the plp table.

Returns

Column index.

Return type

int

Raises

KeyError – If column not found in the table spec.

columnsChanged¶

pyqtSignal(*types, name: str = …, revision: int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

columnsReplaced¶

pyqtSignal(*types, name: str = …, revision: int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

class schrodinger.ui.qt.mapperwidgets.plptable.PLPTableWidget(*args, spec=None, autospec=False, plp=None, view=None, **kwargs)¶

Bases: schrodinger.models.mappers.TargetMixin, schrodinger.ui.qt.basewidgets.BaseWidget

A table widget for displaying data in a ParamListParam. Compatible with mappers.TargetParamMapper and mappers.MapperMixin.

Typically this class is instantiated directly, and defining the behavior of the table is done by creating a custom TableSpec subclass.

__init__(*args, spec=None, autospec=False, plp=None, view=None, **kwargs)¶

Parameters

spec (TableSpec) – Table specification. Will be ignored if autospec is True.
autospec (bool) – Whether to automatically generate the table specification from the PLP item fields.
plp (parameters.ParamListParam) – ParamListParam containing data. It is more common to set the plp using mappers.
view (QtWidgets.QTableView) – Custom table view instance. If None, an instance of table_helper.SampleDataTableView will be created.

property spec¶

setSpec(new_spec)¶

Apply a new table specification to this table.

Parameters: new_spec (TableSpec or None) – the new table spec

initSetUp()¶

Creates widget from ui and stores it ui_widget.

Suggested subclass use: create and initialize subwidgets, and connect signals.

initLayOut()¶

Create a vertical layout for the widget (widget_layout) and populate it with two vertical sub-layouts: main_layout and bottom_layout.

If the user has specified the ui data member, insert the resultant ui_widget into main_layout.

If the widget already has a layout defined, this method will produce a warning (but not a traceback). main_layout and bottom_layout will be inserted into the existing widget layout, which will not be the same as widget_layout. It is therefore recommended that this mixin is used only with widgets that do not already have a layout.

Suggested subclass use: create, initialize, and populate layouts.

addProxy(proxy_model)¶

targetGetValue()¶: Implementation of an abstract method in TargetMixin.

targetSetValue(value)¶

Implementation of an abstract method in TargetMixin.

Creates a table model based on the spec, loads the PLP as data, and sets the newly created table model on the view.

makeAutoSpec(plp: schrodinger.models.parameters.ParamListParam) → schrodinger.ui.qt.mapperwidgets.plptable.TableSpec¶: Wrapper for backwards compatibility.

loadPLP(plp)¶

Replace the current contents of the table PLP with the contents of the supplied plp argument.

Parameters: plp (parameters.ParamListParam) – a ParamListParam of the same type that is used as the domain model for this table

setPLP(plp)¶

Set the supplied PLP as the new model for the table.

Parameters: plp (list(parameters.CompoundParam)) – The PLP representing the table data.

selectedParams()¶

removeSelectedParams()¶: Deletes parameters if they are selected in the table.

setSelectedParams(params)¶

Selects the table rows corresponding to the specified params.

Parameters: params – a list of params to select

removeRow(row_num)¶

exportToCsv(filename)¶

getRowData()¶

Returns: a list of lists, where each list represents the row of a table
Return type: list[list[object]]

getColumnIndex(column)¶

Note that for column of type ColumnSeries we return the index of the 0th column in the series.

Parameters: column (Subclass instance of _BaseColumn) – Column to return the index for.
Returns: Column index.
Return type: int
Raises: KeyError – If column not found in the table.

schrodinger.ui.qt.mapperwidgets.plptable.export_plp_to_csv(plp: schrodinger.models.parameters.ParamListParam, spec_class: schrodinger.ui.qt.mapperwidgets.plptable.TableSpec, output_file: str, role: int = ItemDataRole.DisplayRole, header_role: int = ItemDataRole.DisplayRole) → None¶

Write the supplied PLP to CSV. Formatting is determined by the specified table spec.

Parameters

plp – The PLP to write
spec_class – The TableSpec class to determine CSV formatting
output_file – The name of the desired output file
role – The data role to export for the table contents
header_role – The data role to export for the table headers