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.io.Serializable;
016
017import org.eclipse.january.DatasetException;
018import org.eclipse.january.IMonitor;
019import org.eclipse.january.INameable;
020import org.eclipse.january.metadata.MetadataType;
021
022/**
023 * This interface defines the lazy parts of a dataset. A dataset is a N-dimensional array of items
024 * where N can be zero to represent a zero-rank or single-valued dataset. A zero-rank dataset has
025 * an empty array for shape. An item comprises a number of elements.
026 */
027public interface ILazyDataset extends Serializable, IMetadataProvider, INameable {
028                
029        /**
030         * @return Boxed class of element
031         */
032        public Class<?> getElementClass();
033
034        /**
035         * @return Number of elements per item
036         */
037        public int getElementsPerItem();
038
039        /**
040         * The size of the dataset is the number of items in the array
041         * 
042         * @return number of data items
043         */
044        public int getSize();
045
046        /**
047         * The shape (or array of lengths for each dimension) of the dataset can be empty for zero-rank
048         * datasets
049         * 
050         * @return Copy of shape of dataset
051         */
052        public int[] getShape();
053
054        /**
055         * Set a compatible shape for dataset. A shape is compatible if it has the capacity to contain
056         * the same number of items
057         * 
058         * @param shape
059         */
060        public void setShape(final int... shape);
061
062        /**
063         * The rank (or number of dimensions/indices) of the dataset can be zero for a zero-rank
064         * (single-valued) dataset 
065         * @return rank
066         */
067        public int getRank();
068
069        /**
070         * Remove dimensions of 1 from ends of shape of the dataset
071         */
072        public ILazyDataset squeezeEnds();
073
074        /**
075         * Get a slice of the dataset. The returned dataset is a copied selection of items
076         * 
077         * @param start
078         *            specifies the starting indexes (can be null for origin)
079         * @param stop
080         *            specifies the stopping indexes (can be null for end)
081         * @param step
082         *            specifies the steps in the slice (can be null for unit steps)
083         * @return The dataset of the sliced data
084         * @throws DatasetException
085         */
086        public IDataset getSlice(final int[] start, final int[] stop, final int[] step) throws DatasetException;
087
088        /**
089         * Get a slice of the dataset. The returned dataset is a copied selection of items
090         * 
091         * @param monitor
092         * @param start
093         *            specifies the starting indexes (can be null for origin)
094         * @param stop
095         *            specifies the stopping indexes (can be null for end)
096         * @param step
097         *            specifies the steps in the slice (can be null for unit steps)
098         * @return The dataset of the sliced data
099         * @throws DatasetException
100         */
101        public IDataset getSlice(final IMonitor monitor, final int[] start, final int[] stop,
102                        final int[] step) throws DatasetException;
103
104        /**
105         * Get a slice of the dataset. The returned dataset is a copied selection of items
106         * 
107         * @param slice an array of slice objects (the array can be null or contain nulls)
108         * @return The dataset of the sliced data
109         * @throws DatasetException
110         */
111        public IDataset getSlice(final Slice... slice) throws DatasetException;
112
113        /**
114         * Get a slice of the dataset. The returned dataset is a copied selection of items
115         * 
116         * @param monitor
117         * @param slice an array of slice objects (the array can be null or contain nulls)
118         * @return The dataset of the sliced data
119         * @throws DatasetException
120         */
121        public IDataset getSlice(final IMonitor monitor, final Slice... slice) throws DatasetException;
122
123        /**
124         * Get a slice of the dataset. The returned dataset is a copied selection of items
125         * 
126         * @param slice an n-D slice
127         * @return The dataset of the sliced data
128         * @throws DatasetException
129         */
130        public IDataset getSlice(final SliceND slice) throws DatasetException;
131
132        /**
133         * Get a slice of the dataset. The returned dataset is a copied selection of items
134         * 
135         * @param monitor
136         * @param slice an n-D slice
137         * @return The dataset of the sliced data
138         * @throws DatasetException
139         */
140        public IDataset getSlice(final IMonitor monitor, final SliceND slice) throws DatasetException;
141
142        /**
143         * Get a slice of the dataset. The returned lazy dataset is a view on a selection of items
144         * 
145         * @param start
146         *            specifies the starting indexes (can be null for origin)
147         * @param stop
148         *            specifies the stopping indexes (can be null for end)
149         * @param step
150         *            specifies the steps in the slice (can be null for unit steps)
151         * @return The sliced view of a lazy dataset 
152         */
153        public ILazyDataset getSliceView(final int[] start, final int[] stop, final int[] step);
154
155        /**
156         * Get a slice of the dataset. The returned lazy dataset is a view on a selection of items
157         * 
158         * @param slice an array of slice objects (the array can be null or contain nulls)
159         * @return The sliced view of a lazy dataset
160         */
161        public ILazyDataset getSliceView(final Slice... slice);
162
163        /**
164         * Get a slice of the dataset. The returned lazy dataset is a view on a selection of items
165         * 
166         * @param slice an n-D slice
167         * @return The sliced view of a lazy dataset
168         */
169        public ILazyDataset getSliceView(final SliceND slice);
170
171        /**
172         * Permute copy of dataset's axes so that given order is old order:
173         * 
174         * <pre>
175         *  axisPerm = (p(0), p(1),...) => newdata(n(0), n(1),...) = olddata(o(0), o(1), ...)
176         *  such that n(i) = o(p(i)) for all i
177         * </pre>
178         * 
179         * I.e. for a 3D dataset (1,0,2) implies the new dataset has its 1st dimension running along
180         * the old dataset's 2nd dimension and the new 2nd is the old 1st. The 3rd dimension is left
181         * unchanged.
182         * 
183         * @param axes
184         *            if zero length then axes order reversed
185         * @return remapped view of data
186         */
187        public ILazyDataset getTransposedView(int... axes);
188
189        /**
190         * Add metadata to the dataset
191         * 
192         * @param metadata
193         */
194        public void addMetadata(final MetadataType metadata);
195
196        /**
197         * Set metadata on the dataset
198         * 
199         * @param metadata (null is ignored so use clear(null) instead)
200         */
201        public void setMetadata(MetadataType metadata);
202
203        /**
204         * Remove metadata of given class
205         * @param clazz if null remove everything
206         */
207        public void clearMetadata(Class<? extends MetadataType> clazz);
208
209        /**
210         * Clone dataset
211         * @return a (shallow) copy of dataset
212         */
213        public ILazyDataset clone();
214
215        /**
216         * Set the errors. It may be a single double, a double array or a
217         * whole dataset that can broadcast to the dataset
218         * 
219         * @param errors - may be null to remove the error set
220         * @throws RuntimeException if the rank or shape are incorrect
221         * @since 2.0
222         */
223        public void setErrors(Serializable errors);
224
225        /**
226         * Get the errors, if any. These will be in a shape that can broadcast to the dataset
227         * @since 2.0
228         */
229        public ILazyDataset getErrors();
230
231        /**
232         * If error information is set, returns true.
233         * Faster to call than getError() which constructs a
234         * new dataset.
235         * 
236         * @return true if there is error data.
237         */
238        public boolean hasErrors();
239}