C Interface

Detailed Description

The C interface contains the algorithms for the calculations on raw slices.

Data Structures

struct libSlice_BaseDistribution

Holds a table of the distribution of bases. More...

struct libSlice_Consensus

Holds the quality value of the onsensus and each of the 5 components. More...

struct libSlice_Slice

Structure for specifing slice information. More...

Slice Consensus Calculations

Functions for calculating the consensus and qv of a single slice

void libSlice_setRecallEmpty (int recallEmpty)

Toggles if empty slices should be recalled as gap.

int libSlice_getConsensusParam (const libSlice_Slice *s, libSlice_Consensus *result, const libSlice_BaseDistribution *dist, int highQualityThreshold, int doAmbiguity)

Calculates the consensus quality value for a single slice.

int libSlice_updateAmbiguityConic (const libSlice_Slice *s, libSlice_Consensus *consensus, int highQuality)

Updates the ambiguity flags using the conic model and scoring matrix.

int libSlice_updateAmbiguity (const libSlice_Slice *s, libSlice_Consensus *consensus, int highQualityThreshold)

Updates the ambiguity flags to include all high quality reads.

int libSlice_getConsensus (const libSlice_Slice *s, libSlice_Consensus *results, const libSlice_BaseDistribution *dist, int highQualityThreshold)

Calculates the consensus of a slice with NO ambiguity codes.

int libSlice_getConsensusWithAmbiguity (const libSlice_Slice *s, libSlice_Consensus *results, const libSlice_BaseDistribution *dist, int highQualityThreshold)

Calculates the consensus of a slice with ambiguity codes.

SliceRange Consensus Calculations

Functions for calculating the consensus and qv of a range of slices

int libSlice_getConsensusRangeParam (const libSlice_Slice s[], libSlice_Consensus results[], int len, const libSlice_BaseDistribution *dist, int highQualityThreshold, int doAmbiguity)

Calculates the Consensus Quality Values for a range of slices.

int libSlice_getConsensusRange (const libSlice_Slice s[], libSlice_Consensus results[], int len, const libSlice_BaseDistribution *dist, int highQualityThreshold)

Calculates the consensus of an array of slice with no ambiguity codes.

int libSlice_getConsensusRangeWithAmbiguity (const libSlice_Slice s[], libSlice_Consensus results[], int len, const libSlice_BaseDistribution *dist, int highQualityThreshold)

Calculates the consensus of an array of slice with ambiguity codes.

Quality Class Calculations

Functions for calculating the quality class of slices

char libSlice_getConsQC (const libSlice_Slice *s, int highQualityThreshold)

Calculates the quality class for a single slice.

char * libSlice_getConsQCRange (const libSlice_Slice s[], int len, int highQualityThreshold)

Calculates the quality classes for a range of slices.

Ambiguity Code Calculations

Functions for calculating ambiguity Codes

char libSlice_getAmbiguityCode (long double cpA, long double cpC, long double cpG, long double cpT, long double cpGap, int highQualityThreshold, int baseCount)

Return IUPAC Ambiguity Code in one operation.

char libSlice_calculateAmbiguityFlags (long double cpA, long double cpC, long double cpG, long double cpT, long double cpGap, int highQualityThreshold, int baseCount)

Calculates ambiguity flags from Churchill and Waterman procedure.

char libSlice_convertAmbiguityFlags (char ambiguityFlags)

Calculates extended ambiguity code bases from ambiguity flags.

Utility Functions

Other useful functions

char libSlice_getCompliment (char base)

Get the compliment to a base or ambiguity code.

const char * libSlice_getVersion ()

Gets a string representing the version of the library.

void * libSlice_newmem (int number, int size)

Error Checking malloc.

Slice Consensus Calculations

Functions for calculating the consensus and qv of a single slice

int m_recallEmpty = 0

Defines

#define HIGH_QUALITY_THRESHOLD   30

What is considered high quality by ABI.

#define MIN_QUALITY_VALUE   1

Minimum allowed quality value (gap or otherwise).

#define GAP_QUALITY_VALUE_EMPTY_SLICE   1

Quality value to assign to gap in an empty slice.

#define MAX_QUALITY_VALUE   4000

Quality Value to return when floating point underflows occur.

#define AMBIGUITY_FLAGBIT_A   0x1

Bit flag for 'A' in ambiguity code.

#define AMBIGUITY_FLAGBIT_C   0x2

Bit flag for 'C' in ambiguity code.

#define AMBIGUITY_FLAGBIT_G   0x4

Bit flag for 'G' in ambiguity code.

#define AMBIGUITY_FLAGBIT_T   0x8

Bit flag for 'T' in ambiguity code.

#define AMBIGUITY_FLAGBIT_GAP   0x10

Bit flag for '-' in ambiguity code.

Define Documentation

#define HIGH_QUALITY_THRESHOLD 30

What is considered high quality by ABI.
Default threshold used when highQualityThreshold is 0.
Definition at line 24 of file Slice.h.

#define MAX_QUALITY_VALUE 4000

Quality Value to return when floating point underflows occur.
Effectively, the maximum quality value that can ever occur. Quality Values upto ~3000 can occur, so this has been set at 4000 to indicate that it is higher than all the rest, but there is no way calculate the value exactly without higher precision floats.
Definition at line 39 of file Slice.h.

Function Documentation

char libSlice_calculateAmbiguityFlags ( long double cpA,

long double cpC,

long double cpG,

long double cpT,

long double cpGap,

int highQualityThreshold,

int baseCount

)

Calculates ambiguity flags from Churchill and Waterman procedure.
The procedure has been modified to take as a parameter the maximum number of bases that can be represented by the ambiguity code. This way if only A's and C's were seen in the read a baseCount of 2 can be pased and the ambiguity code will only be one of A,C, or (A || C) = M even if the QV of M does not reach the quality threshold. Set this value to 5 to be compatible with the Churchill and Waterman procedure.
Returns a character of which the 5 lowest bits are used to flag the inclusion of A,C,G,T,-.

Parameters:

cpA Error probability of 'A'

cpC Error probability of 'C'

cpG Error probability of 'G'

cpT Error probability of 'T'

cpGap Error probability of '-'

highQualityThreshold QV Value considered high quality

baseCount Maximum number of bases represented by ambiguity code

Return values:

Ambiguity flags packed into a single character

Definition at line 91 of file getConsQV.c.

char libSlice_convertAmbiguityFlags ( char ambiguityFlags )

Calculates extended ambiguity code bases from ambiguity flags.
Use the five ambiguity flags to find an ambiguity code. Extended ambiguity codes are encoded in lowercase, ie. "A*" = 'a'.

Parameters:

ambiguityFlags Output from calculateAmbiguityFlags

Return values:

Extended Ambiguity Code

Definition at line 173 of file getConsQV.c.

char libSlice_getAmbiguityCode ( long double cpA,

long double cpC,

long double cpG,

long double cpT,

long double cpGap,

int highQualityThreshold,

int baseCount

)

Return IUPAC Ambiguity Code in one operation.
Uses calculateAmbiguityFlags and convertAmbiguityFlags to generate an IUPAC ambiguity code from 5 error probabilities.

Parameters:

cpA Error probability of 'A'

cpC Error probability of 'C'

cpG Error probability of 'G'

cpT Error probability of 'T'

cpGap Error probability of '-'

highQualityThreshold QV Value considered high quality

baseCount Maximum number of bases represented by ambiguity code

Return values:

IUPAC Ambiguity Code

See also:
calculateAmbiguityFlags
convertAmbiguityFlags

Definition at line 229 of file getConsQV.c.

char libSlice_getCompliment ( char base )

Get the compliment to a base or ambiguity code.

Parameters:

base Ambiguity Code/Base to get compliment

Returns:
Compliment of the base (case is preserved)

Definition at line 17 of file utility.c.

int libSlice_getConsensus ( const libSlice_Slice * s,

libSlice_Consensus * result,

const libSlice_BaseDistribution * dist,

int highQualityThreshold

)

Calculates the consensus of a slice with NO ambiguity codes.

Parameters:

s Pointer to a slice.

result Pointer to struct for storing results.

dist Table of distribution of the bases.

highQualityThreshold Threshold for ambiguity codes.

Returns:
errorCode 0 on sucess.

See also:
_getConsensus

Definition at line 788 of file getConsQV.c.

int libSlice_getConsensusParam ( const libSlice_Slice * s,

libSlice_Consensus * result,

const libSlice_BaseDistribution * dist,

int highQualityThreshold,

int doAmbiguity

)

Calculates the consensus quality value for a single slice.
Calculates the consensus and consensus quality values for a slice using Bayes formula and the procedure from Churchill, G.A. and Waterman, M.S. "The accuracy of DNA sequences: Estimating sequence quality." Genomics 14, pp. 89-98 (1992).
Note: If dist is NULL, assumes a normal distribution of {.2,.2,.2,.2,.2} for {A,C,G,T,-}.

Parameters:

s Pointer to a slice.

result Pointer to struct for storing results.

dist Table of distribution of the bases.

highQualityThreshold Threshold for ambiguity codes.

doAmbiguity Flag to calculte ambiguity codes.

Returns:
errorCode 0 on sucess.

Definition at line 280 of file getConsQV.c.

int libSlice_getConsensusRange ( const libSlice_Slice s[],

libSlice_Consensus results[],

int len,

const libSlice_BaseDistribution * dist,

int highQualityThreshold

)

Calculates the consensus of an array of slice with no ambiguity codes.

Parameters:

s Array of slices

results Array of results

len Length of slices (and results)

dist Table of distribution of the bases

highQualityThreshold Threshold for ambiguity codes.

Returns:
errorCode, 0 on sucess

See also:
_getConsensusRange

Definition at line 864 of file getConsQV.c.

int libSlice_getConsensusRangeParam ( const libSlice_Slice s[],

libSlice_Consensus results[],

int len,

const libSlice_BaseDistribution * dist,

int highQualityThreshold,

int doAmbiguity

)

Calculates the Consensus Quality Values for a range of slices.

Parameters:

s Array of slices

results Array of results

len Length of slices (and results)

dist Table of distribution of the bases

highQualityThreshold Threshold for ambiguity codes.

doAmbiguity Flag to calculate ambiguity codes

Returns:
errorCode, 0 on sucess

See also:
_getConsensus

Definition at line 834 of file getConsQV.c.

int libSlice_getConsensusRangeWithAmbiguity ( const libSlice_Slice s[],

libSlice_Consensus results[],

int len,

const libSlice_BaseDistribution * dist,

int highQualityThreshold

)

Calculates the consensus of an array of slice with ambiguity codes.

Parameters:

s Array of slices

results Array of results

len Length of slices (and results)

dist Table of distribution of the bases

highQualityThreshold Threshold for ambiguity codes.

Returns:
errorCode, 0 on sucess

See also:
_getConsensusRange

Definition at line 886 of file getConsQV.c.

int libSlice_getConsensusWithAmbiguity ( const libSlice_Slice * s,

libSlice_Consensus * result,

const libSlice_BaseDistribution * dist,

int highQualityThreshold

)

Calculates the consensus of a slice with ambiguity codes.

Parameters:

s Pointer to a slice.

result Pointer to struct for storing results.

dist Table of distribution of the bases.

highQualityThreshold Threshold for ambiguity codes.

Returns:
errorCode 0 on sucess.

See also:
_getConsensus

Definition at line 806 of file getConsQV.c.

char libSlice_getConsQC ( const libSlice_Slice * s,

int highQualityThreshold

)

Calculates the quality class for a single slice.
Quality classes 1-23 are the same as the quality class definitions from TIGR Assembler. A return value of 0 indicates that an error has occured in calculating the quality class.

Parameters:

s Slice to evaluate

highQualityThreshold Threshold for defining highQuality

Returns:
Quality class of slice

Definition at line 261 of file getConsQC.c.

char* libSlice_getConsQCRange ( const libSlice_Slice s[],

int len,

int highQualityThreshold

)

Calculates the quality classes for a range of slices.

Parameters:

s Array of slices to evaluate quality classes

len Length of array

highQualityThreshold Threshold to use for highQuality

Returns:
Pointer to Null terminated list of quality classes (one for each slice)

See also:
getConsQC

Definition at line 415 of file getConsQC.c.

const char* libSlice_getVersion ( )

Gets a string representing the version of the library.
Creates a string like: "libSlice Version 1.01 (Build: 1.11)"
Note: The value is a pointer to a static buffer, so the value should not be freed.
Definition at line 60 of file utility.c.

void* libSlice_newmem ( int number,

int size

)

Error Checking malloc.
Returns char * to a new block of memory, or prints an error if it couldnt malloc the memory.

Parameters:

number Number of blocks to allocate

size Size of each block to allocate

Returns:
Block of new memory number*size bytes big

Exceptions:

Exits(-1) If it can't malloc memory

Definition at line 24 of file newmem.c.

void libSlice_setRecallEmpty ( int recallEmpty )

Toggles if empty slices should be recalled as gap.
If this is set to true, slices will be recalled as gap. Otherwise, empty slices will be left alone. The probabilities and cqv will be incorrect in either case, but it's pretty meaningless on an empty slice.
Definition at line 259 of file getConsQV.c.

int libSlice_updateAmbiguity ( const libSlice_Slice * s,

libSlice_Consensus * consensus,

int highQuality

)

Updates the ambiguity flags to include all high quality reads.
This is an addition step to support the Annotation UC. Annotation does not utilize the tiling, and only has the consensus available. By adding all high quality conflicts, the resultant consensus will represent all like bases for the slice.

Parameters:

s input slice

consensus libSlice_Consensus to update (only ambiguityFlags)

highQuality Level to consider as high quality

Return values:

0 on sucess, consensus->ambiguityFlags updated.

Definition at line 716 of file getConsQV.c.