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.text.Format; 016 017import org.eclipse.january.metadata.IMetadata; 018 019 020/** 021 * This interface defines the implementation-independent and generic parts of a dataset. 022 * <p> 023 * The position array used in the getters 024 */ 025public interface IDataset extends ILazyDataset { 026 /** 027 * Set string output format 028 * @param format to output 029 */ 030 public void setStringFormat(Format format); 031 032 /** 033 * @return Size of an item in dataset in bytes 034 */ 035 public int getItemBytes(); 036 037 /** 038 * @param pos position 039 * @return Item in given position as an object 040 */ 041 public Object getObject(final int... pos); 042 043 /** 044 * @param pos position 045 * @return Item in given position as a string 046 */ 047 public String getString(final int... pos); 048 049 /** 050 * @param pos position 051 * @return Item in given position as a double 052 */ 053 public double getDouble(final int... pos); 054 055 /** 056 * @param pos position 057 * @return Item in given position as a long 058 */ 059 public long getLong(final int... pos); 060 061 /** 062 * @param pos position 063 * @return Item in given position as a float 064 */ 065 public float getFloat(final int... pos); 066 067 /** 068 * @param pos position 069 * @return Item in given position as an int 070 */ 071 public int getInt(final int... pos); 072 073 /** 074 * @param pos position 075 * @return Item in given position as a short 076 */ 077 public short getShort(final int... pos); 078 079 /** 080 * @param pos position 081 * @return Item in given position as a byte 082 */ 083 public byte getByte(final int... pos); 084 085 /** 086 * @param pos position 087 * @return Item in given position as a boolean 088 */ 089 public boolean getBoolean(final int... pos); 090 091 /** 092 * Set the value given by object at given position 093 * @param obj value to set 094 * @param pos position 095 */ 096 public void set(final Object obj, final int... pos); 097 098 /** 099 * Change shape and size of dataset in-place 100 * @param newShape to use 101 */ 102 public void resize(int... newShape); 103 104 @Override 105 public IDataset squeezeEnds(); 106 107 /** 108 * Remove dimensions of 1 in shape of the dataset 109 * @return this 110 */ 111 public IDataset squeeze(); 112 113 /** 114 * Remove dimensions of 1 in shape of the dataset from ends only if true 115 * 116 * @param onlyFromEnds if true, trim ends 117 * @return this 118 */ 119 public IDataset squeeze(boolean onlyFromEnds); 120 121 /** 122 * @param ignoreInvalids - Can be null, empty, or one or more booleans. By default, all booleans 123 * are false. If the first boolean is true, will ignore NaNs and ignore infinities. Use the second 124 * boolean to ignore infinities separately. 125 * @return Maximum value 126 * @throws UnsupportedOperationException if comparisons are not valid 127 */ 128 public Number max(boolean... ignoreInvalids); 129 130 /** 131 * @param ignoreInvalids - see {@link #max(boolean...)} 132 * @return mean of all items in dataset as a double, array of doubles or a complex number 133 */ 134 public Object mean(boolean... ignoreInvalids); 135 136 /** 137 * @param ignoreInvalids - see {@link #max(boolean...)} 138 * @return Minimum value 139 * @throws UnsupportedOperationException if comparisons are not valid 140 */ 141 public Number min(boolean... ignoreInvalids); 142 143 /** 144 * @param ignoreInvalids - see {@link #max(boolean...)} 145 * @return Position of minimum value (or first position if there are more than one) 146 * @since 2.0 147 */ 148 public int[] minPos(boolean... ignoreInvalids); 149 150 /** 151 * @param ignoreInvalids - see {@link #max(boolean...)} 152 * @return Position of maximum value (or first position if there are more than one) 153 * @since 2.0 154 */ 155 public int[] maxPos(boolean... ignoreInvalids); 156 157 /** 158 * Clone dataset, making new copy of data 159 * @return a (deep) copy of dataset 160 */ 161 @Override 162 public IDataset clone(); 163 164 /** 165 * @deprecated Use {@code getFirstMetadata(IMetadata.class)} instead 166 * @return an instance of IMetadata, may be null 167 */ 168 @Override 169 @Deprecated 170 public IMetadata getMetadata(); 171 172 @Override 173 public IDataset getSlice(int[] start, int[] stop, int[] step); 174 175 @Override 176 public IDataset getSlice(Slice... slice); 177 178 @Override 179 public IDataset getSlice(SliceND slice); 180 181 182 /** 183 * Get a slice of the dataset. The returned dataset is a view on a selection of items 184 * 185 * @param start 186 * specifies the starting indexes (can be null for origin) 187 * @param stop 188 * specifies the stopping indexes (can be null for end) 189 * @param step 190 * specifies the steps in the slice (can be null for unit steps) 191 * @return The sliced view of a dataset 192 */ 193 @Override 194 public IDataset getSliceView(int[] start, int[] stop, int[] step); 195 196 /** 197 * Get a slice of the dataset. The returned dataset is a view on a selection of items 198 * 199 * @param slice an array of slice objects (the array can be null or contain nulls) 200 * @return The sliced view of a dataset 201 */ 202 @Override 203 public IDataset getSliceView(Slice... slice); 204 205 /** 206 * Get a slice of the dataset. The returned dataset is a view on a selection of items 207 * 208 * @param slice an nD slice object 209 * @return The sliced view of a dataset 210 */ 211 @Override 212 public IDataset getSliceView(SliceND slice); 213 214 /** 215 * Permute copy of dataset's axes so that given order is old order: 216 * 217 * <pre>{@literal 218 * axisPerm = (p(0), p(1),...) => newdata(n(0), n(1),...) = olddata(o(0), o(1), ...) 219 * such that n(i) = o(p(i)) for all i 220 * }</pre> 221 * 222 * I.e. for a 3D dataset (1,0,2) implies the new dataset has its 1st dimension running along 223 * the old dataset's 2nd dimension and the new 2nd is the old 1st. The 3rd dimension is left 224 * unchanged. 225 * 226 * @param axes 227 * if zero length then axes order reversed 228 * @return remapped view of data 229 */ 230 @Override 231 IDataset getTransposedView(int... axes); 232 233 /** 234 * 235 * @return the error dataset, constructing one if necessary 236 * @since 2.0 237 */ 238 @Override 239 public IDataset getErrors(); 240 241 /** 242 * Get the error for a given position. 243 * @param pos position 244 * @return error value (symmetric) 245 */ 246 public double getError(int... pos); 247 248 /** 249 * Get the error values for a single point in the dataset 250 * @param pos position 251 * @return the values of the error at this point (can be null when no error defined) 252 */ 253 public double[] getErrorArray(int... pos); 254}