Add documentation

webservice/apps/synthea/lib/utils.py

@@ -8,20 +8,31 @@ import json
 from django.conf import settings
 from uuid import uuid4
 
-
 def available_states():
+    """This method will return a sorted list of available states based on the 'geography/demographics.csv' in the `settings.SYNTHEA_RESOURCE_DIR` folder.
+
+    Returns:
+        List: Sorted list on state name with dicts holding the id and name of the state.
+    """
+
     states = []
     # Read the demographics.csv file from the Synthea resources and get all the unique state names
     # Important, the state name for synthea is case sensitive (field id)
-    df = pd.read_csv(settings.SYNTHEA_STATES_DIR / 'demographics.csv', index_col=False)
+    df = pd.read_csv(settings.SYNTHEA_RESOURCE_DIR / 'geography/demographics.csv', index_col=False)
     for state in df.STNAME.unique():
         states.append({'id' : state , 'name' : state})
 
     # Sort on name
-    states = sorted(states, key=lambda k: k['name'].lower())
+    states = sorted(states, key=lambda s: s['name'].lower())
     return states
 
 def available_modules():
+    """This method will load all the available modules that are in the folder `settings.SYNTHEA_MODULE_DIR`. Only files ending on .json will be loaded.
+
+    Returns:
+        List: Sorted list on module name with dicts holding the id and name of the module.
+    """
+
     # Assumption here: Only .json files in the main folder are modules. The rest are submodules...
     modules = []
     for module in settings.SYNTHEA_MODULE_DIR.iterdir():
@@ -29,10 +40,29 @@ def available_modules():
             data = json.loads(module.read_text())
             modules.append({'id' : module.name.replace('.json',''), 'name' : data['name']})
 
-    modules = sorted(modules, key=lambda k: k['name'].lower())
+    modules = sorted(modules, key=lambda m: m['name'].lower())
     return modules
 
-def run_synthea(state = None, population = None, gender = None, age = None, module = None):
+def run_synthea(state, population = 50, gender = None, age = None, module = None):
+    """This module will run the Synthea application on the background. This method expects Synthea to be installed on the `settings.SYNTHEA_BASE_DIR` location.
+
+    The output will be written to a unique folder in `settings.SYNTHEA_OUTPUT_DIR` that will be zipped and returned.
+
+    It will return the log and the zipfile location for futher processing. The zip file will not be deleted afterwards. So cleanup needs to be done manually.
+
+    Args:
+        state (str, required): The state where to generate synthetic patient data for.
+        population (int, optional): The amount of patients to generate. Defaults to 50.
+        gender (str, optional): Either generate only male(m), only female(f), or None for both. Defaults to None.
+        age (str, optional): This is the age range of the generated patients. Input is always like [min_age]-[max_age]. Defaults to None.
+        module (str, optional): The module to use for generating patient data When None, all modules are used. Defaults to None.
+
+    Raises:
+        Exception: When the Synthea run fails it will return an Exception witht he Java error in it.
+
+    Returns:
+        (str,Path): The returning zipfile has the enabled options in the file name.
+    """
     # Add a unique dir to the output, so multiple Synthea processes can run parallel
     temp_id = uuid4().hex
     output_folder = settings.SYNTHEA_OUTPUT_DIR / temp_id