Affymetrix - Developer's Network- IGDACCELFile Interface


		IGDACCELFile

OVERVIEW

The IGDACCELFile interface provides read-only access to cell intensity (CEL) files. The CEL file contains only intensity information for a given probe on an array. Background information, masking, outliers, probe base, target base information available in the probe objects are not available from the CEL file.

Note: new interfaces have been added to support faster data access. These are the GetIntensity(), GetPixels(), GetStdv(), IsOutlier() and IsOutlier() methods.

COM ATTRIBUTES

Attribute	Type/Supported
Threading model	Both
Interface	Dual
Aggregation	No
ISupportErrorInfo	Yes
Connection Points	No
Free Threading Marshaler	No

PROPERTIES

Name

ID
1

Description
The name of the CEL file without directory path. This value must be set prior to reading the CEL file.

Type BSTR

Length 64 characters including file extension.

Access Read-Write

Remarks It accepts any valid short file name with no path specified (e.g. Hu6800.CEL). If path is specified when setting the Name property, a COM error will be returned. However, the DataPath property must be set to identify the exact location (i.e. full path) of the cell intensity file.
Returns error if setting invalid file name characters: \/:;*?"<>|'`,{}[]
Returns error if file name is not with ".CEL" extension.

DataPath

ID
2

Description
The directory where the CEL files are stored.

Type BSTR

Access Read-Write

Remarks
Must be set prior to using the interface methods.
Returns error if setting invalid path characters: /;*?<>|'`,{}[]
The format of the data path, when reading data stored in a LIMS/GCOS server system, must be \\SERVERNAME\gclims\data where SERVERNAME is the name of the LIMS or GCOS server.

LibPath

ID
3

Description
The directory where the the library files (CDF) are stored.

Type BSTR

Access Read-Write

Remarks
Must be set prior to using the interface methods.
Returns error if setting invalid path characters: /;*?<>|'`,{}[]
The format of the library path, when reading data stored in a LIMS/GCOS server system, must be \\SERVERNAME\gclims\library where SERVERNAME is the name of the LIMS or GCOS server.

FullPathName

ID
4

Description The full path file name for the cell intensity file.

Type BSTR

Access Read-only

Remarks Read() must be called prior to use.

ChipType

ID
5

Description The probe array type associated with the cell intensity file.

Type BSTR

Access Read-only

Remarks Read() must be called prior to use. Returns an empty string if the cell file has not been read.

Date

ID
6

Description The probe array type associated with the cell intensity file.

Type BSTR

Format MMM DD YYYY HH:MM:SS AM/PM

Access Read-only

Remarks Read() must be called prior to use. Returns an empty string if the cell file has not been read.

FileVersion

ID
7

Description The file version of the cell intensity file

Type long

Access Read-only

Remarks Read() must be called prior to use. Returns 0 if the cell file has not been read.

Algorithm

ID
8

Description The algorithm used to create the CEL file. The MAS 5 software uses the percentile algorithm for generating CEL files.

Type BSTR

Access Read-only

Remarks Read() must be called prior to use. Returns an empty string if the cell file has not been read.

NumAlgParams

ID
9

Description The number of algorithm parameters

Type long

Access Read-only

Remarks Read() must be called prior to use. Returns 0 if the cell file has not been read.

AlgParams

ID
10

Description The algorithm parameters used to create the CEL file. This property is a string of the format TAG=VALUE, where multiple parameters are whitespace delimited.

Type BSTR

Access Read-only

Remarks Read() must be called prior to use. Returns an empty string if the cell file has not been read.

CellMargin

ID
11

Description The number of pixels on the border of each probe feature that are excluded when calculating the intensity value.

Type long

Access Read-only

Remarks Read() must be called prior to use. Returns 0 if the cell file has not been read.

Rows

ID
12

Description This is the number of features in the y direction of the array.

Type long

Access Read-only

Remarks Read() must be called prior to use. Returns 0 if the cell file has not been read.

Cols

ID
13

Description This is the number of features in the x direction of the array.

Type long

Access Read-only

Remarks Read() must be called prior to use. Returns 0 if the cell file has not been read.

NumMasked

ID
14

Description The number of probe features that have been "masked".

Type long

Access Read-only

Remarks Read() must be called prior to use. Returns 0 if the cell file has not been read.

NumOutliers

ID
15

Description The number of probe features that have been called an "outlier" by the MAS software.

Type long

Access Read-only

Remarks Read() must be called prior to use. Returns 0 if the cell file has not been read.

NumProbes

ID
16

Description The total number of probe features on the array (rows * cols)

Type long

Access Read-only

Remarks Read() must be called prior to use. Returns 0 if the cell file has not been read.

UpperLeftX

ID
17

Description The upper-left x-position of the grid corner of the cell file.

Type long

Access Read-only

Remarks Read() must be called prior to use. Returns 0 if the cell file has not been read.

UpperLeftY

ID
18

Description The upper-left y-position of the grid corner of the cell file.

Type long

Access Read-only

Remarks Read() must be called prior to use. Returns 0 if the cell file has not been read.

UpperRightX

ID
19

Description The upper-right x-position of the grid corner of the cell file.

Type long

Access Read-only

Remarks Read() must be called prior to use. Returns 0 if the cell file has not been read.

UpperRightY

ID
20

Description The upper-right y-position of the grid corner of the cell file.

Type long

Access Read-only

Remarks Read() must be called prior to use. Returns 0 if the cell file has not been read.

LowerLeftX

ID
21

Description The lower-left x-position of the grid corner of the cell file.

Type long

Access Read-only

Remarks Read() must be called prior to use. Returns 0 if the cell file has not been read.

LowerLeftY

ID
22

Description The lower-left y-position of the grid corner of the cell file.

Type long

Access Read-only

Remarks Read() must be called prior to use. Returns 0 if the cell file has not been read.

LowerRightX

ID
23

Description The lower-right x-position of the grid corner of the cell file.

Type long

Access Read-only

Remarks Read() must be called prior to use. Returns 0 if the cell file has not been read.

LowerRightY

ID
24

Description The lower-right y-position of the grid corner of the cell file.

Type long

Access Read-only

Remarks Read() must be called prior to use. Returns 0 if the cell file has not been read.

ServerName

ID
25

Description The name of the LIMS server if the data resides on a LIMS system. This value should be blank if the data is not stored within a LIMS system.

Type BSTR

Access Read-Write

Remarks This property must be set in LIMS Mode.

NTUserName

ID
26

Description This value is not used by the SDK.

Type BSTR

Access Read-only

Remarks This value is not used by the SDK.

DatHeader

ID
41

Description Returns the DatHeader value stored in the file header.

Type BSTR

Access Read-only

Remarks
Read() or ReadHeader() must be called prior to use.

METHODS

Exists

ID
27

Description This function returns a flag indicating if the CEL file exists within the specified data directory.

Prototype HRESULT Exists(BOOL *pbExists)

Parameters BOOL *pbExists - Flag indicating existence (output)

Return HRESULT - S_OK if successful, E_FAIL otherwise

Remarks The Name and DataPath properties are required.

Read

ID
28

Description This function reads the cell intensity file, including the header.

Prototype HRESULT Read( )

Parameters N/A

Return HRESULT - S_OK if successful, E_FAIL otherwise

Remarks
The Name, DataPath and LibPath properties are required.
This method will return an error if the assay type of the cell file is not expression

ReadHeader

ID
29

Description Reads the header of the CEL file into memory. Reading the header will populate all of the properties of this class (Rows, Cols, ChipType, etc.)

Prototype HRESULT ReadHeader( )

Parameters N/A

Return HRESULT - S_OK if successful, E_FAIL otherwise

Remarks
The Name, DataPath and LibPath properties are required.
This method will return an error if the assay type of the cell file is not expression

GetAlgParam

ID
30

Description This function returns one of the algorithm parameters used to calculate the CEL file. The return value consists of the name of the parameter and its associated value.

Prototype HRESULT GetAlgParam(long nIndex, BSTR *pParam, BSTR *pValue)

Parameters
long nIndex - Algorithm parameter index. It is 0-based and must be between 0 and NumAlgParams (input)
BSTR *pParam - A pointer to the parameter name. (output)
BSTR *pValue - A pointer to the parameter value. (output)

Return HRESULT - S_OK if successful, E_FAIL otherwise

Remarks Read() must be called prior to use. The algorithm parameters will be returned as empty strings if the cell file header has not been read.

GetAlgParams

ID
31

Description This function returns all of the algorithm parameters used to calculate the CEL file. The return value consists of the name of the parameter and its associated value.

Prototype HRESULT GetAlgParams(SAFEARRAY(BSTR)* ppsaParams, SAFEARRAY(BSTR)* ppsaValues)

Parameters
lSAFEARRAY(BSTR)* ppsaParams - A pointer to a pointer of safe array of the parameter name. (output)
SAFEARRAY(BSTR) *ppsaValues - A pointer to a pointer of safe array of the parameter value. (output)

The sizes of the two safe arrays should be the same.

Return HRESULT - S_OK if successful, E_POINTER is either ppsaParams or ppsaValues is NULL or E_FAIL otherwise

Remarks
ReadHeader() must be called prior to use. The safearays will be empty if the cell file header has not been read

GetProbeByIndex

ID
32

Description This function gets the cell entry associated with the cell intensity file by index.

Prototype HRESULT GetProbeByIndex(long nIndex, IGDACProbe *iProbe)

Parameters
long nIndex - The index of the cell entry (input) It must be in between 0 and the number of probes (i.e. NumProbes).
IGDACProbe *iProbe - IGDACProbe object (input/output).

Return HRESULT - S_OK if successful, E_POINTER if iProbe is NULL or E_FAIL otherwise

Remarks
Read() must be called prior to use. The contents of the IGDACProbe object will be reset if the cell file has not been read.
The user has to create the IGDACProbe object instance before passing into the method.

GetProbeByPosition

ID
33

Description This function gets the cell entry associated with the cell intensity file by (x,y) position.

Prototype HRESULT GetProbeByIndex(long x, long y, IGDACProbe *iProbe)

Parameters
long x - The x-coordinate of the cell entry (input) It must be in between 0 and the number of columns of the cell file (i.e. Cols).
long y - The y-coordinate of the cell entry (input) It must be in between 0 and the number of rows of the cell file (i.e. Rows).
IGDACProbe *iProbe - IGDACProbe object (input/output).

Return HRESULT - S_OK if successful, E_POINTER if iProbe is NULL or E_FAIL otherwise

Remarks
Read() must be called prior to use. The contents of the IGDACProbe object will be reset if the cell file has not been read.
The user has to create the IGDACProbe object instance before passing into the method.

GetProbes

ID
34

Description This function returns all probes in the cell file

Prototype HRESULT GetProbes(VARIANT *iProbes)

Parameters
VARIANT *iProbes - _variant_t pointer to objects (input/output)

Return HRESULT - S_OK if successful or E_FAIL otherwise

Remarks
Read() must be called prior to use. The variant will be returned empty (i.e. VT_EMPTY) if the cell file has not been read.
This method will create IGDACProbe object instance for each probe and add it to the _variant_t array. The user can use the NumProbes to get the total number of probes available and iterate the variant array. It is required to destroy each IGDACProbe object after used.

ConvertToVersion3

ID
35

Description This function converts CEL files to the older ASCII format.

Prototype HRESULT ConvertToVersion3()

Parameters
None

Return HRESULT - S_OK if successful or E_FAIL otherwise

Remarks
Read() must be called prior to use.

GetIntensity

ID
36

Description Returns the intensity value at the given coordinate.

Prototype HRESULT GetIntensity([in] long x, [in] long y, [out, retval] float *intensity)

Parameters
long x - The x coordinate
long y - The y coordinate
float *intensity - The intensity value at the specified coordinate.

Return HRESULT - S_OK if successful or E_FAIL otherwise

Remarks
Read() must be called prior to use. This method is provided as a faster method to access probe level data vs. retrieving a IGDACProbe object.

GetStdv

ID
37

Description Returns the stdv value at the given coordinate.

Prototype HRESULT GetStdv([in] long x, [in] long y, [out, retval] float *stdv);

Parameters
long x - The x coordinate
long y - The y coordinate
float *stdv - The stdv value at the specified coordinate.

Return HRESULT - S_OK if successful or E_FAIL otherwise

Remarks
Read() must be called prior to use. This method is provided as a faster method to access probe level data vs. retrieving a IGDACProbe object.

GetPixels

ID
38

Description Returns the pixel count at the given coordinate.

Prototype HRESULT GetPixels([in] long x, [in] long y, [out, retval] long *pixels);

Parameters
long x - The x coordinate
long y - The y coordinate
long *pixels - The number of pixels at the specified coordinate.

Return HRESULT - S_OK if successful or E_FAIL otherwise

Remarks
Read() must be called prior to use. This method is provided as a faster method to access probe level data vs. retrieving a IGDACProbe object.

IsOutlier

ID
39

Description Returns the outlier flag at the given coordinate.

Prototype HRESULT IsOutlier([in] long x, [in] long y, [out, retval] BOOL *outlier);

Parameters
long x - The x coordinate
long y - The y coordinate
BOOL *outlier - The outlier flag at the specified coordinate.

Return HRESULT - S_OK if successful or E_FAIL otherwise

Remarks
Read() must be called prior to use. This method is provided as a faster method to access probe level data vs. retrieving a IGDACProbe object.

IsMasked

ID
40

Description Returns the masked flag at the given coordinate.

Prototype HRESULT IsMasked([in] long x, [in] long y, [out, retval] BOOL *masked);

Parameters
long x - The x coordinate
long y - The y coordinate
BOOL *masked - The masked flag at the specified coordinate.

Return HRESULT - S_OK if successful or E_FAIL otherwise

Remarks
Read() must be called prior to use. This method is provided as a faster method to access probe level data vs. retrieving a IGDACProbe object.