schrodinger.project module¶

A module for accessing and modifying a Maestro Project.

Projects may be accessed while within Maestro or without Maestro from a python script that imports this module. Usually when running from within Maestro the Project object would be returned via maestro.project_table_get()

For a description of basic concepts that clarify the relationship between the Workspace and Maestro Projects as well as when and how changes in one affect the other, please see the Basic Concepts section in the python tutorial. The Scripting with Python tutorial is part of the General documentation and can be accessed from within Maestro’s Help facility from the Manuals Index.

Adding a copy of a structure to a project can be done using

pt=maestro.project_table_get()
pt.importStructure(ct)

All row access is with respect to the order of rows in the project (which can differ from the order of rows in Maestro’s Project Table since the table’s rows can be sorted and rearranged).

Column and Row indices start at 1.

There are 3 ways to refer to rows:

Internal project index in mmproj, they are effectively indices into an array. These values are hidden from the user; avoid using them in scripts.
Project Table row number, as it appears in the left-most column of the PT in Maestro. This number can change when rows are deleted or the table is sorted.
Entry ID, which is unique for each row and never changes. These values are ints, but are often represented as strings, e.g. “1”. Scratch entries will have non-int entry IDs, but are not stored in the project table. These are used in Maestro commands, ASLs, etc, and are visible to the user.

Iterating over all rows in the project is done using an expression of the form:

pt=maestro.project_table_get()
for row in pt.all_rows:
    # Now do something with row

Iterating over selected rows in the project is done using an expression of the form:

pt=maestro.project_table_get()
for row in pt.selected_rows:
    # Now do something with row

Accessing each row of the project table returns a ProjectRow object. Common operations on ProjectRow objects are to get (or set) a structure associated with that row:

st = row.getStructure()
# and then update
row.setStructure(st)

Also common is accessing the project data. This can be done either by the name of the project table column or the dataname (the latter being as it appears in Maestro format files):

energy = row['Relative Potential Energy-MMFF94']
energy = row['r_mmod_Relative_Potential_Energy-MMFF94']

New columns and new properties for existing entries can be added to the project in a similar way. Note that the refreshTable() function is usually required to be called to show the results of additions to the project table.

A project should be open by at most one process at any given time. It is an error to open a project currently opened by another process.

class schrodinger.project.Project(project_name='', project_handle=-1, manage=True, show_cleanup_dialog_on_close=False)¶

Bases: schrodinger.infra.mmobject.MmObject

Class to handle Maestro Projects. This is largely a wrapper to the underlying C library which stores all the state information.

The Project class allows selection of rows in the project via various interfaces.

A Maestro project may be accessed from within a Maestro session which has it open via maestro.project_table_get().

A Maestro project may alternatively be accessed without Maestro running by specifying a the name of the project when creating a project object.

See the doc string for the module for more details.

all_rows¶: Iterator for all rows in the project using the visible project table order

close()¶: Close the project immediately. This method is normally not needed and should only be called if garbage collection cannot be relied upon to close the project as normal. This method may be required in unittests to ensure the project is closed before the next test begins. Note that the project cleanup will occur in-process.

deleteRow(entry_id)¶: Delete the row with the given entry ID from this project.

disable(option=None)¶: Disable the specified option. Currently only AUTOMATIC_CACHE_FREEING is available. See enable() for details.

enable(option=None)¶: Enable the specified option. Currently only AUTOMATIC_CACHE_FREEING is available. This will cause any cached entries to be freed automatically after each iteration when using the all_rows iterator. Other iterators do not allow automatic cache freeing to be enabled.

findRowsMatching(prop, cmp_op, value)¶

Returns a list of ProjectRow entries for all rows matching the given criteria.

cmp_op should be “<”, “<=”, “>”, “>=”, “==”, “!=”

freeCachedEntries()¶

Frees all entries that are cached.

Things like ProjectRow.getStructure(), ProjectRow.structure, ProjectRow.setStructure() will cause entries to be cached. Unless the cache is freed memory usage will grow and can become quite large (if, for example, you are iterating over and retrieving a large number of structures).

Note that on some operating systems any memory already allocated within a process is not returned to the system when it is freed. Instead it is simply marked as available to the process and only gets returned to the system when the process exits.

Given this you may not see your memory usage decrease after calling this method. However, by calling this method at carefully chosen points you can minimize your memory footprint.

If you free the cache, then the next time the above-mentioned methods/properties are invoked they will get and cache the data by fetching it from disk.

fullname¶: Get the full name of the project (including the path)

getAdditionalDataDir()¶: Get the additional data directory of the project

getFixedColumnsCount(in_subset=True)¶

Return number of columns in fixed area. This does not include always fixed columns (Row, Included, Stars, 2D Structure and Title).

Parameters:	column – Whether to return fixed columns count only for the columns in subset (True by default)
Return type:	int
Returns:	Number of columns in the fixed area.

getPropertyNames()¶: Return a list of the data names of usable properties in this project instance, including properties which were hidden. There are some additional properties, like whether an entry is selected or included, which are not returned by this function.

getPropertyNamesForSelectedRows()¶

Return a set of data names of properties (including hidden ones) that are common to all selected entries in this project.

Returns:	List of property data names
Return type:	list of str

getPropertyPrecision(property_name)¶

Return the precision of the property.

Parameters:	property_name (string) – is the m2io data name (the long name) of the property for which you want the precision
Returns:	precision of the property as an integer

Throws a ValueError if the property name isn’t valid.

getRow(entry_id)¶

Retrieve a ProjectRow instance based on the entry ID.

Parameters:	entry_id (int or str) – is the entry ID of this project’s entry. This is the internally assigned identifier that is invariant for the life of the project. The ID does not change even if other entries are deleted or the entries (rows) in the Project are sorted. Entry ID can be passed in as a string also (e.g. “1”).
Return type:	ProjectRow
Returns:	ProjectRow if entry ID is valid Otherwise, returns None.

getSelectedRowTotal()¶: Return the total number of selected rows

getVisiblePropertyNames()¶

Return a list of the data names of visible properties in this project instance (hidden properties are not included).

Return type:	list(str)
Returns:	list of names of the property columns that are currently displayed in the Project Table

groups¶: Get the entry groups in the project

importStructure(st, name=None, wsreplace=False, copy=True)¶

Create a new entry in the Project Table from structure <st> and return the ProjectRow object for the new entry.

In rare cases (when your Structure is managed by C code and use of it is no longer needed in python) using copy=False can give better performance. Doing so will make the Structure invalid for further use in your script.

Parameters:	st (`structure.Structure`) – Structure to add to the Project Table. name (str) – Entry name to give to the new entry. By default, the value of the s_m_entry_name property will be used. wsreplace (bool) – whether to replace the Workspace with new entry. WARNING: if wsreplace is True, then any scratch entries in the Workspace will be disposed of without warning, which is not how Maestro would usually behave. copy (bool) – If set to False, will insert the actual input CT into the PT instead of copying it first.
Return type:	ProjectRow
Returns:	Return ProjectRow object for the new entry.

importStructureFile(filename, wsreplace=True, creategroups='multiple')¶

Imports all structures from the specified file into the Project Table. wsreplace - whether to replace the Workspace with the last structure in the specified file (default True). creategroups - which of the imported structures are to be grouped. Valid values are “multiple”, “all”, and “none”.

This method is only available when used from within Maestro.

includeRows(entry_ids, exclude_others=True)¶

Include rows with the given entry IDs in the Workspace, while optionally excluding all other entries.

Parameters:	entry_ids (list of ints or str.) – List of Entry IDs to include. exclude_others (bool) – Whether to also exclude previously included entries.

included_rows¶: Iterator for all included rows. No specific return order for the rows.

static initialize(error_handler=None)¶: Initialize necessary mmlibs (which will also implicitly initialize all the dependent mmlibs)

isColumnFixed(column)¶

Return whether the column is in fixed area of the Project Table.

Parameters:	column (int) – Project column
Return type:	bool
Returns:	Whether the column is in the fixed area.

last_added_entry¶: Return a ProjectRow instance for the last entry added to the project

moveRowsToGroup(entry_ids, group_name)¶

Move a list of project entries into a group.

Parameters:	entry_ids (list(str)) – a list of project entry IDs group_name (str) – the name of a group; if a group with this name doesn’t exist, it will be created

refreshTable()¶

Refresh the project table

This is only usable from within Maestro.

selectRows(select_mode=1, *args, **keywords)¶

Select rows in the project. Valid modes of selection are:

project.ADD - add rows to existing PT selection.
project.REPLACE - replace current selection.
project.INVERT - invert the PT selection.
project.ALL - select all rows in the PT.
project.NONE - deselect all rows in the PT.

Examples:

pt.selectRows(project.REPLACE, entry_ids=[1, 2, 3])
pt.selectRows(project.ALL)
pt.selectRows(project.NONE)
pt.selectRows(entry_ids=[1, 2, 3])
pt.selectRows(ADD, esl="entry_re entry*")

Parameters:

select_mode – Selection mode.
entry_ids (list(int) or list(str)) – List of entry IDs for the rows to select.
esl (str) – This is an ESL definition.
rows – Project indices for the rows to select (deprecated). Values refer to the values of the ProjectRow.index property.
rows – list(int)
function (callable) – Callback for determining whether a row should be selected or not (deprecated).

selected_rows¶: Iterator for the selected rows using the visible project table order

static setDebug(state)¶: Enable or disable debug output. Use False or True. Sets this for the class, i.e. affects all instances, current and future.

shortname¶: Get the short project name (without the path)

static terminate()¶: Terminate various mmlibs (which also implicitly terminates all the libraries they are dependent upon)

update()¶: If running in Maestro, update the project after a change as the user wants to see their changes in the PT. Does not do anything if the manual_update attribute is set to True.

Previous topic

Next topic

schrodinger.project module¶