001    /*
002     * Copyright (C) 2008-2010 by Holger Arndt
003     *
004     * This file is part of the Universal Java Matrix Package (UJMP).
005     * See the NOTICE file distributed with this work for additional
006     * information regarding copyright ownership and licensing.
007     *
008     * UJMP is free software; you can redistribute it and/or modify
009     * it under the terms of the GNU Lesser General Public License as
010     * published by the Free Software Foundation; either version 2
011     * of the License, or (at your option) any later version.
012     *
013     * UJMP is distributed in the hope that it will be useful,
014     * but WITHOUT ANY WARRANTY; without even the implied warranty of
015     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
016     * GNU Lesser General Public License for more details.
017     *
018     * You should have received a copy of the GNU Lesser General Public
019     * License along with UJMP; if not, write to the
020     * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
021     * Boston, MA  02110-1301  USA
022     */
023    
024    package org.ujmp.core.objectmatrix.calculation;
025    
026    import java.util.Collection;
027    
028    import org.ujmp.core.Matrix;
029    import org.ujmp.core.calculation.Calculation.Ret;
030    import org.ujmp.core.enums.ValueType;
031    import org.ujmp.core.exceptions.MatrixException;
032    
033    public interface ObjectCalculations {
034    
035            public Matrix sortrows(Ret returnType, long column, boolean reverse) throws MatrixException;
036    
037            public Matrix shuffle(Ret returnType) throws MatrixException;
038    
039            public Matrix bootstrap(Ret returnType) throws MatrixException;
040    
041            public Matrix bootstrap(Ret returnType, int count) throws MatrixException;
042    
043            /**
044             * Generates annotation such as row or column labels from the content of
045             * this matrix. This is useful for example for data imported from CSV files
046             * with labels in the first line.
047             * 
048             * @param returnType
049             *            Specify whether to return a new matrix, or a link
050             * @param dimension
051             *            Which axis should be shortened to extract the labels. E.g. if
052             *            you want column labels, you must specify
053             *            <code>Matrix.ROW</code>, which does not seem very intuitive at
054             *            first glance. However, if you're dealing with
055             *            multi-dimensional data, this becomes more clear. If you want
056             *            annotation generated for all dimensions, you can specify
057             *            <code>Matrix.ALL</code> or omit the dimensions parameter.
058             * @return new Matrix with annotation generated from content.
059             * @throws MatrixException
060             */
061            public Matrix extractAnnotation(Ret returnType, int dimension) throws MatrixException;
062    
063            public Matrix includeAnnotation(Ret returnType, int dimension) throws MatrixException;
064    
065            public Matrix reshape(Ret returnType, long... newSize) throws MatrixException;
066    
067            public Matrix squeeze(Ret returnType) throws MatrixException;
068    
069            public Matrix unique(Ret returnType) throws MatrixException;
070    
071            public Matrix uniqueValueCount(Ret returnType, int dimension) throws MatrixException;
072    
073            public Matrix tril(Ret returnType, int k) throws MatrixException;
074    
075            public Matrix triu(Ret returnType, int k) throws MatrixException;
076    
077            public Matrix toColumnVector(Ret returnType) throws MatrixException;
078    
079            public Matrix toRowVector(Ret returnType) throws MatrixException;
080    
081            public Matrix swap(Ret returnType, int dimension, long pos1, long pos2);
082    
083            /**
084             * Returns a matrix with equal size, where all entries are set to a desired
085             * value.
086             * 
087             * @param value
088             *            fill with this value
089             * @return Matrix with ones.
090             */
091            public Matrix fill(Ret ret, Object value) throws MatrixException;
092    
093            /**
094             * Replaces matching values in the matrix with another value
095             * 
096             * @param returnType
097             *            Select whether a new or a linked Matrix is returned, or if the
098             *            operation is performed on the original Matrix
099             * @param search
100             *            Object to search for
101             * @param replacement
102             *            Object used to replace the original value
103             * @return matrix with modified entries
104             * @throws MatrixException
105             */
106            public Matrix replace(Ret returnType, Object search, Object replacement) throws MatrixException;
107    
108            /**
109             * Returns the transpose of the Matrix, where rows and columns are
110             * exchanged. This works also if the Matrix has more than two dimensions.
111             * 
112             * @return transposed Matrix.
113             */
114            public Matrix transpose() throws MatrixException;
115    
116            /**
117             * Returns the transpose of the Matrix, where rows and columns are
118             * exchanged. This works also if the Matrix has more than two dimensions.
119             * 
120             * @param returnType
121             *            Defines if a new Matrix or a link should be returned.
122             * @return transposed Matrix.
123             */
124            public Matrix transpose(Ret returnType) throws MatrixException;
125    
126            public Matrix transpose(Ret returnType, int dimension1, int dimension2) throws MatrixException;
127    
128            public Matrix flipdim(Ret returnType, int dimension);
129    
130            /**
131             * @deprecated Please do not use this method anymore, it will be removed.
132             *             use <code>matrix.clone()</code> instead
133             */
134            public Matrix copy() throws MatrixException;
135    
136            /**
137             * Creates a copy of the matrix with the desired type for matrix entries.
138             * 
139             * @param newValueType
140             *            defines the new format of the matrix
141             * @return Matrix with the same entries in the new format
142             */
143            public Matrix convert(ValueType newValueType) throws MatrixException;
144    
145            /**
146             * Selects rows and columns in the Matrix and returns a link to it.
147             * 
148             * @param returnType
149             *            Defines if a new Matrix or a link should be returned.
150             * @param selection
151             *            selected rows and columns
152             * @return Link to original Matrix with desired rows and columns
153             * @throws MatrixException
154             */
155            public Matrix select(Ret returnType, long[]... selection) throws MatrixException;
156    
157            /**
158             * Delete rows and columns in the Matrix and returns a link to it.
159             * 
160             * @param returnType
161             *            Defines if a new Matrix or a link should be returned.
162             * @param selection
163             *            selected rows and columns
164             * @return Link to original Matrix with desired rows and columns
165             * @throws MatrixException
166             */
167            public Matrix delete(Ret returnType, long[]... selection) throws MatrixException;
168    
169            /**
170             * Selects rows and columns in the Matrix and returns a link to it.
171             * 
172             * @param returnType
173             *            Defines if a new Matrix or a link should be returned.
174             * @param selection
175             *            selected rows and columns
176             * @return Link to original Matrix with desired rows and columns
177             * @throws MatrixException
178             */
179            public Matrix select(Ret returnType, Collection<? extends Number>... selection)
180                            throws MatrixException;
181    
182            /**
183             * Delete rows and columns in the Matrix and returns a link to it.
184             * 
185             * @param returnType
186             *            Defines if a new Matrix or a link should be returned.
187             * @param selection
188             *            selected rows and columns
189             * @return Link to original Matrix with desired rows and columns
190             * @throws MatrixException
191             */
192            public Matrix delete(Ret returnType, Collection<? extends Number>... selection)
193                            throws MatrixException;
194    
195            /**
196             * Selects rows in the Matrix and returns a link to it.
197             * 
198             * @param returnType
199             *            Defines if a new Matrix or a link should be returned.
200             * @param rows
201             *            selected rows
202             * @return Link to original Matrix with desired rows
203             * @throws MatrixException
204             */
205            public Matrix selectRows(Ret returnType, long... rows) throws MatrixException;
206    
207            /**
208             * Deletes rows in the Matrix and returns a link to it.
209             * 
210             * @param returnType
211             *            Defines if a new Matrix or a link should be returned.
212             * @param rows
213             *            selected rows
214             * @return Link to original Matrix with desired rows
215             * @throws MatrixException
216             */
217            public Matrix deleteRows(Ret returnType, long... rows) throws MatrixException;
218    
219            /**
220             * Selects rows in the Matrix and returns a link to it.
221             * 
222             * @param returnType
223             *            Defines if a new Matrix or a link should be returned.
224             * @param rows
225             *            selected rows
226             * @return Link to original Matrix with desired rows
227             * @throws MatrixException
228             */
229            public Matrix selectRows(Ret returnType, Collection<? extends Number> rows)
230                            throws MatrixException;
231    
232            /**
233             * Deletes rows in the Matrix and returns a link to it.
234             * 
235             * @param returnType
236             *            Defines if a new Matrix or a link should be returned.
237             * @param rows
238             *            selected rows
239             * @return Link to original Matrix with desired rows
240             * @throws MatrixException
241             */
242            public Matrix deleteRows(Ret returnType, Collection<? extends Number> rows)
243                            throws MatrixException;
244    
245            /**
246             * Selects columns in the Matrix and returns a link to it.
247             * 
248             * @param returnType
249             *            Defines if a new Matrix or a link should be returned.
250             * @param columns
251             *            selected columns
252             * @return Link to original Matrix with desired columns
253             * @throws MatrixException
254             */
255            public Matrix selectColumns(Ret returnType, long... colums) throws MatrixException;
256    
257            /**
258             * Deletes columns in the Matrix and returns a link to it.
259             * 
260             * @param returnType
261             *            Defines if a new Matrix or a link should be returned.
262             * @param columns
263             *            selected columns
264             * @return Link to original Matrix with desired columns
265             * @throws MatrixException
266             */
267            public Matrix deleteColumns(Ret returnType, long... colums) throws MatrixException;
268    
269            /**
270             * Selects columns in the Matrix and returns a link to it.
271             * 
272             * @param returnType
273             *            Defines if a new Matrix or a link should be returned.
274             * @param columns
275             *            selected columns
276             * @return Link to original Matrix with desired columns
277             * @throws MatrixException
278             */
279            public Matrix selectColumns(Ret returnType, Collection<? extends Number> columns)
280                            throws MatrixException;
281    
282            /**
283             * Deletes columns in the Matrix and returns a link to it.
284             * 
285             * @param returnType
286             *            Defines if a new Matrix or a link should be returned.
287             * @param columns
288             *            selected columns
289             * @return Link to original Matrix with desired columns
290             * @throws MatrixException
291             */
292            public Matrix deleteColumns(Ret returnType, Collection<? extends Number> columns)
293                            throws MatrixException;
294    
295            /**
296             * Selects rows and columns in the Matrix and returns a link to it.
297             * Selections can be made in Matlab/Octave style or similar, e.g.
298             * "1,2,5-6,8:5;*". Dimensions are separated by ';'. Selections in one
299             * dimension are separated by spaces or ','. Ranges are selected using '-'
300             * or ':'. A whole dimension can be selected with '*'.
301             * 
302             * @param returnType
303             *            Defines if a new Matrix or a link should be returned.
304             * @param selection
305             *            String defining the selection
306             * @return Link to original Matrix with desired rows and columns
307             * @throws MatrixException
308             */
309            public Matrix select(Ret returnType, String selection) throws MatrixException;
310    
311            /**
312             * Deletes rows and columns in the Matrix and returns a link to it.
313             * Selections can be made in Matlab/Octave style or similar, e.g.
314             * "1,2,5-6,8:5;*". Dimensions are separated by ';'. Selections in one
315             * dimension are separated by spaces or ','. Ranges are selected using '-'
316             * or ':'. A whole dimension can be selected with '*'.
317             * 
318             * 
319             * @param returnType
320             *            Defines if a new Matrix or a link should be returned.
321             * @param selection
322             *            String defining the selection
323             * @return Link to original Matrix with desired rows and columns deleted
324             * @throws MatrixException
325             */
326            public Matrix delete(Ret returnType, String selection) throws MatrixException;
327    
328            public Matrix subMatrix(Ret returnType, long startRow, long startColumn, long endRow,
329                            long endColumn) throws MatrixException;
330    
331    }