View Javadoc

1   /*
2    * Copyright 2006 - 2012 Christina Bohk and Roland Ewald
3    *  
4    * Licensed under the Apache License, Version 2.0 (the "License"); 
5    * you may not use this file except in compliance with the License. 
6    * You may obtain a copy of the License at 
7    *  
8    *  http://www.apache.org/licenses/LICENSE-2.0
9    *  
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
13   * See the License for the specific language governing permissions and 
14   * limitations under the License. 
15   */
16  package p3j.pppm.parameters;
17  
18  import james.SimSystem;
19  
20  import java.io.ByteArrayInputStream;
21  import java.io.ByteArrayOutputStream;
22  import java.io.IOException;
23  import java.io.ObjectInputStream;
24  import java.io.ObjectOutputStream;
25  import java.io.Serializable;
26  import java.util.logging.Level;
27  
28  import p3j.misc.Misc;
29  import p3j.misc.math.Matrix;
30  import p3j.misc.math.Matrix2D;
31  import p3j.pppm.IStochasticOccurrence;
32  
33  /**
34   * One assignment of a parameter instance. This is a matrix with a concrete
35   * name, a description, and a specific content (stored in
36   * {@link ParameterAssignment#matrix}). This is, in other words, the basic input
37   * for the PPPM. Each object is associated with a specific
38   * {@link ParameterInstance} and therefore with a specific {@link Parameter}. It
39   * also has a specific probability to occur, therefore
40   * {@link IStochasticOccurrence} is implemented.
41   * 
42   * Example for an assignment: TFR is constant at 1.3 for native population in
43   * the next 100 years.
44   * 
45   * Created on January 20, 2007
46   * 
47   * @author Christina Bohk
48   * @author Roland Ewald
49   * 
50   */
51  public class ParameterAssignment implements Serializable, IStochasticOccurrence {
52  
53  	/** Serialization ID. */
54  	private static final long serialVersionUID = 5672796759108189718L;
55  
56  	/** ID of the assignment. */
57  	private int id;
58  
59  	/** Reference to parameter instance. */
60  	private ParameterInstance paramInstance;
61  
62  	/** Assigned value. */
63  	private Matrix matrix;
64  
65  	/** Name of this alternative. */
66  	private String name = "";
67  
68  	/** Description of this alternative. */
69  	private String description = "";
70  
71  	/** Probability of this alternative. */
72  	private double probability;
73  
74  	/**
75  	 * The deviation variable. It represents extra noise that should be included
76  	 * in the calculation. Default is zero, i.e. the same numbers that are put in
77  	 * are also returned.
78  	 */
79  	private double deviation;
80  
81  	/**
82  	 * Default constructor.
83  	 * 
84  	 * @param instance
85  	 *          parameter instance to which this assignment belongs
86  	 */
87  	public ParameterAssignment(ParameterInstance instance) {
88  		paramInstance = instance;
89  	}
90  
91  	/**
92  	 * Full constructor.
93  	 * 
94  	 * @param instance
95  	 *          the associated instance
96  	 * @param assignName
97  	 *          the name of the assignment
98  	 * @param desc
99  	 *          the description of the assignment
100 	 * @param prob
101 	 *          the probability of the assignment
102 	 * @param dev
103 	 *          the assumption-inherent deviation
104 	 * @param val
105 	 *          the assigned value
106 	 */
107 	public ParameterAssignment(ParameterInstance instance, String assignName,
108 	    String desc, double prob, double dev, Matrix val) {
109 		paramInstance = instance;
110 		name = assignName;
111 		description = desc;
112 		probability = prob;
113 		deviation = dev;
114 		matrix = val;
115 	}
116 
117 	/**
118 	 * Constructor for bean compatibility.
119 	 */
120 	public ParameterAssignment() {
121 
122 	}
123 
124 	/**
125 	 * Sets matrix from a byte array (for deserialization).
126 	 * 
127 	 * @param byteArray
128 	 *          the byte array which contains the persistent matrix object
129 	 */
130 	public void setMatrixBinary(byte[] byteArray) {
131 		ByteArrayInputStream inputStream = new ByteArrayInputStream(byteArray);
132 		try {
133 			ObjectInputStream objectInputStream = new ObjectInputStream(inputStream);
134 			matrix = (Matrix) objectInputStream.readObject();
135 			objectInputStream.close();
136 		} catch (Exception ex) {
137 			SimSystem.report(Level.SEVERE, "Deserialization of matrix failed.", ex);
138 		}
139 	}
140 
141 	/**
142 	 * Returns the matrix value as a byte array (for serialization).
143 	 * 
144 	 * @return byte representation of assignment value (a matrix object)
145 	 */
146 	public byte[] getMatrixBinary() {
147 		ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
148 		try {
149 			ObjectOutputStream objectOutputStream = new ObjectOutputStream(
150 			    outputStream);
151 			objectOutputStream.writeObject(matrix);
152 			objectOutputStream.close();
153 		} catch (IOException ex) {
154 			SimSystem.report(Level.SEVERE, "Serialization of matrix failed.", ex);
155 		}
156 		return outputStream.toByteArray();
157 	}
158 
159 	/**
160 	 * Copies the assignment. This produces a deep copy, i.e., the value matrix is
161 	 * copied too.
162 	 * 
163 	 * @return a copy of the parameter assignment
164 	 */
165 	public ParameterAssignment getCopy() {
166 
167 		ParameterAssignment returnAssignment = new ParameterAssignment(
168 		    getParamInstance());
169 		returnAssignment.description = description;
170 		returnAssignment.name = name;
171 		returnAssignment.probability = probability;
172 		returnAssignment.matrix = matrix.copy();
173 
174 		return returnAssignment;
175 	}
176 
177 	@Override
178 	public String toString() {
179 		return getName() + " (" + Misc.round(getProbability(), 2) + ")";
180 	}
181 
182 	// Getter/Setter for bean compatibility
183 
184 	@Override
185 	public double getProbability() {
186 		return probability;
187 	}
188 
189 	@Override
190 	public void setProbability(double probability) {
191 		this.probability = probability;
192 	}
193 
194 	public String getDescription() {
195 		return description;
196 	}
197 
198 	public void setDescription(String description) {
199 		this.description = description;
200 	}
201 
202 	public String getName() {
203 		return name;
204 	}
205 
206 	public void setName(String name) {
207 		this.name = name;
208 	}
209 
210 	public Matrix getMatrix() {
211 		return matrix;
212 	}
213 
214 	public void setMatrix(Matrix matrix) {
215 		this.matrix = matrix;
216 	}
217 
218 	/**
219 	 * Sets the matrix value.
220 	 * 
221 	 * @param matrix2D
222 	 *          the new matrix value
223 	 */
224 	public void setMatrixValue(Matrix2D matrix2D) {
225 		if (matrix == null) {
226 			matrix = new Matrix(matrix2D);
227 		} else {
228 			matrix.setValue(matrix2D);
229 		}
230 	}
231 
232 	/**
233 	 * This method returns the fixed matrix values, as entered by the user. It
234 	 * should NOT be called to get values for any calculations, only for editing.
235 	 * For calculations, call {@link
236 	 * ParameterAssignment#getMatrixValueForExecution(...)}.
237 	 * 
238 	 * @return the matrix values entered by the user
239 	 */
240 	public Matrix2D getMatrixValue() {
241 		return matrix.getValue();
242 	}
243 
244 	public ParameterInstance getParamInstance() {
245 		return paramInstance;
246 	}
247 
248 	public void setParamInstance(ParameterInstance paramInstance) {
249 		this.paramInstance = paramInstance;
250 	}
251 
252 	public int getID() {
253 		return id;
254 	}
255 
256 	public void setID(int uniqueID) {
257 		id = uniqueID;
258 	}
259 
260 	public double getDeviation() {
261 		return deviation;
262 	}
263 
264 	/**
265 	 * Sets deviation. Compatibility with older databases (which do not
266 	 * necessarily include this field) is ensured by taking a {@link Double} as a
267 	 * parameter, which can be null. This is checked, and the primitive is set
268 	 * accordingly.
269 	 * 
270 	 * @param newDeviation
271 	 *          the deviation
272 	 */
273 	public void setDeviation(Double newDeviation) {
274 		if (newDeviation == null || newDeviation < 0) {
275 			this.deviation = 0;
276 		} else {
277 			this.deviation = newDeviation;
278 		}
279 	}
280 
281 }