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