    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}