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