Suite09 Python Scripting

Schrdinger Press

Scripting with Python

Scripting withPythonSchrdinger Suite 2009

Scripting with Python Copyright 2009 Schrdinger, LLC. All rights reserved.

While care has been taken in the preparation of this publication, Schrdinger

assumes no responsibility for errors or omissions, or for damages resulting from

the use of the information contained herein.

Canvas, CombiGlide, ConfGen, Epik, Glide, Impact, Jaguar, Liaison, LigPrep,

Maestro, Phase, Prime, PrimeX, QikProp, QikFit, QikSim, QSite, SiteMap, Strike, and

WaterMap are trademarks of Schrdinger, LLC. Schrdinger and MacroModel are

registered trademarks of Schrdinger, LLC. MCPRO is a trademark of William L.

Jorgensen. Desmond is a trademark of D. E. Shaw Research. Desmond is used with

the permission of D. E. Shaw Research. All rights reserved. This publication may

contain the trademarks of other companies.

Schrdinger software includes software and libraries provided by third parties. For

details of the copyrights, and terms and conditions associated with such included

third party software, see the Legal Notices for Third-Party Software in your product

installation at $SCHRODINGER/docs/html/third_party_legal.html (Linux OS) or

%SCHRODINGER%\docs\html\third_party_legal.html (Windows OS).

This publication may refer to other third party software not included in or with

Schrdinger software ("such other third party software"), and provide links to third

party Web sites ("linked sites"). References to such other third party software or

linked sites do not constitute an endorsement by Schrdinger, LLC. Use of such

other third party software and linked sites may be subject to third party license

agreements and fees. Schrdinger, LLC and its affiliates have no responsibility or

liability, directly or indirectly, for such other third party software and linked sites,

or for damage resulting from the use thereof. Any warranties that we make

regarding Schrdinger products and services do not apply to such other third party

software or linked sites, or to the interaction between, or interoperability of,

Schrdinger products and services and such other third party software.

Revision A, October 2009

ContentsDocument Conventions .................................................................................................... vii

Chapter 1: Introduction ....................................................................................................... 1

Chapter 2.1

2.2

2.3

2.4

2.5

Chapter 3.1

3.2

3.3

3.4

3.5

3.6

3.7

3.8

3.9

3.1

Chapter 4.1

4.2

4.3Scripting with Python iii

2: About Python ................................................................................................... 3What is Python? ........................................................................................................ 3

Where Can I Find Out More About Python? ......................................................... 3

Some Useful Things to Know About the Python Language.............................. 4

Why Python? .............................................................................................................. 5

Isn't It Too Slow? ....................................................................................................... 6

3: Running Python Within Maestro ........................................................ 7What Can I Do With Python in Maestro?............................................................... 7

Basic Concepts.......................................................................................................... 7

A First Python Script in Maestro ............................................................................ 8

Scripts, Modules, and Functions............................................................................ 9

The pythonrun Command ........................................................................................ 9

What To Do If It Doesn't Work ............................................................................... 10

The pythonimport Command ................................................................................ 10

Adding a Parameter ................................................................................................ 11

Module Search Path ................................................................................................ 12

0 The pythoneval Command................................................................................... 12

4: Issuing Maestro Commands ............................................................... 15The maestro Python Module ................................................................................. 15

Sending a Command to Maestro From a Python Script................................... 16

Other Ways to Use maestro.command() ............................................................. 17

Contents

Schrdingeiv

Chapter 5: Manipulating the Workspace .............................................................. 215.1 The Structure Concept ........................................................................................... 21

5.2

5.3

5.4

5.5

5.6

Chapter 6.1

6.2

6.3

6.4

Chapter 7.1

7.2

7.3

7.4r Suite 2009

Getting the Workspace Structure ......................................................................... 21

Setting the Workspace Structure ......................................................................... 22

Operations on Structures ...................................................................................... 225.4.1 Obtaining Information on Atoms ....................................................................... 225.4.2 Obtaining Information on Bonds ....................................................................... 245.4.3 Adding and Deleting Bonds .............................................................................. 255.4.4 Measuring and Adjusting .................................................................................. 255.4.5 Deleting Atoms.................................................................................................. 265.4.6 Other operations ............................................................................................... 26

Iterating Over Objects in the Structure ............................................................... 27Things You Can Do with the Workspace Structure ........................................... 27

6: Scripting the Project Table ................................................................... 33Getting Information About the Project Table...................................................... 33Selecting Entries in the Project Table ................................................................. 35Working on All Entries in the Project Table........................................................ 37Adding New Columns to the Project Table ......................................................... 38

7: Running Jobs from Scripts................................................................... 41Running Jobs From Within Maestro .................................................................... 41

The maestro.job_wait Function ............................................................................ 41Customizing Job Incorporation ............................................................................ 427.3.1 Specifying a Special Job Disposition ................................................................ 437.3.2 Incorporating Results Using Your Specialized Incorporation Function ............. 437.3.3 Removing Your Job Incorporation Callback ...................................................... 44

Running and Managing Jobs Outside Maestro ................................................. 447.4.1 Access to the Job Database ............................................................................. 447.4.2 Information on Job Hosts .................................................................................. 45

Contents

7.4.3 Running Jobs From Python............................................................................... 46

Chapter 8: Writing Your Own Panels ...................................................................... 478.1

8.2

8.3

8.4

8.5

Chapter 9.1

9.2

9.3

Chapter 10

10

Chapter 11

11

11

Chapter 12

12

Chapter 13Scripting with Python v

Tkinter ....................................................................................................................... 47

Important Considerations...................................................................................... 47

Supporting Atom Selection from the Workspace.............................................. 48

Creating Panels with a Maestro Look and Feel ................................................. 50

Adding a Help Topic to a Panel............................................................................. 51

9: Registering Python Functions with Maestro ............................ 53Periodic Functions .................................................................................................. 53

Mouse Hover Functions ......................................................................................... 54

Workspace Drawing and Changed Callbacks .................................................... 55

10: Debugging Your Scripts....................................................................... 57.1 The Power of print ................................................................................................. 57

.2 The pdb Module ..................................................................................................... 57

11: The Maestro Scripts Menu................................................................ 59.1 The scripts.mnu File ............................................................................................. 59

.2 Cascading Menus.................................................................................................. 59

.3 Creating Scripts to be Installed in Maestro ...................................................... 60

12: Tips and Traps ........................................................................................... 63.1 Things to Watch Out For ...................................................................................... 63

.2 Things That Might be Useful ............................................................................... 63

13: Running Scripts Outside Maestro ................................................ 65.1 Running Your Scripts ........................................................................................... 65

Contents

Schrdingevi

13.2 Simple Filters ......................................................................................................... 66

Appendix A: Reference Modules ............................................................................... 69

AppendiB.

B.

B.

Getting Hr Suite 2009

x B: The MacroModel Python Package ............................................. 711 The ComUtil Class ................................................................................................. 71

2 The CluUtil Class ................................................................................................... 77

3 The apps Module ................................................................................................... 78

elp ............................................................................................................................. 81

Document Conventions

In additionthis docume

Links to oththis: Docum

In descriptienclose a csymbol | ssyntax that

File name,tions. To obpath or dire% at each e

In this docuenter text m

References

Font

Sans serif

Monospace

Italic

Sans serifuppercaseScripting with Python viito the use of italics for names of documents, the font conventions that are used innt are summarized in the table below.

er locations in the current document or to other PDF documents are colored likeent Conventions.

ons of command syntax, the following UNIX conventions are used: braces { }hoice of required items, square brackets [ ] enclose optional items, and the bareparates items in a list from which one item must be chosen. Lines of commandwrap should be interpreted as a single command.

path, and environment variable syntax is generally given with the UNIX conven-tain the Windows conventions, replace the forward slash / with the backslash \ inctory names, and replace the $ at the beginning of an environment variable with and. For example, $SCHRODINGER/maestro becomes %SCHRODINGER%\maestro.

ment, to type text means to type the required text in the specified location, and toeans to type the required text, then press the ENTER key.

to literature sources are given in square brackets, like this: [10].

Example Use

Project Table Names of GUI features, such as panels, menus,menu items, buttons, and labels

$SCHRODINGER/maestro File names, directory names, commands, envi-ronment variables, and screen output

filename Text that the user must replace with a valueCTRL+H Keyboard keys

Schrdingeviii r Suite 2009

Chapter 1

Schrdinger Suite Scripting with Python

Chapter 1: Introduction

Since the beabilities havshown us tprovides imcombinatioMaestro funcustomizing

On top of thinterfaces textended inusers needs

Python is eakind of lear

This documThere are loknow aboutbeyond the

Class and fPython AP$SCHRODINquestions adocumentat

Python 2.6examples inentering the

$SCHRODIN

Note: Themaksoftsuc

callScripting with Python 1ginning, Maestro has had a command language. However, until recently, scriptinge been limited to simple lists of Maestro commands. Feedback from users has

hat many people need abilities well beyond that. For this reason Schrdingerproved scripting ability with the well-known scripting language Python. The

n of Python, the Maestro command language, and Python functions for usingctionality, is very powerful and greatly expands the capability for automating and Maestro.

e Maestro interface, the Python tools provided with Schrdingers software includeo the Job Control facility. With these interfaces, scripting capabilities can beto automated workflows that combine Schrdingers products in ways that suit the.

sy to use and fun to learn. It is a straightforward language that doesnt require thening curve normally associated with a programming language.

ent aims to provide a non-technical introduction to using Python within Maestro.ts of examples, and a brief description of the most important things you need toPython is included. While a detailed description of how to program in Python is

scope of this document, that information is readily available elsewhere.

unction documentation for Schrdinger modules is present only in the HTMLI documentation, which you can open from the HTML documentation index atGER/docs/Suite_2009_Index.html. See the HTML API documentation for

bout specific functionality not covered in this tutorial. You can also open the APIion from Maestro, by choosing Python API from the Help menu.

is included with the Schrdinger software distribution in mmshare. Some of thethis manual run Python interactively, which you can do with this version by

command:

GER/run python

following applies if you want to use PyQt: Users of this application may note use of the Qt software or functionality provided by this application to developware unless the user has purchased a Qt Commercial License from Trolltech, itscessors in interest, or one of its authorized distributors or resellers. User is specifi-y prohibited from using the Qt Open Source Edition with this Application.

Schrdinge2 r Suite 2009

Chapter 2


Chapter 2: About Python

2.1 WPython is aapplicationsdevelop othpreted langbefore it cathis documePython langthe hundred

What makeembedded PAt the samMaestro fun

2.2 WThere are amaterials. H

www.

Nearlyyour uPython

If youinto P

If youlike ap

O'Reil

The VScripting with Python 3hat is Python?feature-rich scripting language that has gained broad acceptance in a wide range of. Unlike programming languages such as C, C++ or Fortran (the languages used toer Schrdinger software like Maestro itself) Python is what is known as an inter-uage. This means that it doesn't have to undergo an extensive compilation processn be used. Developing scripts in Python is fast and easy. All the examples given innt are fairly short and deliberately avoid advanced language features. However, alluage features are available from within Maestro including the use of nearly all ofs of third party modules available for Python.

s Python so valuable for us is that it is both embeddable and extensible. We haveython in Maestro so that it can provide scripting facilities to control the program.

e time we have also extended Python by providing access to a whole range ofctionality for dealing with chemical structures, Maestro files, and projects.

here Can I Find Out More About Python?number of excellent sources of information about Python, both online and printere are a few:

python.org contains documentation, examples and a great many interesting links.everything you read about Python on this and related web sites will be relevant tose of Python in Maestro. Schrdinger Suite 2009 uses Python 2.4.3 so all the language features of that version are available from within Maestro.

have some experience with scripting or programming but not with Python, Diveython is filled with valuable, graduated examples that will help you master Python.

are a more experienced user, Thinking in Python covers more advanced conceptsplying design patterns to Python.

ly has published a number of popular Python books.

aults of Parnassus contain many useful Python modules and examples.


Schrdinge4

2.3 Some Useful Things to Know About the PythonLanguage

This section is targeted at those who do not have the time to fully master Python but still wantto write (ortials with w

Indentation{} to groupthey are indthe indentat

# Exax=5y=9if x

x

x = yprint

This examp

# Exax=5y=9if x

x

x

print

This secondgreater thanusually con

Note: YouWe

The # characurrent line

The keyworperform a pr Suite 2009

modify existing) scripts. It focuses on the basic core of Python, just the bare essen-hich to get started.

matters in Python. Unlike other scripting and programming languages which usestatements together, statements in Python are grouped simply by the level to whichented relative to one another. This means you need to take care in order to ensureion reflects the logic you intend. Consider the following two examples:

mple 1:

> 5 : = x-1+1 x

le prints 10 because the line x=y+1 is not part of the if block.

mple 2:

> 5 : = x-1 = y+1 x

example prints 5, since the lines x=x-1 and x=y+1 are executed if and only if x is5. All Python scripts use indentation to indicate grouping of statements, and it is

sidered good form to place each Python statement on its own line.

can use either space characters or tabs for indents, but you should not mix them. recommend using spaces.

cter is used for comments. Comments begin with a # and extend to the end of the. The Python interpreter ignores comments.

d def is used to define functions, which are groups of Python statements called toarticular task. Function parameters may have default values. For example:


# Example 3def myfunc( x, y=10 ):

x = x + yprint x

myfunmyfun

Here we hahas a defauexample. Indefault valuresult whichexplicit valu10.

Variables d(integer, strneed to beC++, there

All Pythonnize the file

2.4 WPython is nPerl are alla preferencand personause Pythonpossible wi

1. Whilemore

scalab

2. Of thePerl, o

3. PythonScripting with Python 5

c( 5 )c( 5, 5 )

ve defined a function called myfunc(). It takes two arguments, x and y where ylt value of 10. This means you can call myfunc in two ways as shown in thisthe first call to myfunc() a value for x is supplied, but no value for y, so the

e for y is used. As a result myfunc computes the sum of 5 and 10 and prints theis 15. In the second use, values are supplied for both x and y. By providing an

e for y, the default value is overridden and the result is the sum of 5 and 5 which is

o not need to be explicitly typed or destroyed. In the above examples, the typesing, real number) of the variables x and y are defined only by the context and do notdeclared before the variable is used. Also, unlike other languages such as C andis no need to allocate or free memory in Pythonthis is handled automatically.

script files should have a .py suffix. Without this suffix, Maestro does not recog-s as Python scripts.

hy Python?ot the only embeddable and extensible scripting language available. Ruby, Tcl andother possibilities. Perl is probably the most serious other contender. In many casese for a given language is a personal matter, that depends on the user's experiencel style. However, given that it is technically possible to use Perl in the same way we, and that in terms of language features essentially the same sorts of things areth either, there were three reasons we chose Python instead of Perl:

Perl is used widely for system administration and web programming, Python ispopular in scientific programming and larger scale development. Python is veryle: it can be used to write simple scripts or to develop full-fledged applications.

Maestro users surveyed, most expressed either a strong preference for Python overr no preference at all.

has a clean, straightforward syntax; a benefit for new or occasional users.


Schrdinge6

In language comparisons (such as between Python and Perl), there really is no right answer.However, while you may find some aspects of Python a little odd at first, we urge you topersist. Python is easy to learn and easy to use.

There are a number of accounts available of programmers who have made the switch from Perlto Python. OEric S. Ray

2.5 IsOne of the lbe parsed acomparisondescription

However, ois that mucactually doMaestro isMaestro itsnificant relascript.r Suite 2009

ne of the best is the Why Python? essay, by well-known programmer and authormond.

n't It Too Slow?imitations of an interpreted language like Python is that because each line needs tond understood (interpreted) at the time the script is run, it tends to be slow into compiled languages like C, which are translated into a low-level machine

before running.

ne important point about the way we use Python, both in Maestro and outside of it,h of the heavyweight computation and manipulation of chemical structures is notne in Python. As you will see from the examples in this document, Python inprimarily used for controlling the program. The real work is actually done by

elf. The time and overhead required to interpret a Python script is generally insig-tive to the work done by Maestro to execute the commands sent to it from a Python

Chapter 3


Chapter 3: Running Python Within Maestro

3.1 WThere arecommandsrealize that,command lachanged is tthe utility ovariables anpossible toMaestro com

While issuiling Maestrreceive infoTable. Thermanipulatevidual atom

3.2 BIn order toconcepts is

A Maestrothis data isoften referrproperties, wto a differestring. Propated by Mae

The Worksstructures amolecular smarkers, anScripting with Python 7hat Can I Do With Python in Maestro?two main ways that Python scripts can interact with Maestro: issue Maestroand manipulate Workspace structures and Project Table entries. It is important toalthough Python is the scripting language for Maestro, there is no change to thenguage. The syntax of Maestro commands remains the same. However, what hashe ability to issue Maestro commands from Python, a feature that greatly increasesf these commands. Python scripts can contain control structures (if, while, for, etc.),d parameters (values supplied by the user when the script is run), so now it is

write scripts that are considerably more flexible and general than the simple lists ofmands previously available.

ng commands with Python scripts is an extremely powerful mechanism for control-o, it is essentially a one-way communication. There is no way for the scripts tormation about Maestro, the structure in the Workspace or entries in the Projectefore we have introduced an additional mechanism so Python scripts can directlystructures and entries, right down to the level of changing the properties of indi-s. In practice many Python scripts use a combination of these two approaches.

asic Conceptseffectively write scripts that control Maestro a basic understanding of Maestro

needed. The two most important concepts are the Project Table and the Workspace.project is a collection of associated data and the Project Table is the way in whichviewed and modified. The Project Table contains zero or more rows. Each row ised to as an entry and consists of a structure (a collection of atoms) and zero or more

hich appear as columns in the table. Each column in the Project Table correspondsnt property. Acceptable property types are: Boolean, integer, floating point, anderties are most commonly produced from computational jobs but can also be gener-stro or added manually by users.

pace is the 3D display area in the center of the main window, where molecularre displayed. All 3D display is done in this area. This includes displaying thetructure as well as other information, including labels, measurements, ribbons,d surfaces. You can include (load) multiple entries simultaneously into the Work-


Schrdinge8

space for 3D viewing, analysis, or modification. Entries loaded into the Workspace containonly their structural information. Their properties are not loaded into the Workspace and there-fore the properties are not accessible via the Workspace structures.

It is also important to understand that entries (structures) that have been modified in the Work-space are nentry is imscripts in wtural entry ibeen synchThis also apin the ProjesynchronizeChapter 6.

When entryproject. Thientry whichWorkspace.

3.3 AThis tutoriarunning scr

You can crspecial capataining theyou can run

Example 1In your edit

# myfirstdef myfir

print

Take care tois part of thwhich you sr Suite 2009

ot immediately updated back into the project. By default, this happens when theplicitly or explicitly excluded from the Workspace. Thus, when writing Pythonhich you manipulate the entries in the Workspace but you want to take the struc-nformation from the project, you need to ensure that the Workspace changes haveronized back into the project prior to getting information from the Project Table.plies to cases where you simply want to get the structural information for an entryct Table: first make sure that the structural information in the Workspace has beend back into the project. For more information on how to modify projects see

properties are edited in the Project Table they are immediately updated in thes contrasts with the mechanism for updating the Workspaces structural data for an, as mentioned above, does so at the point at which the entry is excluded from the

First Python Script in Maestrol starts with a simple script that illustrates the basic mechanism for creating andipts within Maestro.

eate your Python scripts with any text editor. Some editors, like Emacs, includebilities for Python such as colorizing keywords, comments, and strings; and main-

correct indentation. Another possibility is the standard Python editor idle, which with the command $SCHRODINGER/run idle.

. myfirst.pyor, create the following script and name the file myfirst.py:

.pyst():"Hello World from Maestro"

indent the second line. It indicates that print "Hello World from Maestro"e myfirst() function. Save your script and start Maestro from the directory inaved your script.


3.4 Scripts, Modules, and FunctionsBefore we actually run the script in Maestro, it is worth discussing the terminologysurrounding Python scripts. While we will continue to use the term script in fairly loose terms,technicallycontain them

Modules gesingle functbe named a

It is importMaestro togeneral, runinto a single

A commondesigned toMaestro and

We have pryour own. Y

3.5 ThNow it is tifrom the diinput area:

pythonrun

You should

Hello Wor

displayed inwrote and e

Note: We

In this examcontainingdetails on wScripting with Python 9

what you just created is a Python module. Modules are named after the files that. Since you named your file myfirst.py, the module is called myfirst.

nerally contain a number of functions. In this example, our module contains aion, also named myfirst(). There is, however, no reason why a function needs tofter the module: it can have any name you wish.

ant to understand the distinction between functions and modules. When you askrun a script it is actually executing a single function inside a module; it does not, inthe entire contents of the module. You can in fact place all the functions you write file, although this practice is not recommended.

practice is to place a set of related functions into a module. Some may not bebe directly called from Maestro. You might, for example, call one function from that function in turn might call other functions in the same module.

ovided a number of useful functions that you can use as starting points to createou will see more on this in the next chapter.

e pythonrun Commandme to run your script. You saved your script as myfirst.py and started Maestrorectory that contains the script. Now, enter the following in the Maestro command

myfirst.myfirst

see:

ld from Maestro

the terminal window from which you started Maestro. Congratulations! You justxecuted your first Python script from Maestro.

specified both the module and function as part of the pythonrun command.

ple, we had direct access to our script by starting Maestro from the directorythe script, but this can quickly become restrictive. See Section 3.9 on page 12 forhere to store modules.


Schrdinge10

3.6 WIf the scriptin Figure 3following:

The fi The fi You co

If you seescript. For ethe functionmyfirst fu

3.7 ThWhile pythscripting, ipythonimpr Suite 2009

hat To Do If It Doesn't Workdid not run as you expected, there are a few things you can try. The error message

.1 means that Maestro was not able to locate the myfirst module. Check the

le is saved and named myfirst.pyle exists in the directory from which Maestro was startedrrectly typed the command as pythonrun myfirst.myfirst

an error message like Figure 3.2 you probably introduced a syntax error into thexample, this message indicates the indentation was not correct. The second line ofmust be indented relative to the first so that Python knows print belongs to the

nction.

e pythonimport Commandonrun is the most commonly used Maestro command associated with Python

f you are making frequent changes to a python script you will also findort useful. One of the side effects of using pythonrun is that a copy of the

Figure 3.1. Import Error.

Figure 3.2. Indentation Error.


module containing the requested script is actually loaded into memory. This allows Maestro tobe more efficient in handling repeated requests for the same script. But if you now makechanges to the myfirst.py file while Maestro is running and once again enter:

pythonrun myfirst.myfirst

you do notfrom the prcomes into

pythonimp

Maestro repythonrun

3.8 AA small chMaestro.

Example 2# myfirstdef myfir

print

Save your c

pythonrun

It displays tThis is becafor param,""), then ru

Now run th

pythonrun

You should

Hello Wor

This is a vecommand scan take anScripting with Python 11

see the effects of your changes. Maestro is still using the original myfirst scripteviously loaded myfirst.py file. This is where the pythonimport commandplay. When you run:

ort myfirst

loads the myfirst.py file so that the next time you execute the script using, the updated version is used.

dding a Parameterange to myfirst.py illustrates how to pass information to a Python script in

. myfirst.py

.pyst( param = "" ):"Hello World from Maestro " + param

hanges and then use pythonimport to reload myfirst.py. Now run the script:

myfirst.myfirst

he same output as the first version of myfirst.py: Hello World from Maestro.use we added an empty string as the default parameter. If you do not supply a valuethe script supplies an empty string. If we had not added the default value (param =nning myfirst without a value for the parameter results in an error.

e script with a parameter:

myfirst.myfirst "a second time"

see:

ld from Maestro a second time

ry significant feature of running Python from within Maestro. Unlike older Maestrocripts, where everything needed to be hard-coded into the script, Python functionsy number of parameters, some or all of which can have default values. This allows


Schrdinge12

Python scripts to be very general. For example, you can write a script that operates on a file-name supplied by the user at the time the script is run.

Note: With the exception of quoted strings (""), which are treated as a single parameter, allparameters entered from the Maestro command input area must be separated by whitespa

3.9 MThis sectionMaestro wascripts. Howdirectories.

your home

where versilike myfirs

pythonrun

from any di

Note: Mafirshav

3.10 ThThere is a tfrequently t

PythonevaThis means

You can acmodule andmyfirst.p

pythonevapythoneva

is equivalen

pythonrunr Suite 2009

ce.

odule Search Pathdescribes how Maestro locates the module file. In our example we made sure that

s started from the directory containing myfirst.py. This is typical for developingever, it is not very convenient when you want to use your script in many different

To make this easier, we created a special directory for your scripts:

dir/.schrodinger/maestroversion/scripts

on is the 2-digit Maestro version number. Inside this directory you can place filest.py. Then you can issue commands like:

myfirst.myfirst

rectory in which you run Maestro.

estro looks first in the current directory (the one from which you started Maestro)t before looking in $HOME/.schrodinger/maestroversion/scripts. So if youe a local copy of the script, the local copy is used instead.

e pythoneval Commandhird Python-related Maestro command, pythoneval. This command is used lesshan the commands already discussed, but it is described here for completeness.

l allows you to execute any Python expression in the Maestro Python interpreter. you have interactive access to the interpreter.

hieve the same result as pythonrun but you must remember to first import theuse the Python style syntax to call any functions. So using the example fory as described above:

l import myfirstl myfirst.myfirst("a second time")

t to:

myfirst.myfirst "a second time"


Now you know the basics of creating Python scripts and running them from within Maestro.The next chapter describes how to create a Python script that actually interacts with Maestro.Scripting with Python 13

Chapter 4


Chapter 4: Issuing Maestro Commands

The previouintroducedMaestro com

4.1 ThIn order tointo your sccontain a lin

from schr

near the tomaestro m

There are seimport mafunctions inlook at Pythuse the imp

from schr

This meansthe maestr

You can eve

from schr

This means

Note: YoureqprevScripting with Python 15s chapter showed how to run a very simple Python script from within Maestro andmodules and functions. This chapter discusses how you can write scripts to issue

mands.

e maestro Python Modulecommunicate with Maestro you need to first import the provided maestro moduleript. You'll see that most of the example scripts in the remainder of this documente which looks something like:

odinger.maestro import maestro

p. This tells Python to load and make available the functions contained in theodule, which is part of the Schrdinger package of modules.

veral variants of this. In our examples we use the from schrodinger.maestroestro form. This means that in the example scripts we will always reference thethis module in the fully qualified form as maestro.function(). However, if youon documentation or other scripts, you will see that there are other ways you canort command. For example:

odinger.maestro.maestro import *

that everything in the maestro module can be used directly in your script withouto. prefix.

n go further and use an import expression such as:

odinger.maestro.maestro import command as c

that instead of using maestro.command() you can simply use c().

can write your own modules and import them into other modules. The onlyuirement is that your modules are in the module search path as described in theious chapter.


Schrdinge16

4.2 Sending a Command to Maestro From a PythonScript

Example 1. roty.py1. Create

# rotfrom

def r m

2. In Ma

3. In the

pytho

You shabout

4. You cinstan

pytho

rotates

There are a

We usa norm

comm

Maest

Note:

The msubstitthe

"rota

expresissuedthis dor Suite 2009

a file called roty.py that contains the following:

y.pyschrodinger.maestro import maestro

oty( by=90 ):aestro.command( "rotate y=%d" % by )

estro, place a structure in the Workspace.

command input area, enter the following command:

nrun roty.roty

ould see the contents of the Workspace rotate by (the default value of) 90 degreesthe Y axis.

an rotate by any amount by supplying your own value for the parameter. Force:

nrun roty.roty 30

the contents of the Workspace by 30 degrees.

couple of notable things about this script:

e maestro.command() to tell Maestro to issue a command. The command is justal Maestro command (and can include any aliases you may have defined for the

and). The hundreds of available commands and their options are documented in thero Command Reference Manual.

You can review the commands that have been issued in the normal operation ofMaestro by choosing Command Script Editor from the Edit menu.

aestro.command() function takes a single string parameter. However we canute the value of variables into that string before issuing the command. This is what

te y=%d" % by

sion does. The value of by is substituted into the string before the command is. This is an extremely powerful mechanism and we provide more examples later incument.


There are a couple of enhancements we can make to this script. In the previous example theaxis of rotation is hard coded into the Python function. We could create similar functions calledrotx() and rotz() to rotate around the other axes. Another option is to supply the axis ofrotation as a parameter and add that into the command string before issuing the command.Here is thealso taken c

# rot.pyfrom schr

def rot(

if( ar

maest

Now you ca

pythonrun

to get a rota

Note: Whtersstru

r

4.3 OThere are tproviding aMaestro cofollowing:

maestro.cmaestro.cmaestro.c

In this way

It is also pousing a triplabove can aScripting with Python 17

reworked example in which we have not only parameterized the axis of rotation butare to verify that the supplied argument is a valid axis:

odinger.maestro import maestro

axis="y", by=90 ):

xis != "y" and axis != "x" and axis != "z" ):aise Exception, "%s is not a valid axis" % axis

ro.command( "rotate %s=%d" % (axis,by) )

n issue a Maestro command such as:

rot.rot x 30

tion of 30 degrees around the X-axis.

ile this might be a good example of building your own function that uses parame-, you will probably want to use the Maestro rotate command directly to rotatectures in the Workspace:

otate x=30

ther Ways to Use maestro.command()wo other ways in which maestro.command() can be used. First, instead ofsingle string, it is possible to specify the keyword, operands, and options of the

mmand separately. For example, to rotate around the x, y, and z axis use the

ommand("rotate", x=5)ommand("rotate", y=5)ommand("rotate", z=5)

the keyword rotate is a separate parameter from the options: x=5, etc.

ssible to issue more than one command in a single call to maestro.command() bye quoted string with each command on a separate line. For example, the commandslso be issued as:


Schrdinge18

maestro.command("""rotate x=5rotate y=5rotate z=5""")

This is a uscommand s

Example 2Before wefunction thaexample usfrom the ke

#spin.pyfrom schrimport tidef spin( total

# Verif ax

r

while#i

e

e

# m

# t t

retur

When this i

pythonrunr Suite 2009

eful way to issue a series of Maestro commands taken directly from the Maestrocript editor. Note that each command must be on a new line.

. spin.pyfinish this introduction we will look at a more sophisticated examplea Pythont does something not currently possible with a Maestro command. The followinges the form of maestro.command() where the options are specified separatelyyword:

odinger.maestro import maestromeaxis="Y",step=10,slp=0.1):_rotate=0

ify the axis:is != "X" and axis != "Y" and axis != "Z" :aise "MyException", "Can't use axis: " + axis

( total_rotate < 360.0 ) : Issue a rotate command.f axis == "X": maestro.command("rotate", x=step)lif axis == "Y": maestro.command("rotate", y=step)lif axis == "Z" : maestro.command("rotate", z=step) Redraw the windowaestro.redraw() Increment the total rotation by the step increment:otal_rotate += stepime.sleep(slp)

n

s run as:

spin.spin Y 20 0.2


it spins the structure in the Workspace around the Y axis 360 degrees in increments of 20degrees. The axis, increment, and the delay are all specified as parameters.

There are a few points to make about this script:

In addule tiintrod

Note hbinatiomodul

In thisthe Wo

If you wangood placethen anothe

It is also pexample, if

alias spi

then you ca

In general,to achieve iscript, butredrawing t

As powerfucommandsdetail.Scripting with Python 19

ition to including the maestro module we also include the standard Python mod-me. This allows us access to the time.sleep() function, used in this script to

uce a short delay after each rotation.

ow the total_rotate variable is used in the while loop. You can use any com-n of parameters and variables in combination with the functions in the maestroe.

particular function we need to use maestro.redraw() to force the contents ofrkspace to be redrawn after each rotation.

t to experiment with issuing commands from your own scripts, this example is ato start. As an exercise, create a script that rotates the structure first one way andr.

ossible to use Maestro's command alias function to create new commands. Foryou issue:

n pythonrun spin

n just use spin like any other command.if a task can be performed by issuing a Maestro command, that is the preferred wayt from a Python script. Not only does this generally result in the shortest possibleMaestro commands also automatically update the internal state of Maestro,

he Workspace as needed, and so on.

l as these techniques are, there are still things you cannot achieve using Maestroalone. The following chapters describe how to control Maestro at a lower level of

Chapter 5


Chapter 5: Manipulating the Workspace

Previous chissue commimportant toread beforesophisticateWorkspace.

5.1 ThThe chaptertion of atomentries in thatoms, bondstored inforyou can imp

from schr

Once you g

5.2 GAs long as ythe Workspshould takechanges theentries. Thenext Maestr

To get the W

st = maesScripting with Python 21apters covered how to run Python scripts in the Maestro environment and how toands from those scripts. Important information about some of the basic conceptsPython script writers was presented in Section 3.2 on page 7, which you shouldproceeding if you have not already done so. In this chapter we discuss more

d and powerful features that allow you to directly manipulate the structure in the

e Structure Concepts that follow refer to the concept of a structure. In Maestro, a structure is a collec-s. The contents of the Workspace are considered a structure, as are individual

e Project Table. Maestro stores information about structures: information about thes, and their properties. Python can get structures and manipulate them using this

mation. To do this, Python uses the functions in the structure.py module, whichort into your script with the following command:

odinger import structure

et a structure, you can manipulate it in many ways, including deleting all the atoms.

etting the Workspace Structureour script is running you can get the structure which corresponds to the contents oface. This structure is valid for as long as your script is running. However youcare to get the structure again if your script issues a Maestro command thatcontents of the Workspace, such as importing new structures or including newsafest approach is to treat the structure as valid only until the completion of the

o command.

orkspace structure in a Python script, use a statement such as:

tro.workspace_get()


Schrdinge22

Once you have a structure there are a number of operations you can perform on it. You shouldhowever note the following:

The structure that is returned from workspace_get() is the actual Workspace structureas used by Maestro. Any changes made will be reflected in the Workspace.

The stwith tproper

If youwith S

5.3 SOnce you c

maestro.w

Then you c

maestro.r

to request texecuting. Ybefore your

Setting regdistances, laset to True

Note: worfromwor

5.4 OThe followi

5.4.1 OYou can obindex indivstatements ar Suite 2009

ructure object returned does not contain any properties, such as those associatedhe entry in the Project Table. You have to use the project module to get access toties.

want to pass the structure to another operation we suggest you make a copy of ittructure.copy().

etting the Workspace Structurehange the structure, you can pass it back to Maestro for display. To do this, use:

orkspace_set(regenerate_markers=True)

an use:

edraw_request()

hat Maestro redraw the contents of the Workspace when your script has finishedou can also use maestro.redraw() to redraw the contents of the Workspace

script has finished executing.

enerate_markers to True (the default) forces Maestro to update markers forbels, and so on, and to apply any changes to the Workspace structure. It should be

in most circumstances.

kspace_set() will not work correctly if the specified Structure is passed directlyProject Tables row.structure (or if it is managed by another C library). The

karound is to pass a copy of the Structure.

perations on Structuresng summarizes many of the operations possible with a structure object.

btaining Information on Atomstain information on atoms through the atom property of a structure. It is possible toidual atoms (indices start from 1) or to iterate over atoms. So the following twore equivalent:


for iatom in st.atom:print iatom.x

for iatom in range(1,len(st.atom)+1):print st.atom[iatom].x

Here x is tTable 5.2 ca

Table 5.1. A

Property

atom_nam

atom_sty

atom_typ

atomic_n

chain

color

formal_c

growname

inscode

partial_

pdbname

pdbres

resnum

secondar

solvatio

temperat

visible

x

xyz

y

zScripting with Python 23

he x coordinate for the atom, but any of the properties shown in Table 5.1 andn be used.

tom properties for access or modification.

Description

e Maestro atom name (used for Jaguar mostly)le Molecular representation of the atom (wire, CPK etc.)e MacroModel atom type

umber Atomic number

PDB chain name

Integer index representing color in Maestro color palette

harge Formal charge

Maestro builder grow name

PDB residue insertion code

charge Partial atomic charge

PDB atom name

PDB residue name

PDB residue number

y_structure Secondary structure assignment (HE-)n_charge Solvation atomic charge

ure_factor PDB temperature factor (isotropic B factor)Workspace display state

x coordinate

List of atomic coordinates [x, y, z]y coordinate

z coordinate


Schrdinge24

Atom propeFor exampl

for iatomprint

for iatomprint

5.4.2 OOnce you husing the bo

total_ordefor iatom

for i

Table 5.2. Atom properties for access only - cannot be modified.

Property Description

atomic_number Atomic number of the atom.

atomic_w

bond_tot

bonded_a

chirality

element

entry_id

entry_na

index

molecule

number_b

number_br Suite 2009

rties can also be obtained using the data names as they appear in the Maestro file.e the following two ways of printing the x coordinate are equivalent.

in st.atom: iatom.x

in st.atom: iatom.property['r_m_x_coord']

btaining Information on Bondsave an atom, you can obtain information on the bonds associated with that atom bynd property. So for example:

r=0in st.atom:bond in iatom.bond:total_order += ibond.order

eight Atomic weight of the atom. If implicit hydrogens are present, theyare included as part of the atomic weight.

al Total number of bonds to this atom

toms An iterator that returns atoms bonded to this atom

Chirality of the atom: R, S, or None.

Element symbol

Entry ID

me Formerly entry name, now returns entry ID. Use entry_idinstead. Entry name should be obtained as a property from theproject via s_m_entry_nameIndex (atom number) of the atom in the structure, ignoring anyclassification into molecule, entry, and so on.

_number Number of the molecule to which this atom belongs

y_entry Atom number by entry

y_molecule Atom number by molecule


This example uses the bond order property. The available bond properties are listed inTable 5.3.

5.4.3 A

This can be

st.addBon

adds (or setst.delete

deletes the b

There is alsbond betwe

5.4.4 M

To measure

st = maestprint st.mprint st.mprint st.m

Note thatmeasureme

supports deatoms).

Table 5.3. Bond properties for access or modification.

Property

order

atom1

atom2

styleScripting with Python 25

dding and Deleting Bonds done via the structure class:

d( 12, 17, 2 )

s if it already exists) a double bond between atoms 12 and 17.Bond( 12, 17 )

ond between atom 12 and 17.

o the areBound() method which returns True if the two atoms specified have aen them.

easuring and Adjusting, you can use the measure() method of the structure class:

ro.workspace_get()easure( 1, 2 ) # Distance between atoms 1 and 2easure( 1, 2, 3 ) # Bond angle between 1, 2, and 3easure( 1, 2, 3, 4 ) # Torsion angle between 1, 2, 3, and 4

the structureutil module contains a measure() method, which allowsnts of any type to be performed between different Structure objects and alsotermining the angle between two planes (as defined between two sets of three

Description

Bond order

The first atom of the bond

The second atom of the bond

The molecular representation of the bond (wire, tube)


Schrdinge26

Adjust works in a similar manner:st.adjust( 2.5, 1, 3 ) # Set distance between atoms 1 and 2 to 2.5 Angsst.adjust( 110, 1, 2, 3 ) # Set bond angle between atoms 1, 2, and 3 to 110 degreesst.adjust( 180.0, 1, 2, 3, 4 )# Set the

5.4.5 D

This is done

to_del = st.delete

5.4.6 OThe structuThese inclu

Substructur

Match Match Match Evalua Locati Gener Gener

Properties:

Measu Gettin Gettin Testin Determ

Superimpos

Superp Superp

Structure m

Additi Gener

For more der Suite 2009

torsion angle between atoms 1, 2, 3, and 4 to 180.0 degrees

eleting Atoms with the deleteAtoms() method. For example:

[1,2,5]Atoms(to_del)

ther operationsreutil model contains a number of functions which operate on Structure objects.de the following

e searching or matching:

ing a SMARTS expressioning a list of SMARTS expressionsing a list MacroModel substructure notation expressionting a Atom Specification Language (ASL) expressionng the smallest set of smallest ringsating a SMILES expression for a set of atoms in a structureating a SMARTS expression for a set of atoms in a structure

ring distances, angles, dihedrals and plane angles between structuresg a list of chiral atomsg a list of rotatable bondsg if hydrogens are present

ining if a H-bond criteria is fulfilled.

ing structures:

osition based on lists of atomsosition of conformers

anipulation:

on of hydrogens in standard positionsation of crystal mate structures

tail see the HTML documentation of the structureutil Module.


5.5 Iterating Over Objects in the StructureIt is possible to iterate over a number of objects in a Structure objectchains, molecules, resi-dues and rings. These iterators all function in a similar way:

st = maesprint "Thimol=1for mol i

printfor a

# molst molst imol

See the HTators. Noteand ring obwhich it is e

5.6 ThThere are mthem here. F

What follow

Example 1This exampspace structrated by mo

#closecontfrom schrofrom schrofrom schrodef close_

# Get st = m distan

# Loopfor iaScripting with Python 27

tro.workspace_get()ere are %d molecules" % len(st.molecule)

n st.molecule:"There are %d atoms in the molecule" % len(mol.atom)tom in mol.atom: Do something for atoms in molecule = mol.extractStructure().write( "molecule%d.mae" % imol )+= 1

ML documentation for the structure module for more information on these iter-that the extractStructure() method provided for the chain, residue, molecule,jects does not inherit the title or any other structure-level properties of the structurextracted from.

ings You Can Do with the Workspace Structureany things you can do with a structure once you retrieve it. We cannot cover all ofor more information, see the HTML documentation for the structure module.

s are a couple of examples.

. closecontact.pyle illustrates how to issue Maestro commands and manipulate the Maestro Work-ure. We use a Python function to highlight close contacts between any atoms sepa-re than three bonds:

act.pydinger.maestro import maestrodinger import structuredinger import structureutilcontacts(thresh=2.0) :the current Workspace structure and calculate the number of atoms:aestro.workspace_get()ce = 0

over all the atomstom in st.atom :


Schrdinge28

# Calculate a list of all the atoms which are not within three bonds# of the current "iatom". This is done by evaluating an ASL expression# "not( withinbonds 3 atom. iatom)"

not_neighbours = structureutil.evaluate_asl( st,"not( withinbonds 3 atom. %d)" %

fo

di

By now youtional modulower level.

The first tasover all atom

For each atoatom if it ission: not(

Evaluatingthat list in athan the gicommand.

This scriptmaking mestructure di

Example 2The followithe O-H andas possiblemodule. Onimproves th

Note: Thinotpror Suite 2009

int(iatom) )

r jatom in not_neighbours :# Calculate the iatom-jatom distance

stance = st.measure( iatom, jatom)if( distance < thresh ) :

# This distance is less than the threshold - generate# a maestro command:maestro.command("distance %d %d"% (int(iatom), int(jatom)) )

recognize the import maestro statement. This example also imports two addi-les, structure and structureutil, that we provide to perform operations at a

k in close_contacts() is to get the structure from the Workspace. Next we loops in the structure.

m in the Workspace, we only want to calculate the distance away from the currentmore than three bonds away. An easy way to calculate this is with an ASL expres-withinbonds 3 atom.iatom).

this returns a Python list containing the atoms that satisfy our expression. We usen inner loop to calculate the distance from the current atom. If a distance is less

ven threshold, we use Maestro to mark the distance by issuing the distance

contains common tasks: looping over all atoms, evaluating ASL expressions, andasurements on the structure. Note that since we did not make any changes to therectly, we did not need to call maestro.workspace_set().

. rotH.pyng script adds hydrogens to the structure in the Workspace, and attempts to rotateS-H groups on SER, THR, TYR, and CYS residues to place the hydrogen as close

to an acceptor. This is also an example of using multiple functions in a Pythonly one of the functions is intended to be called from Maestro. The other simplye readability of the script.

s script is provided purely as an example of how to manipulate the workspaceit isintended to be a solution to the difficult problem of orienting hydrogens in

teins!


#rotH.py#Import the modules we need:from schrodinger.maestro import maestrofrom schrodinger import structurefrom schrodinger import structureutil

def rotH( """ Th a sing look f

# Star st = m

# Add # comm# we a

struct num_at

# Now # The

rotabl

# Crea# atom

h_list acc_li

# rota# and for h

# di

if

# # # Scripting with Python 29

radius = 4.0 ):is is the function which is to be called from Maestro. It takesle parameter which is for each H-X how far from X we shouldor acceptors (the default is 4.0) """

t by getting the workspace structureaestro.workspace_get()

hydrogens to the structure. We could do this by using a Maestroand but this shows how we can also do it without using Maestro. Afterdd hydrogens we can then get the number of atoms:ureutil.add_hydrogens( st )oms = len(st.atom)

locate all the rotatable atoms in all the CYS, SER, TYR and THR.simplest way to do this is using an ASL expression:es = structureutil.evaluate_asl( st,"(res.ptype SER, THR, TYR, CYS ) and (atom.ptype HG, HG1, HH )")

te a couple of empty lists to hold the numbers of the hydrogens which have nearby acceptors and the nearest acceptor for each one: = []st = []

bles is now a list of the appropriate atoms. We can loop over thatdo what we need to do with them:in rotables:We need to locate a suitable dihedral angle to rotate:hedral = get_dihedral_atoms( st, h )not len(dihedral) == 4 :# Under normal circumstances there shouldn't be any situations# where we can't locate four atoms. However, there is the chance# that we might get an incomplete residue in a PDB file, so we'll# just ignore this residue if that's the case:continue

We can use another ASL expression to locate all the possibleacceptors within a reasonable distance of the heavy atom whichthe hydrogen is attached to:


Schrdinge30

acc_types = "OD1, OE1, OD1, SG, SD, ND1, NE2, OH, O" asl = "( within %f atom.num %d ) and atom.ptype %s" % ( radius, dihedral[1], acc_types)

# Note that we exclude the backbone and the residue we are in: as

"( % ac

an

mi be

# # # # wh

# # if

r Suite 2009

l = \ %s ) and ( sidechain or res. HOH ) and not fillres( atom.num %d )" \( asl, dihedral[1] )ceptors = structureutil.evaluate_asl( st, asl )

g = 0.0n_dist = 1000.0st_ang = 0.0If it actually found some suitable acceptors, we canthen scan the C-C-O-H dihedral see which dihedral gives theclosest contact to an acceptor. The scan is done in incrementsof 5 degrees:ile len(acceptors) > 0 and ang < 360.0 :# Set to the current angle:# Note that we pass the dihedral# as C2-C1-X-H as specifying it in this way indicates# we want to rotate the hydrogen:

st.adjust( ang, dihedral[3], dihedral[2], dihedral[1], dihedral[0] )

# For each acceptor atom measure the distance and find out# whether we've actually found a closer match than we've found# before:for acc in acceptors:

dist = st.measure( h, acc )if dist < min_dist:

min_dist = dist best_ang = ang best_acc = acc

# increment the angle by 5 degrees: ang += 5.0

We've tried all the angles now. Reset it back to the onewhich gave us the closest contact with an acceptor: len(acceptors) > 0: st.adjust( best_ang, dihedral[3], dihedral[2], dihedral[1], dihedral[0] )

# Keep a list of the atoms associated with the best


# interaction. For convenience we keep a string representation# of the atom number as we know now that we will later# transform this into an ASL expression:

h_list.append( "%d" % h ) acc_list.append( "%d" % best_acc )

# Fina# in t

maestr

# Put # haveif( le

h_ ac

ma

return

##########def get_di

""" Fo be use This f

ret_li

# The ret_li

# Now # asso# look

Xatom ret_li

# Now C1atom

for b co

# if

Scripting with Python 31

lly we tell Maestro that we want this structure to be used backhe workspace:o.workspace_set( st )

up some hydrogen bond markers to highlight if we picked up any H-bondsn( h_list ) > 0 ):asl = ", ".join( h_list )c_asl = ", ".join( acc_list )estro.command( "hbondset1 atom.num %s , %s " % (h_asl, acc_asl) )

################################################################hedral_atoms( st, h ):r atom number h in the structure st, find four atoms tod to scan the C-C-X-H dihedral. These are returned as a list.unction illustrates how to traverse the bonds of a structure """

st = []

fist atom will be H itself:st.append(h)

find the O or S attached to the H. Note that bonds (like everythingciated with structures) are indexed from "1" so we areing for the first bond:= st.atom[h].bond[1].atom2st.append( int(Xatom) )

find a suitable non-H atom bonded to the X: = -1in st.atom[Xatom].bond:nn_atom = b.atom2This is probably the easiest way to find a non-H atom:not conn_atom.atomic_number == 1 :

C1atom = int(conn_atom) ret_list.append( C1atom )

# Leave the loop:break


Schrdinge32

# Check to see that we did find a C1 atom:if C1atom < 0 :

return ret_list

# Now for b

co

# if

return

Now that wat how to acr Suite 2009

look for the final atom we need:in st.atom[C1atom].bond:nn_atom = b.atom2This is probably the easiest way to find a non-H atom:not conn_atom.atomic_number == 1 :

C2atom = int(conn_atom) ret_list.append( C2atom )

# Leave the loop:break

ret_list

e have seen how to manipulate the structure from the Workspace, next we will lookcess the Project Table directly.

Chapter 6


Chapter 6: Scripting the Project Table

While usingthe functionProject Tabread Section

6.1 GSometimesWorkspacethe maestrBy default s

pt = # Loo for s

#

only operat

pt = # Loo for i

#

operates on

Example 1Here is an e

#saveimage

from schrofrom schro

def save_i

pt = mScripting with Python 33Python scripts to manipulate the structure in the Workspace is useful for extendingality of Maestro, you can also automate Maestro by operating on structures in the

le. This chapter provides an overview of the possibilities. Before proceeding please3.2 on page 7 for a description of some important basic concepts.

etting Information About the Project Tablethe easiest way to operate on the Project Table is to bring each structure into thein turn and operate on it there by issuing Maestro commands. You can do this witho.project_table_get() function and looping over all the items in the table.uch looping only returns the selected entries. So a loop like:

maestro.project_table_get()p over the selected entriesel_entry in pt: Do something for selected entries only using "sel"

es on the selected entries whereas:

maestro.project_table_get()p over the selected entriesrow in xrange(1,len(pt)+1): Do something for all entries using pt[irow]

all entries.

. saveimage.pyxample that saves a .jpg image for each selected entry:.py

dinger.maestro import maestrodinger import project

mage():

aestro.project_table_get()


Schrdinge34

# Loop over the selected entriesfor sel_entry in pt:

eid = pt[sel_entry]['s_m_entry_id'] maestro.command("entrywsincludeonly entry \"%s\"" % eid ) maestro.command("saveimage format=jpeg jpeg_quality=75 %s.jpg" %

Note: Thecom

If your proentrywsin(To set thesfolder.) You

Example 2The followcommands

#methylate

from schrofrom schrofrom schro

def methyl

pt = mmaestr

for se ei ma

ct am

fo

You can useWorkspaceproject.gr Suite 2009

eid )

entry ID needs to be surrounded with quotes in the entrywsincludeonlymand. This ensures that entry names that contain spaces are treated as one name.

ject synchronization preferences are set to Automatic, each time you initiate ancludeonly on one entry in the Workspace, all entries in the project are updated.e preferences, choose Preferences from the Maestro menu, then select the Project can use this to make a change to all the selected entries.

. meth.pying script methylates amides in every selected structure by combining Maestrowith direct manipulation of the Workspace structure for each selected entry:

.py

dinger.maestro import maestrodinger import structureutildinger import project

ate():

aestro.project_table_get()o.command("fragment organic Methyl")

l_entry in pt:d = pt[sel_entry]['s_m_entry_name']estro.command("entrywsincludeonly entry", eid ) = maestro.workspace_get()ides = structureutil.evaluate_smarts( ct, "[H]NC(=O)" )r amide in amides: maestro.command("attach %d" % amide[0] )

practically any combination of Maestro commands and direct manipulations in thestructure to achieve the results you want. We have also provided a similar function,etPropertyNames() that returns the property names.


6.2 Selecting Entries in the Project TableMaestro has built-in support for selecting entries with entryselectonly and similarcommands. This support is provided in three ways:

Entry ability use of

There are lion Maestroties associa

entrysele

selects onlyare not poss

entrysele

While it ispossible to(number ofas the differ

If your Pytissuing a eproject.sfor every enFalse thesponding toProject Tabnumbers to

Example 3This examp

#select_ri


def selectScripting with Python 35

Selection dialog box to define filters ESL (see below)mits to what type of selections can be generated with these features. They all rely's Entry Selection Language (ESL). The ESL was designed to work on the proper-ted with entries. For example:

ctonly property1 < 4

the entries where property1 has a value less than 4. However, since calculationsible in ESL, the following command would not work:

ctonly (2 * property1) < 4

possible to create expressions of arbitrary complexity with the ESL, it is notmake selections in Maestro based on calculations performed on the actual structureatoms etc.) nor to make selections based on functions of the entry properties suchence between two properties.

hon script needs to make selections in the Project Table that are not possible byntryselectonly command, the preferred method is a selection filter and theelectRows() function. To do this, write a simple Python function that is calledtry in the project. If your function returns True the entry is selected, if it returns

entry is not selected. Your function should accept two parameters: the CT corre-the current entry and a Python dictionary with an entry for each property in the

le. Note that its also possible to use project.selectRows() with a list of rowbe selected. The following example demonstrates both these approaches:

. selring.pyle selects entries that contain rings of a specified size:

ng.py


_ring( ring_size ):


Schrdinge36

pt = maestro.project_table_get() matches = []

# Loop over all the entries in the projectfor row in xrange(1,len(pt)+1):

rifo

# Repl # than pt.sel

# The folldef select

pt = m pt.sel

def myfunc

"""

Exampl Return Return """

ring_s rings

for riif

return

If you call t

pythonrun

only those e

Example 4This exampand propertare interester Suite 2009

ngs = structureutil.find_rings(pt[row].structure)r ring in rings:

if( len(ring) == ring_size ): matches.append(row)

acing them all through one call is quicker calling this method over and overectRows(project.REPLACE, rows=matches)

owing two functions show how to select using a callback function_ring2( ring_size ):

aestro.project_table_get()ectRows(project.REPLACE, ring_size, function=myfunc)

(project, ct, property_dict, *args):

e callback function to select based on a property True if it should be selected False if it should be deselected

ize = args[0]= structureutil.find_rings(ct)ng in rings:( len(ring) == ring_size ):return True

False

his function from Maestro as:

select_ring.select_ring 4

ntries in the project with four-membered rings are selected.

. selprop.pyle selects entries from the project based on a combination of the entry's structureies:. In this case we use the property dictionary to find the value of the property wed in.


#selprop.py

from schrodinger.maestro import maestrofrom schrodinger import structureutilfrom schrodinger import project

def select

pt = m matche

# Loopfor ro

nu

stif

# Repl # than # we b pt.sel

6.3 WAs shown asequentiallythis is not realternative i

Example 5Here is an eenergy

Note: BecPro

#color_by_


def color_

"""Scripting with Python 37

_proerty( ring_size ):

aestro.project_table_get()s = []

over all the entries in the projectw in xrange(1,len(pt)+1):m_atoms = pt[row].structure.atom_totalars = pt[row]['#stars']( num_atoms < 40 and stars != None and stars > 4 ): matches.append(row)

acing them all through one call is quicker calling this method over and over. So pass in the listuilt.ectRows(project.REPLACE, rows=matches)

orking on All Entries in the Project Tablebove, looping over the entries can be used to bring each entry into the Workspaceand operate on it there. While this is a useful technique, there may be times whenquired, or where it would be inefficient to bring all entries into the Workspace. Ans to loop over all entries in the project table and operate on their structures directly.

. color_by_energy_gradient.pyxample that sets the color of each entry, based on the relative molecular mechanics

ause we return True from the function, the entry structure will be updated in theject Tableenergy_gradient.py


relative():


Schrdinge38

Use the property Relative_Potential_Energy-OPLS-2005 to color all entries in the project by the property. Leaves entries without this property alone. """

pt = m

for ro

# # re

if

el

6.4 AThe previomodify thesimply add

Example 6The followiin the proje#count_ch.

from schrofrom schror Suite 2009

aestro.project_table_get()

w in xrange(1, len(pt)+1):

Check to see we actually have the property for thisentry - if not, go to the next one.l_energy = pt[row]['r_mmod_Relative_Potential_Energy-OPLS-2005'] rel_energy == None:print "Skipping entry %s since it has no value" % \

pt[row]['s_m_entry_name']continue

se: # Color values are defined in $SCHRODINGER/mmshare-vXX/data/colors.res col = 16 # red

if rel_energy < 4.0: col = 4 # blue

elif rel_energy < 8.0: col = 10 # green

elif rel_energy < 12.0: col = 14 # orange

num_atoms = pt[row].structure.atom_total ct = pt[row].structure

for i in range(1, num_atoms+1): ct.atom[i].color = col

dding New Columns to the Project Tableus example showed how you can loop over each entry in the project table andstructure. It is also possible to add new properties to the Project Table. To do this,a new value to the property dictionary and make sure your function returns True.

. count_ch.pyng example adds properties for the number of hydrogens and carbons to every entryct.py

dinger.maestro import maestrodinger import project


def count_ch( ):

pt = maestro.project_table_get() matches = []

for ro

ct

nu

nu

fo

# # # # # pt pt

pt

Example 7This is anotperformed o

#supersel.from schrofrom schrofrom schro

def superi

pt = m matche

# Ensuif pt.

re

count for se

ifScripting with Python 39

w in xrange(1, len(pt)+1):

= pt[row].structure

m_h_atoms = 0m_c_atoms = 0r a in ct.atom:

if a.atomic_number == 1: num_h_atoms += 1

elif a.atomic_number == 6: num_c_atoms += 1

Add or overwrite if already presentFormat for name is: __type can be i (integer), r (real), b (boolean), s (string)author is "m" for maestro, "user" for user, etc.property_name is any text. Underscores are allowed.[row]['i_user_Num_Carbons'] = num_c_atoms[row]['i_user_Num_Hydrogens'] = num_h_atoms

.refreshTable()

. supersel.pyher example of looping over all entries. In this case an operation (superposition) isn the entries and the RMS deviation is added as a property in the Project Table.pydinger.maestro import maestrodinger import structureutildinger import project

mpose_select():

aestro.project_table_get()s = []

re superposition can be donegetSelectedRowTotal() < 2:turn

= 1l_entry in pt: count == 1:


Schrdinge40

# First selected entry is the reference ref_entry = pt[sel_entry].structure num_atoms_ref = ref_entry.atom_total pt[sel_entry]['r_user_MyRMS'] = 0.0

else:

co

# Upda # upda pt.refr Suite 2009

# For all others - superimpose non-hydrogen atoms ct = pt[sel_entry].structure num_atoms = pt[sel_entry].structure.atom_total

if not num_atoms == num_atoms_ref :raise Exception, \

"There must be the same number of atoms in each structure" super_list = structureutil.evaluate_asl( ct, "not atom.ele H" ) rms = structureutil.superimpose( ref_entry, super_list, ct, super_list ) pt[sel_entry]['r_user_MyRMS'] = rms

unt = count + 1

te the project table so users can see the added orted property columnreshTable()

Chapter 7


Chapter 7: Running Jobs from Scripts

7.1 RWe have yeeasy, eitherappropriate

7.2 ThOne limitacommands)This is easiexample usHowever, itscript redra

Example 1# allfilesfrom schrofrom schroimport comimport gloimport os

# This is # glob.glodef mini_a

# firs comman

direct path = fileli

for af mi

# The funcdef mini_

import#ConveScripting with Python 41unning Jobs From Within Maestrot to provide an example of running a job from a Python script. It is in fact quiteinside or outside Maestro. From inside maestro, the script needs to simply issue the Maestro commands coupled with the maestro.job_wait function.

e maestro.job_wait Functiontion of Maestro command scripts (which are essentially just lists of Maestrois that it is not possible to write a script that runs a job and waits for it to finish.

ly overcome with a Python script and the maestro.job_wait() function. Thises the glob module to process all PDB files in the current working directory.could have just as easily processed all the entries in a project as we saw earlier. The

ws the Workspace from time to time to display the current state of the process.

. allfiles.py.pydinger.maestro import maestrodinger import structureutilmandsb

the one that should be executed from Maestro. It uses theb subroutine to apply the action to all PDB files:ll_pdb() :t clean up by removing any existing files:ds.getoutput( "rm *-min.pdb" )ory=os.getcwd() os.path.join(directory,"*.pdb")st = glob.glob( path )ile in filelist:ni_pdb( afile )

tion called for every PDB file:pdb(file) : os

rt the filename into a PDB code:


Schrdinge42

( path, fname ) = os.path.split( file ) ( pdb_code, suffix ) = os.path.splitext( fname ) #Import the PDB file: maestro.command("entryimport format=pdb %s" % file ) # Delete all molecules < 100 atoms and add hydrogens: maestr delete hydrog """ )

# Set # and maestr potent potent constr energy minien jobset """ %

maestr# Run

maestr maestr

maestr

maestr #The j out_fi maestr

# Dele maestr

7.3 CWhen a jobresults intotask that wamany cases

If you havestandard jotion.r Suite 2009

o.command(""" atom mol.atom < 100enapply all

up the MacroModel job, in vacuo, OPLSA2001, constrained CAs,100 iterations of LBFGSo.command( """ial field=oplsaaial cutoff=normalainedset atom.ptype " CA "task miniergy method=lbfgs maxiter=100tings mmod incorporate=replaceentries jobname=%spdb_code )

o.redraw()and wait for the job:o.command("energystart")o.job_wait(True)

o.command( "jobcleanup files=jobandmonitor %s "% pdb_code )

o.redraw()ob is now finished - export the structure to a new PDB filele = pdb_code + "-min.pdb"o.command("entryexport format=pdb source=selected %s" % out_file )

te the entry from the projecto.command("entrydelete")

ustomizing Job Incorporationfinishes and has output that is incorporatable, Maestro attempts to incorporate theits project. Exactly what Maestro does when incorporating depends on the specifics run. For each task Maestro has a specific rule it follows when incorporating. In

it just applies its standard rule to the generated data.a task or workflow that you have written and you do not want Maestro to apply its

b incorporation rules, you can register your own job incorporation callback func-


7.3.1 Specifying a Special Job DispositionTo enable your specialized job incorporation callback function to recognize your specializedjob, you may specify a job disposition that is not used by Schrdinger software (or any otherapplication)values are:

appen appen addto repla

These valucustomizedthat starts wmation to ahow Maestrjobs with suyour customand the othe

The Pythonvalue. Heregiven typeAny value cin the specipart of the jtask.

7.3.2 IF

The functiosingle argumporated. Th(a string). Tincorporatethis secondtion.

The callbacfore checkspecial dispScripting with Python 43

. You specify this value when launching the job. Common Schrdinger disposition

ddungroupedentry_ce

es should be avoided if you want your job to receive special handling by yourjob incorporation function. The addtoentry_ disposition is a prefix. Any valueith this string should be avoided. This disposition value tells Maestro to add infor-

n entry and typically has an entry ID appended to the addtoentry_ value. That iso knows into which entry the data should be placed. You can, of course, launchch a disposition and let Maestro handle the incorporation, but if you plan on havingized job incorporation function handle incorporation, then you should avoid thisr values listed above.

script needs to specify the disposition by launching its job with -DISP special-special-value is the unique value mentioned above, like MyProcedure1. For a

of task that you perform you should use the same special-value for all instances.an be used (apart from those listed). You can even include additional informational-value string to help you process the job results. You may find it useful to baseobs disposition value on the name of your company, group, Python panel, script or

ncorporating Results Using Your Specialized Incorporationunction

n maestro.job_incorporation_function_add(callback-function) takes aent, the function to be called by Maestro whenever a job is available to be incor-

e callback function should expect to receive two parameters. The first is the job IDhe second is a Boolean that indicates if we are just testing whether the job can be

d by the script or whether we really expect the script to try and do incorporation. Ifparameter is False, then its OK for the script to actually attempt the incorpora-

k is called by Maestro for every job that is incorporatable. The callback must there-to see if it should handle each job that is ready for incorporation. This is why aosition value helps the callback determine whether to handle the job results or not.


Schrdinge44

You can get the job disposition in the callback by creating a jobcontrol.Job instance basedon the job ID that is passed into the callback. Suppose we call our jobcontrol.Job instancemyjob, then to get the job disposition we use myjob. Disposition, and check to see if thisvalue matches the special-value job disposition that was used to launch your specialized job.For exampl

from schrodef my_job myjob dispos split_

print if spl

pr #

If the callbaso, but the sthe callbacmaestro.Nreturn maes

Returning mporated and

7.3.3 R

You can rem

maestro.j

7.4 RThe PythonMaestro. TSchrdingehost list, an

7.4.1 A

Read-onlyclass. A Jo434ac660 r Suite 2009

e:

dinger.job import jobcontrol_incorporation_callback(jobid, testing):= jobcontrol.Job(jobid)ition = myjob.Dispositiondisposition = disposition.split(':')split_disposition[0]it_disposition[0] == 'My disposition value':int "This is my job and I will handle it."Add your code including returning the appropriate return value

ck function incorporates the job (processes the job results) or it is prepared to doecond parameter was True, then it should return maestro.WILL_HANDLE_JOB. Ifk function is not able to handle the job at this time then it should returnOT_INCORPORATABLE. If it is not going to handle the incorporation at all it shouldtro.NOT_MY_JOB.

aestro.WILL_HANDLE_JOB causes Maestro to treat the job as having been incor- so it will not itself try to incorporate the results.

emoving Your Job Incorporation Callbackove a job incorporation callback by using the following function:ob_incorporation_function_remove(callback-function).

unning and Managing Jobs Outside Maestromodules include some powerful tools for running and managing jobs outside

he schrodinger.job.jobcontrol module provides access to some ofrs job control functionality. It allows read access to the job database and the jobd can help with launching subjobs.

ccess to the Job Databaseaccess to the job database is provided by the schrodinger.job.jobcontrolb object can be created with a job ID string. These strings look like isabel-0-and are printed to the output of all Schrdinger jobs.


Once a Job object is created, the available keys can be listed with the keys() method andtheir values can be obtained as attributes of the object. The database values retrieved at creationtime will never be updated automatically. They must be explicitly updated with thereadAgain method.

This exampattrib

Suite09 Python Scripting

Documents

Transcript of Suite09 Python Scripting