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