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