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}