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