// // BCNucleotideDNA.h // BioCocoa // // Created by John Timmer on 8/11/04. // Copyright 2004 John Timmer. All rights reserved. // #import #import "BCSymbol.h" /*! @class BCNucleotideDNA @abstract All DNA bases are handled through this single class @discussion This class provides in-memory representations of DNA bases. * Through class methods and static variables, single application wide representations * of each individual base and the ambiguous base representations are provided to all * BioCocoa applications. Access to an individual base is provided by methods such as: * [BCNucleotideDNA adenine]; * [BCNucleotideDNA purine]; * Repesentations of a non-base and gap characters (for alignments) are also available. * Typically, bases are not handled directly, but rather through their container objects, * BCSequence subclasses. * * Why not use strings? * Unicode characters are 16bit, while pointers on MacOS-X are (currently) 32 bit. In * the overall picture, memory differences are not significant. In return, each base provides * detailed information about complements, ambiguity, etc. which would otherwise need to be coded * by hand. * * Initialization of base data * Details of base information and relationships are read from the "base template.plist" file * within the Framework bundle. Loss or alteration of this file will cause all DNA-based programs * to fail. References to other bases (ie - the complement) are retained as string-formatted selectors * until they are needed, at which point they are used to generate pointers to the other bases. * Custom bases can be generated using this file as an example - they remain stored in an NSDictionary. * * Individual bases are obtained using their named class method, or by sending an appropriate symbol to the * "baseForSymbol:" class method. */ @interface BCNucleotideDNA : BCSymbol { NSDictionary *baseInfo; BOOL isSingleBase; BCNucleotideDNA *complement; NSArray *complements; NSArray *represents; NSArray *representedBy; float molecularWeight; } //////////////////////////////////////////////////////////////////////////// // CLASS METHODS START HERE #pragma mark â CLASS METHOS //////////////////////////////////////////////////////////////////////////// /*! @method initBases @abstract Used internaly to generate the full set of base objects. */ + (void) initBases; /*! @method baseForSymbol: (unichar)symbol @abstract Returns a BCNucleotideDNA item representing the base submitted */ + (id) baseForSymbol: (unichar)symbol; /*! @method + (id) objectForSavedRepresentation: (NSString *)aSymbol @abstract Returns a BCNucleotideDNA object representing the base submitted @discussion all BC classes should implement a "savableRepresentation" and an * "objectForSavedRepresentation" method to allow archiving/uncarchiving in * .plist formatted files. */ + (id) objectForSavedRepresentation: (NSString *)aSymbol; /*! @method adenosine @abstract Obtains a reference to the single adenosine representation */ + (BCNucleotideDNA *) adenosine; /*! @method thymidine @abstract Obtains a reference to the single thymidine representation */ + (BCNucleotideDNA *) thymidine; /*! @method cytidine @abstract Obtains a reference to the single cytidine representation */ + (BCNucleotideDNA *) cytidine; /*! @method guanidine @abstract Obtains a reference to the single guanidine representation */ + (BCNucleotideDNA *) guanidine; /*! @method anyBase @abstract Obtains a reference to the single N representation */ + (BCNucleotideDNA *) anyBase; /*! @method purine @abstract Obtains a reference to the single purine representation */ + (BCNucleotideDNA *) purine; /*! @method pyrimidine @abstract Obtains a reference to the single pyrimidine representation */ + (BCNucleotideDNA *) pyrimidine; /*! @method strong @abstract Obtains a reference to the single strong-bond representation */ + (BCNucleotideDNA *) strong; /*! @method weak @abstract Obtains a reference to the single weak-bond representation */ + (BCNucleotideDNA *) weak; /*! @method M @abstract Obtains a reference to the single M (A, C) representation */ + (BCNucleotideDNA *) amino; /*! @method K @abstract Obtains a reference to the single K (A, C) representation */ + (BCNucleotideDNA *) keto; /*! @method H @abstract Obtains a reference to the single H (A, C, T) representation */ + (BCNucleotideDNA *) H; /*! @method V @abstract Obtains a reference to the single V (A, C, G) representation */ + (BCNucleotideDNA *) V; /*! @method D @abstract Obtains a reference to the single D (A, G, T) representation */ + (BCNucleotideDNA *) D; /*! @method B @abstract Obtains a reference to the single D (C, G, T) representation */ + (BCNucleotideDNA *) B; /*! @method gap @abstract Obtains a reference to the single representation of a gap, for alignments */ + (BCNucleotideDNA *) gap; /*! @method undefined @abstract Obtains a reference to the single representation of any non-base character */ + (BCNucleotideDNA *) undefined; /*! @method customBase (NSString *)baseName @abstract Obtains a reference to a user-defined base */ + (BCNucleotideDNA *) customBase: (NSString *)baseName; //////////////////////////////////////////////////////////////////////////// // OBJECT METHODS START HERE // #pragma mark â #pragma mark â OBJECT METHODS #pragma mark â #pragma mark âINITIALIZATION METHODS // // INITIALIZATION //////////////////////////////////////////////////////////////////////////// /*! @method - (id)initWithSymbol:(unichar)aSymbol @abstract designated initialization method @discussion Given a symbol, this method generates the appropriate Nucleotide representation using * information in the bundle's "base template.plist" file. */ - (id)initWithSymbol:(unichar)aSymbol; /*! @method initializeBaseRelationships @abstract converts string-based selectors to base references @discussion After the initialization above, internal references to other bases * (complement, representations, etc.) remain in string-based selector form. The first time * the actual reference is needed, this method will use the selectors to generate the actual * references to the bases. */ - (void) initializeBaseRelationships; #pragma mark âBASE INFORMATION METHODS /*! @method isSingleBase @abstract Returns YES if the receiver is not an ambiguous base */ - (BOOL) isSingleBase; /*! @method isBase @abstract Returns NO if the receiver is a gap or undefined */ - (BOOL) isBase; /*! @method - (float) molecularWeight @abstract Returns a value suitable for calculating the molecular weight of a sequence of bases, * including ambiguous bases */ //- (float) molecularWeight; #pragma mark âBASE RELATIONSHIP METHODS /////////////////////////////////////////////////////////// // COMPLEMENTATION METHODS /////////////////////////////////////////////////////////// /*! @method complement @abstract Returns a reference to the base the complements the receiver @discussion When called on adenosine, this method will return a reference to thyidine. * For ambiguous bases, it returns the single most complete complement - when called on purine, * it will return only pyrimidine. */ - (BCNucleotideDNA *)complement; /*! @method complements @abstract Returns references all bases that may complement the receiver in an array @discussion When called on adenosine, this method will return an array containing references * to thyidine, weak, any, etc. */ - (NSArray *)complements; /*! @method complementsBase: (BCNucleotideDNA *)entry; @abstract Evaluates whether the receiver complements the entry @discussion When called on adenosine, this method will return YES if the entry is thymidine, * weak, any base, etc. */ - (BOOL) complementsBase: (BCNucleotideDNA *)entry; /////////////////////////////////////////////////////////// // REPRESENTATION METHODS FOR AMBIGUOUS BASES /////////////////////////////////////////////////////////// /*! @method representedBases; @abstract returns an array containing all bases represented by the receiver @discussion When called on adenosine, this method will return an array with a single item, adenosine. * When called on purine, it will return an array with adenosine and guanidine. */ - (NSArray *) representedBases; /*! @method representingBases @abstract returns an array with all bases that may represent the receiver @discussion When called on adenosine, this method will return adenosine, * weak, any base, etc. */ - (NSArray *) representingBases; /*! @method representsBase: (BCNucleotideDNA *)entry; @abstract Evaluates whether the receiver represents the entry @discussion When called on adenosine, this method will return YES if the entry is adenosine, * It will return NO for anything else. * When called on weak, will return YES for adenosine and thymidine, but NO for anything else. */ - (BOOL) representsBase: (BCNucleotideDNA *) entry; /*! @method isRepresentedByBase: (BCNucleotideDNA *)entry; @abstract Evaluates whether the receiver is represented by the entry @discussion When called on adenosine, this method will return YES if the entry is adenosine, * weak, any base, etc. */ - (BOOL) isRepresentedByBase: (BCNucleotideDNA *) entry; /*! @method symbolsOfRepresentedBases @abstract Returns a character set containing the symbols of all the bases that are represented by the receiver. */ - (NSCharacterSet *) symbolsOfRepresentedBases; @end