.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Tutorial 3"
.TH Tutorial 3 "2005-10-26" "perl v5.22.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Chemistry::Tutorial \- PerlMol Quick Tutorial
.SH "Introduction"
.IX Header "Introduction"
The modules in the PerlMol toolkit are designed to simplify the handling of 
molecules from Perl programs in a general and extensible way. 
These modules are object-oriented; however, this tries to assume little or no
knowledge of object-oriented programming in Perl. For a general introduction
about how to use object-oriented modules, see HTML::Tree::AboutObjects.
.PP
This document shows some of the more common methods included in the PerlMol
toolkit, in a reasonable order for a quick introduction. For more details see
the perldoc pages for each module.
.SH "How to read a molecule from a file"
.IX Header "How to read a molecule from a file"
The following code will read a \s-1PDB\s0 file:
.PP
.Vb 3
\&    use Chemistry::Mol;
\&    use Chemistry::File::PDB;
\&    my $mol = Chemistry::Mol\->read("test.pdb");
.Ve
.PP
The first two lines (which only need to be used once in a given program) tell
Perl that you want to \f(CW\*(C`use\*(C'\fR the specified modules The third line reads the
file and returns a molecule object.
.PP
To read other formats such as \s-1MDL\s0 molfiles,  you need to \f(CW\*(C`use\*(C'\fR the
corresponding module, such as Chemistry::File::MDLMol. Readers for several
formats are under development.
.SH "The molecule object"
.IX Header "The molecule object"
\&\f(CW\*(C`Chemistry::Mol\->read\*(C'\fR returns a Chemistry::Mol object. An \fIobject\fR is
a data structure of a given \fIclass\fR that has \fImethods\fR (i.e. subroutines)
associated with it. To access or modify an object's properties, you call the
methods on the object through \*(L"arrow syntax\*(R":
.PP
.Vb 2
\&    my $name = $mol\->name; # return the name of the molecule
\&    $mol\->name("water");   # set the name of the molecule to "water"
.Ve
.PP
Note that these so-called accessor methods return the molecule object when they
are used to set a property. A consequence of that if you want, you can \*(L"chain\*(R" 
several methods to set several options in one line:
.PP
.Vb 1
\&    $mol\->name("water")\->type("wet");
.Ve
.PP
A Chemistry::Mol object contains essentially a list of atoms, a list of
bonds, and a few generic properties such as name, type, and id. The atoms and
bonds themselves are also objects.
.SH "Writing a molecule file"
.IX Header "Writing a molecule file"
To write a molecule to a file, just use the \f(CW\*(C`write\*(C'\fR method:
.PP
.Vb 1
\&    $mol\->write("test.pdb");
.Ve
.PP
Make sure you \f(CW\*(C`use\*(C'\fRd the right file I/O module. If you want to load all the
available file I/O modules, you can do it with
.PP
.Vb 1
\&    use Chemistry::File \*(Aq:auto\*(Aq;
.Ve
.SH "Selecting atoms in a molecule"
.IX Header "Selecting atoms in a molecule"
You can get an array of all the atoms by calling the atoms method without
parameters, or a specific atom by giving its index:
.PP
.Vb 2
\&    @all_atoms = $mol\->atoms;
\&    $atom3 = $mol\->atoms(3);
.Ve
.PP
\&\fBNote\fR: Atom and bond indices are counted from 1, not from 0. This deviation
from common Perl usage was made to be consistent with the way atoms are
numbered in most common file formats.
.PP
You can select atoms that match an arbitrary expression by using Perl's
built-in \f(CW\*(C`grep\*(C'\fR function:
.PP
.Vb 5
\&    # get all oxygen atoms within 3.0 Angstroms of atom 37
\&    @close_oxygens = grep {
\&        $_\->symbol eq \*(AqO\*(Aq 
\&        and $_\->distance($mol\->atoms(37)) < 3.0 
\&    } $mol\->atoms;
.Ve
.PP
The \f(CW\*(C`grep\*(C'\fR function loops through all the atoms returned by \f(CW\*(C`$mol\->atoms\*(C'\fR,
aliasing each to \f(CW$_\fR at each iteration, and returns only those for which
the expression in braces is true.
.PP
Using \f(CW\*(C`grep\*(C'\fR is a general way of finding atoms; however, since finding atoms
by name is common, a convenience method is available for that purpose.
.PP
.Vb 2
\&    $HB1     = $mol\->atoms_by_name(\*(AqHB1\*(Aq);
\&    @H_atoms = $mol\->atoms_by_name(\*(AqH.*\*(Aq); # name treated as a regex
.Ve
.PP
Since the atom name is not generally unique, even the first example above 
might match more than one atom. In that case, only the first one found is
returned. In the second case, since you are assigning to an array, all matching
atoms are returned.
.SH "The atom object"
.IX Header "The atom object"
Atoms are usually the most interesting objects in a molecule. Some of their
main properties are Z, symbol, and coords.
.PP
.Vb 3
\&    $atom\->Z(8); # set atomic number to 8
\&    $symbol = $atom\->symbol;
\&    $coords = $atom\->coords;
.Ve
.SS "Atom coordinates"
.IX Subsection "Atom coordinates"
The coordinates returned by \f(CW\*(C`$atom\->coords\*(C'\fR are a Math::VectorReal
object. You can print these objects and use them to do vector algebra:
.PP
.Vb 8
\&    $c1            = $atom1\->coords;
\&    $c2            = $atom2\->coords;
\&    $dot_product   = $c1 . $c2;       # returns a scalar
\&    $cross_product = $c1 x $c2;       # returns a vector
\&    $delta         = $c2 \- $c1;       # returns a vector
\&    $distance      = $delta\->length;  # returns a scalar
\&    ($x, $y, $z)   = $c1\->array;      # get the components of $c1
\&    print $c1;     # prints something like "[ 1.0E0  2.0E0  3.0E0 ]"
.Ve
.PP
Since one is very often interested in calculating the distance between atoms,
Atom objects provide a \f(CW\*(C`distance\*(C'\fR method to save some typing:
.PP
.Vb 2
\&    $d  = $atom1\->distance($atom2);
\&    $d2 = $atom1\->distance($molecule2);
.Ve
.PP
In the second case, the value obtained is the minimum distance between the atom
and the molecule. This can be useful for things such as finding the water
molecules closest to a given atom.
.PP
Atoms may also have internal coordinates, which define the position of an atom
relative to the positions of other atoms by means of a distance, an angle,
and a dihedral angle. Those coordinates can be accessed through the
\&\f(CW$atom\fR\->internal_coords method, which uses Chemistry::InternalCoords objects.
.SH "The Bond object"
.IX Header "The Bond object"
A Chemistry::Bond object is a list of atoms with an associated bond order.
In most cases, a bond has exactly two atoms, but we don't want to exclude
possibilities such as three-center bonds. You can get the list of atoms in a
bond by using the \f(CW\*(C`atoms\*(C'\fR method; the bond order is accessed trough the
\&\f(CW\*(C`order\*(C'\fR method;
.PP
.Vb 2
\&    @atoms_in_bond = $bond\->atoms;
\&    $bond_order    = $bond\->order;
.Ve
.PP
The other interesting method for Bond objects is \f(CW\*(C`length\*(C'\fR, which returns
the distance between the two atoms in a bond (this method requires that the 
bond have two atoms).
.PP
.Vb 1
\&    my $bondlength = $bond\->length;
.Ve
.PP
In addition to these properties, Bond objects have the generic properties
described below. The most important of these, as far as bonds are concerned,
is \f(CW\*(C`type\*(C'\fR.
.SH "Generic properties"
.IX Header "Generic properties"
There are three generic properties that all PerlMol objects have:
.IP "id" 4
.IX Item "id"
Each object must have a unique \s-1ID.\s0 In most cases you don't have to worry about
it, because it is assigned automatically unless you specify it. You can use
the \f(CW\*(C`by_id\*(C'\fR method to select an object contained in a molecule:
.Sp
.Vb 1
\&    $atom = $mol\->by_id("a42");
.Ve
.Sp
In general, ids are preferable to indices because they don't change if you 
delete or move atoms or other objects.
.IP "name" 4
.IX Item "name"
The name of the object does not have any meaning from the point of view of the
core modules, but most file types have the concept of molecule name, and some
(such as \s-1PDB\s0) have the concept of atom names.
.IP "type" 4
.IX Item "type"
Again, the meaning of type is not universally defined, but it would likely be 
used to specify atom types and bond orders.
.PP
Besides these, the user can specify arbitrary attributes, as discussed in the
next section.
.SH "User-specified attributes"
.IX Header "User-specified attributes"
The core PerlMol classes define very few, very generic properties for atoms and
molecules. This was chosen as a \*(L"minimum common denominator\*(R" because every file
format and program has different ideas about the names, values and meaning of
these properties. For example, some programs only allow bond orders of 1, 2,
and 3; some also have \*(L"aromatic\*(R" bonds; some use calculated non-integer bond
orders. PerlMol tries not to commit to any particular convention, but it 
allows you to specify whatever attributes you want for any object (be it 
a molecule, an atom, or a bond). This is done through the \f(CW\*(C`attr\*(C'\fR method.
.PP
.Vb 2
\&    $mol\->attr("melting point", "273.15"); # set m.p.
\&    $color = $atom\->attr("color"); # get atom color
.Ve
.PP
The core modules store these values but they don't know what they mean and they
don't care about them. Attributes can have whatever name you want, and they can
be of any type. However, by convention, non-core modules that need additional
attributes should prefix their name with a \fInamespace\fR, followed by a slash.
(This is done to avoid modules fighting over the same attribute name.)
For example, atoms created by the \s-1PDB\s0 reader module (Chemistry::File::PDB)
have the \*(L"pdb/residue\*(R" attribute.
.PP
.Vb 3
\&    $mol  = Chemistry::Mol\->read("test.pdb");
\&    $atom = $mol\->atoms(1234);
\&    print $atom\->attr("pdb/residue_name"); # prints "ALA123"
.Ve
.SH "Molecule subclasses"
.IX Header "Molecule subclasses"
You can do lots of interesting thing with plain molecules. However, for some
applications you may want to extend the features of the main Chemistry::Mol
class. There are several subclasses of Chemistry::Mol available already:
.IP "Chemistry::MacroMol" 4
.IX Item "Chemistry::MacroMol"
Used for macromolecules.
.IP "Chemistry::Pattern" 4
.IX Item "Chemistry::Pattern"
Used for substructure matching.
.IP "Chemistry::Ring" 4
.IX Item "Chemistry::Ring"
Used for representing rings (cycles) in molecules.
.IP "Chemistry::Reaction" 4
.IX Item "Chemistry::Reaction"
Used for representing and applying chemical transformations.
.PP
As an example we'll discuss macromolecules. Future versions of this tutorial
may also include a discussion about patterns and rings.
.SH "Macromolecules"
.IX Header "Macromolecules"
So far we have assumed that we are dealing with molecules of the
Chemistry::Mol class.  However, one of the interesting things about
object-oriented programming is that classes can be extended. For dealing with
macromolecules, we have the MacroMol class, which extends the Chemistry::Mol
class. This means that in practice you can use a Chemistry::MacroMol object
exactly as you would use a Chemistry::Mol object, but with some added
functionality. In fact, the \s-1PDB\s0 reader can return Chemistry::MacroMol
instead of Chemistry::Mol objects just by changing the first example like
this:
.PP
.Vb 3
\&    use Chemistry::MacroMol;
\&    use Chemistry::File::PDB;
\&    my $macromol = Chemistry::MacroMol\->read("test.pdb");
.Ve
.PP
Now the question is, what is the \*(L"added functionality\*(R" that MacroMol objects
have on top of the original Chemistry::Mol object?
.SS "The MacroMol object"
.IX Subsection "The MacroMol object"
For the purposes of this module, a macromolecule is considered to be a big
molecule where atoms are divided in \fIDomains\fR. A domain is just a subset of
the atoms in the molecule; in a protein, a domain would be just a residue.
.PP
You can select domains in a molecule in a way similar to that used for atoms
and bonds, in this case through the \f(CW\*(C`domains\*(C'\fR method:
.PP
.Vb 2
\&    my @all_domains = $macromol\->domains;
\&    my $domain      = $macromol\->domains(57);
.Ve
.SS "The Domain object"
.IX Subsection "The Domain object"
A domain is a substructure of a larger molecule. Other than having a \fIparent\fR
molecule, a domain is just like a molecule. In other words, the Domain class
extends the Chemistry::Mol class; it is basically a collection of atoms and
bonds.
.PP
.Vb 2
\&    my @atoms_in_domain = $domain\->atoms;
\&    my $atom5_in_domain = $domain\->atoms(5);
.Ve
.PP
If you want to get at a given atom in a given domain in a macromolecule, you
can \*(L"chain\*(R" the method calls without having to save the Domain object in a
temporary variable:
.PP
.Vb 2
\&    my $domain57_atom5 = $macromol\->domains(57)\->atoms(5);
\&    my $res233_HA = $macromol\->domains(233)\->atoms_by_name(\*(AqHA\*(Aq);
.Ve
.PP
The second example is a good way of selecting an atom from a \s-1PDB\s0 file when you
know the residue number and atom name.
.SH "VERSION"
.IX Header "VERSION"
0.36
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Chemistry::Mol, Chemistry::Atom, Chemistry::Bond, Chemistry::File,
Chemistry::MacroMol, Chemistry::Domain.
.PP
The PerlMol website <http://www.perlmol.org/>
.SH "AUTHOR"
.IX Header "AUTHOR"
Ivan Tubert-Brohman <itub@cpan.org>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2005 Ivan Tubert-Brohman. All rights reserved. This program is
free software; you can redistribute it and/or modify it under the same terms as
Perl itself.