view release on metacpan or  search on metacpan

Tutorial.pod  view on Meta::CPAN

Each object must have a unique ID. In most cases you don't have to worry about
it, because it is assigned automatically unless you specify it. You can use
the C<by_id> method to select an object contained in a molecule:

    $atom = $mol->by_id("a42");

In general, ids are preferable to indices because they don't change if you 
delete or move atoms or other objects.

=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 PDB) have the concept of atom names.

=item type

Again, the meaning of type is not universally defined, but it would likely be 
used to specify atom types and bond orders.

=back

Besides these, the user can specify arbitrary attributes, as discussed in the
next section.

=head1 User-specified attributes

The core PerlMol classes define very few, very generic properties for atoms and
molecules. This was chosen as a "minimum common denominator" 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 "aromatic" 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 C<attr> method.

    $mol->attr("melting point", "273.15"); # set m.p.
    $color = $atom->attr("color"); # get atom color

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 I<namespace>, followed by a slash.
(This is done to avoid modules fighting over the same attribute name.)
For example, atoms created by the PDB reader module (Chemistry::File::PDB)
have the "pdb/residue" attribute.

    $mol  = Chemistry::Mol->read("test.pdb");
    $atom = $mol->atoms(1234);
    print $atom->attr("pdb/residue_name"); # prints "ALA123"

=head1 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:

=over

=item L<Chemistry::MacroMol>

Used for macromolecules.

=item L<Chemistry::Pattern>

Used for substructure matching.

=item L<Chemistry::Ring>

Used for representing rings (cycles) in molecules.

=item L<Chemistry::Reaction>

Used for representing and applying chemical transformations.

=back

As an example we'll discuss macromolecules. Future versions of this tutorial
may also include a discussion about patterns and rings.

=head1 Macromolecules

So far we have assumed that we are dealing with molecules of the
L<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 L<Chemistry::Mol>
class. This means that in practice you can use a L<Chemistry::MacroMol> object
exactly as you would use a L<Chemistry::Mol> object, but with some added
functionality. In fact, the PDB reader can return L<Chemistry::MacroMol>
instead of L<Chemistry::Mol> objects just by changing the first example like
this:

    use Chemistry::MacroMol;
    use Chemistry::File::PDB;
    my $macromol = Chemistry::MacroMol->read("test.pdb");

Now the question is, what is the "added functionality" that MacroMol objects
have on top of the original Chemistry::Mol object?

=head2 The MacroMol object

For the purposes of this module, a macromolecule is considered to be a big
molecule where atoms are divided in I<Domains>. A domain is just a subset of
the atoms in the molecule; in a protein, a domain would be just a residue.

You can select domains in a molecule in a way similar to that used for atoms
and bonds, in this case through the C<domains> method:

    my @all_domains = $macromol->domains;
    my $domain      = $macromol->domains(57);

=head2 The Domain object

A domain is a substructure of a larger molecule. Other than having a I<parent>
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.

    my @atoms_in_domain = $domain->atoms;
    my $atom5_in_domain = $domain->atoms(5);

If you want to get at a given atom in a given domain in a macromolecule, you
can "chain" the method calls without having to save the Domain object in a
temporary variable:

    my $domain57_atom5 = $macromol->domains(57)->atoms(5);
    my $res233_HA = $macromol->domains(233)->atoms_by_name('HA');

The second example is a good way of selecting an atom from a PDB file when you
know the residue number and atom name.

=head1 VERSION

0.38

=head1 SOURCE CODE REPOSITORY

L<https://github.com/perlmol/Chemistry-Mol>

=head1 SEE ALSO

L<Chemistry::Mol>, L<Chemistry::Atom>, L<Chemistry::Bond>, L<Chemistry::File>,
L<Chemistry::MacroMol>, L<Chemistry::Domain>.

=head1 AUTHOR

Ivan Tubert-Brohman E<lt>itub@cpan.orgE<gt>

=head1 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.

=cut