    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
    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
    039         * @return Item in given position as an object
    040         */
    041        public Object getObject(final int... pos);
    042
    043        /**
    044         * @param pos
    045         * @return Item in given position as a string
    046         */
    047        public String getString(final int... pos);
    048
    049        /**
    050         * @param pos
    051         * @return Item in given position as a double
    052         */
    053        public double getDouble(final int... pos);
    054
    055        /**
    056         * @param pos
    057         * @return Item in given position as a long
    058         */
    059        public long getLong(final int... pos);
    060
    061        /**
    062         * @param pos
    063         * @return Item in given position as a float
    064         */
    065        public float getFloat(final int... pos);
    066
    067        /**
    068         * @param pos
    069         * @return Item in given position as an int
    070         */
    071        public int getInt(final int... pos);
    072
    073        /**
    074         * @param pos
    075         * @return Item in given position as a short
    076         */
    077        public short getShort(final int... pos);
    078
    079        /**
    080         * @param pos
    081         * @return Item in given position as a byte
    082         */
    083        public byte getByte(final int... pos);
    084
    085        /**
    086         * @param pos
    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
    094         * @param pos
    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
    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         */
    110        public IDataset squeeze();
    111
    112        /**
    113         * Remove dimensions of 1 in shape of the dataset from ends only if true
    114         *
    115         * @param onlyFromEnds
    116         */
    117        public IDataset squeeze(boolean onlyFromEnds);
    118
    119        /**
    120         * @param ignoreInvalids - Can be null, empty, or one or more booleans. By default, all booleans
    121         * are false. If the first boolean is true, will ignore NaNs and ignore infinities. Use the second
    122         * boolean to ignore infinities separately.
    123         * @return Maximum value
    124         * @throws UnsupportedOperationException if comparisons are not valid
    125         */
    126        public Number max(boolean... ignoreInvalids);
    127
    128        /**
    129         * @param ignoreInvalids - see {@link #max(boolean...)}
    130         * @return mean of all items in dataset as a double, array of doubles or a complex number
    131         */
    132        public Object mean(boolean... ignoreInvalids);
    133
    134        /**
    135         * @param ignoreInvalids - see {@link #max(boolean...)}
    136         * @return Minimum value
    137         * @throws UnsupportedOperationException if comparisons are not valid
    138         */
    139        public Number min(boolean... ignoreInvalids);
    140
    141        /**
    142         * @param ignoreInvalids - see {@link #max(boolean...)}
    143         * @return Position of minimum value (or first position if there are more than one)
    144         * @since 2.0
    145         */
    146        public int[] minPos(boolean... ignoreInvalids);
    147
    148        /**
    149         * @param ignoreInvalids - see {@link #max(boolean...)}
    150         * @return Position of maximum value (or first position if there are more than one)
    151         * @since 2.0
    152         */
    153        public int[] maxPos(boolean... ignoreInvalids);
    154
    155        /**
    156         * Clone dataset, making new copy of data
    157         * @return a (deep) copy of dataset
    158         */
    159        @Override
    160        public IDataset clone();
    161
    162        /**
    163         * @deprecated Use {@code getFirstMetadata(IMetadata.class)} instead
    164         * @return an instance of IMetadata, may be null
    165         */
    166        @Override
    167        @Deprecated
    168        public IMetadata getMetadata();
    169
    170        @Override
    171        public IDataset getSlice(int[] start, int[] stop, int[] step);
    172
    173        @Override
    174        public IDataset getSlice(Slice... slice);
    175
    176        @Override
    177        public IDataset getSlice(SliceND slice);
    178
    179
    180        /**
    181         * Get a slice of the dataset. The returned dataset is a view on a selection of items
    182         *
    183         * @param start
    184         *            specifies the starting indexes (can be null for origin)
    185         * @param stop
    186         *            specifies the stopping indexes (can be null for end)
    187         * @param step
    188         *            specifies the steps in the slice (can be null for unit steps)
    189         * @return The sliced view of a dataset
    190         */
    191        @Override
    192        public IDataset getSliceView(int[] start, int[] stop, int[] step);
    193
    194        /**
    195         * Get a slice of the dataset. The returned dataset is a view on a selection of items
    196         *
    197         * @param slice an array of slice objects (the array can be null or contain nulls)
    198         * @return The sliced view of a dataset
    199         */
    200        @Override
    201        public IDataset getSliceView(Slice... slice);
    202
    203        /**
    204         * Get a slice of the dataset. The returned dataset is a view on a selection of items
    205         *
    206         * @param slice an nD slice object
    207         * @return The sliced view of a dataset
    208         */
    209        @Override
    210        public IDataset getSliceView(SliceND slice);
    211
    212        /**
    213         * Permute copy of dataset's axes so that given order is old order:
    214         *
    215         * <pre>{@literal
    216         *  axisPerm = (p(0), p(1),...) => newdata(n(0), n(1),...) = olddata(o(0), o(1), ...)
    217         *  such that n(i) = o(p(i)) for all i
    218         * }</pre>
    219         *
    220         * I.e. for a 3D dataset (1,0,2) implies the new dataset has its 1st dimension running along
    221         * the old dataset's 2nd dimension and the new 2nd is the old 1st. The 3rd dimension is left
    222         * unchanged.
    223         *
    224         * @param axes
    225         *            if zero length then axes order reversed
    226         * @return remapped view of data
    227         */
    228        @Override
    229        IDataset getTransposedView(int... axes);
    230
    231        /**
    232         *
    233         * @return the error dataset, constructing one if necessary
    234         * @since 2.0
    235         */
    236        @Override
    237        public IDataset getErrors();
    238
    239        /**
    240         * Get the error for a given position.
    241         * @param pos
    242         * @return error value (symmetric)
    243         */
    244        public double getError(int... pos);
    245
    246        /**
    247         * Get the error values for a single point in the dataset
    248         * @param pos of the point to be referenced
    249         * @return the values of the error at this point (can be null when no error defined)
    250         */
    251        public double[] getErrorArray(int... pos);
    252}