Merge pull request #65 from monarch-initiative/develop

Develop

docs/user-guide/option_column_mapper.md

@@ -1,15 +1,16 @@
 # OptionColumnMapper
 
 
-Mapper to be used if the column has a set of defined items but text mining is not required.
+Mapper to be used if the column has a set of defined items. These items are defined with a map that relates the text used in the
+table to the HPO label. If the original HPO label is used in the table, it does not need to be specified in the map.
 
 ```python title="OptionColumnMapper constructor"
 other_d = {
-    "HP": ["High palate", "HP:0000218"],
-    "D": ["Dolichocephaly", "HP:0000268"],
-    "En": ["Deeply set eye", "HP:0000490"], # i.e., Enophthalmus
-    "DE": ["Dural ectasia", "HP:0100775"],
-    "St": ["Striae distensae", "HP:0001065"]
+    "HP": "High palate",
+    "D": "Dolichocephaly",
+    "En": "Deeply set eye",  # i.e., Enophthalmus
+    "DE": "Dural ectasia",
+    "St": "Striae distensae"
 }
 otherMapper = OptionColumnMapper(concept_recognizer=hpo_cr, option_d=other_d)
 ```
@@ -22,6 +23,39 @@ label of the HPO term.
 If text-mining is required, use the :ref:`custom_column_mapper`.
 
 
+### Excluded items
+
+If some of the items should be mapped to an excluded HPO term, then the `exluded_d` aregument is used analogously. For instance, the following all refer to normal findings.
+
+```python title="OptionColumnMapper - excluded findings"
+ urine_not_xa_d = {'0.04mmol/L': "Xanthinuria",
+                        "1.6umol/mmolCr": "Xanthinuria",
+                        "0.0214XA/Cr": "Xanthinuria",
+                        "normal": "Xanthinuria"}
+```
+
+### Assume excluded
+
+By default, the OptionColumnMapper will assume that items that are not mentioned in a table cell were not measured.
+In some cases, we know that the items have been excluded if they are not listed in the cell (because the article says so or because of contextual knowledge).
+In this case, we can set the argeument `assumeExcluded` to True.
+
+
+```python title="OptionColumnMapper constructor"
+other_d = {
+    "HP": "High palate",
+    "D": "Dolichocephaly",
+    "En": "Deeply set eye",  # i.e., Enophthalmus
+    "DE": "Dural ectasia",
+    "St": "Striae distensae"
+}
+otherMapper = OptionColumnMapper(concept_recognizer=hpo_cr, option_d=other_d, assumeExcluded=True)
+otherMapper.map_cell("HP")
+```
+
+In this example, the mapper would map "HP" to High palate, but would also map it to excluded Dolicocephaly (all four terms except for High palate would be excluded).
+
+
 ## Shortcut to creating option mapper objects
 
 
@@ -50,10 +84,10 @@ column_mapper_d['Pituitary'] = pituitaryMapper
 
 For instance, in the above example, there is a column called `Post fossa` in the DataFrame dft. The cell contents
 for the rows of the column contained several strings that we might want to map. `Enlarged cisterna magna` was
-recognized as the label of the HPO term 
+recognized as the label of the HPO term
 [Enlarged cisterna magna (HP:0002280)](https://hpo.jax.org/app/browse/term/HP:0002280).
-We would remove the label 'Normal' (and possible code it as excluded using other commands). The 
+We would remove the label 'Normal' (and possible code it as excluded using other commands). The
 string `Mega cistema magna` is clearly a spelling error in the original data, and so we can map it
 to the string `Enlarged cisterna magna` (replace the PLACEHOLDER) so that the string will also be mapped to the HPO term.
-The next column, `Pituitary`, just shows normal, and this would not be appropriate for the OptionColumnMapper, but users 
+The next column, `Pituitary`, just shows normal, and this would not be appropriate for the OptionColumnMapper, but users
 might want to use the :ref:`simple_column_mapper` to encoded that Abnormalities of the pituitary were excluded.

mkdocs.yml

@@ -34,19 +34,17 @@ nav:
   - Installation: 'installation.md'
   - Developers: 'developers.md'
   - User guide:
-    - Intro: 'user-guide/intro.md'
-    - "Tutorial":
-      - Introduction: 'user-guide/tutorial.md'
-      - Column mappers:
-        - Choosing a column mapper: 'user-guide/choosing_column_mapper.md'
-        - Simple column mapper: 'user-guide/simple_column_mapper.md'
-        - Constant column mapper: 'user-guide/constant_column_mapper.md'
-        - Option column mapper: 'user-guide/option_column_mapper.md'
-        - Threshold column mapper: 'user-guide/threshold_column_mapper.md'
-      - Variant column mapper: 'user-guide/variant_column_mapper.md'
-      - Cohort encoder: 'user-guide/cohort_encoder.md'
-      - Validation: 'user-guide/validation.md'
-      - Visualization: 'user-guide/visualization.md'
+    - Introduction: 'user-guide/tutorial.md'
+    - Column mappers:
+      - Choosing a column mapper: 'user-guide/choosing_column_mapper.md'
+      - Simple column mapper: 'user-guide/simple_column_mapper.md'
+      - Constant column mapper: 'user-guide/constant_column_mapper.md'
+      - Option column mapper: 'user-guide/option_column_mapper.md'
+      - Threshold column mapper: 'user-guide/threshold_column_mapper.md'
+    - Variant column mapper: 'user-guide/variant_column_mapper.md'
+    - Cohort encoder: 'user-guide/cohort_encoder.md'
+    - Validation: 'user-guide/validation.md'
+    - Visualization: 'user-guide/visualization.md'
   - API:
     - "overview": 'api/overview.md'
     - "creation":