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  import james.core.serialization.IConstructorParameterProvider;
20  import james.core.serialization.SerialisationUtils;
21  
22  import java.io.IOException;
23  import java.io.Serializable;
24  
25  import p3j.misc.Misc;
26  import p3j.misc.math.Matrix;
27  import p3j.misc.math.Matrix2D;
28  import p3j.pppm.IStochasticOccurrence;
29  
30  /**
31   * One assignment of a parameter instance. This is a matrix with a concrete
32   * name, a description, and a specific content (stored in
33   * {@link ParameterAssignment#matrix}). This is, in other words, the basic input
34   * for the PPPM. Each object is associated with a specific
35   * {@link ParameterInstance} and therefore with a specific {@link Parameter}. It
36   * also has a specific probability to occur, therefore
37   * {@link IStochasticOccurrence} is implemented.
38   * 
39   * Example for an assignment: TFR is constant at 1.3 for native population in
40   * the next 100 years.
41   * 
42   * Created on January 20, 2007
43   * 
44   * @author Christina Bohk
45   * @author Roland Ewald
46   * 
47   */
48  public class ParameterAssignment implements Serializable, IStochasticOccurrence {
49    static {
50      SerialisationUtils.addDelegateForConstructor(ParameterAssignment.class,
51          new IConstructorParameterProvider<ParameterAssignment>() {
52            @Override
53            public Object[] getParameters(ParameterAssignment assignment) {
54              Object[] params = null;
55              try {
56                params = new Object[] { assignment.getMatrixBinary(),
57                    assignment.getParamInstance(), assignment.getName(),
58                    assignment.getDescription(), assignment.getProbability(),
59                    assignment.getDeviation() };
60              } catch (IOException e) {
61                SimSystem.report(e);
62              }
63              return params;
64            }
65          });
66    }
67  
68    /** Serialization ID. */
69    private static final long serialVersionUID = 5672796759108189718L;
70  
71    /** ID of the assignment. */
72    private int id;
73  
74    /** Reference to parameter instance. */
75    private ParameterInstance paramInstance;
76  
77    /** Assigned value. */
78    private Matrix matrix;
79  
80    /** Name of this alternative. */
81    private String name = "";
82  
83    /** Description of this alternative. */
84    private String description = "";
85  
86    /** Probability of this alternative. */
87    private double probability;
88  
89    /**
90     * The deviation variable. It represents extra noise that should be included
91     * in the calculation. Default is zero, i.e. the same numbers that are put in
92     * are also returned.
93     */
94    private double deviation;
95  
96    /**
97     * Default constructor.
98     * 
99     * @param instance
100    *          parameter instance to which this assignment belongs
101    */
102   public ParameterAssignment(ParameterInstance instance) {
103     paramInstance = instance;
104   }
105 
106   /**
107    * Full constructor.
108    * 
109    * @param instance
110    *          the associated instance
111    * @param assignName
112    *          the name of the assignment
113    * @param desc
114    *          the description of the assignment
115    * @param prob
116    *          the probability of the assignment
117    * @param dev
118    *          the assumption-inherent deviation
119    * @param val
120    *          the assigned value
121    */
122   public ParameterAssignment(ParameterInstance instance, String assignName,
123       String desc, double prob, double dev, Matrix val) {
124     paramInstance = instance;
125     name = assignName;
126     description = desc;
127     probability = prob;
128     deviation = dev;
129     matrix = val;
130   }
131 
132   public ParameterAssignment() {
133   }
134 
135   /**
136    * Constructor for bean compatibility.
137    * 
138    * @throws IOException
139    * @throws ClassNotFoundException
140    */
141   public ParameterAssignment(String matrixString, ParameterInstance instance,
142       String assignName, String desc, double prob, double dev)
143       throws ClassNotFoundException, IOException {
144     this(instance, assignName, desc, prob, dev, (Matrix) SerialisationUtils
145         .deserializeFromB64String(matrixString));
146   }
147 
148   /**
149    * Sets matrix from a byte array (for deserialization).
150    * 
151    * @param matrixString
152    *          the byte array which contains the persistent matrix object
153    * @throws IOException
154    * @throws ClassNotFoundException
155    */
156   public void setMatrixBinary(String matrixString)
157       throws ClassNotFoundException, IOException {
158     matrix = (Matrix) SerialisationUtils.deserializeFromB64String(matrixString);
159   }
160 
161   /**
162    * Returns the matrix value as a byte array (for serialization).
163    * 
164    * @return byte representation of assignment value (a matrix object)
165    * @throws IOException
166    */
167   public String getMatrixBinary() throws IOException {
168     return SerialisationUtils.serializeToB64String(matrix);
169   }
170 
171   /**
172    * Copies the assignment. This produces a deep copy, i.e., the value matrix is
173    * copied too.
174    * 
175    * @return a copy of the parameter assignment
176    */
177   public ParameterAssignment getCopy() {
178 
179     ParameterAssignment returnAssignment = new ParameterAssignment(
180         getParamInstance());
181     returnAssignment.description = description;
182     returnAssignment.name = name;
183     returnAssignment.probability = probability;
184     returnAssignment.matrix = matrix.copy();
185 
186     return returnAssignment;
187   }
188 
189   @Override
190   public String toString() {
191     return getName() + " (" + Misc.round(getProbability(), 2) + ")";
192   }
193 
194   // Getter/Setter for bean compatibility
195 
196   @Override
197   public double getProbability() {
198     return probability;
199   }
200 
201   @Override
202   public void setProbability(double probability) {
203     this.probability = probability;
204   }
205 
206   public String getDescription() {
207     return description;
208   }
209 
210   public void setDescription(String description) {
211     this.description = description;
212   }
213 
214   public String getName() {
215     return name;
216   }
217 
218   public void setName(String name) {
219     this.name = name;
220   }
221 
222   public Matrix getMatrix() {
223     return matrix;
224   }
225 
226   public void setMatrix(Matrix matrix) {
227     this.matrix = matrix;
228   }
229 
230   /**
231    * Sets the matrix value.
232    * 
233    * @param matrix2D
234    *          the new matrix value
235    */
236   public void setMatrixValue(Matrix2D matrix2D) {
237     // An empty matrix is not a valid value, but set by the xml decoder - ignore
238     // this
239     if (matrix2D.rows() == 0 && matrix2D.columns() == 0) {
240       return;
241     }
242 
243     if (matrix == null) {
244       matrix = new Matrix(matrix2D);
245     } else {
246       matrix.setValue(matrix2D);
247     }
248   }
249 
250   /**
251    * This method returns the fixed matrix values, as entered by the user.
252    * 
253    * @return the matrix values entered by the user
254    */
255   public Matrix2D getMatrixValue() {
256     return matrix.getValue();
257   }
258 
259   public ParameterInstance getParamInstance() {
260     return paramInstance;
261   }
262 
263   public void setParamInstance(ParameterInstance paramInstance) {
264     this.paramInstance = paramInstance;
265   }
266 
267   public int getID() {
268     return id;
269   }
270 
271   public void setID(int uniqueID) {
272     id = uniqueID;
273   }
274 
275   public double getDeviation() {
276     return deviation;
277   }
278 
279   /**
280    * Sets deviation. Compatibility with older databases (which do not
281    * necessarily include this field) is ensured by taking a {@link Double} as a
282    * parameter, which can be null. This is checked, and the primitive is set
283    * accordingly.
284    * 
285    * @param newDeviation
286    *          the deviation
287    */
288   public void setDeviation(Double newDeviation) {
289     if (newDeviation == null || newDeviation < 0) {
290       this.deviation = 0;
291     } else {
292       this.deviation = newDeviation;
293     }
294   }
295 
296 }