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