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 to output
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 position
039         * @return Item in given position as an object
040         */
041        public Object getObject(final int... pos);
042
043        /**
044         * @param pos position
045         * @return Item in given position as a string
046         */
047        public String getString(final int... pos);
048
049        /**
050         * @param pos position
051         * @return Item in given position as a double
052         */
053        public double getDouble(final int... pos);
054
055        /**
056         * @param pos position
057         * @return Item in given position as a long
058         */
059        public long getLong(final int... pos);
060
061        /**
062         * @param pos position
063         * @return Item in given position as a float
064         */
065        public float getFloat(final int... pos);
066
067        /**
068         * @param pos position
069         * @return Item in given position as an int
070         */
071        public int getInt(final int... pos);
072
073        /**
074         * @param pos position
075         * @return Item in given position as a short
076         */
077        public short getShort(final int... pos);
078
079        /**
080         * @param pos position
081         * @return Item in given position as a byte
082         */
083        public byte getByte(final int... pos);
084
085        /**
086         * @param pos position
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 value to set
094         * @param pos position
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 to use
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         * @return this
110         */
111        public IDataset squeeze();
112
113        /**
114         * Remove dimensions of 1 in shape of the dataset from ends only if true
115         * 
116         * @param onlyFromEnds if true, trim ends
117         * @return this
118         */
119        public IDataset squeeze(boolean onlyFromEnds);
120
121        /**
122         * @param ignoreInvalids - Can be null, empty, or one or more booleans. By default, all booleans
123         * are false. If the first boolean is true, will ignore NaNs and ignore infinities. Use the second
124         * boolean to ignore infinities separately.
125         * @return Maximum value
126         * @throws UnsupportedOperationException if comparisons are not valid
127         */
128        public Number max(boolean... ignoreInvalids);
129
130        /**
131         * @param ignoreInvalids - see {@link #max(boolean...)}
132         * @return mean of all items in dataset as a double, array of doubles or a complex number
133         */
134        public Object mean(boolean... ignoreInvalids);
135
136        /**
137         * @param ignoreInvalids - see {@link #max(boolean...)}
138         * @return Minimum value
139         * @throws UnsupportedOperationException if comparisons are not valid
140         */
141        public Number min(boolean... ignoreInvalids);
142
143        /**
144         * @param ignoreInvalids - see {@link #max(boolean...)}
145         * @return Position of minimum value (or first position if there are more than one)
146         * @since 2.0
147         */
148        public int[] minPos(boolean... ignoreInvalids);
149
150        /**
151         * @param ignoreInvalids - see {@link #max(boolean...)}
152         * @return Position of maximum value (or first position if there are more than one)
153         * @since 2.0
154         */
155        public int[] maxPos(boolean... ignoreInvalids);
156
157        /**
158         * Clone dataset, making new copy of data
159         * @return a (deep) copy of dataset
160         */
161        @Override
162        public IDataset clone();
163
164        /**
165         * @deprecated Use {@code getFirstMetadata(IMetadata.class)} instead
166         * @return an instance of IMetadata, may be null
167         */
168        @Override
169        @Deprecated
170        public IMetadata getMetadata();
171
172        @Override
173        public IDataset getSlice(int[] start, int[] stop, int[] step);
174
175        @Override
176        public IDataset getSlice(Slice... slice);
177
178        @Override
179        public IDataset getSlice(SliceND slice);
180
181        
182        /**
183         * Get a slice of the dataset. The returned dataset is a view on a selection of items
184         * 
185         * @param start
186         *            specifies the starting indexes (can be null for origin)
187         * @param stop
188         *            specifies the stopping indexes (can be null for end)
189         * @param step
190         *            specifies the steps in the slice (can be null for unit steps)
191         * @return The sliced view of a dataset
192         */
193        @Override
194        public IDataset getSliceView(int[] start, int[] stop, int[] step);
195
196        /**
197         * Get a slice of the dataset. The returned dataset is a view on a selection of items
198         * 
199         * @param slice an array of slice objects (the array can be null or contain nulls)
200         * @return The sliced view of a dataset
201         */
202        @Override
203        public IDataset getSliceView(Slice... slice);
204
205        /**
206         * Get a slice of the dataset. The returned dataset is a view on a selection of items
207         * 
208         * @param slice an nD slice object
209         * @return The sliced view of a dataset
210         */
211        @Override
212        public IDataset getSliceView(SliceND slice);
213
214        /**
215         * Permute copy of dataset's axes so that given order is old order:
216         * 
217         * <pre>{@literal
218         *  axisPerm = (p(0), p(1),...) => newdata(n(0), n(1),...) = olddata(o(0), o(1), ...)
219         *  such that n(i) = o(p(i)) for all i
220         * }</pre>
221         * 
222         * I.e. for a 3D dataset (1,0,2) implies the new dataset has its 1st dimension running along
223         * the old dataset's 2nd dimension and the new 2nd is the old 1st. The 3rd dimension is left
224         * unchanged.
225         * 
226         * @param axes
227         *            if zero length then axes order reversed
228         * @return remapped view of data
229         */
230        @Override
231        IDataset getTransposedView(int... axes);
232
233        /**
234         * 
235         * @return the error dataset, constructing one if necessary
236         * @since 2.0
237         */
238        @Override
239        public IDataset getErrors();
240
241        /**
242         * Get the error for a given position.
243         * @param pos position
244         * @return error value (symmetric)
245         */
246        public double getError(int... pos);
247
248        /**
249         * Get the error values for a single point in the dataset
250         * @param pos position
251         * @return the values of the error at this point (can be null when no error defined)
252         */
253        public double[] getErrorArray(int... pos);
254}