    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}