#import <AdunDataMatrix.h>

Inheritance diagram for AdDataMatrix:

Public Member Functions
(id)	- initWithStringRepresentation:
(id)	- initWithStringRepresentation:name:
(id)	- initWithGSLVector:columnHeaders:name:
(id)	- initWithGSLMatrix:columnHeaders:name:
(id)	- initWithADMatrix:columnHeaders:name:
(id)	- initWithDataMatrix:columnHeaders:name:
(id)	- initWithRows:columnHeaders:name:
(id)	- initWithRows:name:
(id)	- initWithRows:columnHeaders:
(id)	- initWithRows:
(id)	- init
(id)	- elementAtRow:column:
(id)	- elementAtRow:ofColumnWithHeader:
(NSArray *)	- row:
(NSArray *)	- column:
(void)	- addRow:toArray:
(void)	- addColumn:toArray:
(AdMatrix *)	- cRepresentation
(BOOL)	- compareCRepresentations:
(void)	- cRepresentationUsingBuffer:
(NSEnumerator *)	- rowEnumerator
(NSArray *)	- columnWithHeader:
(void)	- addColumnWithHeader:toArray:
(NSArray *)	- matrixRows
(unsigned int)	- numberOfRows
(unsigned int)	- numberOfColumns
(NSArray *)	- columnHeaders
(id)	- headerForColumn:
(unsigned int)	- indexOfColumnWithHeader:
(NSArray *)	- columnDataTypes
(NSString *)	- dataTypeForColumn:
(NSString *)	- dataTypeForColumnWithHeader:
(NSString *)	- name
(void)	- printMatrix
(BOOL)	- writeMatrixToFile:
(NSString *)	- stringRepresentation
(NSIndexSet *)	- indexesOfRowsContainingElement:
(NSIndexSet *)	- indexesOfRowsMatchingArray:
(void)	- setKeyColumn:
(int)	- keyColumnIndex
(NSArray *)	- keys
(NSArray *)	- rowsForKey:
(NSIndexSet *)	- rowIndexesForKey:
(AdDataMatrix *)	- submatrixFromRowSelection:
(AdDataMatrix *)	- submatrixFromColumnSelection:
(AdDataMatrix *)	- submatrixWithRowRange:
(AdDataMatrix *)	- submatrixWithColumnRange:

Static Public Member Functions
(id)	+ matrixFromADMatrix:
(id)	+ matrixFromGSLMatrix:
(id)	+ matrixFromGSLVector:
(id)	+ matrixFromStringRepresentation:

Detailed Description

Contains a matrix of values. AdDataMatrix is primarily a convenient way to represent heterogenous matrix (tabular) data as an object to facititate transport and transparent access. It conforms to the NSCoding protocol and allows both keyed and non-keyed coding. It also conforms to the NSCopying and NSMutableCopying protocols.

An instance of AdDataMatrix is a immutable: you establish its entries when it's created and cannot modify them afterward. Using the AdDataMatrix subclass AdMutableDataMatrix you can add or delete entries etc.

Each column of the matrix can hold one type of data as determined by the data type assigned to the column. Each data type is assiociated with a class and data is stored as an object of the appropriate class (or a subclass of that class).

The following table indicates the current data types and the corresponding classes - Subclasses of these data types are also stored.

string NSString
double NSDoubleNumber
int NSIntNumber

For AdDataMatrix objects the column data types are set on intialisation.

Note:: AdDataMatrix indexes rows and columns starting with 0 i.e. the first element is (0,0).; AdDataMatrix is not performanced optimised and should not be used where heavy access is required to the matrix elements i.e. for computations use the AdunBase library C structures or the gsl_matrix type.

Todo:

Internal - Examine changing internal matrix representation to optimise performance.

Extra Methods - writeToFile: and initWithContentsOfFile:

Optimise decoding

Add support for NSBoolNumber

Member Function Documentation

- (void) addColumn:	(unsigned int)	columnIndex
toArray:	(NSMutableArray*)	anArray

Adds the elements in column columnIndex to anArray.

- (void) addColumnWithHeader:	(NSString*)	columnHeader
toArray:	(NSMutableArray*)	anArray

Like columnWithHeader: excepts adds the elements to anArray instead of returning an NSArray object.

- (void) addRow:	(unsigned int)	rowIndex
toArray:	(NSMutableArray*)	anArray

Adds the elements in row rowIndex to anArray.

- (NSArray *) column: (unsigned int) columnIndex

Returns a copy of column number columnIndex

- (NSArray*) columnDataTypes

An array containing the data types that can be held in each column. See class description for more.

- (NSArray*) columnHeaders

Returns an array of columnHeaders. If no specific headers have been set using setColumnHeaders: then an array containing the default titles is returned i.e. (Column1, Column2 ...).

- (NSArray *) columnWithHeader: (NSString*) columnHeader

Returns a copy of the column with header columnWithHeader. If columnHeader matches more than one column the one with the lowest index is returned. If the given column header does not exist an NSInvalidArgumentException is raised.

- (BOOL) compareCRepresentations: (AdDataMatrix*) aMatrix

Compares the c representation of the receiver with that of aMatrix using AdCompareDoubleMatrices() with a tolerance of 1E-12.

- (AdMatrix *) cRepresentation

Returns the matrix contents as an AdMatrix struct. i.e. a C matrix of doubles. The caller owns the returned structure as is responsible for deallocating it (using freeMatrix: (AdMemoryManager) method)

- (void) cRepresentationUsingBuffer: (AdMatrix*) aMatrix

Places the matrix contents in the buffer aMatrix. aMatrix must have the correct dimensions. If not an NSInvalidArgumentException is raised.

- (NSString *) dataTypeForColumn: (unsigned int) columnIndex

Returns the data type associated with columnIndex. If no data type has been assigned returns nil. If columnIndex does not exist NSInvalidArgumentException is raised.

- (NSString *) dataTypeForColumnWithHeader: (NSString*) columnHeader

Returns the data type associated with the column with header columnHeader. If columnHeader matches more than one column the data type of the one with the lowest index is returned. If no data type has been assigned returns nil. If columnIndex does not exist NSInvalidArgumentException is raised.

- (id) elementAtRow:	(unsigned int)	row
column:	(unsigned int)	column

Returns the value of the element at (row, column). If the given column or row does not exist an NSInvalidArgumentException is raised.

Parameters:

row	The row number
column	The column number

Returns:: The value of the element

- (id) elementAtRow:	(unsigned int)	row
ofColumnWithHeader:	(NSString*)	columnHeader

Returns the value of the element at row of the column identified by columnHeader to value. If more than one column has the same header the first column is used. If the given column header or row does not exist an NSInvalidArgumentException is raised.

Parameters:

row	The row number
columnHeader	The header of the column to be accessed.

Returns:: The value of the element

- (id) headerForColumn: (unsigned int) index

Returns the header for column index. Raises an NSRangeException if index is greater than or equal to the number of columns in the receiver.

- (NSIndexSet *) indexesOfRowsContainingElement: (id) element

Returns an NSIndexSet containing the indexes of rows containing element

- (NSIndexSet *) indexesOfRowsMatchingArray: (NSArray*) anArray

Returns an NSIndexSet containing the indexes of rows that match array. A match is found if the array contains the same number of objects as the row and objects at a given index in each array satisfy the isEqual: test.

- (unsigned int) indexOfColumnWithHeader: (NSString*) header

If a column with header exists it returns the index of the first one found. Otherwise returns NSNotFound

- (id) init

As initWithRows: passing nil for matrix.

- (id) initWithADMatrix:	(AdMatrix*)	aMatrix
columnHeaders:	(NSArray*)	anArray
name:	(NSString*)	aString

Returns an AdDataMatrix instance initialised with the values of aMatrix.

- (id) initWithDataMatrix:	(AdDataMatrix*)	matrix
columnHeaders:	(NSArray*)	anArray
name:	(NSString*)	aString

Creates a AdDataMatrix from the data in matrix. If matrix is nil the values of headers and name resulting object will be an immutable AdDataMatrix containing no data with name "None". If headers is nil the are headers of matrix are used.

Parameters:

matrix	An AdDataMatrix instance.
headers	Array containing the headers for each column.
name	A NSString specifying the name of the matrix. If nil the name defaults to . the name of the AdDataMatrix.

Returns:: An initialised AdDataMatrix instance.

- (id) initWithGSLMatrix:	(gsl_matrix*)	aMatrix
columnHeaders:	(NSArray*)	anArray
name:	(NSString*)	aString

Returns an AdDataMatrix instance initialised with the values of aMatrix.

- (id) initWithGSLVector:	(gsl_vector*)	aVector
columnHeaders:	(NSArray*)	anArray
name:	(NSString*)	aString

Returns an AdDataMatrix instance initialised with the values of aVector

- (id) initWithRows: (NSArray*) matrix

As initWithRows:columnHeaders:name passing nil for both aString and anArray.

- (id) initWithRows:	(NSArray*)	rows
columnHeaders:	(NSArray*)	anArray

As initWithRows:columnHeaders:name passing nil for aString

- (id) initWithRows:	(NSArray*)	rows
columnHeaders:	(NSArray*)	anArray
name:	(NSString*)	aString

Designated initialiser. Creates an AdDataMatrix from the arrays in rows. Each entry in rows must be an NSArray and contain the same number of elements. headers is an array of strings which are the headers for each of the columns. There must be one entry for each column.

Parameters:

rows	An NSArray of NSArrays.
headers	Array containing the headers for each column.
name	A NSString specifying the name of the matrix.

Returns:: An initialised AdDataMatrix instance.

- (id) initWithRows:	(NSArray*)	rows
name:	(NSString*)	aString

As initWithRows:columnHeaders:name passing nil for anArray

- (id) initWithStringRepresentation: (NSString*) aString

As initWithStringRepresentation:name with name set to nil

- (id) initWithStringRepresentation:	(NSString*)	aString
name:	(NSString*)	nameString

Returns an AdDataMatrix instance initialised with aString. aString must be the string representation of a csv file or a string returned by stringRepresentation. Note: If it is the former case than the first line of the csv file will become the column headers.

- (int) keyColumnIndex

Returns the index of the current key column or -1 if no key column has been set

- (NSArray *) keys

Returns an array of the currently used key. The array is empty of no key column has been set

+ (id) matrixFromADMatrix: (AdMatrix*) aMatrix

Returns an autoreleased AdDataMatrix instance initialised with the values of aMatrix

Parameters:

aMatrx An ::AdMatrix struct

Returns:: An autoreleased AdDataMatrix instance

Implemented in AdMutableDataMatrix.

+ (id) matrixFromGSLMatrix: (gsl_matrix*) aMatrix

Returns an autoreleased AdDataMatrix instance initialised with the values of aMatrix

Parameters:

aMatrx A gsl_matrix struct

Returns:: An autoreleased AdDataMatrix instance

Implemented in AdMutableDataMatrix.

+ (id) matrixFromGSLVector: (gsl_vector*) aVector

Returns an autoreleased AdDataMatrix instance initialised with the values of aVector

Parameters:

aMatrx An gsl_vector struct

Returns:: An autoreleased AdDataMatrix instance

Implemented in AdMutableDataMatrix.

+ (id) matrixFromStringRepresentation: (NSString*) aString

Returns an autoreleasesd AdDataMatrix instance initialised with aString. aString must be the string representation of a csv file or a string returned by stringRepresentation. Note: If it is the former case than the first line of the csv file will become the column headers.

- (NSArray *) matrixRows

Returns an array containing the rows of the matrix (the underlying matrix representation).

Note:: This method is deprecated. Use rowEnumerator to enumerate the matrix rows or access them via row:.

- (NSString*) name

Returns the name of the data matrix

- (unsigned int) numberOfColumns

Returns the number of columns

- (unsigned int) numberOfRows

Returns the number of rows

- (void) printMatrix

Uses NSLog to print the data matrix to stderr. Useful for debugging.

- (NSArray *) row: (unsigned int) rowIndex

Returns a copy of row number rowIndex

- (NSEnumerator *) rowEnumerator

Returns an enumerator over the matrix rows. Each row is an NSMutableArray object

- (NSIndexSet *) rowIndexesForKey: (id) key

Returns the indexes of all rows in the receiver which contain the value key in the current key-column. Returns nil if no rows contain key or if no key column has been set.

- (NSArray *) rowsForKey: (id) key

Retreives all rows which contain the value key in the current key-column. Returns nil if no rows contain key or if no key column has been set.

- (void) setKeyColumn: (NSString*) columnHeader

Hashes the rows in the receiver according the values in the column with header columnHeader. Rows can then quickly retrieved using rowsForKey:. Raises an NSInvalidArgumentException of columnHeader is not valid

- (NSString *) stringRepresentation

Returns a string containing a csv representation of the matrix

- (AdDataMatrix *) submatrixFromColumnSelection: (NSIndexSet*) indexSet

Returns a new AdDataMatrix instance containing only the columns specified by the indexes in indexSet. The column headers are also copied and the returned matrix has the same name as the receiver. If any index in indexSet is exceeds the range of columns in the receiver an NSRangeException is raised.

- (AdDataMatrix *) submatrixFromRowSelection: (NSIndexSet*) indexSet

Returns a new AdDataMatrix instance containing only the rows specified by the indexes in indexSet. The submatrix has the same headers and name as the receiver. If any index in indexSet exceeds the range of rows in the reciever an NSRangeException is raised.

- (AdDataMatrix *) submatrixWithColumnRange: (NSRange) range

Returns a new AdDataMatrix instance containing data from the columns in range The column headers are also copied and the returned matrix has the same name as the receiver. If range exceeds the range of columns in the matrix an NSRangeException is raised.

- (AdDataMatrix *) submatrixWithRowRange: (NSRange) range

Returns a new AdDataMatrix instance containing only the rows in range The submatrix has the same headers and name as the receiver. If range exceeds the range of rows in the matrix an NSRangeException is raised.

- (BOOL) writeMatrixToFile: (NSString*) filename

Writes a plain text representation of the data matrix to a file.

Note:: Deprecated - use stringRepresentation instead

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation