    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         */
    344        public Dataset copy(int dtype);
    345
    346        /**
    347         * Copy and cast a dataset
    348         *
    349         * @param <T> dataset subclass
    350         * @param clazz dataset class
    351         * @return a converted copy of the dataset
    352         */
    353        public <T extends Dataset> T copy(Class<T> clazz);
    354
    355        /**
    356         * Cast a dataset
    357         *
    358         * @param dtype
    359         *            dataset type
    360         * @return a converted dataset
    361         */
    362        public Dataset cast(int dtype);
    363
    364        /**
    365         * Cast a dataset
    366         *
    367         * @param <T> dataset subclass
    368         * @param clazz dataset class
    369         * @return a converted dataset
    370         */
    371        public <T extends Dataset> T cast(Class<T> clazz);
    372
    373        /**
    374         * Cast a dataset
    375         *
    376         * @param repeat
    377         * @param dtype
    378         *            dataset type
    379         * @param isize
    380         *            item size
    381         * @return a converted dataset
    382         */
    383        public Dataset cast(boolean repeat, int dtype, int isize);
    384
    385        /**
    386         * Generate an index dataset for current dataset
    387         *
    388         * @return an index dataset
    389         */
    390        public IntegerDataset getIndices();
    391
    392        @Override
    393        public Dataset getTransposedView(int... axes);
    394
    395        /**
    396         * See {@link #getTransposedView}
    397         * @param axes
    398         * @return remapped copy of data
    399         */
    400        public Dataset transpose(int... axes);
    401
    402        /**
    403         * Swap two axes in dataset
    404         *
    405         * @param axis1
    406         * @param axis2
    407         * @return swapped view of dataset
    408         */
    409        public Dataset swapAxes(int axis1, int axis2);
    410
    411        /**
    412         * Flatten shape
    413         *
    414         * @return a flattened dataset which is a view if dataset is contiguous otherwise is a copy
    415         */
    416        public Dataset flatten();
    417
    418        /**
    419         * Get unique items
    420         * @return a sorted dataset of unique items
    421         */
    422        public Dataset getUniqueItems();
    423
    424        /**
    425         * @param withPosition
    426         *            set true if position is needed
    427         * @return an IndexIterator tailored for this dataset
    428         */
    429        public IndexIterator getIterator(boolean withPosition);
    430
    431        /**
    432         * @return an IndexIterator tailored for this dataset
    433         */
    434        public IndexIterator getIterator();
    435
    436        /**
    437         * @param axes axes to omit from iterator
    438         * @return a PositionIterator that misses out axes
    439         */
    440        public PositionIterator getPositionIterator(int... axes);
    441
    442        /**
    443         * @param start
    444         *            specifies the starting indexes
    445         * @param stop
    446         *            specifies the stopping indexes (nb, these are <b>not</b> included in the slice)
    447         * @param step
    448         *            specifies the steps in the slice
    449         * @return an slice iterator that operates like an IndexIterator
    450         */
    451        public IndexIterator getSliceIterator(int[] start, int[] stop, int[] step);
    452
    453        /**
    454         * @param slice an n-D slice
    455         * @return an slice iterator that operates like an IndexIterator
    456         * @since 2.1
    457         */
    458        public IndexIterator getSliceIterator(SliceND slice);
    459
    460        /**
    461         * Get a slice iterator that is defined by a starting position and a set of axes to include
    462         *
    463         * @param pos
    464         * @param axes
    465         *            to include
    466         * @return slice iterator
    467         */
    468        public SliceIterator getSliceIteratorFromAxes(int[] pos, boolean[] axes);
    469
    470        /**
    471         * Copy content from axes in given position to array
    472         *
    473         * @param pos
    474         *            - null means position at origin
    475         * @param axes
    476         *            - true means copy
    477         * @param dest
    478         */
    479        public void copyItemsFromAxes(int[] pos, boolean[] axes, Dataset dest);
    480
    481        /**
    482         * Set content on axes in given position to values in array
    483         *
    484         * @param pos
    485         * @param axes
    486         *            - true means copy
    487         * @param src
    488         */
    489        public void setItemsOnAxes(int[] pos, boolean[] axes, Object src);
    490
    491        /**
    492         * Get an iterator that visits every item in this dataset where the corresponding item in
    493         * choice dataset is true
    494         *
    495         * @param choice
    496         * @return an iterator of dataset that visits items chosen by given choice dataset
    497         */
    498        public BooleanIterator getBooleanIterator(Dataset choice);
    499
    500        /**
    501         * Get an iterator that visits every item in this dataset where the corresponding item in
    502         * choice dataset is given by value
    503         *
    504         * @param choice
    505         * @param value
    506         * @return an iterator of dataset that visits items chosen by given choice dataset
    507         */
    508        public BooleanIterator getBooleanIterator(Dataset choice, boolean value);
    509
    510        /**
    511         * This is modelled after the NumPy get item with a condition specified by a boolean dataset
    512         *
    513         * @param selection
    514         *            a boolean dataset of same shape to use for selecting items
    515         * @return The new selected dataset
    516         */
    517        public Dataset getByBoolean(Dataset selection);
    518
    519        /**
    520         * This is modelled after the NumPy set item with a condition specified by a boolean dataset
    521         *
    522         * @param obj
    523         *            specifies the object used to set the selected items
    524         * @param selection
    525         *            a boolean dataset of same shape to use for selecting items
    526         *
    527         * @return The dataset with modified content
    528         */
    529        public Dataset setByBoolean(Object obj, Dataset selection);
    530
    531        /**
    532         * This is modelled after the NumPy get item with an index dataset
    533         *
    534         * @param index
    535         *            an integer dataset
    536         * @return The new selected dataset by indices
    537         */
    538        public Dataset getBy1DIndex(IntegerDataset index);
    539
    540        /**
    541         * This is modelled after the NumPy get item with an array of indexing objects
    542         *
    543         * @param indexes
    544         *            an array of integer dataset, boolean dataset, slices or null entries (same as
    545         *            full slices)
    546         * @return The new selected dataset by index
    547         */
    548        public Dataset getByIndexes(Object... indexes);
    549
    550        /**
    551         * This is modelled after the NumPy set item with an index dataset
    552         *
    553         * @param obj
    554         *            specifies the object used to set the selected items
    555         * @param index
    556         *            an integer dataset
    557         *
    558         * @return The dataset with modified content
    559         */
    560        public Dataset setBy1DIndex(Object obj, Dataset index);
    561
    562        /**
    563         * This is modelled after the NumPy set item with an array of indexing objects
    564         *
    565         * @param obj
    566         *            specifies the object used to set the selected items
    567         * @param indexes
    568         *            an array of integer dataset, boolean dataset, slices or null entries (same as
    569         *            full slices)
    570         *
    571         * @return The dataset with modified content
    572         */
    573        public Dataset setByIndexes(Object obj, Object... indexes);
    574
    575        /**
    576         * Fill dataset with given object
    577         *
    578         * @param obj
    579         * @return filled dataset with each item being equal to the given object
    580         */
    581        public Dataset fill(Object obj);
    582
    583        /**
    584         * Get an element from given absolute index as a boolean. See warning in interface doc
    585         *
    586         * @param index
    587         * @return element as boolean
    588         */
    589        public boolean getElementBooleanAbs(int index);
    590
    591        /**
    592         * Get an element from given absolute index as a double. See warning in interface doc
    593         *
    594         * @param index
    595         * @return element as double
    596         */
    597        public double getElementDoubleAbs(int index);
    598
    599        /**
    600         * Get an element from given absolute index as a long. See warning in interface doc
    601         *
    602         * @param index
    603         * @return element as long
    604         */
    605        public long getElementLongAbs(int index);
    606
    607        /**
    608         * Get an item from given absolute index as an object. See warning in interface doc
    609         *
    610         * @param index
    611         * @return item
    612         */
    613        public Object getObjectAbs(int index);
    614
    615        /**
    616         * Get an item from given absolute index as a string. See warning in interface doc
    617         *
    618         * @param index
    619         * @return item
    620         */
    621        public String getStringAbs(int index);
    622
    623        /**
    624         * Set an item at absolute index from an object. See warning in interface doc
    625         *
    626         * @param index
    627         * @param obj
    628         */
    629        public void setObjectAbs(int index, Object obj);
    630
    631        /**
    632         * Get first item as an object. The dataset must not be null
    633         * @return item
    634         * @since 2.0
    635         */
    636        public Object getObject();
    637
    638        /**
    639         * Get an item from given position as an object. The dataset must be 1D
    640         * @param i
    641         * @return item
    642         */
    643        public Object getObject(final int i);
    644
    645        /**
    646         * Get an item from given position as an object. The dataset must be 2D
    647         * @param i
    648         * @param j
    649         * @return item
    650         */
    651        public Object getObject(final int i, final int j);
    652
    653        /**
    654         * Get first item as a string. The dataset must not be null
    655         * @return item
    656         * @since 2.0
    657         */
    658        public String getString();
    659
    660        /**
    661         * Get an item from given position as a string. The dataset must be 1D
    662         * @param i
    663         * @return item
    664         */
    665        public String getString(final int i);
    666
    667        /**
    668         * Get an item from given position as a string. The dataset must be 2D
    669         * @param i
    670         * @param j
    671         * @return item
    672         */
    673        public String getString(final int i, final int j);
    674
    675        /**
    676         * Get first item as a double. The dataset must not be null
    677         * @return item
    678         * @since 2.0
    679         */
    680        public double getDouble();
    681
    682        /**
    683         * Get an item from given position as a double. The dataset must be 1D
    684         * @param i
    685         * @return item
    686         */
    687        public double getDouble(final int i);
    688
    689        /**
    690         * Get an item from given position as a double. The dataset must be 2D
    691         * @param i
    692         * @param j
    693         * @return item
    694         */
    695        public double getDouble(final int i, final int j);
    696
    697        /**
    698         * Get first item as a float. The dataset must not be null
    699         * @return item
    700         * @since 2.0
    701         */
    702        public float getFloat();
    703
    704        /**
    705         * Get an item from given position as a float. The dataset must be 1D
    706         * @param i
    707         * @return item
    708         */
    709        public float getFloat(final int i);
    710
    711        /**
    712         * Get an item from given position as a float. The dataset must be 2D
    713         * @param i
    714         * @param j
    715         * @return item
    716         */
    717        public float getFloat(final int i, final int j);
    718
    719        /**
    720         * Get first item as a long. The dataset must not be null
    721         * @return item
    722         * @since 2.0
    723         */
    724        public long getLong();
    725
    726        /**
    727         * Get an item from given position as a long. The dataset must be 1D
    728         * @param i
    729         * @return item
    730         */
    731        public long getLong(final int i);
    732
    733        /**
    734         * Get an item from given position as a long. The dataset must be 2D
    735         * @param i
    736         * @param j
    737         * @return item
    738         */
    739        public long getLong(final int i, final int j);
    740
    741        /**
    742         * Get first item as an int. The dataset must not be null
    743         * @return item
    744         * @since 2.0
    745         */
    746        public int getInt();
    747
    748        /**
    749         * Get an item from given position as an int. The dataset must be 1D
    750         * @param i
    751         * @return item
    752         */
    753        public int getInt(final int i);
    754
    755        /**
    756         * Get an item from given position as an int. The dataset must be 2D
    757         * @param i
    758         * @param j
    759         * @return item
    760         */
    761        public int getInt(final int i, final int j);
    762
    763        /**
    764         * Get first item as a short. The dataset must not be null
    765         * @return item
    766         * @since 2.0
    767         */
    768        public short getShort();
    769
    770        /**
    771         * Get an item from given position as a short. The dataset must be 1D
    772         * @param i
    773         * @return item
    774         */
    775        public short getShort(final int i);
    776
    777        /**
    778         * Get an item from given position as a short. The dataset must be 2D
    779         * @param i
    780         * @param j
    781         * @return item
    782         */
    783        public short getShort(final int i, final int j);
    784
    785        /**
    786         * Get first item as a byte. The dataset must not be null
    787         * @return item
    788         * @since 2.0
    789         */
    790        public byte getByte();
    791
    792        /**
    793         * Get an item from given position as a byte. The dataset must be 1D
    794         * @param i
    795         * @return item
    796         */
    797        public byte getByte(final int i);
    798
    799        /**
    800         * Get an item from given positionj as a byte. The dataset must be 2D
    801         * @param i
    802         * @param j
    803         * @return item
    804         */
    805        public byte getByte(final int i, final int j);
    806
    807        /**
    808         * Get first item as a boolean. The dataset must not be null
    809         * @return item
    810         * @since 2.0
    811         */
    812        public boolean getBoolean();
    813
    814        /**
    815         * Get an item from given position as a boolean. The dataset must be 1D
    816         * @param i
    817         * @return item
    818         */
    819        public boolean getBoolean(final int i);
    820
    821        /**
    822         * Get an item from given position as a boolean. The dataset must be 2D
    823         * @param i
    824         * @param j
    825         * @return item
    826         */
    827        public boolean getBoolean(final int i, final int j);
    828
    829        /**
    830         * Get the error for the first item. The dataset must not be null
    831         * @return item
    832         * @since 2.0
    833         */
    834        public double getError();
    835
    836        /**
    837         * Get the error for given position. The dataset must be 1D
    838         * @param i
    839         * @return error value (symmetric)
    840         */
    841        public double getError(final int i);
    842
    843        /**
    844         * Get the error for given position. The dataset must be 2D
    845         * @param i
    846         * @param j
    847         * @return error value (symmetric)
    848         */
    849        public double getError(final int i, final int j);
    850
    851        /**
    852         * Get the error values for given position
    853         * @param i
    854         * @return the values of the error at this point (can be null when no error defined)
    855         */
    856        public double[] getErrorArray(final int i);
    857
    858        /**
    859         * Get the error values for given position
    860         * @param i
    861         * @param j
    862         * @return the values of the error at this point (can be null when no error defined)
    863         */
    864        public double[] getErrorArray(final int i, final int j);
    865
    866        /**
    867         * Set the value given by object at the first position. The dataset must not be null
    868         * @param obj
    869         * @since 2.0
    870         */
    871        public void set(final Object obj);
    872
    873        /**
    874         * Set the value given by object at given position. The dataset must be 1D
    875         * @param obj
    876         * @param i
    877         */
    878        public void set(final Object obj, final int i);
    879
    880        /**
    881         * Set the value given by object at given position. The dataset must be 2D
    882         * @param obj
    883         * @param i
    884         * @param j
    885         */
    886        public void set(final Object obj, final int i, final int j);
    887
    888        /**
    889         * In-place sort of dataset
    890         *
    891         * @param axis
    892         *            to sort along. If null, then the flattened view is sorted
    893         * @return sorted dataset
    894         */
    895        public Dataset sort(Integer axis);
    896
    897        @Override
    898        public Dataset getSlice(int[] start, int[] stop, int[] step);
    899
    900        @Override
    901        public Dataset getSlice(IMonitor mon, int[] start, int[] stop, int[] step);
    902
    903        @Override
    904        public Dataset getSlice(Slice... slice);
    905
    906        @Override
    907        public Dataset getSlice(IMonitor mon, Slice... slice);
    908
    909        @Override
    910        public Dataset getSlice(SliceND slice);
    911
    912        @Override
    913        public Dataset getSlice(IMonitor mon, SliceND slice);
    914
    915        @Override
    916        public Dataset getSliceView(int[] start, int[] stop, int[] step);
    917
    918        @Override
    919        public Dataset getSliceView(Slice... slice);
    920
    921        @Override
    922        public Dataset getSliceView(SliceND slice);
    923
    924        /**
    925         * This is modelled after the NumPy array slice
    926         *
    927         * @param obj
    928         *            specifies the object used to set the specified slice
    929         * @param start
    930         *            specifies the starting indexes
    931         * @param stop
    932         *            specifies the stopping indexes (nb, these are <b>not</b> included in the slice)
    933         * @param step
    934         *            specifies the steps in the slice
    935         *
    936         * @return The dataset with the sliced set to object
    937         */
    938        public Dataset setSlice(Object obj, int[] start, int[] stop, int[] step);
    939
    940        /**
    941         * This is modelled after the NumPy array slice
    942         *
    943         * @param obj
    944         * @param slice
    945         */
    946        public Dataset setSlice(Object obj, Slice... slice);
    947
    948        /**
    949         * This is modelled after the NumPy array slice
    950         *
    951         * @param obj
    952         * @param slice
    953         */
    954        public Dataset setSlice(Object obj, SliceND slice);
    955
    956        /**
    957         * @param obj
    958         *            specifies the object used to set the specified slice
    959         * @param iterator
    960         *            specifies the slice iterator
    961         *
    962         * @return The dataset with the sliced set to object
    963         */
    964        public Dataset setSlice(Object obj, IndexIterator iterator);
    965
    966        /**
    967         * Populate another dataset with part of current dataset
    968         *
    969         * @param other
    970         * @param iter
    971         *            over current dataset
    972         */
    973        public void fillDataset(Dataset other, IndexIterator iter);
    974
    975        /**
    976         * Test if all items are true
    977         */
    978        public boolean all();
    979
    980        /**
    981         * @param axis
    982         * @return dataset where items are true if all items along axis are true
    983         */
    984        public Dataset all(int axis);
    985
    986        /**
    987         * Test if any items are true
    988         */
    989        public boolean any();
    990
    991        /**
    992         * @param axis
    993         * @return dataset where items are true if any items along axis are true
    994         */
    995        public Dataset any(int axis);
    996
    997        /**
    998         * In-place addition with object o
    999         *
    1000         * @param o
    1001         * @return sum dataset
    1002         */
    1003        public Dataset iadd(Object o);
    1004
    1005        /**
    1006         * In-place subtraction with object o
    1007         *
    1008         * @param o
    1009         * @return difference dataset
    1010         */
    1011        public Dataset isubtract(Object o);
    1012
    1013        /**
    1014         * In-place multiplication with object o
    1015         *
    1016         * @param o
    1017         * @return product dataset
    1018         */
    1019        public Dataset imultiply(Object o);
    1020
    1021        /**
    1022         * In-place division with object o
    1023         *
    1024         * @param o
    1025         * @return dividend dataset
    1026         */
    1027        public Dataset idivide(Object o);
    1028
    1029        /**
    1030         * In-place floor division with object o
    1031         *
    1032         * @param o
    1033         * @return dividend dataset
    1034         */
    1035        public Dataset ifloorDivide(Object o);
    1036
    1037        /**
    1038         * In-place remainder
    1039         *
    1040         * @return remaindered dataset
    1041         */
    1042        public Dataset iremainder(Object o);
    1043
    1044        /**
    1045         * In-place floor
    1046         *
    1047         * @return floored dataset
    1048         */
    1049        public Dataset ifloor();
    1050
    1051        /**
    1052         * In-place raise to power of object o
    1053         *
    1054         * @param o
    1055         * @return raised dataset
    1056         */
    1057        public Dataset ipower(Object o);
    1058
    1059        /**
    1060         * Calculate residual of dataset with object o
    1061         * See {@link #residual(Object o, boolean ignoreNaNs)} with ignoreNaNs = false
    1062         *
    1063         * @param o
    1064         * @return sum of the squares of the differences
    1065         */
    1066        public double residual(Object o);
    1067
    1068        /**
    1069         * Calculate residual of dataset with object o
    1070         *
    1071         * @param o
    1072         * @param ignoreNaNs if true, skip NaNs
    1073         * @return sum of the squares of the differences
    1074         */
    1075        public double residual(Object o, boolean ignoreNaNs);
    1076
    1077        /**
    1078         * Calculate residual of dataset with object o and weight. The weight is used to multiply
    1079         * the squared differences
    1080         *
    1081         * @param o
    1082         * @param weight
    1083         * @param ignoreNaNs if true, skip NaNs
    1084         * @return sum of the squares of the differences
    1085         */
    1086        public double residual(Object o, Dataset weight, boolean ignoreNaNs);
    1087
    1088        /**
    1089         * @return true if dataset contains any infinities
    1090         */
    1091        public boolean containsInfs();
    1092
    1093        /**
    1094         * @return true if dataset contains any NaNs
    1095         */
    1096        public boolean containsNans();
    1097
    1098        /**
    1099         * @return true if dataset contains any NaNs or infinities
    1100         */
    1101        public boolean containsInvalidNumbers();
    1102
    1103        /**
    1104         * @param axis
    1105         * @param ignoreInvalids - Can be null, empty, or one or more booleans. By default, all booleans
    1106         * are false. If the first boolean is true, will ignore NaNs and ignore infinities. Use the second
    1107         * boolean to ignore infinities separately.
    1108         * @return maxima along axis in dataset
    1109         * @since 2.0
    1110         */
    1111        public Dataset max(int axis, boolean... ignoreInvalids);
    1112
    1113        /**
    1114         * @param axes
    1115         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1116         * @return maxima in given axes of dataset
    1117         * @since 2.2
    1118         */
    1119        public Dataset max(int[] axes, boolean... ignoreInvalids);
    1120
    1121        /**
    1122         * @param axis
    1123         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1124         * @return minima along axis in dataset
    1125         * @since 2.0
    1126         */
    1127        public Dataset min(int axis, boolean... ignoreInvalids);
    1128
    1129        /**
    1130         * @param axes
    1131         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1132         * @return minima in given axes of dataset
    1133         * @since 2.2
    1134         */
    1135        public Dataset min(int[] axes, boolean... ignoreInvalids);
    1136
    1137        /**
    1138         * Find absolute index of maximum value (in a flattened view)
    1139         * @param ignoreInvalids - see {@link IDataset#max(boolean...)}
    1140         * @return absolute index
    1141         * @since 2.0
    1142         */
    1143        public int argMax(boolean... ignoreInvalids);
    1144
    1145        /**
    1146         * Find indices of maximum values along given axis
    1147         * @param axis
    1148         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1149         * @return index dataset
    1150         * @since 2.0
    1151         */
    1152        public Dataset argMax(int axis, boolean... ignoreInvalids);
    1153
    1154        /**
    1155         * Find absolute index of minimum value (in a flattened view)
    1156         * @param ignoreInvalids - see {@link IDataset#max(boolean...)}
    1157         * @return absolute index
    1158         * @since 2.0
    1159         */
    1160        public int argMin(boolean... ignoreInvalids);
    1161
    1162        /**
    1163         * Find indices of minimum values along given axis
    1164         * @param axis
    1165         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1166         * @return index dataset
    1167         * @since 2.0
    1168         */
    1169        public Dataset argMin(int axis, boolean... ignoreInvalids);
    1170
    1171        /**
    1172         * @param ignoreInvalids - see {@link IDataset#max(boolean...)}
    1173         * @return peak-to-peak value, the difference of maximum and minimum of dataset
    1174         * @since 2.0
    1175         */
    1176        public Number peakToPeak(boolean... ignoreInvalids);
    1177
    1178        /**
    1179         * @param axis
    1180         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1181         * @return peak-to-peak dataset, the difference of maxima and minima of dataset along axis
    1182         * @since 2.0
    1183         */
    1184        public Dataset peakToPeak(int axis, boolean... ignoreInvalids);
    1185
    1186        /**
    1187         * @param axes
    1188         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1189         * @return peak-to-peak dataset, the difference of maxima and minima of dataset in given axes
    1190         * @since 2.2
    1191         */
    1192        public Dataset peakToPeak(int[] axes, boolean... ignoreInvalids);
    1193
    1194        /**
    1195         * @param ignoreInvalids - see {@link IDataset#max(boolean...)}
    1196         * @return number of items in dataset
    1197         * @since 2.0
    1198         */
    1199        public long count(boolean... ignoreInvalids);
    1200
    1201        /**
    1202         * @param axis
    1203         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1204         * @return number of items along axis in dataset
    1205         * @since 2.0
    1206         */
    1207        public Dataset count(int axis, boolean... ignoreInvalids);
    1208
    1209        /**
    1210         * @param axes
    1211         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1212         * @return number of items in given axes of dataset
    1213         * @since 2.2
    1214         */
    1215        public Dataset count(int[] axes, boolean... ignoreInvalids);
    1216
    1217        /**
    1218         * @param ignoreInvalids - see {@link IDataset#max(boolean...)}
    1219         * @return sum over all items in dataset as a Double, array of doubles or a complex number
    1220         * @since 2.0
    1221         */
    1222        public Object sum(boolean... ignoreInvalids);
    1223
    1224        /**
    1225         * @param axis
    1226         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1227         * @return sum along axis in dataset
    1228         * @since 2.0
    1229         */
    1230        public Dataset sum(int axis, boolean... ignoreInvalids);
    1231
    1232        /**
    1233         * @param axes
    1234         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1235         * @return sum  in given axes of dataset
    1236         * @since 2.2
    1237         */
    1238        public Dataset sum(int[] axes, boolean... ignoreInvalids);
    1239
    1240        /**
    1241         * @param ignoreInvalids - see {@link IDataset#max(boolean...)}
    1242         * @return product over all items in dataset
    1243         * @since 2.0
    1244         */
    1245        public Object product(boolean... ignoreInvalids);
    1246
    1247        /**
    1248         * @param axis
    1249         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1250         * @return product along axis in dataset
    1251         * @since 2.0
    1252         */
    1253        public Dataset product(int axis, boolean... ignoreInvalids);
    1254
    1255        /**
    1256         * @param axes
    1257         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1258         * @return product in given axes of dataset
    1259         * @since 2.2
    1260         */
    1261        public Dataset product(int[] axes, boolean... ignoreInvalids);
    1262
    1263        /**
    1264         * @param axis
    1265         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1266         * @return mean along axis in dataset
    1267         * @since 2.0
    1268         */
    1269        public Dataset mean(int axis, boolean... ignoreInvalids);
    1270
    1271        /**
    1272         * @param axes
    1273         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1274         * @return mean in given axes of dataset
    1275         * @since 2.2
    1276         */
    1277        public Dataset mean(int[] axes, boolean... ignoreInvalids);
    1278
    1279        /**
    1280         * @return sample variance of whole dataset
    1281         * @see #variance(boolean, boolean...) with isWholePopulation = false
    1282         * @since 2.0
    1283         */
    1284        public double variance();
    1285
    1286        /**
    1287         * The sample variance can be calculated in two ways: if the dataset is considered as the
    1288         * entire population then the sample variance is simply the second central moment:
    1289         *
    1290         * <pre>
    1291         *    sum((x_i - m)^2)/N
    1292         * where {x_i} are set of N population values and m is the mean
    1293         *    m = sum(x_i)/N
    1294         * </pre>
    1295         *
    1296         * Otherwise, if the dataset is a set of samples (with replacement) from the population then
    1297         *
    1298         * <pre>
    1299         *    sum((x_i - m)^2)/(N-1)
    1300         * where {x_i} are set of N sample values and m is the unbiased estimate of the mean
    1301         *    m = sum(x_i)/N
    1302         * </pre>
    1303         *
    1304         * Note that the second definition is also the unbiased estimator of population variance.
    1305         *
    1306         * @param isWholePopulation
    1307         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1308         * @return sample variance
    1309         * @since 2.0
    1310         */
    1311        public double variance(boolean isWholePopulation, boolean... ignoreInvalids);
    1312
    1313        /**
    1314         * @param axis
    1315         * @return sample variance along axis in dataset
    1316         * @see #variance(int, boolean, boolean...) with isWholePopulation = false
    1317         */
    1318        public Dataset variance(int axis);
    1319
    1320        /**
    1321         * @param axes
    1322         * @return sample variance in given axes of dataset
    1323         * @see #variance(int[], boolean, boolean...) with isWholePopulation = false
    1324         * @since 2.2
    1325         */
    1326        public Dataset variance(int[] axes);
    1327
    1328        /**
    1329         * @param axis
    1330         * @param isWholePopulation
    1331         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1332         * @return sample variance along axis in dataset
    1333         * @since 2.0
    1334         */
    1335        public Dataset variance(int axis, boolean isWholePopulation, boolean... ignoreInvalids);
    1336
    1337        /**
    1338         * @param axes
    1339         * @param isWholePopulation
    1340         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1341         * @return sample variance in given axes of dataset
    1342         * @since 2.2
    1343         */
    1344        public Dataset variance(int[] axes, boolean isWholePopulation, boolean... ignoreInvalids);
    1345
    1346        /**
    1347         * Standard deviation is square root of the variance
    1348         *
    1349         * @return sample standard deviation of all items in dataset
    1350         * @see #stdDeviation(boolean, boolean...) with isWholePopulation = false
    1351         * @since 2.0
    1352         */
    1353        public double stdDeviation();
    1354
    1355        /**
    1356         * Standard deviation is square root of the variance
    1357         *
    1358         * @param isWholePopulation
    1359         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1360         * @return sample standard deviation of all items in dataset
    1361         * @see #variance(boolean, boolean...)
    1362         * @since 2.0
    1363         */
    1364        public double stdDeviation(boolean isWholePopulation, boolean... ignoreInvalids);
    1365
    1366        /**
    1367         * Standard deviation is square root of the variance
    1368         *
    1369         * @param axis
    1370         * @return standard deviation along axis in dataset
    1371         * @see #stdDeviation(int, boolean, boolean...) with isWholePopulation = false
    1372         */
    1373        public Dataset stdDeviation(int axis);
    1374
    1375        /**
    1376         * Standard deviation is square root of the variance
    1377         *
    1378         * @param axes
    1379         * @return standard deviation in given axes of dataset
    1380         * @see #stdDeviation(int[], boolean, boolean...) with isWholePopulation = false
    1381         * @since 2.2
    1382         */
    1383        public Dataset stdDeviation(int[] axes);
    1384
    1385        /**
    1386         * Standard deviation is square root of the variance
    1387         *
    1388         * @param axis
    1389         * @param isWholePopulation
    1390         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1391         * @return standard deviation along axis in dataset
    1392         * @since 2.0
    1393         */
    1394        public Dataset stdDeviation(int axis, boolean isWholePopulation, boolean... ignoreInvalids);
    1395
    1396        /**
    1397         * Standard deviation is square root of the variance
    1398         *
    1399         * @param axes
    1400         * @param isWholePopulation
    1401         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1402         * @return standard deviation in given axes of dataset
    1403         * @since 2.2
    1404         */
    1405        public Dataset stdDeviation(int[] axes, boolean isWholePopulation, boolean... ignoreInvalids);
    1406
    1407        /**
    1408         * @param ignoreInvalids - see {@link IDataset#max(boolean...)}
    1409         * @return root mean square
    1410         * @since 2.0
    1411         */
    1412        public double rootMeanSquare(boolean... ignoreInvalids);
    1413
    1414        /**
    1415         * @param axis
    1416         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1417         * @return root mean square along axis in dataset
    1418         * @since 2.0
    1419         */
    1420        public Dataset rootMeanSquare(int axis, boolean... ignoreInvalids);
    1421
    1422        /**
    1423         * @param axes
    1424         * @param ignoreInvalids - see {@link #max(int, boolean...)}
    1425         * @return root mean square in given axes of dataset
    1426         * @since 2.2
    1427         */
    1428        public Dataset rootMeanSquare(int[] axes, boolean... ignoreInvalids);
    1429}