    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.IMonitor;
    018
    019/**
    020 * <p>
    021 * Interface for our implementation of dataset that adds a lot of extra functionality.
    022 * </p>
    023 * <p>
    024 * <b>Warning:</b>
    025 * It is important to note that methods (get*Abs() and set*Abs()) which use the absolute
    026 * index <em>must</em> be used with care. In (sliced) views of datasets, neighbouring
    027 * positions do not necessarily correspond to contiguous indexes. This is also the case
    028 * with multi-element (or compound) items. Therefore index iterators should be used in
    029 * conjunction with these methods unless the dataset can be proven to be not a view or
    030 * be a wholly contiguous slice of a dataset; a copy or new dataset satisfies this criterion.
    031 * </p>
    032 */
    033public interface Dataset extends IDataset {
    034        /**
    035         * Boolean
    036         */
    037        public static final int BOOL = 0;
    038
    039        /**
    040         * Signed 8-bit integer
    041         */
    042        public static final int INT8 = 1;
    043
    044        /**
    045         * Signed 16-bit integer
    046         */
    047        public static final int INT16 = 2;
    048
    049        /**
    050         * Signed 32-bit integer
    051         */
    052        public static final int INT32 = 3;
    053        /**
    054         * Integer (same as signed 32-bit integer)
    055         */
    056        public static final int INT = INT32;
    057
    058        /**
    059         * Signed 64-bit integer
    060         */
    061        public static final int INT64 = 4;
    062
    063        /**
    064         * 32-bit floating point
    065         */
    066        public static final int FLOAT32 = 5;
    067
    068        /**
    069         * 64-bit floating point
    070         */
    071        public static final int FLOAT64 = 6;
    072
    073        /**
    074         * Floating point (same as 64-bit floating point)
    075         */
    076        public static final int FLOAT = FLOAT64;
    077
    078        /**
    079         * 64-bit complex floating point (real and imaginary parts are 32-bit floats)
    080         */
    081        public static final int COMPLEX64 = 7;
    082
    083        /**
    084         * 128-bit complex floating point (real and imaginary parts are 64-bit floats)
    085         */
    086        public static final int COMPLEX128 = 8;
    087
    088        /**
    089         * Complex floating point (same as 64-bit floating point)
    090         */
    091        public static final int COMPLEX = COMPLEX128;
    092
    093        /**
    094         * String
    095         */
    096        public static final int STRING = 9;
    097
    098        /**
    099         * Object
    100         */
    101        public static final int OBJECT = 10;
    102
    103        /**
    104         * Date
    105         */
    106        public static final int DATE = 11;
    107
    108        static final int ARRAYMUL = 100;
    109
    110        /**
    111         * Array of signed 8-bit integers
    112         */
    113        public static final int ARRAYINT8 = ARRAYMUL * INT8;
    114
    115        /**
    116         * Array of signed 16-bit integers
    117         */
    118        public static final int ARRAYINT16 = ARRAYMUL * INT16;
    119
    120        /**
    121         * Array of three signed 16-bit integers for RGB values
    122         */
    123        public static final int RGB = ARRAYINT16 + 3;
    124
    125        /**
    126         * Array of signed 32-bit integers
    127         */
    128        public static final int ARRAYINT32 = ARRAYMUL * INT32;
    129
    130        /**
    131         * Array of signed 64-bit integers
    132         */
    133        public static final int ARRAYINT64 = ARRAYMUL * INT64;
    134
    135        /**
    136         * Array of 32-bit floating points
    137         */
    138        public static final int ARRAYFLOAT32 = ARRAYMUL * FLOAT32;
    139
    140        /**
    141         * Array of 64-bit floating points
    142         */
    143        public static final int ARRAYFLOAT64 = ARRAYMUL * FLOAT64;
    144
    145        /**
    146         * Update this when there are any serious changes to API
    147         */
    148        static final long serialVersionUID = -6891075135217265625L;
    149
    150        /**
    151         * The shape (or array of lengths for each dimension) of the dataset can be empty for zero-rank
    152         * datasets and null for null datasets
    153         *
    154         * @return reference of shape of dataset
    155         */
    156        public int[] getShapeRef();
    157
    158        /**
    159         * @return type of dataset item
    160         */
    161        public int getDType();
    162
    163        /**
    164         * @return a stride array (can be null)
    165         */
    166        public int[] getStrides();
    167
    168        /**
    169         * @return offset where dataset view begins
    170         */
    171        public int getOffset();
    172
    173        /**
    174         * @return true if dataset has elements which are floating point values
    175         */
    176        public boolean hasFloatingPointElements();
    177
    178        /**
    179         * @return number of bytes used
    180         */
    181        public int getNbytes();
    182
    183        /**
    184         * @return the buffer that backs the dataset
    185         */
    186        public Serializable getBuffer();
    187
    188        /**
    189         * Set the buffer that backs the dataset and its shape
    190         * <p>This is very, very <b>dangerous</b>. Please use carefully
    191         * @param buffer (can be null to leave unchanged)
    192         * @param shape (can be null to leave unchanged)
    193         */
    194        public void overrideInternal(Serializable buffer, int... shape);
    195
    196        /**
    197         * This is a <b>synchronized</b> version of the clone method
    198         *
    199         * @return a copy of dataset
    200         */
    201        public Dataset synchronizedCopy();
    202
    203        /**
    204         * @param deepCopyMetadata if true then deep-copy metadata
    205         * @return whole view of dataset (i.e. data buffer is shared)
    206         */
    207        public Dataset getView(boolean deepCopyMetadata);
    208
    209        /**
    210         * @param shape
    211         * @return view of dataset that is broadcasted to given shape
    212         */
    213        public Dataset getBroadcastView(int... shape);
    214
    215        /**
    216         * @param showData
    217         * @return string representation
    218         */
    219        public String toString(boolean showData);
    220
    221        @Override
    222        public Dataset squeezeEnds();
    223
    224        @Override
    225        public Dataset squeeze();
    226
    227        @Override
    228        public Dataset squeeze(boolean onlyFromEnds);
    229
    230        @Override
    231        public Dataset clone();
    232
    233        /**
    234         * This method allows anything that dirties the dataset to clear various metadata values
    235         * so that the other methods can work correctly.
    236         */
    237        public void setDirty();
    238
    239        /**
    240         * This method calculates the n-dimensional position in the dataset of
    241         * the given index in the data array
    242         *
    243         * @param n
    244         *            The index in the array
    245         * @return the corresponding [a,b,...,n] position in the dataset
    246         */
    247        public int[] getNDPosition(int n);
    248
    249        /**
    250         * This method calculates the index in the data array that corresponds to
    251         * the given n-dimensional position
    252         *
    253         * @param n
    254         *            the integer array specifying the n-D position
    255         * @return the index on the data array corresponding to that location
    256         */
    257        public int get1DIndex(final int... n);
    258
    259        /**
    260         * Check that axis is in range [-rank,rank)
    261         *
    262         * @param axis
    263         * @return sanitized axis in range [0, rank)
    264         */
    265        public int checkAxis(int axis);
    266
    267        /**
    268         * This method takes a dataset and checks its shape against the current dataset. If they are
    269         * both of the same size, then this returns true otherwise it returns false.
    270         *
    271         * @param g
    272         *            The dataset to be compared
    273         * @return true if shapes are compatible
    274         */
    275        public boolean isCompatibleWith(ILazyDataset g);
    276
    277        /**
    278         * This method takes a dataset and checks its shape against the current dataset. If they are
    279         * both of the same size, then this returns with no error, if there is a problem, then an error
    280         * is thrown.
    281         *
    282         * @param g
    283         *            The dataset to be compared
    284         * @throws IllegalArgumentException
    285         *             This will be thrown if there is a problem with the compatibility
    286         */
    287        public void checkCompatibility(ILazyDataset g) throws IllegalArgumentException;
    288
    289        /**
    290         * Returns new dataset with new shape but old data if possible, otherwise a copy is made
    291         *
    292         * @param shape new shape
    293         * @return reshaped dataset
    294         */
    295        public Dataset reshape(int... shape);
    296
    297        /**
    298         * @return true if dataset is complex
    299         */
    300        public boolean isComplex();
    301
    302        /**
    303         * @return real part of dataset (if necessary, as new dataset)
    304         * @since 2.0
    305         */
    306        public Dataset getRealPart();
    307
    308        /**
    309         * @return real part of dataset as a view
    310         */
    311        public Dataset getRealView();
    312
    313        /**
    314         * Get the error array from the dataset of same shape. This will create a new dataset
    315         * if the error set was of lower rank
    316         *
    317         * @return the dataset which contains the error information (can be null)
    318         * @since 2.0
    319         */
    320        @Override
    321        public Dataset getErrors();
    322
    323        /**
    324         * Get the (un-broadcasted) dataset that backs the (squared) error data
    325         *
    326         * @return the dataset which contains the (squared) error information (can be null)
    327         */
    328        public Dataset getErrorBuffer();
    329
    330        /**
    331         * Set the buffer that backs the (squared) error data
    332         *
    333         * @param buffer the buffer which contains the (squared) error information (can be null)
    334         */
    335        public void setErrorBuffer(Serializable buffer);
    336
    337        /**
    338         * Copy and cast a dataset
    339         *
    340         * @param dtype
    341         *            dataset type
    342         * @return a converted copy of the dataset
    343         * @deprecated Please use class-based method {@link Dataset#copy(Class)}
    344         */
    345        @Deprecated
    346        public Dataset copy(int dtype);
    347
    348        /**
    349         * Copy and cast a dataset
    350         *
    351         * @param <T> dataset subclass
    352         * @param clazz dataset class
    353         * @return a converted copy of the dataset
    354         */
    355        public <T extends Dataset> T copy(Class<T> clazz);
    356
    357        /**
    358         * Cast a dataset
    359         *
    360         * @param dtype
    361         *            dataset type
    362         * @return a converted dataset
    363         * @deprecated Please use class-based method {@link Dataset#cast(Class)}
    364         */
    365        @Deprecated
    366        public Dataset cast(int dtype);
    367
    368        /**
    369         * Cast a dataset
    370         *
    371         * @param <T> dataset subclass
    372         * @param clazz dataset class
    373         * @return a converted dataset
    374         */
    375        public <T extends Dataset> T cast(Class<T> clazz);
    376
    377        /**
    378         * Cast a dataset
    379         *
    380         * @param isize
    381         *            item size
    382         * @param <T> dataset subclass
    383         * @param repeat
    384         * @return a converted dataset
    385         * @since 2.3
    386         */
    387        public <T extends Dataset> T cast(int isize, Class<T> clazz, boolean repeat);
    388
    389        /**
    390         * Cast a dataset
    391         *
    392         * @param repeat
    393         * @param dtype
    394         *            dataset type
    395         * @param isize
    396         *            item size
    397         * @return a converted dataset
    398         * @deprecated Please use class-based method {@link Dataset#cast(int, Class, boolean))}
    399         */
    400        @Deprecated
    401        public Dataset cast(boolean repeat, int dtype, int isize);
    402
    403        /**
    404         * Generate an index dataset for current dataset
    405         *
    406         * @return an index dataset
    407         */
    408        public IntegerDataset getIndices();
    409
    410        @Override
    411        public Dataset getTransposedView(int... axes);
    412
    413        /**
    414         * See {@link #getTransposedView}
    415         * @param axes
    416         * @return remapped copy of data
    417         */
    418        public Dataset transpose(int... axes);
    419
    420        /**
    421         * Swap two axes in dataset
    422         *
    423         * @param axis1
    424         * @param axis2
    425         * @return swapped view of dataset
    426         */
    427        public Dataset swapAxes(int axis1, int axis2);
    428
    429        /**
    430         * Flatten shape
    431         *
    432         * @return a flattened dataset which is a view if dataset is contiguous otherwise is a copy
    433         */
    434        public Dataset flatten();
    435
    436        /**
    437         * Get unique items
    438         * @return a sorted dataset of unique items
    439         */
    440        public Dataset getUniqueItems();
    441
    442        /**
    443         * @param withPosition
    444         *            set true if position is needed
    445         * @return an IndexIterator tailored for this dataset
    446         */
    447        public IndexIterator getIterator(boolean withPosition);
    448
    449        /**
    450         * @return an IndexIterator tailored for this dataset
    451         */
    452        public IndexIterator getIterator();
    453
    454        /**
    455         * @param axes axes to omit from iterator
    456         * @return a PositionIterator that misses out axes
    457         */
    458        public PositionIterator getPositionIterator(int... axes);
    459
    460        /**
    461         * @param start
    462         *            specifies the starting indexes
    463         * @param stop
    464         *            specifies the stopping indexes (nb, these are <b>not</b> included in the slice)
    465         * @param step
    466         *            specifies the steps in the slice
    467         * @return an slice iterator that operates like an IndexIterator
    468         */
    469        public IndexIterator getSliceIterator(int[] start, int[] stop, int[] step);
    470
    471        /**
    472         * @param slice an n-D slice
    473         * @return an slice iterator that operates like an IndexIterator
    474         * @since 2.1
    475         */
    476        public IndexIterator getSliceIterator(SliceND slice);
    477
    478        /**
    479         * Get a slice iterator that is defined by a starting position and a set of axes to include
    480         *
    481         * @param pos
    482         * @param axes
    483         *            to include
    484         * @return slice iterator
    485         */
    486        public SliceIterator getSliceIteratorFromAxes(int[] pos, boolean[] axes);
    487
    488        /**
    489         * Copy content from axes in given position to array
    490         *
    491         * @param pos
    492         *            - null means position at origin
    493         * @param axes
    494         *            - true means copy
    495         * @param dest
    496         */
    497        public void copyItemsFromAxes(int[] pos, boolean[] axes, Dataset dest);
    498
    499        /**
    500         * Set content on axes in given position to values in array
    501         *
    502         * @param pos
    503         * @param axes
    504         *            - true means copy
    505         * @param src
    506         */
    507        public void setItemsOnAxes(int[] pos, boolean[] axes, Object src);
    508
    509        /**
    510         * Get an iterator that visits every item in this dataset where the corresponding item in
    511         * choice dataset is true
    512         *
    513         * @param choice
    514         * @return an iterator of dataset that visits items chosen by given choice dataset
    515         */
    516        public BooleanIterator getBooleanIterator(Dataset choice);
    517
    518        /**
    519         * Get an iterator that visits every item in this dataset where the corresponding item in
    520         * choice dataset is given by value
    521         *
    522         * @param choice
    523         * @param value
    524         * @return an iterator of dataset that visits items chosen by given choice dataset
    525         */
    526        public BooleanIterator getBooleanIterator(Dataset choice, boolean value);
    527
    528        /**
    529         * This is modelled after the NumPy get item with a condition specified by a boolean dataset
    530         *
    531         * @param selection
    532         *            a boolean dataset of same shape to use for selecting items
    533         * @return The new selected dataset
    534         */
    535        public Dataset getByBoolean(Dataset selection);
    536
    537        /**
    538         * This is modelled after the NumPy set item with a condition specified by a boolean dataset
    539         *
    540         * @param obj
    541         *            specifies the object used to set the selected items
    542         * @param selection
    543         *            a boolean dataset of same shape to use for selecting items
    544         *
    545         * @return The dataset with modified content
    546         */
    547        public Dataset setByBoolean(Object obj, Dataset selection);
    548
    549        /**
    550         * This is modelled after the NumPy get item with an index dataset
    551         *
    552         * @param index
    553         *            an integer dataset
    554         * @return The new selected dataset by indices
    555         */
    556        public Dataset getBy1DIndex(IntegerDataset index);
    557
    558        /**
    559         * This is modelled after the NumPy get item with an array of indexing objects
    560         *
    561         * @param indexes
    562         *            an array of integer dataset, boolean dataset, slices or null entries (same as
    563         *            full slices)
    564         * @return The new selected dataset by index
    565         */
    566        public Dataset getByIndexes(Object... indexes);
    567
    568        /**
    569         * This is modelled after the NumPy set item with an index dataset
    570         *
    571         * @param obj
    572         *            specifies the object used to set the selected items
    573         * @param index
    574         *            an integer dataset
    575         *
    576         * @return The dataset with modified content
    577         */
    578        public Dataset setBy1DIndex(Object obj, Dataset index);
    579
    580        /**
    581         * This is modelled after the NumPy set item with an array of indexing objects
    582         *
    583         * @param obj
    584         *            specifies the object used to set the selected items
    585         * @param indexes
    586         *            an array of integer dataset, boolean dataset, slices or null entries (same as
    587         *            full slices)
    588         *
    589         * @return The dataset with modified content
    590         */
    591        public Dataset setByIndexes(Object obj, Object... indexes);
    592
    593        /**
    594         * Fill dataset with given object
    595         *
    596         * @param obj
    597         * @return filled dataset with each item being equal to the given object
    598         */
    599        public Dataset fill(Object obj);
    600
    601        /**
    602         * Get an element from given absolute index as a boolean. See warning in interface doc
    603         *
    604         * @param index
    605         * @return element as boolean
    606         */
    607        public boolean getElementBooleanAbs(int index);
    608
    609        /**
    610         * Get an element from given absolute index as a double. See warning in interface doc
    611         *
    612         * @param index
    613         * @return element as double
    614         */
    615        public double getElementDoubleAbs(int index);
    616
    617        /**
    618         * Get an element from given absolute index as a long. See warning in interface doc
    619         *
    620         * @param index
    621         * @return element as long
    622         */
    623        public long getElementLongAbs(int index);
    624
    625        /**
    626         * Get an item from given absolute index as an object. See warning in interface doc
    627         *
    628         * @param index
    629         * @return item
    630         */
    631        public Object getObjectAbs(int index);
    632
    633        /**
    634         * Get an item from given absolute index as a string. See warning in interface doc
    635         *
    636         * @param index
    637         * @return item
    638         */
    639        public String getStringAbs(int index);
    640
    641        /**
    642         * Set an item at absolute index from an object. See warning in interface doc
    643         *
    644         * @param index
    645         * @param obj
    646         */
    647        public void setObjectAbs(int index, Object obj);
    648
    649        /**
    650         * Get first item as an object. The dataset must not be null
    651         * @return item
    652         * @since 2.0
    653         */
    654        public Object getObject();
    655
    656        /**
    657         * Get an item from given position as an object. The dataset must be 1D
    658         * @param i
    659         * @return item
    660         */
    661        public Object getObject(final int i);
    662
    663        /**
    664         * Get an item from given position as an object. The dataset must be 2D
    665         * @param i
    666         * @param j
    667         * @return item
    668         */
    669        public Object getObject(final int i, final int j);
    670
    671        /**
    672         * Get first item as a string. The dataset must not be null
    673         * @return item
    674         * @since 2.0
    675         */
    676        public String getString();
    677
    678        /**
    679         * Get an item from given position as a string. The dataset must be 1D
    680         * @param i
    681         * @return item
    682         */
    683        public String getString(final int i);
    684
    685        /**
    686         * Get an item from given position as a string. The dataset must be 2D
    687         * @param i
    688         * @param j
    689         * @return item
    690         */
    691        public String getString(final int i, final int j);
    692
    693        /**
    694         * Get first item as a double. The dataset must not be null
    695         * @return item
    696         * @since 2.0
    697         */
    698        public double getDouble();
    699
    700        /**
    701         * Get an item from given position as a double. The dataset must be 1D
    702         * @param i
    703         * @return item
    704         */
    705        public double getDouble(final int i);
    706
    707        /**
    708         * Get an item from given position as a double. The dataset must be 2D
    709         * @param i
    710         * @param j
    711         * @return item
    712         */
    713        public double getDouble(final int i, final int j);
    714
    715        /**
    716         * Get first item as a float. The dataset must not be null
    717         * @return item
    718         * @since 2.0
    719         */
    720        public float getFloat();
    721
    722        /**
    723         * Get an item from given position as a float. The dataset must be 1D
    724         * @param i
    725         * @return item
    726         */
    727        public float getFloat(final int i);
    728
    729        /**
    730         * Get an item from given position as a float. The dataset must be 2D
    731         * @param i
    732         * @param j
    733         * @return item
    734         */
    735        public float getFloat(final int i, final int j);
    736
    737        /**
    738         * Get first item as a long. The dataset must not be null
    739         * @return item
    740         * @since 2.0
    741         */
    742        public long getLong();
    743
    744        /**
    745         * Get an item from given position as a long. The dataset must be 1D
    746         * @param i
    747         * @return item
    748         */
    749        public long getLong(final int i);
    750
    751        /**
    752         * Get an item from given position as a long. The dataset must be 2D
    753         * @param i
    754         * @param j
    755         * @return item
    756         */
    757        public long getLong(final int i, final int j);
    758
    759        /**
    760         * Get first item as an int. The dataset must not be null
    761         * @return item
    762         * @since 2.0
    763         */
    764        public int getInt();
    765
    766        /**
    767         * Get an item from given position as an int. The dataset must be 1D
    768         * @param i
    769         * @return item
    770         */
    771        public int getInt(final int i);
    772
    773        /**
    774         * Get an item from given position as an int. The dataset must be 2D
    775         * @param i
    776         * @param j
    777         * @return item
    778         */
    779        public int getInt(final int i, final int j);
    780
    781        /**
    782         * Get first item as a short. The dataset must not be null
    783         * @return item
    784         * @since 2.0
    785         */
    786        public short getShort();
    787
    788        /**
    789         * Get an item from given position as a short. The dataset must be 1D
    790         * @param i
    791         * @return item
    792         */
    793        public short getShort(final int i);
    794
    795        /**
    796         * Get an item from given position as a short. The dataset must be 2D
    797         * @param i
    798         * @param j
    799         * @return item
    800         */
    801        public short getShort(final int i, final int j);
    802
    803        /**
    804         * Get first item as a byte. The dataset must not be null
    805         * @return item
    806         * @since 2.0
    807         */
    808        public byte getByte();
    809
    810        /**
    811         * Get an item from given position as a byte. The dataset must be 1D
    812         * @param i
    813         * @return item
    814         */
    815        public byte getByte(final int i);
    816
    817        /**
    818         * Get an item from given positionj as a byte. The dataset must be 2D
    819         * @param i
    820         * @param j
    821         * @return item
    822         */
    823        public byte getByte(final int i, final int j);
    824
    825        /**
    826         * Get first item as a boolean. The dataset must not be null
    827         * @return item
    828         * @since 2.0
    829         */
    830        public boolean getBoolean();
    831
    832        /**
    833         * Get an item from given position as a boolean. The dataset must be 1D
    834         * @param i
    835         * @return item
    836         */
    837        public boolean getBoolean(final int i);
    838
    839        /**
    840         * Get an item from given position as a boolean. The dataset must be 2D
    841         * @param i
    842         * @param j
    843         * @return item
    844         */
    845        public boolean getBoolean(final int i, final int j);
    846
    847        /**
    848         * Get the error for the first item. The dataset must not be null
    849         * @return item
    850         * @since 2.0
    851         */
    852        public double getError();
    853
    854        /**
    855         * Get the error for given position. The dataset must be 1D
    856         * @param i
    857         * @return error value (symmetric)
    858         */
    859        public double getError(final int i);
    860
    861        /**
    862         * Get the error for given position. The dataset must be 2D
    863         * @param i
    864         * @param j
    865         * @return error value (symmetric)
    866         */
    867        public double getError(final int i, final int j);
    868
    869        /**
    870         * Get the error values for given position
    871         * @param i
    872         * @return the values of the error at this point (can be null when no error defined)
    873         */
    874        public double[] getErrorArray(final int i);
    875
    876        /**
    877         * Get the error values for given position
    878         * @param i
    879         * @param j
    880         * @return the values of the error at this point (can be null when no error defined)
    881         */
    882        public double[] getErrorArray(final int i, final int j);
    883
    884        /**
    885         * Set the value given by object at the first position. The dataset must not be null
    886         * @param obj
    887         * @since 2.0
    888         */
    889        public void set(final Object obj);
    890
    891        /**
    892         * Set the value given by object at given position. The dataset must be 1D
    893         * @param obj
    894         * @param i
    895         */
    896        public void set(final Object obj, final int i);
    897
    898        /**
    899         * Set the value given by object at given position. The dataset must be 2D
    900         * @param obj
    901         * @param i
    902         * @param j
    903         */
    904        public void set(final Object obj, final int i, final int j);
    905
    906        /**
    907         * In-place sort of dataset
    908         *
    909         * @param axis
    910         *            to sort along. If null, then the flattened view is sorted
    911         * @return sorted dataset
    912         */
    913        public Dataset sort(Integer axis);
    914
    915        @Override
    916        public Dataset getSlice(int[] start, int[] stop, int[] step);
    917
    918        @Override
    919        public Dataset getSlice(IMonitor mon, int[] start, int[] stop, int[] step);
    920
    921        @Override
    922        public Dataset getSlice(Slice... slice);
    923
    924        @Override
    925        public Dataset getSlice(IMonitor mon, Slice... slice);
    926
    927        @Override
    928        public Dataset getSlice(SliceND slice);
    929
    930        @Override
    931        public Dataset getSlice(IMonitor mon, SliceND slice);
    932
    933        @Override
    934        public Dataset getSliceView(int[] start, int[] stop, int[] step);
    935
    936        @Override
    937        public Dataset getSliceView(Slice... slice);
    938
    939        @Override
    940        public Dataset getSliceView(SliceND slice);
    941
    942        /**
    943         * This is modelled after the NumPy array slice
    944         *
    945         * @param obj
    946         *            specifies the object used to set the specified slice
    947         * @param start
    948         *            specifies the starting indexes
    949         * @param stop
    950         *            specifies the stopping indexes (nb, these are <b>not</b> included in the slice)
    951         * @param step
    952         *            specifies the steps in the slice
    953         *
    954         * @return The dataset with the sliced set to object
    955         */
    956        public Dataset setSlice(Object obj, int[] start, int[] stop, int[] step);
    957
    958        /**
    959         * This is modelled after the NumPy array slice
    960         *
    961         * @param obj
    962         * @param slice
    963         */
    964        public Dataset setSlice(Object obj, Slice... slice);
    965
    966        /**
    967         * This is modelled after the NumPy array slice
    968         *
    969         * @param obj
    970         * @param slice
    971         */
    972        public Dataset setSlice(Object obj, SliceND slice);
    973
    974        /**
    975         * @param obj
    976         *            specifies the object used to set the specified slice
    977         * @param iterator
    978         *            specifies the slice iterator
    979         *
    980         * @return The dataset with the sliced set to object
    981         */
    982        public Dataset setSlice(Object obj, IndexIterator iterator);
    983
    984        /**
    985         * Populate another dataset with part of current dataset
    986         *
    987         * @param other
    988         * @param iter
    989         *            over current dataset
    990         */
    991        public void fillDataset(Dataset other, IndexIterator iter);
    992
    993        /**
    994         * Test if all items are true
    995         */
    996        public boolean all();
    997
    998        /**
    999         * @param axis
    1000         * @return dataset where items are true if all items along axis are true
    1001         */
    1002        public Dataset all(int axis);
    1003
    1004        /**
    1005         * Test if any items are true
    1006         */
    1007        public boolean any();
    1008
    1009        /**
    1010         * @param axis
    1011         * @return dataset where items are true if any items along axis are true
    1012         */
    1013        public Dataset any(int axis);
    1014
    1015        /**
    1016         * In-place addition with object o
    1017         *
    1018         * @param o
    1019         * @return sum dataset
    1020         */
    1021        public Dataset iadd(Object o);
    1022
    1023        /**
    1024         * In-place subtraction with object o
    1025         *
    1026         * @param o
    1027         * @return difference dataset
    1028         */
    1029        public Dataset isubtract(Object o);
    1030
    1031        /**
    1032         * In-place multiplication with object o
    1033         *
    1034         * @param o
    1035         * @return product dataset
    1036         */
    1037        public Dataset imultiply(Object o);
    1038
    1039        /**
    1040         * In-place division with object o
    1041         *
    1042         * @param o
    1043         * @return dividend dataset
    1044         */
    1045        public Dataset idivide(Object o);
    1046
    1047        /**
    1048         * In-place floor division with object o
    1049         *
    1050         * @param o
    1051         * @return dividend dataset
    1052         */
    1053        public Dataset ifloorDivide(Object o);
    1054
    1055        /**
    1056         * In-place remainder
    1057         *
    1058         * @return remaindered dataset
    1059         */
    1060        public Dataset iremainder(Object o);
    1061
    1062        /**
    1063         * In-place floor
    1064         *
    1065         * @return floored dataset
    1066         */
    1067        public Dataset ifloor();
    1068
    1069        /**
    1070         * In-place raise to power of object o
    1071         *
    1072         * @param o
    1073         * @return raised dataset
    1074         */
    1075        public Dataset ipower(Object o);
    1076
    1077        /**
    1078         * Calculate residual of dataset with object o
    1079         * See {@link #residual(Object o, boolean ignoreNaNs)} with ignoreNaNs = false
    1080         *
    1081         * @param o
    1082         * @return sum of the squares of the differences
    1083         */
    1084        public double residual(Object o);
    1085
    1086        /**
    1087         * Calculate residual of dataset with object o
    1088         *
    1089         * @param o
    1090         * @param ignoreNaNs if true, skip NaNs
    1091         * @return sum of the squares of the differences
    1092         */
    1093        public double residual(Object o, boolean ignoreNaNs);
    1094
    1095        /**
    1096         * Calculate residual of dataset with object o and weight. The weight is used to multiply
    1097         * the squared differences
    1098         *
    1099         * @param o
    1100         * @param weight
    1101         * @param ignoreNaNs if true, skip NaNs
    1102         * @return sum of the squares of the differences
    1103         */
    1104        public double residual(Object o, Dataset weight, boolean ignoreNaNs);
    1105
    1106        /**
    1107         * @return true if dataset contains any infinities
    1108         */
    1109        public boolean containsInfs();
    1110
    1111        /**
    1112         * @return true if dataset contains any NaNs
    1113         */
    1114        public boolean containsNans();
    1115
    1116        /**
    1117         * @return true if dataset contains any NaNs or infinities
    1118         */
    1119        public boolean containsInvalidNumbers();
    1120
    1121        /**
    1122         * @param axis
    1123         * @param ignoreInvalids - Can be null, empty, or one or more booleans. By default, all booleans
    1124         * are false. If the first boolean is true, will ignore NaNs and ignore infinities. Use the second
    1125         * boolean to ignore infinities separately.
    1126         * @return maxima along axis in dataset
    1127         * @since 2.0
    1128         */
    1129        public Dataset max(int axis, boolean... ignoreInvalids);
    1130
    1131        /**
    1132         * @param axes
    1133         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1134         * @return maxima in given axes of dataset
    1135         * @since 2.2
    1136         */
    1137        public Dataset max(int[] axes, boolean... ignoreInvalids);
    1138
    1139        /**
    1140         * @param axis
    1141         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1142         * @return minima along axis in dataset
    1143         * @since 2.0
    1144         */
    1145        public Dataset min(int axis, boolean... ignoreInvalids);
    1146
    1147        /**
    1148         * @param axes
    1149         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1150         * @return minima in given axes of dataset
    1151         * @since 2.2
    1152         */
    1153        public Dataset min(int[] axes, boolean... ignoreInvalids);
    1154
    1155        /**
    1156         * Find absolute index of maximum value (in a flattened view)
    1157         * @param ignoreInvalids - see {@link IDataset#max(boolean...)}
    1158         * @return absolute index
    1159         * @since 2.0
    1160         */
    1161        public int argMax(boolean... ignoreInvalids);
    1162
    1163        /**
    1164         * Find indices of maximum values along given axis
    1165         * @param axis
    1166         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1167         * @return index dataset
    1168         * @since 2.0
    1169         */
    1170        public Dataset argMax(int axis, boolean... ignoreInvalids);
    1171
    1172        /**
    1173         * Find absolute index of minimum value (in a flattened view)
    1174         * @param ignoreInvalids - see {@link IDataset#max(boolean...)}
    1175         * @return absolute index
    1176         * @since 2.0
    1177         */
    1178        public int argMin(boolean... ignoreInvalids);
    1179
    1180        /**
    1181         * Find indices of minimum values along given axis
    1182         * @param axis
    1183         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1184         * @return index dataset
    1185         * @since 2.0
    1186         */
    1187        public Dataset argMin(int axis, boolean... ignoreInvalids);
    1188
    1189        /**
    1190         * @param ignoreInvalids - see {@link IDataset#max(boolean...)}
    1191         * @return peak-to-peak value, the difference of maximum and minimum of dataset
    1192         * @since 2.0
    1193         */
    1194        public Number peakToPeak(boolean... ignoreInvalids);
    1195
    1196        /**
    1197         * @param axis
    1198         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1199         * @return peak-to-peak dataset, the difference of maxima and minima of dataset along axis
    1200         * @since 2.0
    1201         */
    1202        public Dataset peakToPeak(int axis, boolean... ignoreInvalids);
    1203
    1204        /**
    1205         * @param axes
    1206         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1207         * @return peak-to-peak dataset, the difference of maxima and minima of dataset in given axes
    1208         * @since 2.2
    1209         */
    1210        public Dataset peakToPeak(int[] axes, boolean... ignoreInvalids);
    1211
    1212        /**
    1213         * @param ignoreInvalids - see {@link IDataset#max(boolean...)}
    1214         * @return number of items in dataset
    1215         * @since 2.0
    1216         */
    1217        public long count(boolean... ignoreInvalids);
    1218
    1219        /**
    1220         * @param axis
    1221         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1222         * @return number of items along axis in dataset
    1223         * @since 2.0
    1224         */
    1225        public Dataset count(int axis, boolean... ignoreInvalids);
    1226
    1227        /**
    1228         * @param axes
    1229         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1230         * @return number of items in given axes of dataset
    1231         * @since 2.2
    1232         */
    1233        public Dataset count(int[] axes, boolean... ignoreInvalids);
    1234
    1235        /**
    1236         * @param ignoreInvalids - see {@link IDataset#max(boolean...)}
    1237         * @return sum over all items in dataset as a Double, array of doubles or a complex number
    1238         * @since 2.0
    1239         */
    1240        public Object sum(boolean... ignoreInvalids);
    1241
    1242        /**
    1243         * @param axis
    1244         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1245         * @return sum along axis in dataset
    1246         * @since 2.0
    1247         */
    1248        public Dataset sum(int axis, boolean... ignoreInvalids);
    1249
    1250        /**
    1251         * @param axes
    1252         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1253         * @return sum  in given axes of dataset
    1254         * @since 2.2
    1255         */
    1256        public Dataset sum(int[] axes, boolean... ignoreInvalids);
    1257
    1258        /**
    1259         * @param ignoreInvalids - see {@link IDataset#max(boolean...)}
    1260         * @return product over all items in dataset
    1261         * @since 2.0
    1262         */
    1263        public Object product(boolean... ignoreInvalids);
    1264
    1265        /**
    1266         * @param axis
    1267         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1268         * @return product along axis in dataset
    1269         * @since 2.0
    1270         */
    1271        public Dataset product(int axis, boolean... ignoreInvalids);
    1272
    1273        /**
    1274         * @param axes
    1275         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1276         * @return product in given axes of dataset
    1277         * @since 2.2
    1278         */
    1279        public Dataset product(int[] axes, boolean... ignoreInvalids);
    1280
    1281        /**
    1282         * @param axis
    1283         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1284         * @return mean along axis in dataset
    1285         * @since 2.0
    1286         */
    1287        public Dataset mean(int axis, boolean... ignoreInvalids);
    1288
    1289        /**
    1290         * @param axes
    1291         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1292         * @return mean in given axes of dataset
    1293         * @since 2.2
    1294         */
    1295        public Dataset mean(int[] axes, boolean... ignoreInvalids);
    1296
    1297        /**
    1298         * @return sample variance of whole dataset
    1299         * @see #variance(boolean, boolean...) with isWholePopulation = false
    1300         * @since 2.0
    1301         */
    1302        public double variance();
    1303
    1304        /**
    1305         * The sample variance can be calculated in two ways: if the dataset is considered as the
    1306         * entire population then the sample variance is simply the second central moment:
    1307         *
    1308         * <pre>
    1309         *    sum((x_i - m)^2)/N
    1310         * where {x_i} are set of N population values and m is the mean
    1311         *    m = sum(x_i)/N
    1312         * </pre>
    1313         *
    1314         * Otherwise, if the dataset is a set of samples (with replacement) from the population then
    1315         *
    1316         * <pre>
    1317         *    sum((x_i - m)^2)/(N-1)
    1318         * where {x_i} are set of N sample values and m is the unbiased estimate of the mean
    1319         *    m = sum(x_i)/N
    1320         * </pre>
    1321         *
    1322         * Note that the second definition is also the unbiased estimator of population variance.
    1323         *
    1324         * @param isWholePopulation
    1325         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1326         * @return sample variance
    1327         * @since 2.0
    1328         */
    1329        public double variance(boolean isWholePopulation, boolean... ignoreInvalids);
    1330
    1331        /**
    1332         * @param axis
    1333         * @return sample variance along axis in dataset
    1334         * @see #variance(int, boolean, boolean...) with isWholePopulation = false
    1335         */
    1336        public Dataset variance(int axis);
    1337
    1338        /**
    1339         * @param axes
    1340         * @return sample variance in given axes of dataset
    1341         * @see #variance(int[], boolean, boolean...) with isWholePopulation = false
    1342         * @since 2.2
    1343         */
    1344        public Dataset variance(int[] axes);
    1345
    1346        /**
    1347         * @param axis
    1348         * @param isWholePopulation
    1349         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1350         * @return sample variance along axis in dataset
    1351         * @since 2.0
    1352         */
    1353        public Dataset variance(int axis, boolean isWholePopulation, boolean... ignoreInvalids);
    1354
    1355        /**
    1356         * @param axes
    1357         * @param isWholePopulation
    1358         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1359         * @return sample variance in given axes of dataset
    1360         * @since 2.2
    1361         */
    1362        public Dataset variance(int[] axes, boolean isWholePopulation, boolean... ignoreInvalids);
    1363
    1364        /**
    1365         * Standard deviation is square root of the variance
    1366         *
    1367         * @return sample standard deviation of all items in dataset
    1368         * @see #stdDeviation(boolean, boolean...) with isWholePopulation = false
    1369         * @since 2.0
    1370         */
    1371        public double stdDeviation();
    1372
    1373        /**
    1374         * Standard deviation is square root of the variance
    1375         *
    1376         * @param isWholePopulation
    1377         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1378         * @return sample standard deviation of all items in dataset
    1379         * @see #variance(boolean, boolean...)
    1380         * @since 2.0
    1381         */
    1382        public double stdDeviation(boolean isWholePopulation, boolean... ignoreInvalids);
    1383
    1384        /**
    1385         * Standard deviation is square root of the variance
    1386         *
    1387         * @param axis
    1388         * @return standard deviation along axis in dataset
    1389         * @see #stdDeviation(int, boolean, boolean...) with isWholePopulation = false
    1390         */
    1391        public Dataset stdDeviation(int axis);
    1392
    1393        /**
    1394         * Standard deviation is square root of the variance
    1395         *
    1396         * @param axes
    1397         * @return standard deviation in given axes of dataset
    1398         * @see #stdDeviation(int[], boolean, boolean...) with isWholePopulation = false
    1399         * @since 2.2
    1400         */
    1401        public Dataset stdDeviation(int[] axes);
    1402
    1403        /**
    1404         * Standard deviation is square root of the variance
    1405         *
    1406         * @param axis
    1407         * @param isWholePopulation
    1408         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1409         * @return standard deviation along axis in dataset
    1410         * @since 2.0
    1411         */
    1412        public Dataset stdDeviation(int axis, boolean isWholePopulation, boolean... ignoreInvalids);
    1413
    1414        /**
    1415         * Standard deviation is square root of the variance
    1416         *
    1417         * @param axes
    1418         * @param isWholePopulation
    1419         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1420         * @return standard deviation in given axes of dataset
    1421         * @since 2.2
    1422         */
    1423        public Dataset stdDeviation(int[] axes, boolean isWholePopulation, boolean... ignoreInvalids);
    1424
    1425        /**
    1426         * @param ignoreInvalids - see {@link IDataset#max(boolean...)}
    1427         * @return root mean square
    1428         * @since 2.0
    1429         */
    1430        public double rootMeanSquare(boolean... ignoreInvalids);
    1431
    1432        /**
    1433         * @param axis
    1434         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1435         * @return root mean square along axis in dataset
    1436         * @since 2.0
    1437         */
    1438        public Dataset rootMeanSquare(int axis, boolean... ignoreInvalids);
    1439
    1440        /**
    1441         * @param axes
    1442         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1443         * @return root mean square in given axes of dataset
    1444         * @since 2.2
    1445         */
    1446        public Dataset rootMeanSquare(int[] axes, boolean... ignoreInvalids);
    1447}