NAME
    Bio::DB::Das::Chado - DAS-style access to a chado database

SYNOPSIS
      # Open up a feature database
                     $db    = Bio::DB::Das::Chado->new(
                                -dsn  => 'dbi:Pg:dbname=gadfly;host=lajolla'
                                -user => 'jimbo',
                                -pass => 'supersecret',
                                           );

      @segments = $db->segment(-name  => '2L',
                               -start => 1,
                               -end   => 1000000);

      # segments are Bio::Das::SegmentI - compliant objects

      # fetch a list of features
      @features = $db->features(-type=>['type1','type2','type3']);

      # invoke a callback over features
      $db->features(-type=>['type1','type2','type3'],
                    -callback => sub { ... }
                    );

      # get all feature types
      @types   = $db->types;

      # count types
      %types   = $db->types(-enumerate=>1);

      @feature = $db->get_feature_by_name($class=>$name);
      @feature = $db->get_feature_by_target($target_name);
      @feature = $db->get_feature_by_attribute($att1=>$value1,$att2=>$value2);
      $feature = $db->get_feature_by_id($id);

      $error = $db->error;

DESCRIPTION
    Chado is the GMOD database schema, and chado is a specific instance of
    it. It is still somewhat of a moving target, so this package will
    probably require several updates over the coming months to keep it
    working.

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

      gmod-gbrowse@lists.sourceforge.com

  Reporting Bugs
    Report bugs to the GMOD bug tracking system at SourceForge to help us
    keep track the bugs and their resolution.

      http://sourceforge.net/tracker/?group_id=27707&atid=391291

AUTHOR - Scott Cain
    Email scain@cpan.org

LICENSE
    This software may be redistributed under the same license as perl.

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

  new
     Title   : new
     Usage   : $db    = Bio::DB::Das::Chado(
                                -dsn  => 'dbi:Pg:dbname=gadfly;host=lajolla'
                                -user => 'jimbo',
                                -pass => 'supersecret',
                                           );

     Function: Open up a Bio::DB::DasI interface to a Chado database
     Returns : a new Bio::DB::Das::Chado object
     Args    :

  use_all_feature_names
      Title   : use_all_feature_names
      Usage   : $obj->use_all_feature_names()
      Function: set or return flag indicating that all_feature_names view is present
      Returns : 1 if all_feature_names present, 0 if not
      Args    : to return the flag, none; to set, 1

  organism_id
      Title   : organism_id
      Usage   : $obj->organism_id()
      Function: set or return the organism_id
      Returns : the value of the id
      Args    : to return the flag, none; to set, the common name of the organism

    If -organism is set when the Chado feature is instantiated, this method
    queries the database with the common name to cache the organism_id.

  inferCDS
      Title   : inferCDS
      Usage   : $obj->inferCDS()
      Function: set or return the inferCDS flag
      Returns : the value of the inferCDS flag
      Args    : to return the flag, none; to set, 1

    Often, chado databases will be populated without CDS features, since
    they can be inferred from a union of exons and polypeptide features.
    Setting this flag tells the adaptor to do the inferrence to get those
    derived CDS features (at some small performance penatly).

  allow_obsolete
      Title   : allow_obsolete
      Usage   : $obj->allow_obsolete()
      Function: set or return the allow_obsolete flag
      Returns : the value of the allow_obsolete flag
      Args    : to return the flag, none; to set, 1

    The chado feature table has a flag column called 'is_obsolete'.
    Normally, these features should be ignored by GBrowse, but the
    -allow_obsolete method is provided to allow displaying obsolete
    features.

  sofa_id
      Title   : sofa_id 
      Usage   : $obj->sofa_id()
      Function: get or return the ID to use for SO terms
      Returns : the cv.cv_id for the SO ontology to use
      Args    : to return the id, none; to determine the id, 1

  recursivMapping
      Title   : recursivMapping
      Usage   : $obj->recursivMapping($newval)
      Function: Flag for activating the recursive mapping (desactivated by default)
      Returns : value of recursivMapping (a scalar)
      Args    : on set, new value (a scalar or undef, optional)

      Goal : When we have a clone mapped on a chromosome, the recursive mapping maps the features of the clone on the chromosome.

  srcfeatureslice
      Title   : srcfeatureslice
      Usage   : $obj->srcfeatureslice
      Function: Flag for activating 
      Returns : value of srcfeatureslice
      Args    : on set, new value (a scalar or undef, optional)
      Desc    : Allows to use a featureslice of type featureloc_slice(srcfeat_id, int, int)
      Important : this and recursivMapping are mutually exclusives

  do2Level
      Title   : do2Level
      Usage   : $obj->do2Level
      Function: Flag for activating the fetching of 2levels in segment->features
      Returns : value of do2Level
      Args    : on set, new value (a scalar or undef, optional)

  dbh
      Title   : dbh
      Usage   : $obj->dbh($newval)
      Function:
      Returns : value of dbh (a scalar)
      Args    : on set, new value (a scalar or undef, optional)

  term2name
      Title   : term2name
      Usage   : $obj->term2name($newval)
      Function: When called with a hashref, sets cvterm.cvterm_id to cvterm.name 
                mapping hashref; when called with an int, returns the name
                corresponding to that cvterm_id; called with no arguments, returns
                the hashref.
      Returns : see above
      Args    : on set, a hashref; to retrieve a name, an int; to retrieve the
                hashref, none.

    Note: should be replaced by Bio::GMOD::Util->term2name

  name2term
      Title   : name2term
      Usage   : $obj->name2term($newval)
      Function: When called with a hashref, sets cvterm.name to cvterm.cvterm_id
                mapping hashref; when called with a string, returns the cvterm_id
                corresponding to that name; called with no arguments, returns
                the hashref.
      Returns : see above
      Args    : on set, a hashref; to retrieve a cvterm_id, a string; to retrieve
                the hashref, none.

    Note: Should be replaced by Bio::GMOD::Util->name2term

  segment
     Title   : segment
     Usage   : $db->segment(@args);
     Function: create a segment object
     Returns : segment object(s)
     Args    : see below

    This method generates a Bio::Das::SegmentI object (see
    Bio::Das::SegmentI). The segment can be used to find overlapping
    features and the raw sequence.

    When making the segment() call, you specify the ID of a sequence
    landmark (e.g. an accession number, a clone or contig), and a positional
    range relative to the landmark. If no range is specified, then the
    entire region spanned by the landmark is used to generate the segment.

    Arguments are -option=>value pairs as follows:

     -name         ID of the landmark sequence.

     -class        A namespace qualifier.  It is not necessary for the
                   database to honor namespace qualifiers, but if it
                   does, this is where the qualifier is indicated.

     -version      Version number of the landmark.  It is not necessary for
                   the database to honor versions, but if it does, this is
                   where the version is indicated.

     -start        Start of the segment relative to landmark.  Positions
                   follow standard 1-based sequence rules.  If not specified,
                   defaults to the beginning of the landmark.

     -end          End of the segment relative to the landmark.  If not specified,
                   defaults to the end of the landmark.

    The return value is a list of Bio::Das::SegmentI objects. If the method
    is called in a scalar context and there are no more than one segments
    that satisfy the request, then it is allowed to return the segment.
    Otherwise, the method must throw a "multiple segment exception".

  features
     Title   : features
     Usage   : $db->features(@args)
     Function: get all features, possibly filtered by type
     Returns : a list of Bio::SeqFeatureI objects
     Args    : see below
     Status  : public

    This routine will retrieve features in the database regardless of
    position. It can be used to return all features, or a subset based on
    their type

    Arguments are -option=>value pairs as follows:

      -type      List of feature types to return.  Argument is an array
                 of Bio::Das::FeatureTypeI objects or a set of strings
                 that can be converted into FeatureTypeI objects.

      -callback   A callback to invoke on each feature.  The subroutine
                  will be passed each Bio::SeqFeatureI object in turn.

      -attributes A hash reference containing attributes to match.

    The -attributes argument is a hashref containing one or more attributes
    to match against:

      -attributes => { Gene => 'abc-1',
                       Note => 'confirmed' }

    Attribute matching is simple exact string matching, and multiple
    attributes are ANDed together.

    If one provides a callback, it will be invoked on each feature in turn.
    If the callback returns a false value, iteration will be interrupted.
    When a callback is provided, the method returns undef.

  types
     Title   : types
     Usage   : $db->types(@args)
     Function: return list of feature types in database
     Returns : a list of Bio::Das::FeatureTypeI objects
     Args    : see below

    This routine returns a list of feature types known to the database. It
    is also possible to find out how many times each feature occurs.

    Arguments are -option=>value pairs as follows:

      -enumerate  if true, count the features

    The returned value will be a list of Bio::Das::FeatureTypeI objects (see
    Bio::Das::FeatureTypeI.

    If -enumerate is true, then the function returns a hash (not a hash
    reference) in which the keys are the stringified versions of
    Bio::Das::FeatureTypeI and the values are the number of times each
    feature appears in the database.

    NOTE: This currently raises a "not-implemented" exception, as the BioSQL
    API does not appear to provide this functionality.

  get_feature_by_alias, get_features_by_alias
     Title   : get_features_by_alias
     Usage   : $db->get_feature_by_alias(@args)
     Function: return list of feature whose name or synonyms match
     Returns : a list of Bio::Das::Chado::Segment::Feature objects
     Args    : See below

    This method finds features matching the criteria outlined by the
    supplied arguments. Wildcards (*) are allowed. Valid arguments are:

    -name
    -class
    -ref (refrence sequence)
    -start
    -end

  get_feature_by_name, get_features_by_name
     Title   : get_features_by_name
     Usage   : $db->get_features_by_name(@args)
     Function: return list of feature whose names match
     Returns : a list of Bio::Das::Chado::Segment::Feature objects
     Args    : See below

    This method finds features matching the criteria outlined by the
    supplied arguments. Wildcards (*) are allowed. Valid arguments are:

    -name
    -class
    -ref (refrence sequence)
    -start
    -end

  _by_alias_by_name
     Title   : _by_alias_by_name
     Usage   : $db->_by_alias_by_name(@args)
     Function: return list of feature whose names match
     Returns : a list of Bio::Das::Chado::Segment::Feature objects
     Args    : See below

    A private method that implements the get_features_by_name and
    get_features_by_alias methods. It accepts the same args as those
    methods, plus an addtional on (-operation) which is either 'by_alias' or
    'by_name' to indicate what rule it is to use for finding features.

  srcfeature2name
    returns a srcfeature name given a srcfeature_id

  gff_source_db_id
      Title   : gff_source_db_id
      Function: caches the chado db_id from the chado db table

  gff_source_dbxref_id
    Gets dbxref_id for features that have a gff source associated

  dbxref2source
    returns the source (string) when given a dbxref_id

  source_dbxref_list
     Title   : source_dbxref_list
     Usage   : @all_dbxref_ids = $db->source_dbxref_list()
     Function: Gets a list of all dbxref_ids that are used for GFF sources
     Returns : a comma delimited string that is a list of dbxref_ids
     Args    : none
     Status  : public

    This method queries the database for all dbxref_ids that are used to
    store GFF source terms.

  search_notes
     Title   : search_notes
     Usage   : $db->search_notes($search_term,$max_results)
     Function: full-text search on features, ENSEMBL-style
     Returns : an array of [$name,$description,$score]
     Args    : see below
     Status  : public

    This routine performs a full-text search on feature attributes (which
    attributes depend on implementation) and returns a list of
    [$name,$description,$score], where $name is the feature ID (accession?),
    $description is a human-readable description such as a locus line, and
    $score is the match strength.

  ** NOT YET ACTIVE: search_notes IS IN TESTING STAGE **
    sub search_notes { my $self = shift; my ($search_string,$limit) = @_; my
    $limit_str; if (defined $limit) { $limit_str = " LIMIT $limit "; } else
    { $limit_str = ""; }

    # so here's the plan: # if there is only 1 word, do 1-3 # 1. search for
    accessions like $string.'%'--if any are found, quit and return them # 2.
    search for feature.name like $string.'%'--if found, keep and continue #
    3. search somewhere in analysis like $string.'%'--if found, keep and
    continue # if there is more than one word, don't search accessions # 4.
    search each word anded together like '%'.$string.'%' --if found, keep
    and continue # 5. search somewhere in analysis like '%'.$string.'%'

    # $self->dbh->trace(1);

      my @search_str = split /\s+/, $search_string;
      my $qsearch_term = $self->dbh->quote($search_str[0]);
      my $like_str = "( (dbx.accession ~* $qsearch_term OR \n"
            ."           f.name        ~* $qsearch_term) ";
      for (my $i=1;$i<(scalar @search_str);$i++) {
        $qsearch_term = $self->dbh->quote($search_str[$i]);
        $like_str .= "and \n";
        $like_str .= "          (dbx.accession ~* $qsearch_term OR \n"
                    ."           f.name        ~* $qsearch_term) ";
      } 
      $like_str .= ")";

      my $sth = $self->dbh->prepare("
         select dbx.accession,f.name,0 
         from feature f, dbxref dbx, feature_dbxref fd
         where
            f.feature_id = fd.feature_id and
            fd.dbxref_id = dbx.dbxref_id and 
            $like_str 
         $limit_str
        ");
      $sth->execute or throw ("couldn't execute keyword query");

      my @results;
      while (my ($acc, $name, $score) = $sth->fetchrow_array) {
        $score = sprintf("%.2f",$score);
        push @results, [$acc, $name, $score];
      }
      $sth->finish;
      return @results;
    }

  attributes
     Title   : attributes
     Usage   : @attributes = $db->attributes($id,$name)
     Function: get the "attributes" on a particular feature
     Returns : an array of string
     Args    : feature ID [, attribute name]
     Status  : public

    This method is intended as a "work-alike" to Bio::DB::GFF's attributes
    method, which has the following returns:

    Called in list context, it returns a list. If called in a scalar
    context, it returns the first value of the attribute if an attribute
    name is provided, otherwise it returns a hash reference in which the
    keys are attribute names and the values are anonymous arrays containing
    the values.

  _segclass
     Title   : _segclass
     Usage   : $class = $db->_segclass
     Function: returns the perl class that we use for segment() calls
     Returns : a string containing the segment class
     Args    : none
     Status  : reserved for subclass use

  chado_reference_class
      Title   : chado_reference_class 
      Usage   : $obj->chado_reference_class()
      Function: get or return the ID to use for Gbrowse map reference class 
                using cvtermprop table, value = MAP_REFERENCE_TYPE 
      Returns : the cvterm.name 
      Args    : to return the id, none; to determine the id, 1
      See also: default_class, refclass_feature_id

      Optionally test that user/config supplied ref class is indeed a proper
      chado feature type.
  
  refclass_feature_id
     Title   : refclass_feature_id
     Usage   : $self->refclass_srcfeature_id()
     Function: Used to store the feature_id of the reference class feature we are working on (e.g. contig, supercontig)
               With this feature we can filter out all the request to be sure we are extracting a feature located on 
               the reference class feature.
     Returns : A scalar
     Args    : The feature_id on setting

LEFTOVERS FROM BIO::DB::GFF NEEDED FOR DAS
    these methods should probably be declared in an interface class that
    Bio::DB::GFF implements. for instance, the aggregator methods could be
    described in Bio::SeqFeature::AggregatorI

END LEFTOVERS
