    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 &lt; 0 || index &gt;=
    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    }