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