<commit_before>.. include:: _includes/_replacements.rst

Results
=======

Pliers is meant to provide a unified interface to a wide range of feature extraction tools and services, so it's imperative that the results we get back from different extractors can also be represented and accessed in a standardized way. In this section, we provide a detailed description of the pliers |ExtractorResult| class and the various options available for exporting results to pandas DataFrames. In many typical workflows, the export process will be done implicitly, so that all a user has to worry about is making sure to specify appropriate formatting arguments. In particular, if you only ever work with the :ref:`Graph API <graphs>`, you may want to skip down to the :ref:`Graph results` section.

The ExtractorResult class
-------------------------
Calling ``transform()`` on an instantiated |Extractor| returns an object of class |ExtractorResult|. This is a lightweight container that contains all of the extracted feature information returned by the |Extractor|, references to the |Stim| and |Extractor| objects used to generate the result, and both "raw" and processed forms of the results returned by the |Extractor| (though note that many Extractors don't set a ``.raw`` attribute). For example:

::

    >>> from pliers.extractors import FaceRecognitionFaceLocationsExtractor
    >>> ext = FaceRecognitionFaceLocationsExtractor()
    >>> result = ext.transform(image)

    >>> result.stim.name
    'obama.jpg'

    >>> result.extractor.name
    'FaceRecognitionFaceLocationsExtractor'

    >>> result.raw
    [(142, 349, 409, 82)]

    >>> result.data
    array([[142, 349, 409,  82]])

.. _results-to-df:

Exporting results to pandas DataFrames
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Typically, we'll want to work with the data in a more convenient form. Fortunately, every |ExtractorResult| instance provides a .to_df() method that returns a pandas DataFrame:

::
    >>> result.to_df()
    onset   duration   object_id   face_locations
    NaN     NaN        0           (142, 349, 409, 82)
<commit_msg>minor results doc update<commit_after>.. include:: _includes/_replacements.rst

Results
=======

Pliers is meant to provide a unified interface to a wide range of feature extraction tools and services, so it's imperative that the results we get back from different extractors can also be represented and accessed in a standardized way. In this section, we provide a detailed description of the pliers |ExtractorResult| class and the various options available for exporting results to pandas DataFrames. In many typical workflows, the export process will be done implicitly, so that all a user has to worry about is making sure to specify appropriate formatting arguments. In particular, if you only ever work with the :ref:`Graph API <graphs>`, you may want to skip down to the :ref:`Graph results` section.

The ExtractorResult class
-------------------------
Calling ``transform()`` on an instantiated |Extractor| returns an object of class |ExtractorResult|. This is a lightweight container that contains all of the extracted feature information returned by the |Extractor|, references to the |Stim| and |Extractor| objects used to generate the result, and both "raw" and processed forms of the results returned by the |Extractor| (though note that many Extractors don't set a ``.raw`` property). For example:

::

    >>> from pliers.extractors import FaceRecognitionFaceLocationsExtractor
    >>> ext = FaceRecognitionFaceLocationsExtractor()
    >>> result = ext.transform(image)

    >>> result.stim.name
    'obama.jpg'

    >>> result.extractor.name
    'FaceRecognitionFaceLocationsExtractor'

    >>> result.raw
    [(142, 349, 409, 82)]

.. _results-to-df:

Exporting results to pandas DataFrames
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Typically, we'll want to work with the data in a more convenient form. Fortunately, every |ExtractorResult| instance provides a .to_df() method that returns a pandas DataFrame:

::
    >>> result.to_df()
    onset   duration   object_id   face_locations
    NaN     NaN        0           (142, 349, 409, 82)

{'fraction_non_alphanumeric': 0.10314979562394806, 'fraction_numerical': 0.013705217600384708, 'mean_word_length': 4.054678007290401, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 50, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '716138', 'n_tokens_mistral': 1137, 'n_tokens_neox': 1010, 'n_words': 506}