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.DatasetException; 018import org.eclipse.january.IMonitor; 019import org.eclipse.january.INameable; 020import org.eclipse.january.metadata.MetadataType; 021 022/** 023 * This interface defines the lazy parts of a dataset. A dataset is a N-dimensional array of items 024 * where N can be zero to represent a zero-rank or single-valued dataset. A zero-rank dataset has 025 * an empty array for shape. An item comprises a number of elements. 026 */ 027public interface ILazyDataset extends Serializable, IMetadataProvider, INameable { 028 029 /** 030 * @return Boxed class of element 031 */ 032 public Class<?> getElementClass(); 033 034 /** 035 * @return Number of elements per item 036 */ 037 public int getElementsPerItem(); 038 039 /** 040 * The size of the dataset is the number of items in the array 041 * 042 * @return number of data items 043 */ 044 public int getSize(); 045 046 /** 047 * The shape (or array of lengths for each dimension) of the dataset can be empty for zero-rank 048 * datasets 049 * 050 * @return Copy of shape of dataset 051 */ 052 public int[] getShape(); 053 054 /** 055 * Set a compatible shape for dataset. A shape is compatible if it has the capacity to contain 056 * the same number of items 057 * 058 * @param shape 059 */ 060 public void setShape(final int... shape); 061 062 /** 063 * The rank (or number of dimensions/indices) of the dataset can be zero for a zero-rank 064 * (single-valued) dataset 065 * @return rank 066 */ 067 public int getRank(); 068 069 /** 070 * Remove dimensions of 1 from ends of shape of the dataset 071 */ 072 public ILazyDataset squeezeEnds(); 073 074 /** 075 * Get a slice of the dataset. The returned dataset is a copied selection of items 076 * 077 * @param start 078 * specifies the starting indexes (can be null for origin) 079 * @param stop 080 * specifies the stopping indexes (can be null for end) 081 * @param step 082 * specifies the steps in the slice (can be null for unit steps) 083 * @return The dataset of the sliced data 084 * @throws DatasetException 085 */ 086 public IDataset getSlice(final int[] start, final int[] stop, final int[] step) throws DatasetException; 087 088 /** 089 * Get a slice of the dataset. The returned dataset is a copied selection of items 090 * 091 * @param monitor 092 * @param start 093 * specifies the starting indexes (can be null for origin) 094 * @param stop 095 * specifies the stopping indexes (can be null for end) 096 * @param step 097 * specifies the steps in the slice (can be null for unit steps) 098 * @return The dataset of the sliced data 099 * @throws DatasetException 100 */ 101 public IDataset getSlice(final IMonitor monitor, final int[] start, final int[] stop, 102 final int[] step) throws DatasetException; 103 104 /** 105 * Get a slice of the dataset. The returned dataset is a copied selection of items 106 * 107 * @param slice an array of slice objects (the array can be null or contain nulls) 108 * @return The dataset of the sliced data 109 * @throws DatasetException 110 */ 111 public IDataset getSlice(final Slice... slice) throws DatasetException; 112 113 /** 114 * Get a slice of the dataset. The returned dataset is a copied selection of items 115 * 116 * @param monitor 117 * @param slice an array of slice objects (the array can be null or contain nulls) 118 * @return The dataset of the sliced data 119 * @throws DatasetException 120 */ 121 public IDataset getSlice(final IMonitor monitor, final Slice... slice) throws DatasetException; 122 123 /** 124 * Get a slice of the dataset. The returned dataset is a copied selection of items 125 * 126 * @param slice an n-D slice 127 * @return The dataset of the sliced data 128 * @throws DatasetException 129 */ 130 public IDataset getSlice(final SliceND slice) throws DatasetException; 131 132 /** 133 * Get a slice of the dataset. The returned dataset is a copied selection of items 134 * 135 * @param monitor 136 * @param slice an n-D slice 137 * @return The dataset of the sliced data 138 * @throws DatasetException 139 */ 140 public IDataset getSlice(final IMonitor monitor, final SliceND slice) throws DatasetException; 141 142 /** 143 * Get a slice of the dataset. The returned lazy dataset is a view on a selection of items 144 * 145 * @param start 146 * specifies the starting indexes (can be null for origin) 147 * @param stop 148 * specifies the stopping indexes (can be null for end) 149 * @param step 150 * specifies the steps in the slice (can be null for unit steps) 151 * @return The sliced view of a lazy dataset 152 */ 153 public ILazyDataset getSliceView(final int[] start, final int[] stop, final int[] step); 154 155 /** 156 * Get a slice of the dataset. The returned lazy dataset is a view on a selection of items 157 * 158 * @param slice an array of slice objects (the array can be null or contain nulls) 159 * @return The sliced view of a lazy dataset 160 */ 161 public ILazyDataset getSliceView(final Slice... slice); 162 163 /** 164 * Get a slice of the dataset. The returned lazy dataset is a view on a selection of items 165 * 166 * @param slice an n-D slice 167 * @return The sliced view of a lazy dataset 168 */ 169 public ILazyDataset getSliceView(final SliceND slice); 170 171 /** 172 * Permute copy of dataset's axes so that given order is old order: 173 * 174 * <pre> 175 * axisPerm = (p(0), p(1),...) => newdata(n(0), n(1),...) = olddata(o(0), o(1), ...) 176 * such that n(i) = o(p(i)) for all i 177 * </pre> 178 * 179 * I.e. for a 3D dataset (1,0,2) implies the new dataset has its 1st dimension running along 180 * the old dataset's 2nd dimension and the new 2nd is the old 1st. The 3rd dimension is left 181 * unchanged. 182 * 183 * @param axes 184 * if zero length then axes order reversed 185 * @return remapped view of data 186 */ 187 public ILazyDataset getTransposedView(int... axes); 188 189 /** 190 * Add metadata to the dataset 191 * 192 * @param metadata 193 */ 194 public void addMetadata(final MetadataType metadata); 195 196 /** 197 * Set metadata on the dataset 198 * 199 * @param metadata (null is ignored so use clear(null) instead) 200 */ 201 public void setMetadata(MetadataType metadata); 202 203 /** 204 * Remove metadata of given class 205 * @param clazz if null remove everything 206 */ 207 public void clearMetadata(Class<? extends MetadataType> clazz); 208 209 /** 210 * Clone dataset 211 * @return a (shallow) copy of dataset 212 */ 213 public ILazyDataset clone(); 214 215 /** 216 * Set the errors. It may be a single double, a double array or a 217 * whole dataset that can broadcast to the dataset 218 * 219 * @param errors - may be null to remove the error set 220 * @throws RuntimeException if the rank or shape are incorrect 221 * @since 2.0 222 */ 223 public void setErrors(Serializable errors); 224 225 /** 226 * Get the errors, if any. These will be in a shape that can broadcast to the dataset 227 * @since 2.0 228 */ 229 public ILazyDataset getErrors(); 230 231 /** 232 * If error information is set, returns true. 233 * Faster to call than getError() which constructs a 234 * new dataset. 235 * 236 * @return true if there is error data. 237 */ 238 public boolean hasErrors(); 239}