LibAMOS Quick Reference

From AMOS WIKI
Revision as of 02:22, 2 November 2009 by Mcschatz (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

libAMOS API quick reference

#include <foundation_AMOS.hh>   all of the below

#include <inttypes_AMOS.hh>     integer typedefs
#include <exceptions_AMOS.hh>   exception types
#include <datatypes_AMOS.hh>    structs
#include <databanks_AMOS.hh>    bank types
#include <messages_AMOS.hh>     message types and message NCodes
#include <universals_AMOS.hh>   assembly classes

TERMINOLOGY

IID             internal integer identifier and object reference
EID             external string identifier
BID             bank specific identifier (index of the file store)
3-Code          3-character identifier string for objects and fields
N-Code          an integer representation of a 3-code (Encode/Decode functions)
message         a single curly-bracketed AMOS message
sub-message     a single curly-bracketed AMOS message contained by another
normal           ---a--->  ---b--->
anti-normal     <---a---  <---b---
innie            ---a---> <---b---
outie           <---a---   ---b--->

GLOBAL NAMESPACE

TYPEDEFS

[u]int(bits)_t  signed or unsigned 8,16,32,64 bit integers

ID_t            uint32_t        integer identifier
NCode_t         uint32_t        integer object identifier
SD_t            uint32_t        standard deviation
Size_t          int32_t         size type
Status_t        char            object status
Pos_t           int32_t         position type 

"AMOS" NAMESPACE

CONSTANTS

NCODE_SIZE      3               length of NCode string
NULL_NCODE      0               null object code
NULL_ID         0               null identifier
NULL_STATUS     0               null status
MIN_QUALITY     '0'             minimum quality score
MAX_QUALITY     '0' + 63        maximum quality score
NULL_CHAR       '\0'            null character
NL_CHAR         '\n'            newline character
NULL_STRING     string("")      null string
MAX_ID          (1<<32)-1       maximum identifier
MAX_SIZE        (1<<31)-1       maximum size
MAX_POS         (1<<31)-1       maximum position

E_ADD           'A'             bank addition event
E_DELETE        'D'             bank deletion event
E_REPLACE       'R'             bank replacement event
F_IID           Encode("iid")   internal identifier (IID) field NCode
M_READ          Encode("RED")   read message NCode
F_*                             see API for full list of fields
M_*                             see API for full list of messages

FUNCTIONS

BankExists (NCode_t, string)    check for a bank of type in dir
string Decode (NCode_t)         NCode_t to string
NCode_t Encode (string)         string to NCode_t
ostream << Exception_t          write AMOS exception info to stream
ostream << exception            write std exception info to stream
readLE (istream, int*)          read a little-endian int from a stream
writeLE (ostream, int*)         write a little-endian int to a stream
char Qual2Char (uint8_t)        convert a qual score to a viewable char
uint8_t Char2Qual (char)        convert a viewable qual char to a qual score
SafeCalloc (size_t, size_t)     same as calloc but throws AMOS exception
SafeMalloc (size_t)             same as malloc but throws AMOS exception
SafeRealloc (void*, size_t)     same as realloc but throws AMOS exception
SafeStrdup (const char*)        same as strdup but throws AMOS exception 

CLASSES

Bank_t                         random access bank
     BankStream_t              stream-style access bank
Exception_t                    general exception
    AlignmentException_t       alignment error exception
    AllocException_t           allocation error exception
    ArgumentException_t        logical parameter error exception
    IOException_t              I/O error exception
IBankable_t                    bank-able object interface
    Universal_t                bank-able and message-able object
         Contig_t
         Feature_t
         Fragment_t
         Group_t
         Index_t
         Kmer_t
         Layout_t
         Library_t
         Link_t
              ContigLink_t
              ScaffoldLink_t
              Edge_t
                   ContigEdge_t
                   ScaffoldEdge_t
         Matepair_t
         Overlap_t
         Scaffold_t
         Sequence_t
              Contig_t
              Read_t
IMessageable_t                 message-able object interface
    Distribution_t
    IDMap_t                    IID, EID, BID mapping
    Tile_t
    Universal_t*
Message_t                      message I/O class
Range_t                        linear range
BankSet_t                      complete set of banks hashed by NCode
BankStreamSet_t                complete set of bank streams hashed by NCode
UniversalSet_t                 complete set of universals hashed by NCode

EXAMPLES

MESSAGE to BANK

#include <iostream>
#include <foundation_AMOS.hh>
using namespace std;
using namespace AMOS; 

int main ( )
{
  Message_t msg;
  Universal_t obj;
  BankStream_t bank(Universal_t::NCODE); 
  
  try {
    bank.create ("bankdir");
    while ( msg.read (cin) )   // gets next message from cin
    {
      obj.readMessage (msg);   // gets obj from msg
      bank << obj;             // appends obj to bank
    }
    bank.close( );
  }
  catch (Exception_t & e) {
    cerr << "ERROR: -- AMOS Exception --" << endl << e;
  }
  return 0;
}

BANK to MESSAGE

...
int main ( )
{
  Message_t msg;
  Universal_t obj;
  BankStream_t bank(Universal_t::NCODE); 

  try {
    bank.open ("bankdir");
    while ( bank >> obj )      // fetches next banked object
    {
      obj.writeMessage (msg);  // writes the obj to msg
      msg.write (cout);        // writes message to cout
    }
    bank.close( );
  }
  catch (Exception_t & e) {
    cerr << “FATAL: “ << e . what( ) << endl
         << “  could not complete, abort” << endl;
  }
  return 0;
}


RANDOM FETCH

...
int main ( )
{
  ID_t iid;
  Read_t red;
  Bank_t bank(Read_t::NCODE); 

  bank.open ("bankdir");
  if ( (iid = bank.lookupIID (“GBSAA01TF”)) != NULL_ID )
  {
    bank.fetch (iid, red);            // gets the read by IID
    bank.fetch (“GBSAA01TF”, red);    // gets same read by EID
  }
  bank.close( );
  
  return 0;

}