Input justification

The Constructor software, and perhaps Francis Baumont de Oliveira's Vertical Farming software, use a scheme that encourages users to document the justifications for any parameters they specify as input. The software tracks inputs and decisions to create self-documenting input files that keep tabs on the magnitude and its units, uncertainty, provenance, and justification including any relevant references and data.

Constructor strongly encourages you to enter explicit justifications for all the numerical entries and list choices you make in specifying what’s known about the uncertain number on any of the tabbed input pages. This section explains how Constructor uses justification dialogs to let you record the reasoning and ancillary details that you had in mind when you decided the value or choice you intended to use for any of these inputs. With the justifications you enter, the program creates self-documenting input files that can help you keep track of the

• • input description of the value, including its units,

  • interpreted value and units after any internal dimensional conversion,

  • format of the uncertainty characterisation,

  • nature of the estimate or observation,

  • agent or agency who estimated or vouches for the value,

  • justifying arguments or reason, and

  • relevant references and supporting data.

This information can be collected together in a survey by selecting Justification/Survey from the main menu. This survey can be printed or captured for inclusion in reports.

Different input fields on the several input pages have separate justifications, except that a spreadsheet (such as those appearing on the Data, Density and Graph pages) have only one justification for all the cells in the spreadsheet, considered as a group. This is mostly a matter of convenience, as the task of justifying individual data points could be quite daunting. The justification for the spreadsheet should certainly include a discussion of any outliers or other values within the data sets that merit special mention or focus.

If an input field is color-coded yellow, Constructor is telling you that the value needs justification. You needn’t wait for a field to be yellow however. You can give justifications for white input fields just as well. By design, the input fields on the “Name and units” page are exempt from color coding, so they do not become yellow. Nevertheless, you can give justifications for most of these inputs too. The only input fields for which justifications are not supported are the description and references inputs on the “Name and units” page, and the inputs comprising the justifications themselves.

Your justifications and the supporting and ancillary information for each input are organized on a justification dialog for that input. You can invoke the justification dialog by right-clicking on any input field. Right-clicking on the mean field on the Parameters page invokes the justification dialog shown in Figure 30 below.

Figure 30.

This justification dialog is typical of what you’ll see for any of other numerical inputs in Constructor. You can tell which input you are justifying by the title at the top of the justification dialog. Justification dialogs for list choices and non-numeric inputs have fewer fields. For instance, the ensemble field on the Name and units page only has fields for the informant, justification and references. The justification dialog for the unimodal box on the Shape page has these three plus fields for the nature and history.

Original. The first field of the justification dialog is a record of the input that you first made for the quantity. It remembers what you said you knew about the value, with its original expression of uncertainty and in its original units. The ability to recollect this original expression is obviously important for the sake of tracking information quality. If you had typed anything on the numeric field on which you right-clicked, the value would automatically appear on the original field on the justification dialog. You can edit the contents of the original field. This gives you the ability to revise and extend your original statement. Any changes you make will be reflected on the input field when you close the justification dialog.

Every numerical value representing a physical quantity (rather than some purely mathematical entity) should be accompanied by an explicit and unambiguous expression of the units in which the quantity is expressed. You may elect to have Constructor infer the units of each value you enter from the default units you specified on the “Name and units” page. If you do, then the original field can simply be a number without any units. This might be convenient when initially entering values, but it could make changing the default units later more difficult. You might want to change the default units, for instance, if you wanted to change the units of the output that Constructor produces.

In any case, you can always specify the units for the quantities explicitly as you enter them. Just put the units after the numeric value, as in the expressions “[1,3] meters” or “[40 sec, 2 minutes]”. When you’re giving the units for the variance, remember that they should be squared, and that the coefficient of variation and probabilities are always dimensionless.) Generally, the units you give should be the original units in which the quantity was measured or otherwise estimated. If the units for any quantity are not the same as the default units you gave on the “Name and units” page, the program will automatically convert* the value to the necessary units whenever it uses the value in calculations, or generate an error message if the units cannot be so converted.

Interpreted. The interpreted field on the justification dialog spells out how Constructor interpreted your original input. This interpretation depends not only on the original input you made, but on the default units you specified on the “Name and units” page, and any subsequent inferences drawn from information about other fields.

The plot at the bottom of the justification dialog graphically displays both the original and the interpreted values. By default, the former appears in green and the latter appears in yellow. The interpreted estimate is usually only narrower than the original value’s uncertainty. The vertical distance on the plot is not meaningful.

Uncertainty. The uncertainty field on the justification dialog provides a space for you to characterize the uncertainty present in your expression for the quantity. You can type anything at all you like in this field. If you click on the little down arrow at the far right of the input field, you’ll see a list of the kinds of characterizations you might make. If you do, the display will look like Figure 31.

Figure 31.

You can choose one of these characterizations of uncertainty by clicking on it in the drop down list. Doing so will overwrite any text you might already have entered in the field. If none of these characterization quite fit, don’t hesitate to give a different characterization that is more appropriate for your situation and approach.

Nature. This field provides a space for you to characterize the nature of the value and the circumstance under which the value you’ve used for the quantity was estimated. Clicking the down arrow at the right of the field invokes another drop down list of choices. The resulting display will look like Figure 32.

Figure 32.

The justification dialog can be closed by clicking the Done button. If color coding for input fields is turned on, the yellow input field for the mean parameter would then be shown in white. You can select Input/Options from the main menu to change the colors used by this system, or to turn it off altogether.

*Unless you’ve unchecked the “Automatically convert” checkbox in the lower, right-hand corner of the Input/Options dialog, in which case all the units you enter must already conform.