Source code for api.postprocessor.evaluations.evaluation_setup

""" Handling of evaluations """

import typing

from abc import abstractmethod, ABC


[docs]
class EvaluationSetup(ABC):

    def __init__(self, item):
        self._evaluation = item


    def _get_wrapped_object(self):
        return self._evaluation


[docs]
    @abstractmethod
    def get_name(self) -> str:
        """ Returns the name of the evaluation

        .. admonition:: Example
            :class: note

            ..
                >>> import more.project
                >>> proj = more.project.Project()

            >>> from more.api import ApiGateway
            >>> api = ApiGateway(proj=proj)
            >>> postprocessor_setup = api.create_postprocessor_setup()

            ..
                >>> from more.api_implementations._api_tools.postprocessor.mocking_utils import append_simresult_with_empty_result
                >>> append_simresult_with_empty_result(proj, 'example_simresult')

            >>> simresult_setup = postprocessor_setup.get_simresult(name='example_simresult') # The simresult object must already exist
            >>> evaluation_setup = simresult_setup.create_evaluation(evaluation_type='Filter evaluation').set_name(name='new_name')
            >>> evaluation_setup.get_name()
            'new_name'

        Returns
        -------
        name: str
            The name of the evaluation


        """
        pass



[docs]
    @abstractmethod
    def get_result_names(self) -> typing.List:
        """ Gets the names of the results, typically these are the job labels assigned in the study


        .. admonition:: Example
            :class: note

            ..
                >>> import more.project
                >>> proj = more.project.Project()

            >>> from more.api import ApiGateway
            >>> api = ApiGateway(proj=proj)
            >>> postprocessor_setup = api.create_postprocessor_setup()

            ..
                >>> from more.api_implementations._api_tools.postprocessor.mocking_utils import append_simresult_with_empty_result
                >>> append_simresult_with_empty_result(proj, 'example_simresult')

            >>> simresult_setup = postprocessor_setup.get_simresult(name='example_simresult') # The simresult object must already exist
            >>> evaluation_setup = simresult_setup.create_evaluation(evaluation_type='Custom')
            >>> print("Available results: {}".format(evaluation_setup.get_result_names()))
            Available results: [...]


        Returns
        -------
        list of strings
            Names of available results

        """
        pass



[docs]
    @abstractmethod
    def set_name(self, name: str, resolve_duplicate_name: bool = False) -> 'EvaluationSetup':
        """ Changes the name of the evaluation


        .. admonition:: Example
            :class: note

            ..
                >>> import more.project
                >>> proj = more.project.Project()

            >>> from more.api import ApiGateway
            >>> api = ApiGateway(proj=proj)
            >>> postprocessor_setup = api.create_postprocessor_setup()

            ..
                >>> from more.api_implementations._api_tools.postprocessor.mocking_utils import append_simresult_with_empty_result
                >>> append_simresult_with_empty_result(proj, 'example_simresult')

            >>> simresult_setup = postprocessor_setup.get_simresult(name='example_simresult') # The simresult object must already exist
            >>> evaluation_setup = simresult_setup.create_evaluation(evaluation_type='Filter evaluation')
            >>> evaluation_setup.set_name(name='new_name')
            <more...>
            >>> second_evaluation_setup = simresult_setup.create_evaluation(evaluation_type='Filter evaluation')\\
            ...     .set_name(name='new_name', resolve_duplicate_name=True)
            >>> second_evaluation_setup.get_name()
            'new_name 1'

            ..
                >>> evaluation_setup._evaluation.name
                'new_name'

                Trying to set the name to a non-string value
                >>> evaluation_setup.set_name(name=None)
                Traceback (most recent call last):
                ...
                TypeError: ...

                Setting a non-unique name
                >>> evaluation_setup.set_name('new_name')
                Traceback (most recent call last):
                ...
                more.api.exceptions.api_exception.NameNotUniqueError: ...

        Parameters
        ----------
        resolve_duplicate_name: bool
            Whether to automatically assign a new name when the chosen one is already taken
        name: str
            The new name of the evaluation

        Returns
        -------
        self: :class:`~api.postprocessor.evaluations.evaluation_setup.EvaluationSetup`


        Raises
        ------
        NameNotUniqueError
            Raised if the given name is not unique
        TypeError
            Raised if the given name is not a string

        """
        pass



[docs]
    @abstractmethod
    def remove_viewer(self, name: str) -> 'EvaluationSetup':
        """ Removes a viewer object

        .. admonition:: Deprecated
            :class: warning

            the 'remove_viewer' method is deprecated and will be removed. Viewers are now evaluations,
             please use the :meth:`~remove_evaluation` method

        """
        pass



[docs]
    @abstractmethod
    def duplicate_viewer(self, name: str) -> 'more.api.postprocessor.evaluations.EvaluationSetup':
        """ Duplicates a viewer object and returns the :class:`~api.postprocessor.viewers.viewer_setup.ViewerSetup` object for the newly created copy


        .. admonition:: Deprecated
            :class: warning

            the 'duplicate_viewer' method is deprecated and will be removed. Viewers are now evaluations,
             please use the :meth:`~duplicate_evaluation` method

        """
        pass



[docs]
    @abstractmethod
    def get_viewer_names(self) -> typing.List[str]:
        """ Gets the names of existing child viewers


        .. admonition:: Deprecated
            :class: warning

            the 'get_viewer_names' method is deprecated and will be removed. Viewers are now evaluations,
             please use the :meth:`~get_evaluation_names` method

        """
        pass



[docs]
    @abstractmethod
    def create_viewer(self, viewer_type: str) -> 'more.api.postprocessor.evaluations.EvaluationSetup':
        """ Creates a viewer and returns a :class:`~api.postprocessor.viewers.viewer_setup.ViewerSetup` object

        .. admonition:: Deprecated
            :class: warning

            the 'create_viewer' method is deprecated and will be removed. Viewers are now evaluations,
             please use the :meth:`~create_evaluation` method

        """

        pass



[docs]
    @abstractmethod
    def get_compatible_viewer_types(self) -> typing.List[str]:
        """ Gets the names of viewer types compatible with this evaluation

        .. admonition:: Deprecated
            :class: warning

            the 'get_compatible_viewer_types' method is deprecated and will be removed. Viewers are now evaluations,
             please use the :meth:`~get_compatible_evaluation_types` method

        """
        pass





[docs]
    @abstractmethod
    def get_viewer(self, name: str) -> 'more.api.postprocessor.evaluations.EvaluationSetup':
        """ Creates a :class:`~api.postprocessor.viewers.viewer_setup.ViewerSetup`  for an already existing viewer


        .. admonition:: Deprecated
            :class: warning

            the 'get_viewer' method is deprecated and will be removed. Viewers are now evaluations,
             please use the :meth:`~get_evaluation` method

        """

        pass


####################################################################################################



[docs]
    @abstractmethod
    def remove_evaluation(self, name: str) -> 'EvaluationSetup':
        """ Removes an evaluation object

        .. admonition:: Example
            :class: note

            ..
                >>> import more.project
                >>> proj = more.project.Project()

            >>> from more.api import ApiGateway
            >>> api = ApiGateway(proj=proj)
            >>> postprocessor_setup = api.create_postprocessor_setup()

            ..
                >>> from more.api_implementations._api_tools.postprocessor.mocking_utils import append_simresult_with_empty_result
                >>> append_simresult_with_empty_result(proj, 'example_simresult')

            >>> simresult_setup = postprocessor_setup.get_simresult(name='example_simresult') # The simresult object must already exist
            >>> evaluation_setup = simresult_setup.create_evaluation(evaluation_type='Filter evaluation').set_name(name='example_evaluation')
            >>> evaluation_setup.create_viewer(viewer_type='Figure').set_name(name='example_viewer')
            <more...>
            >>> evaluation_setup.remove_viewer(name='example_viewer')
            <more...>

            ..
                >>> len(proj.post.simresults_container.elements[0].evaluation_container.elements[0].evaluation_container.elements)
                0
                >>> evaluation_setup.remove_viewer(name='non_existent_example_viewer')
                Traceback (most recent call last):
                ...
                more.api.exceptions.api_exception.NameNotFoundError: ...


        Parameters
        ----------
        name : str
            The name of the viewer object to remove

        Returns
        -------
        self : :class:`~api.postprocessor.evaluations.evaluation_setup.EvaluationSetup`

        Raises
        ------
        NameNotFoundError
            Raised if no viewer with the given name exist

        """
        pass



[docs]
    @abstractmethod
    def duplicate_evaluation(self, name: str) -> 'more.api.postprocessor.evaluations.EvaluationSetup':
        """ Duplicates an evaluation object and returns the :class:`~api.postprocessor.evaluations.EvaluationSetup` object for the newly created copy

        .. admonition:: Example
            :class: note

            ..
                >>> import more.project
                >>> proj = more.project.Project()

            >>> from more.api import ApiGateway
            >>> api = ApiGateway(proj=proj)
            >>> postprocessor_setup = api.create_postprocessor_setup()

            ..
                >>> from more.api_implementations._api_tools.postprocessor.mocking_utils import append_simresult_with_empty_result
                >>> append_simresult_with_empty_result(proj, 'example_simresult')

            >>> simresult_setup = postprocessor_setup.get_simresult(name='example_simresult') # The simresult object must already exist
            >>> evaluation_setup = simresult_setup.create_evaluation(evaluation_type='Filter evaluation').set_name(name='example_evaluation')
            >>> evaluation_setup.create_viewer(viewer_type='Figure').set_name(name='example_viewer')
            <more...>
            >>> duplicate_viewer = evaluation_setup.duplicate_viewer(name='example_viewer')
            >>> print("Automatically assigned name of the duplicate: {}".format(duplicate_viewer.get_name()))
            Automatically assigned name of the duplicate: ...

            ..
                >>> len(proj.post.simresults_container.elements[0].evaluation_container.elements[0].evaluation_container.elements)
                2
                >>> evaluation_setup.duplicate_viewer(name='non_existent_example_viewer')
                Traceback (most recent call last):
                ...
                more.api.exceptions.api_exception.NameNotFoundError: ...

        Parameters
        ----------
        name : str
            The name of the evaluation object to duplicate

        Returns
        -------
        :class:`~api.postprocessor.evaluations.EvaluationSetup`
            The setup object for the newly created copy

        Raises
        ------
        NameNotFoundError
            Raised if no evaluation with the given name exist

        """
        pass



[docs]
    @abstractmethod
    def get_evaluation_names(self) -> typing.List[str]:
        """ Gets the names of existing child evaluations


        .. admonition:: Example
            :class: note

            ..
                >>> import more.project
                >>> proj = more.project.Project()

            >>> from more.api import ApiGateway
            >>> api = ApiGateway(proj=proj)
            >>> postprocessor_setup = api.create_postprocessor_setup()

            ..
                >>> from more.api_implementations._api_tools.postprocessor.mocking_utils import append_simresult_with_empty_result
                >>> append_simresult_with_empty_result(proj, 'example_simresult')

            >>> simresult_setup = postprocessor_setup.get_simresult(name='example_simresult') # The simresult object must already exist
            >>> evaluation_setup = simresult_setup.create_evaluation(evaluation_type='Filter evaluation')
            >>> evaluation_setup.create_viewer(viewer_type='Figure').set_name(name='example_viewer')
            <more...>
            >>> print("Available viewers: {}".format(evaluation_setup.get_viewer_names()))
            Available viewers: [...]

        Returns
        -------
        list of strings
            Names of existing child evaluations

        """
        pass



[docs]
    @abstractmethod
    def create_evaluation(self, evaluation_type: str) -> 'more.api.postprocessor.evaluations.EvaluationSetup':
        """ Creates an evaluation and returns a :class:`~api.postprocessor.evaluations.EvaluationSetup` object

        .. admonition:: Example
                :class: note

                ..
                    >>> import more.project
                    >>> proj = more.project.Project()

                >>> from more.api import ApiGateway
                >>> api = ApiGateway(proj=proj)
                >>> postprocessor_setup = api.create_postprocessor_setup()

                ..
                    >>> from more.api_implementations._api_tools.postprocessor.mocking_utils import append_simresult_with_empty_result
                    >>> append_simresult_with_empty_result(proj, 'example_simresult')

                >>> simresult_setup = postprocessor_setup.get_simresult(name='example_simresult') # The simresult object must already exist
                >>> evaluation_setup = simresult_setup.create_evaluation(evaluation_type='Filter evaluation')
                >>> print("Available viewer types: {}".format(evaluation_setup.get_compatible_viewer_types()))
                Available viewer types: [...]
                >>> viewer_setup = evaluation_setup.create_viewer(viewer_type='Figure')

                 ..
                    >>> from more.api.postprocessor.evaluations.evaluation_setup import EvaluationSetup
                    >>> isinstance(viewer_setup, EvaluationSetup)
                    True
                    >>> len(proj.post.simresults_container.elements[0].evaluation_container.elements[0].evaluation_container.elements)
                    1
                    >>> evaluation_setup.create_viewer(viewer_type='non_existent_name')
                    Traceback (most recent call last):
                    ...
                    more.api.exceptions.api_exception.NameNotFoundError: ...
                    >>> evaluation_setup.create_viewer(viewer_type='Modal')
                    Traceback (most recent call last):
                    ...
                    more.api.exceptions.api_exception.NameNotFoundError: ...


        Parameters
        ----------
        evaluation_type: str
            The name of the evaluation type to add, to check which names are compatible run the :meth:`~get_compatible_evaluation_types` method

        Returns
        -------
        :class:`~api.postprocessor.evaluations.EvaluationSetup`
            An object for managing evaluation setup


        Raises
        ------
        NameNotFoundError
            Raised if no evaluation with the given type exists

        """

        pass



[docs]
    @abstractmethod
    def get_compatible_evaluation_types(self) -> typing.List[str]:
        """ Gets the names of evaluation types compatible with this evaluation

        .. admonition:: Example
            :class: note

            ..
                >>> import more.project
                >>> proj = more.project.Project()

            >>> from more.api import ApiGateway
            >>> api = ApiGateway(proj=proj)
            >>> postprocessor_setup = api.create_postprocessor_setup()

            ..
                >>> from more.api_implementations._api_tools.postprocessor.mocking_utils import append_simresult_with_empty_result
                >>> append_simresult_with_empty_result(proj, 'example_simresult')

            >>> simresult_setup = postprocessor_setup.get_simresult(name='example_simresult') # The simresult object must already exist
            >>> evaluation_setup = simresult_setup.create_evaluation(evaluation_type='Filter evaluation')
            >>> evaluation_setup.create_viewer(viewer_type='Figure').set_name(name='example_viewer')
            <more...>
            >>> print("Available viewer types: {}".format(evaluation_setup.get_compatible_viewer_types()))
            Available viewer types: [...]

        Returns
        -------
        list of strings
            Names of compatible evaluation types

        """
        pass





[docs]
    @abstractmethod
    def get_evaluation(self, name: str) -> 'more.api.postprocessor.evaluations.EvaluationSetup':
        """ Creates a :class:`~api.postprocessor.evaluations.EvaluationSetup`  for an already existing evaluation


        .. admonition:: Example
            :class: note

            ..
                >>> import more.project
                >>> proj = more.project.Project()

            >>> from more.api import ApiGateway
            >>> api = ApiGateway(proj=proj)
            >>> postprocessor_setup = api.create_postprocessor_setup()

            ..
                >>> from more.api_implementations._api_tools.postprocessor.mocking_utils import append_simresult_with_empty_result
                >>> append_simresult_with_empty_result(proj, 'example_simresult')

            >>> simresult_setup = postprocessor_setup.get_simresult(name='example_simresult') # The simresult object must already exist
            >>> evaluation_setup = simresult_setup.create_evaluation(evaluation_type='Filter evaluation')
            >>> viewer_setup = evaluation_setup.create_viewer(viewer_type='Figure').set_name(name='example_viewer')
            >>> print("Available viewer types: {}".format(evaluation_setup.get_compatible_viewer_types()))
            Available viewer types: [...]
            >>> found_viewer_setup = evaluation_setup.get_viewer(name='example_viewer')

            ..
                >>> found_viewer_setup._evaluation == proj.post.simresults_container.elements[0].evaluation_container.elements[0].evaluation_container.elements[0]
                True


        Parameters
        ----------
        name : str
            The name of the existing evaluation for which to return a :class:`~api.postprocessor.evaluations.EvaluationSetup`

        Returns
        -------
        :class:`~api.postprocessor.evaluations.EvaluationSetupp`
            A :class:`~api.postprocessor.evaluations.EvaluationSetup` object for the found evaluation

        Raises
        ------
        NameNotFoundError
            Raised if no evaluation with the given name was found

        """

        pass