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