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