Surface

2010-06-10T12:18:24Z

Folf: /* Representation-independent Color Control */

Surface

2010-06-10T12:17:41Z

Folf: /* Representation-independent Color Control */

The surface representation of a protein, in PyMol, shows the [http://en.wikipedia.org/wiki/Connolly_surface "Connolly" surface] or the surface that would be traced out by the '''surfaces''' of waters in contact with the protein at all possible positions. [[Image:Surface_ex.png|thumb|Surface Representation Example|right]]

==Enabling==
To enable the surface representation do
show surface, SEL
for any proper selection SEL.

==Settings==
*[[surface_best]]
*[[surface_negative_color]]
*[[surface_carve_cutoff]]
*[[surface_negative_visible]]
*[[surface_carve_normal_cutoff]]
*[[surface_normal]]
*[[surface_carve_selection]]
*[[surface_optimize_subsets]]
*[[surface_carve_state]]
*[[surface_poor]]
*[[surface_circumscribe]]
*[[surface_proximity]]
*[[surface_clear_cutoff]]
*[[surface_quality]]
*[[surface_clear_selection]]
*[[surface_ramp_above_mode]]
*[[surface_clear_state]]
*[[surface_solvent]]
*[[surface_color]]
*[[surface_trim_cutoff]]
*[[surface_debug]]
*[[surface_trim_factor]]
*[[surface_miserable]]
*[[surface_type]]
*[[surface_mode]]

===Examples===
====Transparency====
To adjust the transparency of surfaces try:
<source lang="python">
set transparency, 0.5
</source>
Where 1.0 will be an invisible and 0.0 a completely solid surface.

====Quality====
To smooth your surface representation try:
<source lang="python">
set surface_quality, 1
</source>
or higher if you wish, though it will take longer and might look odd.

====Probe Radius====
To change the probe radius other than default 1.4 Å, you need to change the solvent radius, say, 1.6 Å:
<source lang="python">
set solvent_radius, 1.6
</source>
If the surface does not change correspondingly, use:
<source lang="python">
rebuild
</source>

==Tips==

=== Exporting Surface/Mesh Coordinates to File===

PyMOL can export its coordinates as WRL wireframe model files for VRML input.

====Older PyMOL Versions====
<source lang="python">
# export the coordinates to povray
open("surface.inc","w").write(cmd.get_povray()[1])
</source>

====Newer PyMOL Versions====
<source lang="python">
# export the coordinates to .wrl file
save myscene.wrl
</source>
or
<source lang="python">
# export the coordinates to .obj file
save myscene.obj
</source>

===Representation-independent Color Control===
To color the surface representation a different color than the underlying cartoon or ligand representations, simply duplicate the object, show only the surface in the duplicate, and show only the cartoon and/or ligands in the original object.

Or use the *[[surface_color]] setting that is available.

[[Image:Representation independent color control.jpg|thumb|Representation-independent Color Control Example|left]]

===Displaying a protein as surface with a ligand as sticks===
An easy way to do this is to create separate objects for each type of display.

1 Load your protein

2 Select the ligand

3 Create a separate object for the ligand

4 Remove ligand atoms from the protein

5 Display both objects separately

Example:
<source lang="python">
load prot.ent,protein
select ligand,resn FAD
create lig_sticks,ligand
remove ligand
show sticks,lig_sticks
show surface,protein
</source>

Even easier is to:

1 Load the protein

2 S (Show) > organic > stick

3 S (Show) > surface

===Calculating a partial surface===
There is, until now, an undocumented way to calculate a surface for only a part of an object without creating a new one:
<source lang="python">
flag ignore, not A/49-63/, set
delete indicate
show surface
</source>
If the surface was already computed, then you'll also need to issue the command:
<source lang="python">
rebuild
</source>

See [[Get_Area]] for more information on surface area calculations.

===Displaying surface inside a molecule===
As far as I can tell, setting ambient to zero alone doesn't quite do the job, since some triangles still get lit by the light source. The best combination I can find is:
<source lang="python">
set ambient=0
set direct=0.7
set reflect=0.0
set backface_cull=0
</source>
Which gives no shadows and only a few artifacts.

As an alternative, you might just consider showing the inside of the surface directly...that will create less visual artifacts, and so long as ambient and direct are sufficiently low, it will look reasonable in "ray".
<source lang="python">
util.ray_shadows("heavy")
set two_sided_lighting=1
set backface_cull=0
</source>

===Creating a Closed Surface===
<gallery>
Image:Surface_open.png|Example OPEN Surface
Image:Surface_closed.png|Example CLOSED Surface
</gallery>

To create what I'll call a '''closed surface''' (see images), you need to first make your atom selections, then create a new object for that selection then show the surface for that object. Here's an example.
<source lang="python">
sel A, id 1-100
create B, A
show surface, B
</source>

=== Huge Surfaces ===
If your protein or complex is too large to render ([[ray]] runs out of RAM, for example) then check out the [[Huge_surfaces|tip for huge surfaces]].

== Performance ==
To optimize performance and responsiveness, PyMOL tends to defer compute-intensive tasks until their results are actually needed. Thus,
<source lang="python">
cmd.show("surface")
</source>
doesn't actually show a surface, it only sets the surface visibility flag on the atoms present (for future reference). An actual surface won't be computed until PyMOL is asked to refresh or render the display. When running a script, you can force an update by calling:
<source lang="python">
cmd.refresh()
</source>
after cmd.show.

[[Category:Representations|Surface]]
[[Category:VRML]]
[[Category:Surfaces]]
[[Category:Performance]]

User:Inchoate

2009-09-11T13:59:33Z

Folf:

My name is Jason Vertrees and I'm an independent consultant working with DeLano Scientific to promote PyMOL. My previous work was in theoretical biophysics and machine learning to predict properties of proteins.

Also, I am the owner of the PyMOLWiki website. I started it to help the PyMOL community store and organize information regarding PyMOL.

If you are interested in Biophysical, Structural or Compuational Biology, check out [http://www.bscb.utmb.edu/ BSCB@UTMB] -- my old school.

-- '''Jason Vertrees, PhD 
''Jason dot Vertrees (_at-) gmail dot com''

= My ~/.pymolrc =
<source lang="python">
run ~/playground/pymol_scripts/oload.py
run ~/playground/cealign/qkabsch.py
run ~/playground/cealign/cealign.py
run ~/playground/pymol_scripts/find_bind.py
run ~/playground/pymol_scripts/zero.py
run ~/playground/pymol_scripts/removeAlt.py
run ~/playground/pymol_scripts/toGroup.py

one_letter ={'VAL':'V', 'ILE':'I', 'LEU':'L', 'GLU':'E', 'GLN':'Q', \
'ASP':'D', 'ASN':'N', 'HIS':'H', 'TRP':'W', 'PHE':'F', 'TYR':'Y', \
'ARG':'R', 'LYS':'K', 'SER':'S', 'THR':'T', 'MET':'M', 'ALA':'A', \
'GLY':'G', 'PRO':'P', 'CYS':'C'}

set ribbon_width, 8
set antialias,2
set cartoon_fancy_helices,1
set ray_trace_mode,1
set depth_cue,0
set ray_trace_fog,0
set ray_opaque_background,0
set defer_builds_mode, 3
set async_builds, 1
</source>

== To Do ==
* Movie->UpdateMovie
* Scene->Optmize (before saving scenes; use before optimizing)
* Scene->Cache (cache's surface data)
* dot_solvent

=== Movie Notes ===
<source lang="python">
#
# Simple movie of independent motions
#

# This create an ala and a tyr. It moves the ala indepdendent
# of the tyr.
#
# Q: Why are the orientations off? What is the equivalent
# command to moving something with mouse_motions?

# reinit
reinitialize

set matrix_mode, 1
# turns on handy scene buttons
set scene_buttons, 1
# turns on the movie panel at the bottom of the sceen
set movie_panel, 1
# turns on a special mouse button panel
config_mouse three_button_motions

# start with an empty movie, scene 1 with 90 frames
mset 1 x90

# create an ala and tyr
frag ala
frag tyr
as spheres

# create our scene
translate [10, 0, 0], object=ala, camera=0
orient

# store the first frame
frame 1
mview store, object=ala

# goto the next frame
frame 45
translate [-20, 0, 0], object=ala, camera=0
orient

# store this frame
mview store, object=ala

#reinterpolate the scene
mview reinterpolate, object=ala
</source>

New motions
* Enter alone will store+reinterpolate
* Shift-Enter will just store & clears the reinterpolation
* CTRL-Enter will store but not reinterpolate

New Scenes
* setups the scenes first
* then just goto the frame you want and hit enter and the current will be stored with it
* or you can right-click on the movie_panel and store with scene

* purge kills the matrix info for the object

New movie stuff
* CTRL-LEFTCLK + DRAG RIGHT = add frame/states
* CTRL-LEFTCLK + DRAG LEFT = erase frame/states
* Rt clk on object
** Shift+Middle = drag
** shift+Left = rotate

= See Also =
[[oload]], [[Cealign]], [[find_bind]], [[zero]], [[removeAlt]], [[toGroup]], [[ribbon_width]], [[antialias]], [[cartoon_fancy_helices]], [[depth_cue]], [[ray_trace_fog]], [[ray_opaque_background]], [[defer_builds_mode]], [[ray_trace_mode]].

[[User:Inchoate|Tree]] 19:08, 26 May 2009 (UTC)

User:Folf

2009-09-11T13:57:40Z

Folf: Created page with ' == Description == I am a post-doc at the Danish Technical University doing crystallography and depending on PyMOL for generation of publication quality pictures as well as stru…'

== Description ==

I am a post-doc at the Danish Technical University doing crystallography and depending on PyMOL for generation of publication quality pictures as well as structure analysis.

Align

2009-09-11T13:27:12Z

Folf: /* Algorithm Details */

===DESCRIPTION===
'''align''' performs a sequence alignment followed by a structural alignment, and then carrys out zero or more cycles of refinement in order to reject structural outliers found during the fit. For comparing proteins with lower sequence identity, an alignment program like, [[Cealign]] might be a better choice.
<gallery>
Image:before_alignment.png|Two unaligned proteins
Image:after_alignment.png|Two proteins after structure alignment
</gallery>

==== Algorithm Details ====
'''align''' does a BLAST-like BLOSUM62-weighted dynamic programming sequence alignment followed by a series of refinement cycles intended to improve the fit by eliminating pairing with high relative variability (e.g. >2 standard deviations from the cycle's mean deviance).

Your can write the final alignment to a file see [[save]].

=== Super! ===
PyMOL now has another command -- '''[[super]]'''. Super allows for much more robust alignments. It's fast, and under testing, does MUCH better than the original '''align''' command.

===USAGE===
<source lang="python">
align (source), (target) [,cutoff [,cycles [,gap [,extend \
[,skip [,object [,matrix [, quiet ]]]]]]]]
</source>

===PYMOL API===
<source lang="python">
cmd.align( string source, string target, float cutoff=2.0,
int cycles=2, float gap=-10.0, float extend=-0.5,
int skip=0, string object=None, string matrix="BLOSUM62",
int quiet=1 )
</source>

===EXAMPLES===
<source lang="python">
align prot1////CA, prot2, object=alignment
</source>

===NOTE===
* If object is not None, then align will create an object which indicates which atoms were paired between the two structures

* Important note: the molecules you want to align need to be in two different objects. Else, PyMol will answer with a rather cryptic error:

<source lang="python">
ExecutiveAlign: invalid selections for alignment.
</source>
You can skirt this problem by making a temporary object and aligning your original to the copy.

* Sometimes Align may appear to give a mediocre fit. This is not due to any shortcoming of the algorithm or Pymol for that matter. This usually happens if one or more of the objects, that you are trying to align, have multiple states. For instance, certain PDB files may contain multiple structures/ensembles of the same protein. This is especially true for PDB files containing NMR structures. The workaround in such a situation is to use this workflow (provided by Warren - thanks!):
<source lang="python">
set all_states, on
intra_fit <your_structure_1>
intra_fit <your_structure_2>
align <your_structure_1>////CA, <your_structure_2>////CA
</source>

===SEE ALSO===
[[Cmd fit|fit]], [[Cmd rms|rms]], [[Cmd rms_cur|rms_cur]], [[Cmd intra_rms|intra_rms]], [[Cmd intra_rms_cur|intra_rms_cur]], [[Cmd pair_fit|pair_fit]], [[Cmd intra_fit|intra_fit]], [[Kabsch]], [[Cealign]].

[[Category:Commands|Align]]
[[Category:Structure_Alignment|Align]]

Align

2009-09-11T13:26:58Z

Folf: /* Algorithm Details */

===DESCRIPTION===
'''align''' performs a sequence alignment followed by a structural alignment, and then carrys out zero or more cycles of refinement in order to reject structural outliers found during the fit. For comparing proteins with lower sequence identity, an alignment program like, [[Cealign]] might be a better choice.
<gallery>
Image:before_alignment.png|Two unaligned proteins
Image:after_alignment.png|Two proteins after structure alignment
</gallery>

==== Algorithm Details ====
'''align''' does a BLAST-like BLOSUM62-weighted dynamic programming sequence alignment followed by a series of refinement cycles intended to improve the fit by eliminating pairing with high relative variability (e.g. >2 standard deviations from the cycle's mean deviance).

Your can write the final alignment to a file see [[save]]

=== Super! ===
PyMOL now has another command -- '''[[super]]'''. Super allows for much more robust alignments. It's fast, and under testing, does MUCH better than the original '''align''' command.

===USAGE===
<source lang="python">
align (source), (target) [,cutoff [,cycles [,gap [,extend \
[,skip [,object [,matrix [, quiet ]]]]]]]]
</source>

===PYMOL API===
<source lang="python">
cmd.align( string source, string target, float cutoff=2.0,
int cycles=2, float gap=-10.0, float extend=-0.5,
int skip=0, string object=None, string matrix="BLOSUM62",
int quiet=1 )
</source>

===EXAMPLES===
<source lang="python">
align prot1////CA, prot2, object=alignment
</source>

===NOTE===
* If object is not None, then align will create an object which indicates which atoms were paired between the two structures

* Important note: the molecules you want to align need to be in two different objects. Else, PyMol will answer with a rather cryptic error:

<source lang="python">
ExecutiveAlign: invalid selections for alignment.
</source>
You can skirt this problem by making a temporary object and aligning your original to the copy.

* Sometimes Align may appear to give a mediocre fit. This is not due to any shortcoming of the algorithm or Pymol for that matter. This usually happens if one or more of the objects, that you are trying to align, have multiple states. For instance, certain PDB files may contain multiple structures/ensembles of the same protein. This is especially true for PDB files containing NMR structures. The workaround in such a situation is to use this workflow (provided by Warren - thanks!):
<source lang="python">
set all_states, on
intra_fit <your_structure_1>
intra_fit <your_structure_2>
align <your_structure_1>////CA, <your_structure_2>////CA
</source>

===SEE ALSO===
[[Cmd fit|fit]], [[Cmd rms|rms]], [[Cmd rms_cur|rms_cur]], [[Cmd intra_rms|intra_rms]], [[Cmd intra_rms_cur|intra_rms_cur]], [[Cmd pair_fit|pair_fit]], [[Cmd intra_fit|intra_fit]], [[Kabsch]], [[Cealign]].

[[Category:Commands|Align]]
[[Category:Structure_Alignment|Align]]

Save

2009-09-11T13:25:57Z

Folf: /* DESCRIPTION */

===DESCRIPTION===
'''save''' writes selected atoms to a file. The file format is
autodetected if the extesion is ".pdb", ".pse", ".mol", ".mmod", or
".pkl"

Note that if the file extension ends in ".pse" (PyMOL Session), the
complete PyMOL state is always saved to the file (the selection and
state parameters are thus ignored).

If aligning two structures
<source lang="python">
align proteinA, proteinB, object=A_on_B
</source>
a clustal formatted alignment file can be written
<source lang="python">
save A_aligned_with_B.aln, A_on_B
</source>

===USAGE===
<source lang="python">
save file [,(selection) [,state [,format]] ]
</source>
===PYMOL API===
<source lang="python">
cmd.save(file, selection, state, format)
</source>

===NOTES===
* When saving a session file, then "state" has no effect.
* When state = 0 (default), only the current state is written.
* When state = -1, then a multi-state output file is written (PDB only).

* In versions 1.XX, a multi-state output file is written when state = 0 (which is not default)
===SEE ALSO===
[[Load]], [[Get Model]]

[[Category:Commands|Save]]
[[Category:States|Save]]
[[Category:Input Output Module|Save]]

Roving delay

2009-09-10T12:35:28Z

Folf:

== Description ==

'''roving_delay''' determines the time before updating the scene.

== Syntax ==
<source lang="python">
# change roving_delay
set roving_delay, number # number > 0
</source>

== Usage ==
If you are on a slow computer it might prove useful to set this value to e.g. 2 (seconds). This prevents the scene from getting updated before you reach your place of interest.

== Related settings ==
*[[roving_byres]]
*[[roving_cartoon]]
*[[roving_delay]]
*[[roving_detail]]
*[[roving_isomesh]]
*[[roving_isosurface]]
*[[roving_labels]]
*[[roving_lines]]
*[[roving_map1_level]]
*[[roving_map1_name]]
*[[roving_map2_level]]
*[[roving_map2_name]]
*[[roving_map3_level]]
*[[roving_map3_name]]
*[[roving_nb_spheres]]
*[[roving_nonbonded]]
*[[roving_origin]]
*[[roving_origin_z]]
*[[roving_origin_z_cushion]]
*[[roving_polar_contacts ]]
*[[roving_polar_cutoff]]
*[[roving_ribbon]]
*[[roving_selection]]
*[[roving_spheres]]
*[[roving_sticks]]

[[Category:Settings|Settings]]

Roving delay

2009-09-10T12:33:25Z

Folf: Created page with '== Description == '''roving_delay''' determines the time before updating the scene. == Syntax == <source lang="python"> # change roving_delay set roving_delay, number # number …'

== Description ==

'''roving_delay''' determines the time before updating the scene.

== Syntax ==
<source lang="python">
# change roving_delay
set roving_delay, number # number > 0
</source>

== Related settings ==
*[[roving_byres]]
*[[roving_cartoon]]
*[[roving_delay]]
*[[roving_detail]]
*[[roving_isomesh]]
*[[roving_isosurface]]
*[[roving_labels]]
*[[roving_lines]]
*[[roving_map1_level]]
*[[roving_map1_name]]
*[[roving_map2_level]]
*[[roving_map2_name]]
*[[roving_map3_level]]
*[[roving_map3_name]]
*[[roving_nb_spheres]]
*[[roving_nonbonded]]
*[[roving_origin]]
*[[roving_origin_z]]
*[[roving_origin_z_cushion]]
*[[roving_polar_contacts ]]
*[[roving_polar_cutoff]]
*[[roving_ribbon]]
*[[roving_selection]]
*[[roving_spheres]]
*[[roving_sticks]]

[[Category:Settings|Settings]]

Roving byres

2009-09-10T12:24:05Z

Folf: Created page with '== Description == '''roving_byres''' determines if roving_detail selection is by residue or not. == Syntax == <source lang="python"> # to turn on roving_detail byres set rov…'

== Description ==

'''roving_byres''' determines if [[roving_detail]] selection is by residue or not.
== Syntax ==
<source lang="python">
# to turn on roving_detail byres
set roving_byres, true

# to turn off roving_detail byres
set roving_byres, false
</source>

== Related settings ==
*[[roving_byres]]
*[[roving_cartoon]]
*[[roving_delay]]
*[[roving_detail]]
*[[roving_isomesh]]
*[[roving_isosurface]]
*[[roving_labels]]
*[[roving_lines]]
*[[roving_map1_level]]
*[[roving_map1_name]]
*[[roving_map2_level]]
*[[roving_map2_name]]
*[[roving_map3_level]]
*[[roving_map3_name]]
*[[roving_nb_spheres]]
*[[roving_nonbonded]]
*[[roving_origin]]
*[[roving_origin_z]]
*[[roving_origin_z_cushion]]
*[[roving_polar_contacts ]]
*[[roving_polar_cutoff]]
*[[roving_ribbon]]
*[[roving_selection]]
*[[roving_spheres]]
*[[roving_sticks]]

[[Category:Settings|Settings]]

Roving nb spheres

2009-09-10T12:19:06Z

Folf: /* Syntax */

== Description ==

'''roving_nb_spheres''' determines the radius within spheres are shown for non-bonded atoms (e.g. waters).

== Syntax ==
<source lang="python">
# set radius for non-bonded spheres while roving_detail is on
set roving_nb_spheres, typeNumber # typeNumber = [1...], 0 to disable
</source>

== Related settings ==
*[[roving_byres]]
*[[roving_cartoon]]
*[[roving_delay]]
*[[roving_detail]]
*[[roving_isomesh]]
*[[roving_isosurface]]
*[[roving_labels]]
*[[roving_lines]]
*[[roving_map1_level]]
*[[roving_map1_name]]
*[[roving_map2_level]]
*[[roving_map2_name]]
*[[roving_map3_level]]
*[[roving_map3_name]]
*[[roving_nb_spheres]]
*[[roving_nonbonded]]
*[[roving_origin]]
*[[roving_origin_z]]
*[[roving_origin_z_cushion]]
*[[roving_polar_contacts ]]
*[[roving_polar_cutoff]]
*[[roving_ribbon]]
*[[roving_selection]]
*[[roving_spheres]]
*[[roving_sticks]]

[[Category:Settings|Settings]]

Roving nb spheres

2009-09-10T12:17:34Z

Folf: Created page with '== Description == '''roving_nb_spheres''' determines the radius within spheres are shown for non-bonded atoms (e.g. waters). == Syntax == <source lang="python"> # set radius f…'

== Description ==

'''roving_nb_spheres''' determines the radius within spheres are shown for non-bonded atoms (e.g. waters).

== Syntax ==
<source lang="python">
# set radius for non-bonded spheres while roving_detail is on
set roving_nb_spheres, typeNumber # typeNumber = [1...]
</source>

== Related settings ==
*[[roving_byres]]
*[[roving_cartoon]]
*[[roving_delay]]
*[[roving_detail]]
*[[roving_isomesh]]
*[[roving_isosurface]]
*[[roving_labels]]
*[[roving_lines]]
*[[roving_map1_level]]
*[[roving_map1_name]]
*[[roving_map2_level]]
*[[roving_map2_name]]
*[[roving_map3_level]]
*[[roving_map3_name]]
*[[roving_nb_spheres]]
*[[roving_nonbonded]]
*[[roving_origin]]
*[[roving_origin_z]]
*[[roving_origin_z_cushion]]
*[[roving_polar_contacts ]]
*[[roving_polar_cutoff]]
*[[roving_ribbon]]
*[[roving_selection]]
*[[roving_spheres]]
*[[roving_sticks]]

[[Category:Settings|Settings]]

Roving detail

2009-09-10T12:05:22Z

Folf:

== Description ==

'''Roving_detail''' shows details of the environment centered on the screen.

== Syntax ==
<source lang="python">
# to turn on roving detail
set roving_detail, true

# to turn off roving detail
set roving_detail, false
</source>

== Disclaimer ==

When turning on roving_detail you immediately get the effect on your screen effectively changing all your representations.

== Related settings ==
*[[roving_byres]]
*[[roving_cartoon]]
*[[roving_delay]]
*[[roving_detail]]
*[[roving_isomesh]]
*[[roving_isosurface]]
*[[roving_labels]]
*[[roving_lines]]
*[[roving_map1_level]]
*[[roving_map1_name]]
*[[roving_map2_level]]
*[[roving_map2_name]]
*[[roving_map3_level]]
*[[roving_map3_name]]
*[[roving_nb_spheres]]
*[[roving_nonbonded]]
*[[roving_origin]]
*[[roving_origin_z]]
*[[roving_origin_z_cushion]]
*[[roving_polar_contacts ]]
*[[roving_polar_cutoff]]
*[[roving_ribbon]]
*[[roving_selection]]
*[[roving_spheres]]
*[[roving_sticks]]

[[Category:Settings|Settings]]

2009-07-10T09:44:42Z

Folf: /* Labels Using One Letter Abbreviations */

[[Image:Pl.png|right|500px]]

= Overview =
The [[Label]] command controls how PyMOL draws text labels for PyMOL objects. Labeling is important so there are many options for your fine tuning needs. You can change the [[Label_size|label size]], [[Label_color|label color]], positioning, [[Label_font_id|font]], the [[Label_outline_color|label outline color]] that masks the font and much, much more.

You can have PyMOL label atoms by properties or arbitrary strings as you want; you can even use Unicode fonts for special symbols like, <math>\alpha, \beta, \pm, \textrm{\AA}</math>, etc.

The following gallery shows some examples of how extensible the [[Label]] command is.
<gallery heights="180px" widths="200px" align="center" perrow="3">
Image:Label_pre.png|Simple label
Image:New_fonts.jpeg|Example showing usage of Unicode fonts for special characters
Image:Font_ex.png|Another example with Unicode fonts
Image:Label_ex.png|Example label
Image:Ls0.png|Label shadows turned off
Image:Ls2.png|Label shadows turned on
</gallery>

==Built-in Object Properties==
Aside from arbitrary string labels, like "This is the catalytic residue" for an atom/residue you can also use the following built-in molecular properties:
* '''name''', the atom name
* '''resn''', the residue name
*'''resi''', the residue number/identifier
*'''chain''', the chain name
*'''q''', charge
*'''b''', the occupancy/b-factor
*'''segi''', the segment identifier
*'''type''' ''(ATOM,HETATM)'', the type of atom
*'''formal_charge''', the formal charge
*'''partial_charge''', the partial charge
*'''numeric_type''', the numeric type
*'''text_type''', the text type

You can use one of these properties as:
<source lang="python">
# simple example: label residue 22's atoms with their names
label i. 22, name

# Label residue #44's alpha carbon with it's residue name, residue number and B-factor.
label n. CA and i. 44, "(%s, %s, %s") % (resn, resi, b)
</source>

See the syntax and examples below for more info.

=Syntax=
To use the label command follow this syntax:
<source lang="python">
# labeling syntax
label [ selection[, expression]]
</source>
where '''selection''' is some object/selection you want to label and '''expression''' is some string (or set of strings) which PyMOL is to use to label the given selection.

We have plenty of examples. See [[#Examples|the examples]] below.

=Settings=
Here are all the label settings and their general effect. For each label setting, see the respective web page for more details.

'''[[label_angle_digits]]'''
:: (no idea)
'''[[label_distance_digits]]'''
:: (no idea)
'''[[label_shadow_mode]]'''
:: sets whether or not PyMOL will ray trace shadows for your label text. Eg: <source lang="python">set label_shadow_mode, 2</source>
'''[[label_color]]'''
:: sets the color of the label text. Note that you can have labels of different colors for different objects or selections. Some examples:
<source lang="python">
# per-object:
set label-color, color-name, object-name #eg, set label-color, magenta, /protein

# per-atom:
set label-color, color-name, selection #eg, set label-color, marine, /protein/A/A/23/CA

# another example
fragment arg
label all, name
set label_color, yellow, arg
set label_color, red, elem c
</source>

'''[[label_font_id]]'''
:: sets the font to render your label. There are 12 different fonts from 5—16. Numbers 15 and 16 are special for unicode. Eg: <source lang="python">set label_font_id, 12</source>
'''[[label_size]]'''
:: sets the size of the text. You can use positive numbers 2, 3, 4, etc for point sizes, or negative sizes for Angstrom-based sizes: A 2Ang font woukld then be -2. Eg: <source lang="python">set label_size, -2</source>
'''[[label_digits]]'''
:: (no idea)
'''[[label_outline_color]]'''
:: each label is outlined (so you can do white-on-white labels, for example). This options sets the color of the label outline. Eg. <source lang="python">set label_outline_color, orange</source>
'''[[label_dihedral_digits]]'''
:: (no idea)
'''[[label_position]]'''
:: sets any offset from the original X,Y,Z coordinates for the label. If you like to use the mouse, you can enter [[edit_mode]] and '''ctrl-middle-click''' to drag labels around; '''ctrl-shift-left_click''' will let you move the labels in the z-direction. '''"Save labels"-workaround''' If you want to save the position of your labels, the best way might be to create a new object and move the atoms in this object. Since the labels are positioned from the atom positions this is an indirect way of moving the labels and beeing able to save them.

=Examples=
<source lang="python">
#1.
# make a very simple label on the 14th alpha carbon.
label n. CA and i. 14, "This is carbon 14."

#2.
# make a fake scene label; use this to label entire scenes, not just atoms/bonds.
pseudoatom foo
label foo, "Once upon a time..."

#3.
# make a huge label
set label_size, -5
pseudoatom foo
label foo, "This is large text"

#4. Partial Charge
label (chain A),chain
label (n;ca),"%s-%s" % (resn,resi)
label (resi 200),"%1.3f" % partial_charge

#5. The gallery image above Label_ex.png was created with this code
# and finally, some labels were moved around in '''edit_mode'''.
label (resi 200),"%1.3f" % b
set label_font_id, 10
set label_size, 10

#6. This example shows how to label a selection with the
# XYZ coordinates of the atoms
from pymol import stored
stored.pos = []
# select the carbon atoms in my hetero atoms to label
select nn, het and e. C
# get the XYZ coordinates and put htem into stored.pos
iterate_state 1, (nn), stored.pos.append((x,y,z))
# label all N atoms. You need the pop() function or else
# PyMOL will complain b/c you didn't provide enough coords.
label nn, ("%5.5s, %5.5s, %5.5s") % stored.pos.pop()
</source>

= User Comments =
==Labels Using ID Numbers==
The following commnent,
<source lang="python">
label SELECTION, " %s" % ID
</source>
labels the SELECTION with atom ID numbers.

You can make more complicated selections/lables such as
<source lang="python">
label SELECTION, " %s:%s %s" % (resi, resn, name)
</source>
which will give you something like "GLU:139 CG"

==Labels Using One Letter Abbreviations==
* First, Add this to your $HOME/.pymolrc file:
<source lang="python">
# start $HOME/.pymolrc modification
one_letter ={'VAL':'V', 'ILE':'I', 'LEU':'L', 'GLU':'E', 'GLN':'Q', \
'ASP':'D', 'ASN':'N', 'HIS':'H', 'TRP':'W', 'PHE':'F', 'TYR':'Y', \
'ARG':'R', 'LYS':'K', 'SER':'S', 'THR':'T', 'MET':'M', 'ALA':'A', \
'GLY':'G', 'PRO':'P', 'CYS':'C'}
# end modification
</source>

* Second, instead of:
<source lang="python">
label n. ca, resn
</source>
use:
<source lang="python">
label n. ca, one_letter[resn]
</source>
or: ( to get something like D85)
<source lang="python">
label n. ca, "%s%s" %(one_letter[resn],resi)
</source>

=See Also=
[[:Category:Labeling]]

All the settings posted above.

[[Category:Labeling|Label]]
[[Category:Commands|Label]]

Label

2009-07-10T09:42:35Z

Folf: /* Settings */

[[Image:Pl.png|right|500px]]

= Overview =
The [[Label]] command controls how PyMOL draws text labels for PyMOL objects. Labeling is important so there are many options for your fine tuning needs. You can change the [[Label_size|label size]], [[Label_color|label color]], positioning, [[Label_font_id|font]], the [[Label_outline_color|label outline color]] that masks the font and much, much more.

You can have PyMOL label atoms by properties or arbitrary strings as you want; you can even use Unicode fonts for special symbols like, <math>\alpha, \beta, \pm, \textrm{\AA}</math>, etc.

The following gallery shows some examples of how extensible the [[Label]] command is.
<gallery heights="180px" widths="200px" align="center" perrow="3">
Image:Label_pre.png|Simple label
Image:New_fonts.jpeg|Example showing usage of Unicode fonts for special characters
Image:Font_ex.png|Another example with Unicode fonts
Image:Label_ex.png|Example label
Image:Ls0.png|Label shadows turned off
Image:Ls2.png|Label shadows turned on
</gallery>

==Built-in Object Properties==
Aside from arbitrary string labels, like "This is the catalytic residue" for an atom/residue you can also use the following built-in molecular properties:
* '''name''', the atom name
* '''resn''', the residue name
*'''resi''', the residue number/identifier
*'''chain''', the chain name
*'''q''', charge
*'''b''', the occupancy/b-factor
*'''segi''', the segment identifier
*'''type''' ''(ATOM,HETATM)'', the type of atom
*'''formal_charge''', the formal charge
*'''partial_charge''', the partial charge
*'''numeric_type''', the numeric type
*'''text_type''', the text type

You can use one of these properties as:
<source lang="python">
# simple example: label residue 22's atoms with their names
label i. 22, name

# Label residue #44's alpha carbon with it's residue name, residue number and B-factor.
label n. CA and i. 44, "(%s, %s, %s") % (resn, resi, b)
</source>

See the syntax and examples below for more info.

=Syntax=
To use the label command follow this syntax:
<source lang="python">
# labeling syntax
label [ selection[, expression]]
</source>
where '''selection''' is some object/selection you want to label and '''expression''' is some string (or set of strings) which PyMOL is to use to label the given selection.

We have plenty of examples. See [[#Examples|the examples]] below.

=Settings=
Here are all the label settings and their general effect. For each label setting, see the respective web page for more details.

'''[[label_angle_digits]]'''
:: (no idea)
'''[[label_distance_digits]]'''
:: (no idea)
'''[[label_shadow_mode]]'''
:: sets whether or not PyMOL will ray trace shadows for your label text. Eg: <source lang="python">set label_shadow_mode, 2</source>
'''[[label_color]]'''
:: sets the color of the label text. Note that you can have labels of different colors for different objects or selections. Some examples:
<source lang="python">
# per-object:
set label-color, color-name, object-name #eg, set label-color, magenta, /protein

# per-atom:
set label-color, color-name, selection #eg, set label-color, marine, /protein/A/A/23/CA

# another example
fragment arg
label all, name
set label_color, yellow, arg
set label_color, red, elem c
</source>

'''[[label_font_id]]'''
:: sets the font to render your label. There are 12 different fonts from 5—16. Numbers 15 and 16 are special for unicode. Eg: <source lang="python">set label_font_id, 12</source>
'''[[label_size]]'''
:: sets the size of the text. You can use positive numbers 2, 3, 4, etc for point sizes, or negative sizes for Angstrom-based sizes: A 2Ang font woukld then be -2. Eg: <source lang="python">set label_size, -2</source>
'''[[label_digits]]'''
:: (no idea)
'''[[label_outline_color]]'''
:: each label is outlined (so you can do white-on-white labels, for example). This options sets the color of the label outline. Eg. <source lang="python">set label_outline_color, orange</source>
'''[[label_dihedral_digits]]'''
:: (no idea)
'''[[label_position]]'''
:: sets any offset from the original X,Y,Z coordinates for the label. If you like to use the mouse, you can enter [[edit_mode]] and '''ctrl-middle-click''' to drag labels around; '''ctrl-shift-left_click''' will let you move the labels in the z-direction. '''"Save labels"-workaround''' If you want to save the position of your labels, the best way might be to create a new object and move the atoms in this object. Since the labels are positioned from the atom positions this is an indirect way of moving the labels and beeing able to save them.

=Examples=
<source lang="python">
#1.
# make a very simple label on the 14th alpha carbon.
label n. CA and i. 14, "This is carbon 14."

#2.
# make a fake scene label; use this to label entire scenes, not just atoms/bonds.
pseudoatom foo
label foo, "Once upon a time..."

#3.
# make a huge label
set label_size, -5
pseudoatom foo
label foo, "This is large text"

#4. Partial Charge
label (chain A),chain
label (n;ca),"%s-%s" % (resn,resi)
label (resi 200),"%1.3f" % partial_charge

#5. The gallery image above Label_ex.png was created with this code
# and finally, some labels were moved around in '''edit_mode'''.
label (resi 200),"%1.3f" % b
set label_font_id, 10
set label_size, 10

#6. This example shows how to label a selection with the
# XYZ coordinates of the atoms
from pymol import stored
stored.pos = []
# select the carbon atoms in my hetero atoms to label
select nn, het and e. C
# get the XYZ coordinates and put htem into stored.pos
iterate_state 1, (nn), stored.pos.append((x,y,z))
# label all N atoms. You need the pop() function or else
# PyMOL will complain b/c you didn't provide enough coords.
label nn, ("%5.5s, %5.5s, %5.5s") % stored.pos.pop()
</source>

= User Comments =
==Labels Using ID Numbers==
The following commnent,
<source lang="python">
label SELECTION, " %s" % ID
</source>
labels the SELECTION with atom ID numbers.

You can make more complicated selections/lables such as
<source lang="python">
label SELECTION, " %s:%s %s" % (resi, resn, name)
</source>
which will give you something like "GLU:139 CG"

==Labels Using One Letter Abbreviations==
* First, Add this to your $HOME/.pymolrc file:
<source lang="python">
# start $HOME/.pymolrc modification
one_letter ={'VAL':'V', 'ILE':'I', 'LEU':'L', 'GLU':'E', 'GLN':'Q', \
'ASP':'D', 'ASN':'N', 'HIS':'H', 'TRP':'W', 'PHE':'F', 'TYR':'Y', \
'ARG':'R', 'LYS':'K', 'SER':'S', 'THR':'T', 'MET':'M', 'ALA':'A', \
'GLY':'G', 'PRO':'P', 'CYS':'C'}
# end modification
</source>

* Second, instead of:
<source lang="python">
label n. ca, resn
</source>
use:
<source lang="python">
label n. ca, one_letter[resn]
</source>

=See Also=
[[:Category:Labeling]]

All the settings posted above.

[[Category:Labeling|Label]]
[[Category:Commands|Label]]