Source code for pypath.internals.annot_formats

#!/usr/bin/env python
# -*- coding: utf-8 -*-

#
#  This file is part of the `pypath` python module
#
#  Copyright 2014-2023
#  EMBL, EMBL-EBI, Uniklinik RWTH Aachen, Heidelberg University
#
#  Authors: see the file `README.rst`
#  Contact: Dénes Türei (turei.denes@gmail.com)
#
#  Distributed under the GPLv3 License.
#  See accompanying file LICENSE.txt or copy at
#      https://www.gnu.org/licenses/gpl-3.0.html
#
#  Website: https://pypath.omnipathdb.org/
#

import collections

try:
    import collections.abc as collections_abc
except:
    import collections as collections_abc

import pypath.share.settings as settings
import pypath.share.common as common
import pypath.core.entity as entity


AnnotDefKey = collections.namedtuple(
    'AnnotDefKey',
    [
        'name',
        'parent',
        'resource',
    ],
)



[docs]
class AnnotDef(
        collections.namedtuple(
            'AnnotDefBase',
            [
                'name',
                'resource',
                'parent',
                'aspect',
                'scope',
                'source',
                'args',
                'exclude',
                'transmitter',
                'receiver',
                'resource_name',
                'limit',
                'avoid',
                'enabled',
            ]
        )
    ):
    """
    Annotations are defined by a ``name``, a ``resource`` and an ``args``
    parameter. If the former is a string it will be first looked up among the
    annotation resources in ``pypath.annot.db``. Otherwise among the keys of
    the classes in the ``CustomAnnotation`` object or in the dictionary of
    the class_definitions. If ``source`` is a `set`, it will be used as a
    category without further processing. If it is callable it will be called
    and should return a `set`. If ``bool(args)`` is `False`, in case of
    annotations in ``pypath.annot.db`` the ``to_set`` method will be called.
    Otherwise ``args`` will be passed to the ``get_subset`` method.
    If ``resource`` is callable, ``args`` will be passed if available.
    """


    def __new__(
            cls,
            name,
            resource,
            parent = None,
            aspect  = 'functional',
            scope = 'specific',
            source = 'resource_specific',
            args = None,
            exclude = None,
            transmitter = None,
            receiver = None,
            resource_name = None,
            limit = None,
            avoid = None,
            enabled = True,
        ):

        resource_name = (
            resource
                if cls._is_resource_name(resource) else
            (
                resource_name or
                settings.get('annot_composite_database_name') or
                'Unknown'
            )
        )

        return super().__new__(
            cls,
            name = name,
            resource = resource,
            parent = parent or name,
            aspect = aspect,
            scope = scope,
            source = source,
            args = args,
            exclude = exclude,
            transmitter = transmitter,
            receiver = receiver,
            resource_name = resource_name,
            limit = cls._zero_one_or_more(limit),
            avoid = cls._zero_one_or_more(avoid),
            enabled = enabled,
        )


    @property
    def key(self):

        return AnnotDefKey(
            name = self.name,
            parent = self.parent,
            resource = self.resource_name,
        )


    @staticmethod
    def _is_resource_name(name):

        return (
            isinstance(name, str) and
            not (
                name.startswith('~') or
                name.startswith('#')
            )
        )


    @staticmethod
    def _zero_one_or_more(arg):

        return (
            ()
                if not arg else
            (arg,)
                if isinstance(arg, (str, _annot_type)) else
            arg
        )





[docs]
class AnnotOp(
        collections.namedtuple(
            'AnnotOpBase',
            ['annots', 'op'],
        )
    ):
    """
    Annotation operations consist of list of annotation definitions or names as
    they can be looked up in the ``class_definitions`` of the
    ``CustomAnnotation`` object and an operator to be called on the sets
    (union, intersection or difference).
    """

    def __new__(cls, annots, op = set.union):

        if op in AnnotationGroup._set_methods:

            op = getattr(AnnotationGroup, op.__name__)

        return super().__new__(cls, annots, op)




[docs]
class AnnotationGroup(collections_abc.Set):
    """
    Represents a set of molecular entities sharing a custom defined
    annotation. This class behaves like a ``set`` and set operations on it
    result set objects. Normally this class is instantiated by
    ``pypath.core.annot.CustomAnnotation`` in the process of populating
    categories and the contents of the groups defined in
    ``pypath.core.intercell_annot`` in case of annotations of the
    intercellular communication roles.
    For detailed definitions of the parameter values see the Supplementary
    Table S10 in Turei et al. 2020 (in prep).

    :param list,set,tuple members:
        The identifiers of the entities in the category.
    :param str name:
        The name of the category.
    :param str parent:
        The name of the parent category; might be the same as ``name`` in
        case of high level (generic) categories.
    :param str aspect:
        Either *functional* or *locational*.
    :param str source:
        Either *resource_specific* or *composite*.
    :param str scope:
        Either *specific* or *generic*.
    :param str resource:
        The resource (database) name; in case of composite categories it
        should be the name of the database you are actually building, this
        by default is `OmniPath` and you can change by the
        ``pypath.share.settings`` module using the
        ``annot_composite_database_name`` key.
    :param bool transmitter:
        Whether the category contains transmitters of signaling information
        from the cell expressing the molecular entities in direction of other
        cells.
    :param bool receiver:
        Whether the category contains receivers of signaling information
        from other cells in direction of the cells expressing the molecular
        entites in the category.
    :param str,set limit:
        Limit to this or these categories. E.g. if it's 'extracellular'
        the result will be the intersection of this category and
        'extracellular' i.e. the category will be limited to extracellular
        proteins.
    :param str,set avoid:
        Avoid elements of this or these categories. E.g. if it's
        'cell_surface' then all cell_surface proteins will be removed from
        this category.
    """


    _set_methods = {
        set.union,
        set.intersection,
        set.difference,
        set.symmetric_difference,
    }



[docs]
    def __init__(
            self,
            members,
            name = None,
            parent = None,
            aspect = 'functional',
            source = 'resource_specific',
            scope = 'specific',
            resource = None,
            transmitter = None,
            receiver = None,
            limit = None,
            avoid = None,
            enabled = True,
        ):

        collections_abc.Set.__init__(self)
        self.members = set(members)
        self.name = name or 'unnamed'
        self.parent = parent or self.name
        self.aspect = aspect
        self.source = source
        self.scope = scope
        self.resource = (
            resource or
            settings.get('annot_composite_database_name') or
            'Unknown'
        )
        self.transmitter = transmitter
        self.receiver = receiver
        self.limit = common.to_set(limit)
        self.avoid = common.to_set(avoid)
        self.enabled = enabled



    def __iter__(self):

        return self.members.__iter__()


    def __contains__(self, other):

        return other in self.members


    def __len__(self):

        return len(self.members)


    @classmethod
    def _from_iterable(cls, iterable):

        return set(iterable)


    def __repr__(self):

        return '<AnnotationGroup `%s` from %s, %u elements>' % (
            self.name,
            self.resource,
            len(self),
        )


    @property
    def label(self):

        return '%s%s@%s' % (
            self.parent,
            '::%s' % self.name if self.name != self.parent else '',
            self.resource
        )


    @property
    def name_label(self):

        return common.upper0(self.name).replace('_', ' ')


    @property
    def key(self):

        return AnnotDefKey(
            name = self.name,
            parent = self.parent,
            resource = self.resource,
        )



[docs]
    def filter_entity_type(self, entity_type = None):
        """
        Returns a copy of the group with only the selected entity types.
        If ``entity_type`` is None returns the object itself.
        """

        if entity_type is None:

            return self

        else:

            members = entity.Entity.filter_entity_type(
                self.members,
                entity_type = entity_type,
            )

            return AnnotationGroup(
                members = members,
                name = self.name,
                parent = self.parent,
                aspect = self.aspect,
                source = self.source,
                scope = self.scope,
                resource = self.resource,
                transmitter = self.transmitter,
                receiver = self.transmitter,
            )



    def count_entity_type(self, entity_type = None):

        return (
            entity.Entity.count_entity_type(
                self.members,
                entity_type = entity_type,
            )
        )


    @property
    def args(self):

        return dict(**self)


    def keys(self):

        return ['name', 'parent', 'source', 'scope', 'aspect']


    def __getitem__(self, key):

        return getattr(self, key)


    @property
    def n_proteins(self):

        return self.count_entity_type(entity_type = 'protein')


    @property
    def n_mirnas(self):

        return self.count_entity_type(entity_type = 'mirna')


    @property
    def n_complexes(self):

        return self.count_entity_type(entity_type = 'complex')


    @property
    def proteins(self):

        return self.filter_entity_type(entity_type = 'protein')


    @property
    def complexes(self):

        return self.filter_entity_type(entity_type = 'complex')


    @property
    def mirnas(self):

        return self.filter_entity_type(entity_type = 'mirna')


    @staticmethod
    def sets(*args):

        return (
            (
                a
                    if isinstance(a, set) else
                a.members
                    if hasattr(a, 'members') else
                common.to_set(a)
            )
            for a in args
        )


    @classmethod
    def union(cls, *args):

        return set.union(*cls.sets(*args))


    @classmethod
    def intersection(cls, *args):

        return set.intersection(*cls.sets(*args))


    @classmethod
    def difference(cls, *args):

        return set.difference(*cls.sets(*args))


    @classmethod
    def symmetric_difference(cls, *args):

        return set.symmetric_difference(*cls.sets(*args))



[docs]
    @classmethod
    def isdisjoint(cls, *args):

        return set.isdisjoint(*cls.sets(*args))




_set_type = (set, AnnotationGroup)
_annot_type = _set_type + (AnnotDef, AnnotOp)