NAME

       Bio::Structure::Entry - Bioperl structure Object, describes the whole entry

SYNOPSIS

         #add synopsis here

DESCRIPTION

       This object stores a whole Bio::Structure entry. It can consist of one or more models
       (Bio::Structure::Model), which in turn consist of one or more chains
       (Bio::Structure::Chain). A chain is composed of residues (Bio::Structure::Residue) and a
       residue consists of atoms (Bio::Structure::Atom). If no specific model or chain is chosen,
       the first one is chosen.

FEEDBACK

   Mailing Lists
       User feedback is an integral part of the evolution of this and other Bioperl modules. Send
       your comments and suggestions preferably to one of the Bioperl mailing lists.  Your
       participation is much appreciated.

         bioperl-l@bioperl.org                  - General discussion
         http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

   Support
       Please direct usage questions or support issues to the mailing list:

       bioperl-l@bioperl.org

       rather than to the module maintainer directly. Many experienced and reponsive experts will
       be able look at the problem and quickly address it. Please include a thorough description
       of the problem with code and data examples if at all possible.

   Reporting Bugs
       Report bugs to the Bioperl bug tracking system to help us keep track the bugs and their
       resolution.  Bug reports can be submitted via the web:

         https://github.com/bioperl/bioperl-live/issues

AUTHOR - Kris Boulez

       Email kris.boulez@algonomics.com

APPENDIX

       The rest of the documentation details each of the object methods. Internal methods are
       usually preceded with a _

   new()
        Title   : new()
        Usage   : $struc = Bio::Structure::Entry->new(
                                                  -id  => 'structure_id',
                                                  );

        Function: Returns a new Bio::Structure::Entry object from basic
                       constructors. Probably most called from Bio::Structure::IO.
        Returns : a new Bio::Structure::Model object

   model()
        Title   : model
        Function: Connects a (or a list of) Model objects to a Bio::Structure::Entry.
                       To add a Model (and keep the existing ones) use add_model()
                       It returns a list of Model objects.
        Returns : List of Bio::Structure::Model objects
        Args    : One Model or a reference to an array of Model objects

   add_model()
        Title   : add_model
        Usage   : $structure->add_model($model);
        Function: Adds a (or a list of) Model objects to a Bio::Structure::Entry.
        Returns :
        Args    : One Model or a reference to an array of Model objects

   get_models()
        Title   : get_models
        Usage   : $structure->get_models($structure);
        Function: general get method for models attached to an Entry
        Returns : a list of models attached to this entry
        Args    : an Entry

   id()
        Title   : id
        Usage   : $entry->id("identity");
        Function: Gets/sets the ID
        Returns : The ID
        Args    :

   chain()
        Title   : chain
        Usage   : @chains  = $structure->chain($chain);
        Function: Connects a Chain or a list of Chain objects to a Bio::Structure::Entry.
        Returns : List of Bio::Structure::Chain objects
        Args    : A Chain or a reference to an array of Chain objects

   add_chain()
        Title   : add_chain
        Usage   : @chains  = $structure->add_chain($model,$chain);
        Function: Adds one or more Chain objects to a Bio::Structure::Entry.
        Returns : List of Chain objects associated with the Model
        Args    : A Model object and a Chain object or a reference to an array of
                  of Chain objects

   get_chains()
        Title   : get_chains
        Usage   : $entry->get_chains($model);
        Function: General get method for Chains attached to a Model
        Returns : A list of Chains attached to this model
        Args    : A Model

   residue()
        Title   : residue
        Usage   : @residues  = $structure->residue($residue);
        Function: Connects a (or a list of) Residue objects to a Bio::Structure::Entry.
        Returns : List of Bio::Structure::Residue objects
        Args    : One Residue or a reference to an array of Residue objects

   add_residue()
        Title   : add_residue
        Usage   : @residues  = $structure->add_residue($chain,$residue);
        Function: Adds one or more Residue objects to a Bio::Structure::Entry.
        Returns : List of Bio::Structure::Residue objects
        Args    : A Chain object and a Residue object or a reference to an array of
                  Residue objects

   get_residues()
        Title   : get_residues
        Usage   : $structure->get_residues($chain);
        Function: General get method for Residues attached to a Chain
        Returns : A list of residues attached to this Chain
        Args    : A Chain

   add_atom()
        Title   : add_atom
        Usage   : @atoms  = $structure->add_atom($residue,$atom);
        Function: Adds a (or a list of) Atom objects to a Bio::Structure::Residue.
        Returns : List of Bio::Structure::Atom objects
        Args    : A Residue and an Atom

   get_atoms()
        Title   : get_atoms
        Usage   : $structure->get_atoms($residue);
        Function: General get method for Atoms attached to a Residue
        Returns : A list of Atoms attached to this Residue
        Args    : A Residue

   parent()
        Title   : parent
        Usage   : $structure->parent($residue);
        Function: Returns the parent of the argument
        Returns : The parent of the argument
        Args    : A Bio::Structure object

   connect
        Title   : connect
        Usage   :
        Function: Alias to conect()
        Returns :
        Args    :

   conect()
        Title   : conect
        Usage   : $structure->conect($source);
        Function: Get/set method for conect
        Returns : A list of serial numbers for Atoms connected to source
                       (together with $entry->get_atom_by_serial($model, $serial),
                  this should be OK for now)
        Args    : The source, the serial number for the source Atom, and the type

   get_all_connect_source
        Title   : get_all_connect_source
        Usage   :
        Function: Alias to get_all_conect_source()
        Returns :
        Args    :

   get_all_conect_source()
        Title   : get_all_conect_source
        Usage   : @sources = $structure->get_all_conect_source;
        Function: Get all the sources for the conect records
        Returns : A list of serial numbers for atoms connected to source
                       (together with $entry->get_atom_by_serial($model, $serial),
                  this should be OK for now)
        Args    :
        Notes   : This is a bit of a kludge, but it is the best for now. Conect info might need
                       to go in a separate object

   master()
        Title   : master
        Usage   : $structure->master($source);
        Function: Get/set method for master
        Returns : The master line
        Args    : The master line for this entry

   seqres()
        Title   : seqres
        Usage   : $seqobj = $structure->seqres("A");
        Function: Gets a sequence object containing the sequence from the SEQRES record.
                       if a chain-ID is given, the sequence for this chain is given, if none
                       is provided the first chain is chosen
        Returns : A Bio::PrimarySeq
        Args    : The chain-ID of the chain you want the sequence from

   get_atom_by_serial()
        Title   : get_atom_by_serial
        Usage   : $structure->get_atom_by_serial($model,$serial);
        Function: Get the Atom by serial
        Returns : The Atom object with this serial number in the model
        Args    : Model on which to work, serial number for atom
                       (if only a number is supplied, the first model is chosen)

   annotation
        Title   : annotation
        Usage   : $obj->annotation($seq_obj)
        Function:
        Example :
        Returns : value of annotation
        Args    : newvalue (optional)

   _remove_models()
        Title   : _remove_models
        Usage   :
        Function: Removes the models attached to an Entry. Tells the models they
                       do not belong to this Entry any more
        Returns :
        Args    :

   _create_default_model()
        Title   : _create_default_model
        Usage   :
        Function: Creates a default Model for this Entry. Typical situation
                       in an X-ray structure where there is only one model
        Returns :
        Args    :

   _create_default_chain()
        Title   : _create_default_chain
        Usage   :
        Function: Creates a default Chain for this Model. Typical situation
                       in an X-ray structure where there is only one chain
        Returns :
        Args    :

   _parent()
        Title   : _parent
        Usage   : This is an internal function only. It is used to have one
                       place that keeps track of which object has which other object
                       as parent. Thus allowing the underlying modules (Atom, Residue,...)
                       to have no knowledge about all this (and thus removing the possibility
                       of reference cycles).
                       This method hides the details of manipulating references to an anonymous
                       hash.
        Function: To get/set an objects parent
        Returns : A reference to the parent if it exist, undef otherwise. In the
                       current implementation each node should have a parent (except Entry).
        Args    :

   _child()
        Title   : _child
        Usage   : This is an internal function only. It is used to have one
                       place that keeps track of which object has which other object
                       as child. Thus allowing the underlying modules (Atom, Residue,...)
                       to have no knowledge about all this (and thus removing the possibility
                       to have no knowledge about all this (and thus removing the possibility
                       of reference cycles).
                       This method hides the details of manipulating references to an anonymous
                       hash.
        Function: To get/set an the children of an object
        Returns : A reference to an array of child(ren) if they exist, undef otherwise.
        Args    :

   _remove_from_graph()
        Title   : _remove_from_graph
        Usage   : This is an internal function only. It is used to remove from
                       the parent/child graph. We only remove the links from object to
                       his parent. Not the ones from object to its children.
        Function: To remove an object from the parent/child graph
        Returns :
        Args    : The object to be orphaned