A developer sample class for Metafeature groups.

This class was built to give a model of how you should write a metafeature group class as a Pymfe developer. Please read this entire guide with attention before programming your own class.

At the end of this reading, you will know:
  • How to register your class as a valid MFE metafeature class

  • Which are the special method name prefixes, and how to properly use each of them

  • Which are the rules involving precomputation, metafeature extraction and post-processing methods

  • Which are the coding practices usually adopted in this library, that you should follow in order to get your changes accepted in the master branch

Also, feel free to copy this file to use as template for your own class.

First, some tips and tricks which may help you follow the code standards stabilished in this library.

1. Use type annotations as much as possible

Always run mypy to check if the variable types was specified correctly. You can install it with pip using the following command line:

>>> pip install -U mypy

Use the following command before pushing your modifications to the remote repository:

>>> mypy pymfe --ignore-missing-imports

The expected output for this command is no output.

Note that all warnings must be fixed to your modifications be accepted in the master branch, so take your time to fix your variable types carefully.

2. Use pylint to check your code style and auto-formatters such as yapf

Pylint can be used to check if your code follow some coding practices adopted by the python community. You can install with with pip using the following command:

>>> pip install -U pylint

It can be harsh sometimes, so we have decided to disable some of the verifications. You can use the following command to check if your code met the standards stabilished in this library,

>>> pylint pymfe -d 'C0103, R0913, R0902, R0914, C0302, R0904, R0801, E1101'

The expected output is something like

>>> Your code has been rated at 10.00/10 (previous run: x/10, y)

Your code will not be accepted in the master branch unless it gets the maximum pylint score.

Yapf is a code auto-formatter which usually solves a large amount of coding style related issues automatically.

>>> pip install -U yapf

If you use the flag -i, Yapf changes your code in-place.

>>> yapf -i yourModulename.py

3. Make all verifications with the provided Makefile

You can use the Makefile provided in the root directory to run mypy, pylint, and also pytest. Obviously, all tests (both for coding style and programming logic) must pass in order to your modifications be accepted.

You can use the tag test-cov for run tests and get the code coverage:

>>> make test-cov

You can use the tag test for only run the tests:

>>> make test

You can use the tag code-check for make all verifications with mypy, pylint and pep8:

>>> make code-check

Remember that your code must pass all verifications included in both code-check and test/test-cov to your changes be accepted in the master branch.


This example shows how to create a new group of meta-features. If you want only to add a new meta-feature, you should insert it in the meta-feature group file and create an “ft_” method to it. The new meta-feature will be automatically picked up (as the method “ft_metafeature_name” in this example). You should not forget to use the precompute methods to save time.


You should not forget to create tests for all new functionalities that you implemented. All tests can be found in ./tests/ fold. Please follow the existing code style while creating your tests as much as possible.


This class is being updated in GitHub, check this link to see the current version.

import typing as t
import time

import numpy as np

class MFEBoilerplate:
    """The class name must start with ``MFE`` (just to keep code consistency)
    concatenated with the corresponding metafeature group name (e.g.,
    ``MFEStatistical`` or ``MFEGeneral``) in CamelCase format.

    Also, the class must be registered in the ``_internal.py`` module to be
    an official MFE class, because the pymfe framework is supposed to detect
    the metafeature extraction methods automatically, so you must explain
    where it is supposed to look for those methods.

    Three tuples at module level in ``_internal.py`` module must be updated
    to your new class be detected correctly:

        1. VALID_GROUPS: str
            Here you should write the name of your metafeature group. (e.g.,
            ``statistical`` or ``general``. This name is the value that will
            be given by the user in the ``groups`` MFE parameter to extract
            the all the metafeatures programmed here. Please select a
            sufficiently representative name for your metafeature group.

        2. GROUP_PREREQUISITES : str or :obj:`tuple` of str
            Use this tuple to register other MFE metafeature group classes
            as dependencies of your class. This means that, if the user ask
            to extract the metafeatures of your class, then all metafeature
            groups in the prerequisites will also be extracted also (even if
            the user doesn't ask explicity for these groups). Note that the
            possible consequences this may imply must be solved within this
            class post-processing methods (these methods will be explained
            later in this same guide.)

            The values of this tuple can be strings (which means one single
            dependency), sequences with strings (which means your class has
            multiple dependencies), or simply None (which means your class
            has no dependencies). Generally your class will not have any
            dependency, so just stick to the last option if you are not sure
            so far.

        3. VALID_MFECLASSES : MFE Classes
            In this tuple you should just insert a reference to your class.
            Note that this imply that this module must be imported at the top
            of the module ``_internal.py``.

        These three tuples have one-to-one correspondence using the indexes,
        so the order of values does matter. Please insert your class in the
        same index for all three tuples.


    For example, if we want to make this specific template class an official
    MFE class, those three tuples should be updated as follows: (Remember that
    all tuples below are found in ``_internal.py`` module.)


    # 1. First, choose carefully a metafeature group name. This value will be
    # used directly by the user when extracting the metafeatures programmed
    # in this class, so it must be meaningful and as short as possible.


    # 2. Generally your class will not have any dependency, so you should
    # just register ``None`` as prerequisites. Remember that a class can
    # have any number of dependencies (0, 1 or more than 1.)


    # 3. The last step is to insert your class in this tuple below.
    # Remember to import your module in the ``_internal.py`` module.
    # So, for instance, to register this class, 'MFEBoilerplate', as
    # an official MFE metafeature extractor class, we should make the
    # following modifications:

    import pymfe._dev as _dev


    After this three simple steps, your class is now an official MFE
    metafeature extraction class. From now on you no longer need to
    worry about the ``_internal.py`` module and any other external
    pymfe module.


    Now that you know how to handle the issues related to the
    ``_internal.py`` module, let's start with the actual MFE class

    This tutorial is built to introduce all the different elements
    following the natural order of how a regular MFE Class is usually

    Therefore, the order that we shall see the different concepts in
    this guide is:

    1. Precomputation methods (prefixed with ``precompute_``)
    Methods related to this subject:
        1.1 precompute_basic_precomp_method
        1.2 precompute_more_info
        1.3 precompute_random_values

    2. Feature extraction methods (prefixed with ``ft_``)
    Methods related to this subject:
        2.1 ft_metafeature_name
        2.2 ft_fitted_data_arguments
        2.3 ft_using_precomputed_values
        2.4 ft_about_return_values

    3. Regular/auxiliary methods (non-prefixed )
    Methods related to this subject:
        3.1 _protected_methods
        3.2 non_protected_methods_without_any_prefixes

    4. Postprocessing methods (prefixed with ``postprocess_``)
    Methods related to this subject:
        4.1 postprocess_groupName1_groupName2

    So, we shall start looking at a example of a precomputation

    # Important detail: all methods must be classmethods; there is no class
    # instantiation in the pymfe framework.
    def precompute_basic_precomp_method(cls,
                                        y: t.Optional[np.ndarray] = None,
                                        argument_bar: t.Optional[int] = None,
                                        **kwargs) -> t.Dict[str, t.Any]:
        """A precomputation method example.

        The pydoc of each method must explain cleary what is the purpose of
        that method. This method is supposed to introduce a powerful concept
        of the pymfe framework: precomputation methods.

        1. Why precomputation methods?
        All methods whose name is prefixed with ``precompute_`` are
        executed automatically before the metafeature extraction. These
        methods are extremely important to improve the performance of
        the Pymfe library, as it is quite common that different metafeature
        extraction methods uses the very same information.

        The idea behind this type of methods is to fill up a shared cache
        with all values that can be shared by different metafeature extraction
        methods, and also between different metafeature group classes. This
        means that the values precomputed in ``MFEFoo`` class can also be used
        in the ``MFEBar`` class methods.

        2. Naming convention of a precomputation method
        The name of the method does not matter, as long as it starts with
        the prefix ``precompute_``. This prefix is used to tell the Pymfe
        framework that this is a precomputation method. As you will see during
        this guide, the Pymfe rely heavily on prefixes in the method names, so
        it is important that you don't forget them, and use them appropriately.

        3. Arguments of a precomputation method
        The structure of these precomputation methods is pretty simple. In the
        arguments you can specify custom parameters such as ``X`` and ``y``
        that are automatically given by the MFE class. Those attributes can be
        registered in a special attribute in the MFE class, or also given by
        the user, but you should not rely on this feature; just stick to the
        MFE registered arguments, and let all user-customizable attributes
        have a default value. How exactly those arguments arrive as method
        arguments is not important to develop an MFE metafeature extraction
        class. If you're curious, you should examine the ``mfe.py`` and
        ``_internal.py`` modules by yourself, but it will take some time and
        is not encouraged unless you plan an actual framework redesign.

        It is obligatory to receive the ``kwargs`` in every precomputation
        method. You are free to pick up values from it. We recommend you to
        use the ``get`` method for this task. However, it is forbidden to
        remove or modify the existing values in it. This parameter must be
        considered ``read-only`` except to the insertion of new key-value
        pairs. The reason behind this is that there's no guarantee of any
        execution order of the precomputation methods within a class and
        neither between classes, so all precomputation methods must have
        the chance to read the same values.

        4. Return values of precomputation methods
        All precomputation methods must return a dictionary with strings as
        keys. The value data type can be anything. Note that the name of the
        keys will be used later to match the argument names of feature
        extraction methods. It means that, if you return a dictionary in the
        form: {'foo': 1, 'bar': ('a', 'b')}, then all feature extraction
        methods with an argument named ``foo`` will receive value ``1``, and
        every method with argument named ``bar`` will receive a tuple with 'a'
        and 'b' elements. Always choose meaningful key/argument names.

        As this framework rely on a dictionary to distribute the parameters
        between feature extraction methods, your precomputed keys should never
        replace existing keys with different values, and you should not give
        the same name to parameters with different semantics or purposes.
        The rule of thumb for the pymfe lybrary is: 'if two things have the
        same name, then they are the same thing'. Therefore, avoid extremely
        generic argument names such as ``freqs``, ``mean``, ``model`` etc.

        5. The user can disable precomputation methods
        Keep in mind that the user can disable the precomputation methods,
        mainly due to memory constraints.

        Never rely on these methods to produce any mandatory arguments. All
        the precomputed values here should go to optional parameters and all
        receptor metafeature extraction methods must be responsible to verify
        if all values were effectively precomputed (i.e., they are not
        ``None``). If this is not the case, unfortunately these methods must
        compute those arguments for themselves. If it is not clear how it
        works for you by now, it will probably be easier to grasp when we
        reach our first actual metafeature extraction method. For now, it is
        just important to keep in mind that: you will need to recompute all
        the stuff precomputed in every precomputations methods inside other
        methods whenever those values are needed for the case when the user
        disable the precomputation methods.

        y : :obj:`np.ndarray`, optional
            Always give clear and meaningful description to every argument.

        argument_bar : int, optional
            Some user-given attribute.

            Additional arguments. May have previously precomputed before
            this method from other precomputed methods, so they can help
            speed up this precomputation avoiding duplicated work.

            The following precomputed items are returned:
                * ``y_unique`` (:obj:`np.ndarray`): unique values from
                    ``y``, if it is not None.
                * ``absolute_bar`` (float): absolute value of
                    ``argument_bar``, if it is not None.
        precomp_vals = {}  # type: t.Dict[str, t.Any]

        # Always consider that your precomputation argument could
        # be precomputed by another precomputation method (even if
        # from a different module), so check if the new key is not
        # already in kwargs before calculating anything.
        if argument_bar is not None and "absolute_bar" not in kwargs:
            precomp_vals["absolute_bar"] = abs(argument_bar)

        # The number of precomputed values within a single precomputation
        # method vary greatly, from just a single value to a few amount.
        # As long as all values are semantically sufficiently related with
        # each other, you don't need to create new precomputation methods.
        if y is not None and "y_unique" not in kwargs:
            y_unique = np.unique(y, return_counts=False)
            precomp_vals["y_unique"] = y_unique

        # Always return a dictionary, even if it is empty
        return precomp_vals

    def precompute_more_info(cls,
                             argument_bar: t.Optional[int] = None,
                             **kwargs) -> t.Dict[str, t.Any]:
        """Highly relevant information about precomputation methods.

        1. How many precomputation methods per class?
        Every MFE metafeature extraction class can have as many of
        precomputation methods as needed. Don't hesitate to create
        new precomputation methods whenever you think it will help
        to improve the performance of the package.

        2. How many precomputed values per precomputation method?
        There is no limit of how many values can be precomputed within
        a single precomputation method.

        However, try to keep every precomputation method precompute only
        related values to avoid confusion. Prefer to calculate dissociated
        values in distinct precomputation methods.

        3. Using other precomputed values in a precomputation method
        Don't rely on the execution order of precomputation methods. Always
        assume that the precomputation methods (even within the same class)
        can be executed in any order. However, it does not mean that you
        can't at least try to use previously precomputed methods: that's why
        the 'kwargs' is used in all precomputation methods.

        If needed, try to get a value from 'kwargs' using the 'get' method
        (i.e., kwargs.get('argument_name') - remember 'kwargs' is just a
        Python dictionary.) Then, check whether that value was successfully
        gotten (i.e., is not None).

        argument_bar : int, optional
            Some user-given attribute. Note that it has the same value as
            in the previous precomputation method, because it is the same
            argument (it has the same name.)

            Additional arguments. May have previously precomputed before
            this method from other precomputed methods, so they can help
            speed up this precomputation avoiding duplicated work.

            The following precomputed items are returned:
                * ``double_absolute_bar`` (int): two times the
                    value of ``absolute_bar``, which may or may not
                    be precomputed in the previous precomputation
                    method. If it is not the case, we precompute
                    ``absolute_bar`` here and also store its value.
                * ``qux`` (float): value is equal to 1.0.
                * ``quux`` (:obj:`complex`) Imaginary value related to
                * ``quuz`` (:obj:`np.ndarray`): an sequence based
                    on ``qux``.
        precomp_vals = {}  # type: t.Dict[str, t.Any]

        if argument_bar is not None and "double_absolute_bar" not in kwargs:
            # May have been precomputed from another precomputation method
            absolute_bar = kwargs.get("absolute_bar")

            # Wrong! 'absolute_bar' may be None
            # precomp_vals["double_absolute_bar"] = 2 * absolute_bar

            if absolute_bar is None:
                absolute_bar = abs(argument_bar)
                # Because we needed to calculate 'absolute_bar' here, does
                # not hurt also storing this value also, to prevent it
                # being recalculated in 'precompute_basic_precomp_method'.
                precomp_vals["absolute_bar"] = absolute_bar

            # Correct: now 'absolute_bar' is guaranteed to be not None
            precomp_vals["double_absolute_bar"] = 2 * absolute_bar

        if not {"qux", "quux", "quuz"}.issubset(kwargs):
            precomp_vals["qux"] = 1.0
            precomp_vals["quux"] = 5 + 1.0j * (precomp_vals["qux"])
            precomp_vals["quuz"] = np.array(
                [precomp_vals["qux"] + i for i in np.arange(5)])

        return precomp_vals

    def precompute_random_values(cls,
                                 random_state: t.Optional[int] = None,
                                 **kwargs) -> t.Dict[str, t.Any]:
        """Precomputation method with pseudo-random behavior.

        1. An important pymfe default argument for you: 'random_state'
        If you are using anything with pseudo-random properties, you shall
        always get the pymfe framework global random seed using the
        ``random_state`` argument. This seed is user defined. You can get
        it for any precomputation, metafeature extraction or post-processing

        2. Important aspects related to pseudo-random behaviour
        Uncontrolled pseudo-random behavior is absolutely forbidden in
        this package.

        Also, pseudo-random methods must have related automated tests.
        Therefore, setting up the random seed (as long as the user define
        it) is never optional.

        random_state : int, optional
            If given, controls the pseudo-random behavior inside this
            method, so the results will be reproducible.

            Additional arguments. May have previously precomputed before
            this method from other precomputed methods, so they can help
            speed up this precomputation avoiding duplicated work.

            The following precomputed items are returned:
                * ``random_special_num`` (float): a random value
                  that must be controlled by the random seed specified
                  by the user using the ``random_state`` pymfe framework
                  global argument.
        precomp_vals = {}  # type: t.Dict[str, t.Any]

        if "random_special_num" not in kwargs:
            if random_state is not None:

            aux = np.random.randint(-5, 5, size=10)
            precomp_vals["random_special_num"] = np.random.choice(aux, size=1)

        return precomp_vals

    def ft_metafeature_name(
            X: np.ndarray,
            y: np.ndarray,
            random_state: t.Optional[int] = None,
            opt_arg_bar: float = 1.0,
            opt_arg_baz: np.ndarray = None,
    ) -> int:
        """Single-line description of this feature extraction method.

        The purpose of this method is to introduce the first actual
        metafeature extraction method.

        1. Metafeature extraction methods: the most important ones
        Similarly to the precomputation methods, the feature extraction
        method names are also prefixed. All your feature extraction method
        names must be prefixed with ``ft_``.

        2. The pymfe framework provides arguments automatically
        As mentioned in the documentation of the very first precomputation
        method, the pymfe framework is responsible to provide to every
        precomputation (those prefixed with ``precompute_``, metafeature
        extraction (those prefixed with ``ft_``) and post-processing (we
        will see those later) methods its arguments. 'How?', you may ask.
        The short answer is dictionary unpacking: the MFE class holds some
        dictionaries that are unpacked while calling those prefixed methods.
        Then, if a method's argument happens to match with a dictionary
        key, that argument will assume the matched key value.

        All precomputed values are packed into one of those dictionaries
        (and it happens automatically; you don't need to worry about it.)
        Therefore, the same value provided as the key of some precomputed
        dictionary is used to match directly the parameter name. All
        parameters must be treated as read-only values; it is forbidden to
        modify any value inside any feature extraction method.

        We will see more about which default parameters are given by the
        pymfe framework soon in the ``ft_fitted_data_arguments`` method
        just below. However, if you want to see with your own eyes the
        actual values, you can check out search for the instance attribute
        ``mfe.MFE._custom_args_ft`` of the MFE class (inside the ``mfe.py``
        module). This attribute is set up inside the ``mfe.MFE.fit`` method.

        If you have a very good reason, feel free to insert new values
        in there if (and only if) they are needed. Note that it is highly

        2. Mandatory & optional arguments of metafeature extraction methods
        The only arguments allowed to be mandatory (i.e., arguments without
        any default value) are the ones registered inside the MFE attribute
        ``_custom_args_ft`` (check this out in the ``mfe.py`` module.)
        All other values must have a default value, without any exception.

        Remember that all arguments can be customized directly by the user
        while calling the ``extract`` MFE method. You usually don't need
        to worry about if the user uses incorrect data types for the
        arguments, as it will most probably raise an TypeError exception.
        However, sometimes you should consider handling incorrect values
        (such as probability arguments with values not within the range
        0 and 1.) Usually, just returning ``np.nan`` (if your metafeature
        is non-summarizable) or ``np.array([np.nan])`` (if your metafeature
        is summarizable)  is one way to go when handling incorrect arguments.

        3. Return values of metafeature extraction methods
        We'll see about this soon in the ``ft_about_return_values`` method.

        X : :obj:`np.ndarray`
            All attributes fitted in the model (numerical and categorical
            ones). While writing your method documentations, you don't need
            to write about very common arguments such as ``X``, ``y``, ``N``
            and ``C``. In fact, you are encouraged to just omit these.

        y : :obj:`np.ndarray`
            Target attributes. Again, no need to write about these type of
            arguments in the method documentation, as it can get way too
            much repetitive without any information gain.

        random_state : int, optional
            Extremely important argument. This one is a fixed feature from the
            MFE framework. If your method has ANY pseudo-random behaviour,
            you should use specifically this argument to provide the random
            seed. In this case, it would be nice if you write about what
            is the random behaviour of your method to make clear to the
            user why he or she ever needs a random seed in the first place.

        opt_arg_bar : float, optional
            Argument used to detect carbon footprints of hungry dinosaurs.

        opt_arg_baz : :obj:`np.ndarray`, optional
            If None, this argument is foo. Otherwise, this argument is bar.

            Give a clear description about the returned value.

        You can use the notes section of the documentation to provide
        references, and also ``very specific`` details of the method.
        # Inside the feature extraction method you can do whenever you
        # want, just make sure to:
        # 1. Always return a single number, a single np.nan or a numpy
        #    array with numeric values (or np.nan) - no exceptions!
        # 2. Make it run as fast as possible. Metafeatures with high
        #    computational complexity are discouraged.

        # You can raise ValueError, TypeError and LinAlgError exceptions.
        if opt_arg_bar <= 0.0:
            raise ValueError("'opt_arg_bar' must be positive!")

        # When using pseudo-random functions, ALWAYS use random_state
        # to enforce experiment replication. Uncontrolled pseudo-random
        # behavior is absolutely forbidden.
        if opt_arg_baz is None:
            opt_arg_baz = np.random.choice(10, size=5, replace=False)

        aux_1, aux_2 = np.array(X.shape) * y.size

        random_ind = np.random.randint(opt_arg_baz.size)

        ret = aux_1 * opt_arg_bar / (aux_2 + opt_arg_baz[random_ind])

        return ret

    def ft_fitted_data_arguments(cls, X: np.ndarray, N: np.ndarray,
                                 C: np.ndarray, y: np.ndarray) -> int:
        """Information about some arguments related to fitted data.

        1. Handling Numerical, Categorical and Mixed data types
        Not all feature extraction methods handles all type of data. Some
        methods only work for numerical values, while others works only for
        categorical values. A few ones work for both data types, but this
        is generally not the case.

        The Pymfe framework provides easy access to the fitted data
        attributes separated by data type (numerical and categorical).

        You can use the attribute ``X`` to get all the original fitted
        data (without any data transformations), attribute ``N`` to get
        only the numerical attributes and, similarly, ``C`` to get only
        the categorical attributes.

        X : :obj:`np.ndarray`
            All fitted original data, without any data transformation
            such as discretization or one-hot encoding.

        N : :obj:`np.ndarray`
            Just numerical attributes of the fitted data, with possibly
            categorical data one-hot encoded (if the user uses this
            type of transformation.)

        C : :obj:`np.ndarray`
            Just the categorical attributes of the fitted data, with
            possibly numerical data discretized (if the user uses
            this type of transformation.)

        y : :obj:`np.ndarray`
            Target attribute.

            Some important return value.

        You can even receive more than one of these attributes in the
        same method, but keep in mind that this may cause confusion as
        the user may enable or disable data transformations (encoding
        for categorical values and discretization for numerical values).
        ret = np.array(X.shape) + np.array(N.shape) + np.array(C.shape)
        return np.prod(ret) * y.size

    def ft_using_precomputed_values(
            y: np.ndarray,
            # y_unique: np.ndarray,  # Wrong! Need an default value.
            y_unique: t.Optional[np.ndarray] = None) -> np.ndarray:
        """Metafeature extraction method using precomputed values.

        1. How to use precomputed arguments
        Within any metafeature extraction method, you can safely assume that
        all precomputation methods (even the ones of other MFE classes) were
        all executed (successfully or not!), and their values are hopefully
        ready to be used as arguments. Note that the pymfe framework has a
        huge resilience against exceptions, so the code will most probably
        continue to flow even if a few precomputation methods were not
        successful for some reasons (e.g., math domain errors.)

        To get precomputed values is no different than getting a pymfe
        default automatic argument (such as ``X`` and ``y``): just match
        the argument name with the precomputed dictionary key. For
        instance, the argument ``y_unique`` was precomputed in the
        ``precompute_basic_precomp_method`` and is probably ready to be used in
        this metafeature extraction method, IF the user does not
        disabled the precomputations. As we can't guarantee whether the
        user will or will not disable the precomputations, we need to
        always check if ``y_unique`` is different than ``None`` before
        using it. If, unfortunatelly, it is not the case, then we need
        to compute ``y_unique`` inside this method.

        2. When to use precomputed arguments
        Always! :)

        3. The precomputation cache is shared among all pymfe classes
        Remember that you can also use precomputed values from other
        pymfe metafeature extraction classes (and, therefore, your
        precomputed values will also be automatically available to the
        other classes aswell.)

        y : :obj:`np.ndarray`
            Target attribute.

        y_unique : :obj:`np.ndarray`, optional
            Argument precomputed in the ``precompute_basic_precomp_method``
            precomputation method. Note that it must be an optional
            argument (because it is forbidden to rely on precomputation
            methods to fill mandatory arguments, as the user can disable
            precomputation methods whenever he or she wants.) Note also
            that the argument name must match exatcly the corresponding
            dictionary key given inside the precomputation method.

            Describe your return value.
        # res = -1.0 * y_unique  # Wrong! 'y_unique' may be None!

        # You need to verify if precomputed values is None. If this
        # is the case, you need to manually compute it inside the method
        # that needs that value.
        if y_unique is None:
            # If ``y_unique`` is None, it means probably that the user
            # disabled the precomputations (or something went wrong inside
            # the precomputation method,) so we need to compute
            # it now as this argument is needed to compute the
            # method's output.

            # Obviously, the computation inside the metafeature
            # extraction method must be identical to the computation
            # in the precomputation method, as both results must
            # always match. Once again, remember:
            # 'If two things have the same name, then they are the
            # same thing'.
            y_unique = np.unique(y, return_counts=False)

        res = -1.0 * y_unique  # Correct: 'y_unique' is surely not None

        return res

    def ft_about_return_values(
            y: np.ndarray,
    ) -> np.ndarray:
        """Information about return values of feature extraction methods.

        1. You have two return options for metafeature extraction methods
        The return value of any feature extraction method should be
        a single value (int, float, numpy number, or a :obj:`np.nan`,)
        or a numpy array. This array must contain only numbers or

        2. What's the difference?
        If the return value is a single number, the output value of this
        method will be transformed directly into a MFE class extract output.
        If it is a numpy array, then this output will automatically be
        summarized using every user selected summary functions.

        3. A more detailed explanation
        If you return a single value, your metafeature is said to be
        'non-summarizable'. It means that the value your method return is
        the value the user will get. If you need to return an invalid
        value, always return 'np.nan'.

        If you return an numpy array, then your metafeature is said to be
        'summarizable', and the user will get a few statistics related to
        the values your method returns (instead of the actual values):
        its mean, standard deviation, quantiles, variance etc. It will
        happen automatically, and you should not worry about this. You
        can put 'np.nan' inside your array. If you need to return an
        entire invalid array, consider returning 'np.array([np.nan])'.
        DO NOT return a single 'np.nan', as it is reserved for the
        'non-summarizable' metafeature extraction methods.

        y : :obj:`np.ndarray`
            Target attribute.

            This method returns a numpy array, so its output value will
            be summarized automatically by the MFE framework before
            outputting to the user.
        # Either your method return a single value, or it return an
        # numpy array. You can't mix both within a single metafeature
        # extraction method.

        if np.any(y < 0):
            # My metafeature can't handle negative 'y' values, so I
            # can return an invalid array

            # return np.nan  # Wrong! It is not an array!
            return np.array([np.nan])  # Correct.

        if y.size > 20:
            return np.power(y, 1 / 4) + np.arange(y.size)

        return np.sqrt(y) + np.arange(y.size)

    def _protected_methods(cls, arg_foo: float) -> float:
        """Tips for using protected methods.

        1. How to use Python's protected methods in pymfe code
        Protected methods (methods whose name starts with a underscore)
        should be used whenever you need to modularize better your code,
        and even more if you need to use the same piece of code between
        two or more different metafeature extraction methods.

        2. Using private methods
        Private methods (methods prefixed with two underscores) are not
        really necessary, and their use must be justified somehow.

        So far, there is not even a single private method in any pymfe

        3. Protected method documentation
        You don't need to follow the standard documentation format for
        protected methods (method description, argument list, return value
        description etc.) Instead, you can be more technical since the
        documentation will probably be more suitable for other developers
        and maintainers of the package. If you fell more confortable with
        the standard format (just like the public methods), there is no
        harm to follow it in the protected method documentation then.

        def inner_functions(x: float, lamb: float = 1.0) -> float:
            """Usage of inner functions.

            1. When to use inner functions
            Use them whenever you need modularize a piece of code that
            is way too much specific for the method that contains it.
            Therefore, it is highly unlikely that this same piece of
            code may ever be used from another method.

            2. How many inner functions per method?
            These functions are quite useful for very complex feature
            extraction methods with many steps needed to reach the final
            result. In that case, consider creating a separated inner
            function for every step.
            return np.abs(np.tanh(x * lamb) * 0.7651j)

        return np.max(inner_functions(arg_foo), 0.0)

    def non_protected_methods_without_any_prefixes(cls) -> None:
        """Don't use non-protected regular methods.

        The main reason to avoid this type of methods is because
        it will be shown in the package documentation despite the
        fact that it is not of the user's interest.
        raise NotImplementedError(
            "Hide me prefixing my name with a single '_'.")

    def postprocess_groupName1_groupName2(
            cls, mtf_names: t.List[str], mtf_vals: t.List[float],
            mtf_time: t.List[float], class_indexes: t.Sequence[int],
            groups: t.Tuple[str, ...], inserted_group_dep: t.FrozenSet[str],
    ) -> t.Optional[t.Tuple[t.List[str], t.List[float], t.List[float]]]:
        """Introduction to post-processing methods.

        1. What is a post-processing method?
        The post-processing methods can be used to either modify in-place
        previously generated metafeatures (not necessarily from the same
        group) or to generate new metafeatures using previously extracted
        metafeatures just before outputting the results to the user. The
        popularity of this type of method is not even close to the
        preprocessing ones, but they may be useful in some specific cases
        (mainly related to `somehow` merge the dependencies data with the
        generated data from the dependent class.)

        For instance, the 'Relative Landmarking' metafeature group is
        entirely based on post-processing methods: that specific group needs
        every 'Landmarking' metafeature results and, therefore, it can be
        computed only after the metafeature extraction process finishes
        (because we have no guarantees of the metafeature extraction order.)

        So, if your MFE class does not have any external dependencies, nor it
        is supposed to somehow merge two or more metafeature values, you
        don't need to read this section, and you are already good to go
        and develop your own MFE class. If it is not your case, then stay
        with us for a couple of extra minutes more.

        2. Structure of a post-processing method
        All post-processing methods receive all previously extracted
        metafeatures from every MFE class. It will not receive just the
        metafeatures related to the metafeature extraction methods of this
        class. It is very import to keep this in mind.

        There's a very important trick with the naming of these post-processing
        methods, other than just prefixing they with ``postprocess_``.
        You can put names of metafeature groups of interest separated by
        underscores. All metafeature indexes related to any of the selected
        groups will arrive in the ``class_indexes`` argument automatically.

        For example, suppose a post-processing method named like:


        This implies that the indices of both `information theory` and
        `statistical` metafeature groups will arrive inside the
        ``class_indexes`` sequence. Using this feature, one can easily
        work with these metafeatures without needing to separate them by
        hand. Of course, you can give as many metafeature group names as
        needed. If you need them all, then simply don't put any metafeature
        group name, as every metafeature is an metafeature of interest in
        this case.

        There were various arguments that are automatically filled for
        this type of methods (as you can see just above in this method
        signature). Check the ``arguments`` section for more details
        about each one.

        3. How many post-processing methods are necessary?
        Just like the preprocessing and metafeature extraction methods,
        an MFE class may have any number post-processing methods, including
        none. In fact, no post-processing method is by far the common case.

        4. Return value of post-processing methods
        The return value of post-processing methods must be either None,
        or a tuple with exactly three lists. In the first case (returning
        None), the post-processing method is probably supposed to modify
        the received metafeature values in-place (which is perfectly
        fine). In the second case (returning three lists), these lists
        will be considered new metafeatures and will be appended to the
        MFE output before given to the user. These lists must follow the
        order given below:

            1. New metafeature names
            2. New metafeature values
            3. Time elapsed to extract every new metafeature

        Now, let's take a quick look at the common post-processing method
        arguments. Note that all the arguments listed below are actual
        arguments from the pymfe framework, and you can use they in your
        post-processing methods.

        mtf_names : :obj:`list` of str
            A list containing all previously extracted metafeature names.

        mtf_vals : :obj:`list` of float
            A list containing all previously extracted metafeature values.

        mtf_time : :obj:`list` of float
            A list containing all time elapsed for each metafeature
            previously extracted.

        class_indexes : Sequence of int
            Indexes of the metafeatures related to this method ``groups of
            interest``. The ``groups of interest`` are the metafeature groups
            whose name are in this method's name after the ``postprocess_``
            prefix, separated with underscores (in this example, they are
            ``groupName1`` and ``groupName2``.)

            If it is not clear for you so far, the metafeatures received
            in this method are all the metafeatures extracted in every MFE
            classes, not just the ones related to this class. Then, this
            argument can be used as reference to target only the metafeatures
            effectively used in this post-processing method.

            If you need every single metafeature extracted for your
            post-processing method, then this argument does not matter (nor
            your post-processing method name, as long as it is correctly
            prefixed with ``postprocess_``) as every metafeature is of your
            particular interest, and there is no need for an auxiliary
            list to split the metafeatures.

        groups : :obj:`tuple` of str
            Extracted metafeature groups (including metafeature groups
            inserted due to group dependencies). Can be used as reference
            inside the post-processing method.

        inserted_group_dep : :obj:`tuple` of :obj:`str
            Extracted metafeature groups due to class dependencies. Can be
            used as a reference inside the post-processing method.

            Just like the preprocessing methods, the kwargs is also
            mandatory in post-processing methods. It can be used to
            retrieve additional arguments using the ``get`` method.

        if not None:
            :obj:`tuple` with three :obj:`list`
                These lists are (necessarily in this order):
                    1. New metafeature names
                    2. New metafeature values
                    3. Time elapsed to extract every new metafeature
        # Sometimes you can cheat pylint in case you are not using some
        # arguments, such as kwargs. Keep in mind that this fact should
        # not be abused just to avoid pylint warnings. Always take some
        # time to fix your code.
        # pylint: disable=W0613

        new_mtf_names = []  # type: t.List[str]
        new_mtf_vals = []  # type: t.List[float]
        new_mtf_time = []  # type: t.List[float]

        # In this example, this post-processing method returns
        # new metafeatures conditionally. Note that this variable
        # ``change_in_place`` is fabricated for this example; it
        # is not a true feature of the Pymfe framework!!! The
        # decision of whether or not to change metafeatures in
        # place depends on your particular context!
        change_in_place = kwargs.get("change_in_place", False)

        if change_in_place:
            # Make changes in-place using the ``class_indexes`` as
            # reference. Note that these indexes are collected using
            # this post-processing method name as reference (check the
            # documentation of this method for a clear explanation.)
            for index in class_indexes:
                time_start = time.time()
                mtf_vals[index] *= 2.0
                mtf_names[index] += ".twice"
                mtf_time[index] += time.time() - time_start

            # Don't return new metafeatures, as the changes made are
            # in-place in this particular situation.
            return None

        # The previous branch was not taken: therefore, the changes
        # are not in-place. This means that new metafeatures will be
        # created and appended to the previously existing ones. Note
        # that whether the new feature values are supposed to be identical
        # to its in-place variants are context dependent. If you have
        # good reasons to do make they different, then you are allowed to.

        # Create new metafeatures (in this case, the user will receive
        # twice as many values as separated metafeatures.) Note that the
        # number of new metafeatures also is context dependent: your
        # post-processing method may return as many as new metafeatures it
        # is supposed to return.
        for index in class_indexes:
            time_start = time.time()
            new_mtf_vals.append(-1.0 * new_mtf_vals[index])
            new_mtf_time.append(new_mtf_time[index] + time.time() - time_start)

        # Finally:
        # Return new metafeatures produced in this method. Pay attention to the
        # order of these lists, as it must be preserved for any post-processing
        # method.
        return new_mtf_names, new_mtf_vals, new_mtf_time

Total running time of the script: ( 0 minutes 0.005 seconds)

Gallery generated by Sphinx-Gallery