001 /**
002 * Copyright 2009-2010 by The Broad Institute.
003 *
004
005 */
006 package org.broadinstitute.genee.matrix;
007
008 import java.util.Collection;
009
010 /**
011 * The interface for a dataset consisting of a two-dimensional matrix of float
012 * values. A dataset may also optionally contain one or more series of
013 * two-dimensional matrices. A dataset also has metadata associated with each
014 * row and column.
015 */
016 public interface Dataset {
017 /**
018 * Returns the number of columns in the dataset.
019 *
020 * @return the number of columns
021 */
022 public int getColumnCount();
023
024 /**
025 * Gets the column metadata for this dataset.
026 *
027 * @return The column metadata
028 */
029 public MetadataModel getColumnMetadata();
030
031 /**
032 * Returns the name of this dataset.
033 *
034 * @return The dataset name
035 */
036 public String getName();
037
038 /**
039 * Returns the value at the given row and column for the given series.
040 * Series can be used to store standard error of data points for example.
041 *
042 * @param rowIndex
043 * the row index
044 * @param columnIndex
045 * the column index
046 * @param seriesIndex
047 * the series index
048 * @return the value
049 * @throws IndexOutOfBoundsException
050 * if <tt>rowIndex</tt> or <tt>columnIndex</tt> are out of
051 * range.
052 */
053 public Object getObjectValue(int rowIndex, int columnIndex, int seriesIndex);
054
055 /**
056 * Returns the value to which the specified key is mapped, or <tt>null</tt>
057 * if this dataset does not contain the specified property.
058 *
059 * @param key
060 * the key
061 * @return the value the value for the specified key
062 */
063 public Object getProperty(Object key);
064
065 /**
066 * Returns a collection of all the property keys contained in this dataset.
067 *
068 * @return the property keys
069 */
070 public Collection<Object> getPropertyKeys();
071
072 /**
073 * Returns the number of rows in the dataset.
074 *
075 * @return the number of rows
076 */
077 public int getRowCount();
078
079 /**
080 * Gets the row metadata for this dataset.
081 *
082 * @return the row metadata
083 */
084 public MetadataModel getRowMetadata();
085
086 /**
087 * Returns the most specific superclass for all the values in the series.
088 *
089 * @param series
090 * the index of the series
091 * @return the common ancestor class of the series values
092 */
093 public Class<?> getSeriesClass(int series);
094
095 /**
096 * Returns the number of matrix series, which is always at least 1 (the
097 * dataset itself). Series can be used to store standard error of data
098 * points for example.
099 *
100 * @return the number of series
101 */
102 public int getSeriesCount();
103
104 /**
105 * Returns the name for the given series. Series can be used to store
106 * standard error of data points for example.
107 *
108 * @param series
109 * the series
110 * @return the data series name
111 * @throws IndexOutOfBoundsException
112 * if <tt>series</tt> is out of range
113 * <tt>(index < 0 || index >=
114 * getSeriesCount())</tt>
115 */
116 public String getSeriesName(int series);
117
118 /**
119 * Returns the value at the given row and column.
120 *
121 * @param rowIndex
122 * the row index.
123 * @param columnIndex
124 * the column index.
125 * @return the value.
126 * @throws IndexOutOfBoundsException
127 * if <tt>rowIndex</tt> or <tt>columnIndex</tt> are out of
128 * range.
129 */
130 public float getValue(int rowIndex, int columnIndex);
131
132 /**
133 * Returns the value at the given row and column for the given series as a
134 * float. Series can be used to store standard error of data points for
135 * example.
136 *
137 * @param rowIndex
138 * the row index
139 * @param columnIndex
140 * the column index
141 * @param seriesIndex
142 * the series index
143 * @return the value
144 * @throws IndexOutOfBoundsException
145 * if <tt>rowIndex</tt> or <tt>columnIndex</tt> are out of range
146 */
147 public float getValue(int rowIndex, int columnIndex, int seriesIndex);
148
149 /**
150 * Sets the name of this dataset.
151 *
152 * @throws UnsupportedOperationException
153 * if the <tt>setName</tt> operation is not supported by this
154 * Dataset
155 *
156 * @param name
157 * The dataset name
158 */
159 public void setName(String name);
160
161 /**
162 * Sets the property for the specified key.
163 *
164 * @param key
165 * the key
166 * @param value
167 * the value
168 */
169 public void setProperty(Object key, Object value);
170
171 /**
172 * Sets the value at the given row and column indices.
173 *
174 * @param rowIndex
175 * the row index
176 *
177 * @param columnIndex
178 * the column index
179 * @param value
180 * the value
181 * @throws UnsupportedOperationException
182 * if the <tt>setValue</tt> operation is not supported by this
183 * Dataset
184 */
185 public void setValue(int rowIndex, int columnIndex, float value);
186
187 }