001/*-
002 *******************************************************************************
003 * Copyright (c) 2011, 2016 Diamond Light Source Ltd.
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the Eclipse Public License v1.0
006 * which accompanies this distribution, and is available at
007 * http://www.eclipse.org/legal/epl-v10.html
008 *
009 * Contributors:
010 *    Peter Chang - initial API and implementation and/or initial documentation
011 *******************************************************************************/
012
013package org.eclipse.january.dataset;
014
015import java.text.Format;
016
017import org.eclipse.january.metadata.IMetadata;
018
019
020/**
021 * This interface defines the implementation-independent and generic parts of a dataset.
022 * <p>
023 * The position array used in the getters
024 */
025public interface IDataset extends ILazyDataset {
026        /**
027         * Set string output format
028         * @param format
029         */
030        public void setStringFormat(Format format);
031
032        /**
033         * @return Size of an item in dataset in bytes
034         */
035        public int getItemBytes();
036
037        /**
038         * @param pos
039         * @return Item in given position as an object
040         */
041        public Object getObject(final int... pos);
042
043        /**
044         * @param pos
045         * @return Item in given position as a string
046         */
047        public String getString(final int... pos);
048
049        /**
050         * @param pos
051         * @return Item in given position as a double
052         */
053        public double getDouble(final int... pos);
054
055        /**
056         * @param pos
057         * @return Item in given position as a long
058         */
059        public long getLong(final int... pos);
060
061        /**
062         * @param pos
063         * @return Item in given position as a float
064         */
065        public float getFloat(final int... pos);
066
067        /**
068         * @param pos
069         * @return Item in given position as an int
070         */
071        public int getInt(final int... pos);
072
073        /**
074         * @param pos
075         * @return Item in given position as a short
076         */
077        public short getShort(final int... pos);
078
079        /**
080         * @param pos
081         * @return Item in given position as a byte
082         */
083        public byte getByte(final int... pos);
084
085        /**
086         * @param pos
087         * @return Item in given position as a boolean
088         */
089        public boolean getBoolean(final int... pos);
090
091        /**
092         * Set the value given by object at given position
093         * @param obj
094         * @param pos
095         */
096        public void set(final Object obj, final int... pos);
097
098        /**
099         * Change shape and size of dataset in-place
100         * @param newShape
101         */
102        public void resize(int... newShape);
103
104        @Override
105        public IDataset squeezeEnds();
106
107        /**
108         * Remove dimensions of 1 in shape of the dataset
109         */
110        public IDataset squeeze();
111
112        /**
113         * Remove dimensions of 1 in shape of the dataset from ends only if true
114         * 
115         * @param onlyFromEnds
116         */
117        public IDataset squeeze(boolean onlyFromEnds);
118
119        /**
120         * @param ignoreInvalids - Can be null, empty, or one or more booleans. By default, all booleans
121         * are false. If the first boolean is true, will ignore NaNs and ignore infinities. Use the second
122         * boolean to ignore infinities separately.
123         * @return Maximum value
124         * @throws UnsupportedOperationException if comparisons are not valid
125         */
126        public Number max(boolean... ignoreInvalids);
127
128        /**
129         * @param ignoreInvalids - see {@link #max(boolean...)}
130         * @return mean of all items in dataset as a double, array of doubles or a complex number
131         */
132        public Object mean(boolean... ignoreInvalids);
133
134        /**
135         * @param ignoreInvalids - see {@link #max(boolean...)}
136         * @return Minimum value
137         * @throws UnsupportedOperationException if comparisons are not valid
138         */
139        public Number min(boolean... ignoreInvalids);
140
141        /**
142         * @param ignoreInvalids - see {@link #max(boolean...)}
143         * @return Position of minimum value (or first position if there are more than one)
144         * @since 2.0
145         */
146        public int[] minPos(boolean... ignoreInvalids);
147
148        /**
149         * @param ignoreInvalids - see {@link #max(boolean...)}
150         * @return Position of maximum value (or first position if there are more than one)
151         * @since 2.0
152         */
153        public int[] maxPos(boolean... ignoreInvalids);
154
155        /**
156         * Clone dataset, making new copy of data
157         * @return a (deep) copy of dataset
158         */
159        @Override
160        public IDataset clone();
161
162        /**
163         * @deprecated Use {@code getFirstMetadata(IMetadata.class)} instead
164         * @return an instance of IMetadata, may be null
165         */
166        @Override
167        @Deprecated
168        public IMetadata getMetadata();
169
170        @Override
171        public IDataset getSlice(int[] start, int[] stop, int[] step);
172
173        @Override
174        public IDataset getSlice(Slice... slice);
175
176        @Override
177        public IDataset getSlice(SliceND slice);
178
179        
180        /**
181         * Get a slice of the dataset. The returned dataset is a view on a selection of items
182         * 
183         * @param start
184         *            specifies the starting indexes (can be null for origin)
185         * @param stop
186         *            specifies the stopping indexes (can be null for end)
187         * @param step
188         *            specifies the steps in the slice (can be null for unit steps)
189         * @return The sliced view of a dataset
190         */
191        @Override
192        public IDataset getSliceView(int[] start, int[] stop, int[] step);
193
194        /**
195         * Get a slice of the dataset. The returned dataset is a view on a selection of items
196         * 
197         * @param slice an array of slice objects (the array can be null or contain nulls)
198         * @return The sliced view of a dataset
199         */
200        @Override
201        public IDataset getSliceView(Slice... slice);
202
203        /**
204         * Get a slice of the dataset. The returned dataset is a view on a selection of items
205         * 
206         * @param slice an nD slice object
207         * @return The sliced view of a dataset
208         */
209        @Override
210        public IDataset getSliceView(SliceND slice);
211
212        /**
213         * Permute copy of dataset's axes so that given order is old order:
214         * 
215         * <pre>{@literal
216         *  axisPerm = (p(0), p(1),...) => newdata(n(0), n(1),...) = olddata(o(0), o(1), ...)
217         *  such that n(i) = o(p(i)) for all i
218         * }</pre>
219         * 
220         * I.e. for a 3D dataset (1,0,2) implies the new dataset has its 1st dimension running along
221         * the old dataset's 2nd dimension and the new 2nd is the old 1st. The 3rd dimension is left
222         * unchanged.
223         * 
224         * @param axes
225         *            if zero length then axes order reversed
226         * @return remapped view of data
227         */
228        @Override
229        IDataset getTransposedView(int... axes);
230
231        /**
232         * 
233         * @return the error dataset, constructing one if necessary
234         * @since 2.0
235         */
236        @Override
237        public IDataset getErrors();
238
239        /**
240         * Get the error for a given position.
241         * @param pos
242         * @return error value (symmetric)
243         */
244        public double getError(int... pos);
245
246        /**
247         * Get the error values for a single point in the dataset
248         * @param pos of the point to be referenced 
249         * @return the values of the error at this point (can be null when no error defined)
250         */
251        public double[] getErrorArray(int... pos);
252}