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