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. Can be null when interface is not defined
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 to set
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         * @return this
072         */
073        public ILazyDataset squeezeEnds();
074
075        /**
076         * Get a slice of the dataset. The returned dataset is a copied selection of items
077         * 
078         * @param start
079         *            specifies the starting indexes (can be null for origin)
080         * @param stop
081         *            specifies the stopping indexes (can be null for end)
082         * @param step
083         *            specifies the steps in the slice (can be null for unit steps)
084         * @return The dataset of the sliced data
085         * @throws DatasetException when cannot retrieve slice of lazy dataset
086         */
087        public IDataset getSlice(final int[] start, final int[] stop, final int[] step) throws DatasetException;
088
089        /**
090         * Get a slice of the dataset. The returned dataset is a copied selection of items
091         * 
092         * @param monitor can be null
093         * @param start
094         *            specifies the starting indexes (can be null for origin)
095         * @param stop
096         *            specifies the stopping indexes (can be null for end)
097         * @param step
098         *            specifies the steps in the slice (can be null for unit steps)
099         * @return The dataset of the sliced data
100         * @throws DatasetException when cannot retrieve slice of lazy dataset
101         */
102        public IDataset getSlice(final IMonitor monitor, final int[] start, final int[] stop,
103                        final int[] step) throws DatasetException;
104
105        /**
106         * Get a slice of the dataset. The returned dataset is a copied selection of items
107         * 
108         * @param slice an array of slice objects (the array can be null or contain nulls)
109         * @return The dataset of the sliced data
110         * @throws DatasetException when cannot retrieve slice of lazy dataset
111         */
112        public IDataset getSlice(final Slice... slice) throws DatasetException;
113
114        /**
115         * Get a slice of the dataset. The returned dataset is a copied selection of items
116         * 
117         * @param monitor can be null
118         * @param slice an array of slice objects (the array can be null or contain nulls)
119         * @return The dataset of the sliced data
120         * @throws DatasetException when cannot retrieve slice of lazy dataset
121         */
122        public IDataset getSlice(final IMonitor monitor, final Slice... slice) throws DatasetException;
123
124        /**
125         * Get a slice of the dataset. The returned dataset is a copied selection of items
126         * 
127         * @param slice an n-D slice
128         * @return The dataset of the sliced data
129         * @throws DatasetException when cannot retrieve slice of lazy dataset
130         */
131        public IDataset getSlice(final SliceND slice) throws DatasetException;
132
133        /**
134         * Get a slice of the dataset. The returned dataset is a copied selection of items
135         * 
136         * @param monitor can be null
137         * @param slice an n-D slice
138         * @return The dataset of the sliced data
139         * @throws DatasetException when cannot retrieve slice of lazy dataset
140         */
141        public IDataset getSlice(final IMonitor monitor, final SliceND slice) throws DatasetException;
142
143        /**
144         * Get a slice of the dataset. The returned lazy dataset is a view on a selection of items
145         * 
146         * @param start
147         *            specifies the starting indexes (can be null for origin)
148         * @param stop
149         *            specifies the stopping indexes (can be null for end)
150         * @param step
151         *            specifies the steps in the slice (can be null for unit steps)
152         * @return The sliced view of a lazy dataset 
153         */
154        public ILazyDataset getSliceView(final int[] start, final int[] stop, final int[] step);
155
156        /**
157         * Get a slice of the dataset. The returned lazy dataset is a view on a selection of items
158         * 
159         * @param slice an array of slice objects (the array can be null or contain nulls)
160         * @return The sliced view of a lazy dataset
161         */
162        public ILazyDataset getSliceView(final Slice... slice);
163
164        /**
165         * Get a slice of the dataset. The returned lazy dataset is a view on a selection of items
166         * 
167         * @param slice an n-D slice
168         * @return The sliced view of a lazy dataset
169         */
170        public ILazyDataset getSliceView(final SliceND slice);
171
172        /**
173         * Permute copy of dataset's axes so that given order is old order:
174         * 
175         * <pre>{@literal
176         *  axisPerm = (p(0), p(1),...) => newdata(n(0), n(1),...) = olddata(o(0), o(1), ...)
177         *  such that n(i) = o(p(i)) for all i
178         * }</pre>
179         * 
180         * I.e. for a 3D dataset (1,0,2) implies the new dataset has its 1st dimension running along
181         * the old dataset's 2nd dimension and the new 2nd is the old 1st. The 3rd dimension is left
182         * unchanged.
183         * 
184         * @param axes
185         *            if zero length then axes order reversed
186         * @return remapped view of data
187         */
188        public ILazyDataset getTransposedView(int... axes);
189
190        /**
191         * Add metadata to the dataset
192         * 
193         * @param metadata to add
194         */
195        public void addMetadata(final MetadataType metadata);
196
197        /**
198         * Set metadata on the dataset
199         * 
200         * @param metadata (null is ignored so use clear(null) instead)
201         */
202        public void setMetadata(MetadataType metadata);
203
204        /**
205         * Remove metadata of given class
206         * @param clazz if null remove everything
207         */
208        public void clearMetadata(Class<? extends MetadataType> clazz);
209
210        /**
211         * Clone dataset
212         * @return a (shallow) copy of dataset
213         */
214        public ILazyDataset clone();
215
216        /**
217         * Set the errors. It may be a single double, a double array or a
218         * whole dataset that can broadcast to the dataset
219         * 
220         * @param errors - may be null to remove the error set
221         * @throws RuntimeException if the rank or shape are incorrect
222         * @since 2.0
223         */
224        public void setErrors(Serializable errors);
225
226        /**
227         * Get the errors, if any. These will be in a shape that can broadcast to the dataset
228         * @return errors
229         * @since 2.0
230         */
231        public ILazyDataset getErrors();
232
233        /**
234         * If error information is set, returns true.
235         * Faster to call than getError() which constructs a
236         * new dataset.
237         * 
238         * @return true if there is error data.
239         */
240        public boolean hasErrors();
241}