Improve doc

Change-Id: Ie59fc27a5138184942310a52e2ad6e5afc267588

src/synthesis_workflow/tasks/circuit.py

@@ -22,6 +22,7 @@
 from synthesis_workflow.tasks.config import SynthesisConfig
 from synthesis_workflow.tasks.luigi_tools import BoolParameter
 from synthesis_workflow.tasks.luigi_tools import copy_params
+from synthesis_workflow.tasks.luigi_tools import OptionalChoiceParameter
 from synthesis_workflow.tasks.luigi_tools import ParamLink
 from synthesis_workflow.tasks.luigi_tools import RatioParameter
 from synthesis_workflow.tasks.luigi_tools import WorkflowTask
@@ -31,19 +32,19 @@
 
 
 class CreateAtlasLayerAnnotations(WorkflowTask):
-    """Create the annotation file for layers from an atlas.
-
-    Args:
-        layer_annotations_path (str): path to save layer annotations constructed from atlas
-        use_half (bool): set to True to use half of the atlas (left or right hemisphere)
-        half_axis (int): direction to select half of the atlas (can be 0, 1 or 2)
-        half_side (int): side to choose to halve the atlas (0=left, 1=right)
-    """
+    """Create the annotation file for layers from an atlas."""
 
     layer_annotations_path = luigi.Parameter(default="layer_annotation.nrrd")
+    """str: Path to save layer annotations constructed from atlas."""
+
     use_half = BoolParameter(default=False)
+    """bool: Set to True to use half of the atlas (left or right hemisphere)."""
+
     half_axis = luigi.IntParameter(default=0)
+    """int: Direction to select half of the atlas (can be 0, 1 or 2)."""
+
     half_side = luigi.IntParameter(default=0)
+    """int: Side to choose to halve the atlas (0=left, 1=right)."""
 
     def run(self):
         """"""
@@ -82,36 +83,60 @@ def output(self):
 
 
 class CreateAtlasPlanes(WorkflowTask):
-    """Create plane cuts of an atlas.
-
-    Args:
-        plane_type (str): type of planes creation algorithm, two choices:
-
-            * centerline: centerline is computed between first_bound and last_bound with
-              internal algorithm (from atlas-analysis package), (warning: experimental)
-            * aligned: centerline is a straight line, along the centerline_axis
-
-        plane_count (int): number of planes to create slices of atlas,
-        slice_thickness (float): thickness of slices (in micrometer)
-        centerline_first_bound (list): (for plane_type == centerline) location of first bound
-            for centerline (in voxcell index)
-        centerline_last_bound (list): (for plane_type == centerline) location of last bound
-            for centerline (in voxcell index)
-        centerline_axis (str): (for plane_type = aligned) axis along which to create planes
-        atlas_planes_path (str): path to save atlas planes
-    """
+    """Create plane cuts of an atlas."""
 
     plane_type = luigi.ChoiceParameter(
-        default="centerline", choices=["aligned", "centerline"]
+        default="centerline",
+        choices=["aligned", "centerline"],
+        description="Type of planes creation algorithm.",
+    )
+    """str: Type of planes creation algorithm, two choices:
+
+        * centerline: centerline is computed between first_bound and last_bound with
+          internal algorithm (from atlas-analysis package), (warning: experimental)
+        * aligned: centerline is a straight line, along the centerline_axis
+    """
+
+    plane_count = luigi.IntParameter(
+        default=10, description="Number of planes to create slices of atlas."
+    )
+    """int: Number of planes to create slices of atlas."""
+
+    slice_thickness = luigi.FloatParameter(
+        default=100, description="Thickness of slices (in micrometer)."
+    )
+    """float: Thickness of slices (in micrometer)."""
+
+    centerline_first_bound = luigi.ListParameter(
+        default=[126, 181, 220],
+        description=(
+            "(only for plane_type == centerline) Location of first bound for centerline "
+            "(in voxcell index)."
+        ),
+    )
+    """list: (only for plane_type == centerline) Location of first bound for centerline
+    (in voxcell index)."""
+
+    centerline_last_bound = luigi.ListParameter(
+        default=[407, 110, 66],
+        description=(
+            "(only for plane_type == centerline) Location of last bound for centerline "
+            "(in voxcell index)."
+        ),
     )
-    plane_count = luigi.IntParameter(default=10)
-    slice_thickness = luigi.FloatParameter(default=100)
+    """list: (only for plane_type == centerline) Location of last bound for centerline
+    (in voxcell index)."""
 
-    centerline_first_bound = luigi.ListParameter(default=[126, 181, 220])
-    centerline_last_bound = luigi.ListParameter(default=[407, 110, 66])
-    centerline_axis = luigi.IntParameter(default=0)
+    centerline_axis = luigi.IntParameter(
+        default=0,
+        description="(only for plane_type = aligned) Axis along which to create planes.",
+    )
+    """str: (only for plane_type = aligned) Axis along which to create planes."""
 
-    atlas_planes_path = luigi.Parameter(default="atlas_planes")
+    atlas_planes_path = luigi.Parameter(
+        default="atlas_planes", description="Path to save atlas planes."
+    )
+    """str: Path to save atlas planes."""
 
     def requires(self):
         """"""
@@ -143,26 +168,30 @@ def output(self):
 class BuildCircuit(WorkflowTask):
     """Generate cell positions and me-types from atlas, compositions and taxonomy.
 
-    Args:
-        cell_composition_path (str): path to the cell composition file (YAML)
+    Attributes:
         mtype_taxonomy_path (str): path to the taxonomy file (TSV)
-        density_factor (float): density factor
-        seed (int): pseudo-random generator seed
     """
 
     cell_composition_path = luigi.Parameter(
         default="cell_composition.yaml",
-        description="path to the cell composition file (YAML)",
+        description="Path to the cell composition file (YAML).",
     )
+    """str: Path to the cell composition file (YAML)."""
+
     density_factor = RatioParameter(
         default=0.01,
         left_op=luigi.parameter.operator.lt,
-        description="The density of positions generated from the atlas",
+        description="The density of positions generated from the atlas.",
     )
+    """float: The density of positions generated from the atlas."""
+
     mask_path = luigi.Parameter(
-        default=None, description="path to save thickness mask (NCx only)"
+        default=None, description="Path to save thickness mask (NCx only)."
     )
-    seed = luigi.IntParameter(default=None, description="pseudo-random generator seed")
+    """str: Path to save thickness mask (NCx only)."""
+
+    seed = luigi.IntParameter(default=None, description="Pseudo-random generator seed.")
+    """int: Pseudo-random generator seed."""
 
     def requires(self):
         """"""
@@ -201,16 +230,20 @@ def output(self):
 class SliceCircuit(WorkflowTask):
     """Create a smaller circuit .mvd3 file for subsampling.
 
-    Args:
-        sliced_circuit_path (str): path to save sliced circuit somata mvd3
-        mtypes (list): list of mtypes to consider
-        n_cells (int): number of cells per mtype to consider
-        hemisphere (str): 'left' or 'right'
+    Attributes:
+        mtypes (list): List of mtypes to consider.
     """
 
     sliced_circuit_path = luigi.Parameter(default="sliced_circuit_somata.mvd3")
+    """str: Path to save sliced circuit somata mvd3."""
+
     n_cells = luigi.IntParameter(default=10)
-    hemisphere = luigi.Parameter(default=None)
+    """int: Number of cells per mtype to consider."""
+
+    hemisphere = OptionalChoiceParameter(
+        default=None, choices=["left", "right"], description="The hemisphere side."
+    )
+    """str: (optional) The hemisphere side."""
 
     def requires(self):
         """"""

src/synthesis_workflow/tasks/config.py

@@ -66,14 +66,14 @@ class RunnerConfig(luigi.Config):
     """Runner global configuration."""
 
     nb_jobs = luigi.IntParameter(
-        default=-1, description="Number of jobs used by parallel tasks"
+        default=-1, description="Number of jobs used by parallel tasks."
     )
     joblib_verbose = luigi.NumericalParameter(
         default=0,
         var_type=int,
         min_value=0,
         max_value=50,
-        description="Verbosity level used by the joblib library",
+        description="Verbosity level used by the joblib library.",
     )
 
 
@@ -82,56 +82,95 @@ class SynthesisConfig(luigi.Config):
 
     tmd_parameters_path = luigi.Parameter(
         default="tns_input/tmd_parameters.json",
-        description="The path to the TMD parameters",
+        description="The path to the TMD parameters.",
     )
     tmd_distributions_path = luigi.Parameter(
         default="tns_input/tmd_distributions.json",
-        description="The path to the TMD distributions",
+        description="The path to the TMD distributions.",
     )
     cortical_thickness = luigi.ListParameter(
         default=[165, 149, 353, 190, 525, 700],
-        description="The list of cortical thicknesses",
+        description="The list of cortical thicknesses.",
     )
     mtypes = luigi.ListParameter(
         default=None,
         description=(
             "The list of mtypes to process (default is None, which means that all found "
-            "mtypes are taken)"
+            "mtypes are taken)."
         ),
     )
 
 
 class CircuitConfig(luigi.Config):
     """Circuit configuration."""
 
-    circuit_somata_path = luigi.Parameter(default="circuit_somata.mvd3")
-    atlas_path = luigi.Parameter(default=None)
+    circuit_somata_path = luigi.Parameter(
+        default="circuit_somata.mvd3", description="Path to the circuit somata."
+    )
+    atlas_path = luigi.Parameter(
+        default=None, description="Path to the atlas directory."
+    )
 
 
 class PathConfig(luigi.Config):
     """Morphology path configuration."""
 
+    # Input paths
     mtype_taxonomy_path = luigi.Parameter(
-        default="mtype_taxonomy.tsv", description="path to the taxonomy file (TSV)"
+        default="mtype_taxonomy.tsv", description="Path to the taxonomy file (TSV)."
+    )
+    local_synthesis_input_path = luigi.Parameter(
+        default="synthesis_input", description="Path to the synthesis input directory."
     )
-    local_synthesis_input_path = luigi.Parameter(default="synthesis_input")
 
-    result_path = luigi.Parameter(default="out")
-    atlas_subpath = luigi.Parameter(default="atlas")
-    circuit_subpath = luigi.Parameter(default="circuit")
-    morphs_df_subpath = luigi.Parameter(default="morphs_df")
-    synthesis_subpath = luigi.Parameter(default="synthesis")
-    validation_subpath = luigi.Parameter(default="validation")
+    # Output tree
+    result_path = luigi.Parameter(
+        default="out", description="Path to the output directory."
+    )
+    atlas_subpath = luigi.Parameter(
+        default="atlas", description="Path to output atlas subdirectory."
+    )
+    circuit_subpath = luigi.Parameter(
+        default="circuit", description="Path to output circuit subdirectory."
+    )
+    morphs_df_subpath = luigi.Parameter(
+        default="morphs_df", description="Path to output morphs_df subdirectory."
+    )
+    synthesis_subpath = luigi.Parameter(
+        default="synthesis", description="Path to output synthesis subdirectory."
+    )
+    validation_subpath = luigi.Parameter(
+        default="validation", description="Path to output validation subdirectory."
+    )
 
-    ext = ExtParameter(default="asc")
-    morphology_path = luigi.Parameter(default="repaired_morphology_path")
-    morphs_df_path = luigi.Parameter(default="morphs_df.csv")
-    substituted_morphs_df_path = luigi.Parameter(default="substituted_morphs_df.csv")
-    synth_morphs_df_path = luigi.Parameter(default="synth_morphs_df.csv")
-    synth_output_path = luigi.Parameter(default="synthesized_morphologies")
+    # Default internal values
+    ext = ExtParameter(default="asc", description="Default extension used.")
+    morphology_path = luigi.Parameter(
+        default="repaired_morphology_path",
+        description="Column name in the morphology dataframe to access morphology paths",
+    )
+    morphs_df_path = luigi.Parameter(
+        default="morphs_df.csv", description="Path to the morphology DataFrame."
+    )
+    substituted_morphs_df_path = luigi.Parameter(
+        default="substituted_morphs_df.csv",
+        description="Path to the substituted morphology DataFrame.",
+    )
+    synth_morphs_df_path = luigi.Parameter(
+        default="synth_morphs_df.csv",
+        description="Path to the synthesized morphology DataFrame.",
+    )
+    synth_output_path = luigi.Parameter(
+        default="synthesized_morphologies",
+        description="Path to the synthesized morphologies.",
+    )
 
     debug_region_grower_scales_path = luigi.Parameter(
-        default="region_grower_scales_logs"
+        default="region_grower_scales_logs",
+        description=(
+            "Path to the log files in which the scaling factors computed in region-grower "
+            "are stored."
+        ),
     )
 
 

src/synthesis_workflow/tasks/diametrizer.py

@@ -70,7 +70,11 @@ def _plot_models(models_params, models_data, fig_folder="figures", ext=".png"):
     nb_jobs=ParamLink(RunnerConfig),
 )
 class BuildDiameterModels(WorkflowTask):
-    """Task to build diameter models from set of cells."""
+    """Task to build diameter models from set of cells.
+
+    Attributes:
+        nb_jobs (int): Number of workers.
+    """
 
     morphs_df_path = luigi.Parameter(default="morphs_df.csv")
     morphology_path = luigi.Parameter(default="morphology_path")

src/synthesis_workflow/tasks/luigi_tools.py

@@ -209,6 +209,12 @@ def parse(self, x):
         else:
             return None
 
+    def normalize(self, x):
+        if x is not None:
+            return self._base_cls.normalize(self, x)
+        else:
+            return None
+
     def _warn_on_wrong_param_type(self, param_name, param_value):
         if self.__class__ != self._cls:
             return
@@ -224,6 +230,10 @@ class OptionalIntParameter(OptionalParameter, luigi.IntParameter):
     """Class to parse optional int parameters."""
 
 
+class OptionalChoiceParameter(OptionalParameter, luigi.ChoiceParameter):
+    """Class to parse optional choice parameters."""
+
+
 class OptionalNumericalParameter(OptionalParameter, luigi.NumericalParameter):
     """Class to parse optional int parameters."""