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