    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>{@literal
    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}