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. Can be null when interface is not defined 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 to set 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 * @return this 072 */ 073 public ILazyDataset squeezeEnds(); 074 075 /** 076 * Get a slice of the dataset. The returned dataset is a copied selection of items 077 * 078 * @param start 079 * specifies the starting indexes (can be null for origin) 080 * @param stop 081 * specifies the stopping indexes (can be null for end) 082 * @param step 083 * specifies the steps in the slice (can be null for unit steps) 084 * @return The dataset of the sliced data 085 * @throws DatasetException when cannot retrieve slice of lazy dataset 086 */ 087 public IDataset getSlice(final int[] start, final int[] stop, final int[] step) throws DatasetException; 088 089 /** 090 * Get a slice of the dataset. The returned dataset is a copied selection of items 091 * 092 * @param monitor can be null 093 * @param start 094 * specifies the starting indexes (can be null for origin) 095 * @param stop 096 * specifies the stopping indexes (can be null for end) 097 * @param step 098 * specifies the steps in the slice (can be null for unit steps) 099 * @return The dataset of the sliced data 100 * @throws DatasetException when cannot retrieve slice of lazy dataset 101 */ 102 public IDataset getSlice(final IMonitor monitor, final int[] start, final int[] stop, 103 final int[] step) throws DatasetException; 104 105 /** 106 * Get a slice of the dataset. The returned dataset is a copied selection of items 107 * 108 * @param slice an array of slice objects (the array can be null or contain nulls) 109 * @return The dataset of the sliced data 110 * @throws DatasetException when cannot retrieve slice of lazy dataset 111 */ 112 public IDataset getSlice(final Slice... slice) throws DatasetException; 113 114 /** 115 * Get a slice of the dataset. The returned dataset is a copied selection of items 116 * 117 * @param monitor can be null 118 * @param slice an array of slice objects (the array can be null or contain nulls) 119 * @return The dataset of the sliced data 120 * @throws DatasetException when cannot retrieve slice of lazy dataset 121 */ 122 public IDataset getSlice(final IMonitor monitor, final Slice... slice) throws DatasetException; 123 124 /** 125 * Get a slice of the dataset. The returned dataset is a copied selection of items 126 * 127 * @param slice an n-D slice 128 * @return The dataset of the sliced data 129 * @throws DatasetException when cannot retrieve slice of lazy dataset 130 */ 131 public IDataset getSlice(final SliceND slice) throws DatasetException; 132 133 /** 134 * Get a slice of the dataset. The returned dataset is a copied selection of items 135 * 136 * @param monitor can be null 137 * @param slice an n-D slice 138 * @return The dataset of the sliced data 139 * @throws DatasetException when cannot retrieve slice of lazy dataset 140 */ 141 public IDataset getSlice(final IMonitor monitor, final SliceND slice) throws DatasetException; 142 143 /** 144 * Get a slice of the dataset. The returned lazy dataset is a view on a selection of items 145 * 146 * @param start 147 * specifies the starting indexes (can be null for origin) 148 * @param stop 149 * specifies the stopping indexes (can be null for end) 150 * @param step 151 * specifies the steps in the slice (can be null for unit steps) 152 * @return The sliced view of a lazy dataset 153 */ 154 public ILazyDataset getSliceView(final int[] start, final int[] stop, final int[] step); 155 156 /** 157 * Get a slice of the dataset. The returned lazy dataset is a view on a selection of items 158 * 159 * @param slice an array of slice objects (the array can be null or contain nulls) 160 * @return The sliced view of a lazy dataset 161 */ 162 public ILazyDataset getSliceView(final Slice... slice); 163 164 /** 165 * Get a slice of the dataset. The returned lazy dataset is a view on a selection of items 166 * 167 * @param slice an n-D slice 168 * @return The sliced view of a lazy dataset 169 */ 170 public ILazyDataset getSliceView(final SliceND slice); 171 172 /** 173 * Permute copy of dataset's axes so that given order is old order: 174 * 175 * <pre>{@literal 176 * axisPerm = (p(0), p(1),...) => newdata(n(0), n(1),...) = olddata(o(0), o(1), ...) 177 * such that n(i) = o(p(i)) for all i 178 * }</pre> 179 * 180 * I.e. for a 3D dataset (1,0,2) implies the new dataset has its 1st dimension running along 181 * the old dataset's 2nd dimension and the new 2nd is the old 1st. The 3rd dimension is left 182 * unchanged. 183 * 184 * @param axes 185 * if zero length then axes order reversed 186 * @return remapped view of data 187 */ 188 public ILazyDataset getTransposedView(int... axes); 189 190 /** 191 * Add metadata to the dataset 192 * 193 * @param metadata to add 194 */ 195 public void addMetadata(final MetadataType metadata); 196 197 /** 198 * Set metadata on the dataset 199 * 200 * @param metadata (null is ignored so use clear(null) instead) 201 */ 202 public void setMetadata(MetadataType metadata); 203 204 /** 205 * Remove metadata of given class 206 * @param clazz if null remove everything 207 */ 208 public void clearMetadata(Class<? extends MetadataType> clazz); 209 210 /** 211 * Clone dataset 212 * @return a (shallow) copy of dataset 213 */ 214 public ILazyDataset clone(); 215 216 /** 217 * Set the errors. It may be a single double, a double array or a 218 * whole dataset that can broadcast to the dataset 219 * 220 * @param errors - may be null to remove the error set 221 * @throws RuntimeException if the rank or shape are incorrect 222 * @since 2.0 223 */ 224 public void setErrors(Serializable errors); 225 226 /** 227 * Get the errors, if any. These will be in a shape that can broadcast to the dataset 228 * @return errors 229 * @since 2.0 230 */ 231 public ILazyDataset getErrors(); 232 233 /** 234 * If error information is set, returns true. 235 * Faster to call than getError() which constructs a 236 * new dataset. 237 * 238 * @return true if there is error data. 239 */ 240 public boolean hasErrors(); 241}