Add details, improve grammar, syntax in doc (#224)

Some examples were missing details or explanations. Effectiveness fits better earlier in the inspection doc as a more basic parameter. Clean up dynamic skip lot example file.

Author: wenzeslaus

docs/consignments.md

@@ -72,9 +72,8 @@ consignment:
 
 The generator adds origin, flower (commodity type), and port (where consignment
 was received). These are randomly selected from the lists specified in the
-configuration. These values are not currently used, but may be used to configure
-other parameters in the future (e.g., variable contamination rates by origin or
-inspection efficacy by commodity).
+configuration. These values may be used to configure other simulation parameters
+(e.g., variable contamination rates by origin).
 
 ```yaml
 origins:

docs/contamination.md

@@ -10,11 +10,11 @@ contamination:
 ```
 
 The possible values for `contamination_unit` include `items` and `boxes`. If
-`contamination_unit` = items, the contamination rate (described below) is applied to
+`contamination_unit = items`, the contamination rate (described below) is applied to
 the total number of items in the consignment and individual items are contaminated
 using the specified contaminant arrangement method (described below).
 
-Alternatively, if `contamination_unit` = boxes, the contamination rate is
+Alternatively, if `contamination_unit = boxes`, the contamination rate is
 applied to the total number of boxes in the consignment. The number of boxes to
 contaminate is computed as a decimal (float). Full boxes are contaminated (all
 items within box), except for the last box which uses the remainder of the
@@ -219,7 +219,7 @@ contamination:
   random_box:
     probability: 0.2
     ratio: 0.5
-    in_box_arrangement: all
+    in_box_arrangement: random
 ```
 
 ## Consignment-specific contamination
@@ -268,7 +268,8 @@ contamination:
 
 Although any combination is accepted as valid input, specifying overlapping rules may result in
 unexpected behavior. For example, in case you specify only `commodity` in one rule and `port`
-in another rule, it is hard to tell which rule is applied to which consignment. This is an issue
+in another rule, it is hard to tell which rule is applied to which consignment. While this is not
+an issue when simply selecting which consignments should be contaminated, it becomes an issue
 when it is used in combination with different contamination settings for different consignments
 (see below).
 
@@ -290,9 +291,9 @@ Similarly, `end_date` specifies last day when the consignments are contaminated
 ### Setting consignment-specific parameters
 
 When all selected consignments should use the same contamination configuration,
-the `contamination` on the top-level is used, i.e., the contamination configuration is done
-exactly as if it would apply to all consignment and it is rules under `consignments` which limit
-to which consignment the contamination is applied.
+the `contamination` on the top-level is used to specify that, i.e., the contamination configuration is done
+exactly as if it would apply to all consignments and it uses rules under `consignments` to limit
+to which consignments the contamination is applied.
 
 ```yaml
 contamination:
@@ -331,7 +332,7 @@ then the top-level `contamination` is used to get default values which can be th
 overwritten by values from the nested `contamination`.
 
 In the following example, both consignments with both Tulipa and Rose will be contaminated and
-will use values from the top-level `contamination` and at the same time, these values will be
+will use values from the top-level `contamination`, and at the same time, these values will be
 overwritten by the nested `contamination`. As a result, contamination configuration for Tulipa
 will have `arrangement: random_box` and `contamination_unit: item`, while contamination
 for Rose will have `arrangement: random` and `contamination_unit: box`.
@@ -375,6 +376,9 @@ contamination:
   arrangement: random
 ```
 
+Sedum will use the top-level `contamination` values, Tulipa will not use it,
+and Rose will use it, but overwrite some of the values with its own values.
+
 ---
 
 Next: [Inspections](inspections.md)

docs/inspections.md

@@ -225,6 +225,19 @@ release_programs:
       file_name: schedule.csv
 ```
 
+## Effectiveness
+
+Contaminated items can be either always be detected during the inspection,
+or only a certain percentage of them can be detected based on the
+effectiveness. The `effectiveness` is a value between 0 and 1.
+The following will cause 1 out of 10 contaminated items on average to pass
+undetected.
+
+```yaml
+inspection:
+  effectiveness: 0.9
+```
+
 ## Inspection unit
 
 The inspection unit can be determined by:
@@ -254,18 +267,6 @@ meaning all items within a box can be inspected. If `within_box_proportion < 1`,
 only the first `n = within_box_proportion * items_per_box` items in each box
 will be inspected.
 
-## Effectiveness
-
-Contaminated items can be either always be detected during the inspection,
-or only a certain percentage of them can be detected based on the
-effectiveness. The `effectiveness` is a value between 0 and 1.
-The following will cause 1 out of 10 contaminated items to pass undetected.
-
-```yaml
-inspection:
-  effectiveness: 0.9
-```
-
 ## Tolerance level
 
 The simulation provides a count of the number of missed consignments (slippage) with
@@ -289,15 +290,15 @@ inspection:
 
 ## Sample strategy
 
-The sample strategy can be determined by:
+The sample strategy defines the method used to compute the number of
+units to inspect. The sample strategy can be determined by:
 
 ```yaml
 inspection:
   sample_strategy: proportion
 ```
 
-The sample strategy defines the method used to compute the number of
-units to inspect. The possible sample strategies include `proportion`
+The possible sample strategies include `proportion`
 for sampling a specified proportion of units, `hypergeometric` for
 sampling to detect a specified contamination level at a specified
 confidence level using the hypergeometric distribution, `fixed_n` for
@@ -309,6 +310,7 @@ The settings for `proportion` are:
 
 ```yaml
 inspection:
+  sample_strategy: proportion
   proportion:
     value: 0.02
     min_boxes: 1
@@ -326,6 +328,7 @@ The settings for `hypergeometric` are:
 
 ```yaml
 inspection:
+  sample_strategy: hypergeometric
   hypergeometric:
     detection_level: 0.05
     confidence_level: 0.95
@@ -352,6 +355,7 @@ The settings for `fixed_n` are:
 
 ```yaml
 inspection:
+  sample_strategy: fixed_n
   fixed_n: 10
 ```
 

examples/notebooks/data/dynamic_skip_lot_config.yml

@@ -35,9 +35,6 @@ consignment:
       - WA Seattle Air CBP
       - TX Brownsville CBP
       - WA Blaine CBP
-  input_file:
-    file_type: AQIM
-    file_name: blank_aqim_for_testing.csv
 contamination:
   contamination_unit: box
   contamination_rate: