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