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 typeColumnSeries
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 itui_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
andbottom_layout
.If the user has specified the
ui
data member, insert the resultantui_widget
intomain_layout
.If the widget already has a layout defined, this method will produce a warning (but not a traceback).
main_layout
andbottom_layout
will be inserted into the existing widget layout, which will not be the same aswidget_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 typeColumnSeries
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