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