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