:mod:`neuron_morphology.feature_extractor.feature_writer`
=========================================================

.. py:module:: neuron_morphology.feature_extractor.feature_writer

.. autoapi-nested-parse::

   Utilities (mainly the FeatureWriter class) used by the feature extractor 
   executable to format and write outputs.

   ..
       !! processed by numpydoc !!



Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   neuron_morphology.feature_extractor.feature_writer.FeatureWriter
   neuron_morphology.feature_extractor.feature_writer.FeatureFormatter



Functions
~~~~~~~~~

.. autoapisummary::

   neuron_morphology.feature_extractor.feature_writer.has_subkey
   neuron_morphology.feature_extractor.feature_writer.add_layer_histogram
   neuron_morphology.feature_extractor.feature_writer.process_earth_movers_distance


.. py:class:: FeatureWriter(heavy_path: str, table_path: Optional[str] = None, formatters: Optional[Iterable['FeatureFormatter']] = None, filemode: Optional[str] = 'w')

   .. method:: add_run(self, identifier: str, run: Dict[str, Any])

      Add the results of a feature extraction run to this writer


      :Parameters:

          **identifier** : the unique identifier for this run
              ..

          **run** : will be added
              ..














      ..
          !! processed by numpydoc !!


   .. method:: process_feature(self, owner: str, key: str, value: Any)

      Processes a feature for writing. This may involve:
          1. changing its type to something json serializable
          2. adding its value to this writer's heavy output


      :Parameters:

          **owner** : identifies the reconstruction that owns this feature
              ..

          **key** : the name of the feature
              ..

          **value** : the feature's raw value
              ..

      :Returns:

          Transformed feature value
              ..













      ..
          !! processed by numpydoc !!


   .. method:: write(self)

      Write this writer's output to disk



      :Returns:

          This writer's outputs as a dictionary
              ..













      ..
          !! processed by numpydoc !!


   .. method:: validate_table_extension(self)

      If an output table was requested, check that the path has a 
      supported extension.
















      ..
          !! processed by numpydoc !!


   .. method:: build_output_table(self)

      Convert this writer's output to a reconstruction X feature table



      :Returns:

          the generated table
              ..













      ..
          !! processed by numpydoc !!


   .. method:: write_table(self)

      Construct and write a reconstructions X features table from this 
      writer.
















      ..
          !! processed by numpydoc !!


   .. method:: register_formatters(self, formatters: Iterable['FeatureFormatter'])

      Add formatters to this writer. The order matters! If multiple 
      formatters match a feature, only the first will be applied.


      :Parameters:

          **foratters** : an ordered collection of formatter to register
              ..














      ..
          !! processed by numpydoc !!



.. data:: FeatureOutputHandler
   

   

.. data:: FeatureOutputCheck
   

   

.. py:class:: FeatureFormatter

   Bases: :class:`typing.NamedTuple`

   Format feature results for output
















   ..
       !! processed by numpydoc !!

   .. attribute:: name
      :annotation: :str

      

   .. attribute:: check
      :annotation: :FeatureOutputCheck

      

   .. attribute:: handler
      :annotation: :FeatureOutputHandler

      


.. function:: has_subkey(subkey: str, key: str)

   Check whether a string occurs as one of the "."-separated members of 
   another. 
















   ..
       !! processed by numpydoc !!


.. function:: add_layer_histogram(writer: FeatureWriter, owner: str, key: str, histogram: LayerHistogram) -> str

   Add a layer histogram to this writer's heavy data


   :Parameters:

       **owner** : identifies the reconstruction that owns this feature
           ..

       **key** : the name of the histogram
           ..

       **histogram** : the histogram's data
           ..

   :Returns:

       the path at which this writer's heavy data will be stored
           ..













   ..
       !! processed by numpydoc !!


.. function:: process_earth_movers_distance(_writer: FeatureWriter, _owner: str, _key: str, value: EarthMoversDistanceResult) -> Dict[str, Union[str, float]]

   Convert an EarthMoversDistanceResult to a form suitable for json 
   serialization


   :Parameters:

       **_*** : these are unused
           ..

       **value** : The result to be transformed
           ..

   :Returns:

       a dictionary like:
           ..

       {
           "result": <float result>,
           "interpretation" : <name of interpretation enum value>

       }
           ..













   ..
       !! processed by numpydoc !!


.. data:: numpy_array_formatter
   

   

.. data:: normalized_depth_histogram_formatter
   

   

.. data:: earth_movers_distance_formatter
   

   

.. data:: DEFAULT_FEATURE_FORMATTERS