#!/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 csv
import itertools
import collections
import pypath.resources.urls as urls
import pypath.share.curl as curl
import pypath.utils.taxonomy as taxonomy
import pypath.utils.mapping as mapping
import pypath.internals.intera as intera
import pypath.share.session as session
import pypath.core.entity as entity
_logger = session.Logger(name = 'cellinker_input')
_log = _logger._log
CellinkerInteraction = collections.namedtuple(
'CellinkerInteraction',
(
'ligand',
'receptor',
'ligand_location',
'receptor_location',
'resources',
'pmids',
'type',
),
)
[docs]
def cellinker_complexes_raw(organism = 9606):
"""
Downloads protein complex data from the Cellinker database
(http://www.rna-society.org/cellinker/).
Args
organism (int,str): Name or identifier of the organism. Only mouse
and human are available.
Returns
(list): List of tuples each describing a protein complex with its
role (ligand or receptor), components, localization and
Cellinker ID.
"""
CellinkerComplex = collections.namedtuple(
'CellinkerComplex',
(
'role',
'cellinker_id',
'components',
'location',
),
)
CellinkerComplexComponent = collections.namedtuple(
'CellinkerComplexComponent',
(
'genesymbol',
'entrez',
),
)
organism_common = taxonomy.ensure_common_name(organism).lower()
if organism_common not in {'human', 'mouse'}:
msg = (
'Unknown organism: %s (%s). Only human and mouse '
'are available.' % (str(organism_common), str(organism))
)
_log(msg)
raise ValueError(msg)
url = urls.urls['cellinker_rescued']['complex'] % organism_common
c = curl.Curl(url, large = True, silent = False)
result = []
_ = next(c.result)
for r in c.result:
r = r.split(',')
components = tuple(
CellinkerComplexComponent(
genesymbol = r[i],
entrez = r[i + 1],
)
for i in range(3, 13, 2)
if r[i]
)
result.append(
CellinkerComplex(
role = 'ligand' if r[0] else 'receptor',
cellinker_id = r[0] or r[1],
components = components,
location = r[13],
)
)
return result
[docs]
def components_to_complex(components, organism = None):
"""
Converts a set of components to `pypath.internals.intera.Complex`
objects.
Args
components (tuple): Components of a complex, as returned by
`cellinker_complexes_raw`.
organism (int,str): Name or identifier of the organism. Only mouse
and human are available. Optional, because organism can be
guessed from the identifiers.
Returns
(set): A set of `pypath.internals.intera.Complex` objects.
"""
if not organism:
organism = (
9606 if (
all(c.genesymbol.upper() == c.genesymbol for c in components)
) else 10090
)
_organism = taxonomy.ensure_ncbi_tax_id(organism)
if _organism not in {9606, 10090}:
msg = (
'Unknown organism: %s (%s). Only human and mouse '
'are available.' % (str(_organism), str(organism))
)
_log(msg)
raise ValueError(msg)
result = set()
for uniprots in itertools.product(*(
_cellinker_uniprots(c.genesymbol, c.entrez, _organism)
for c in components
)):
result.add(
intera.Complex(
components = uniprots,
ncbi_tax_id = _organism,
sources = 'Cellinker',
)
)
return result
[docs]
def cellinker_complexes(organism = 9606):
"""
Protein complex information from the Cellinker database
(http://www.rna-society.org/cellinker/).
Args
organism (int,str): Name or identifier of the organism. Only mouse
and human are available.
Returns
(dict): A dict of complexes, with string representations as keys and
`pypath.internals.intera.Complex` objects as values.
"""
result = {}
for c in cellinker_complexes_raw(organism = organism):
for cplex in components_to_complex(c.components, organism = organism):
result[cplex.__str__()] = cplex
return result
[docs]
def cellinker_lr_interactions_raw(organism = 9606):
"""
Ligand-receptor interactions from the Cellinker database
(http://www.rna-society.org/cellinker/).
Args
organism (int,str): Name or identifier of the organism. Only mouse
and human are available.
Returns
(list): A list of dicts, each representing an interaction records
as it is provided by the database.
"""
return _cellinker_interactions_raw(organism = organism)
[docs]
def cellinker_smol_interactions_raw(organism = 9606):
"""
Small molecule ligand-protein receptor interactions from the Cellinker
database (http://www.rna-society.org/cellinker/).
Args
organism (int,str): Name or identifier of the organism. Only mouse
and human are available.
Returns
(list): A list of dicts, each representing an interaction records
as it is provided by the database.
"""
return _cellinker_interactions_raw(dataset = 'smol', organism = organism)
def _cellinker_interactions_raw(dataset = 'lr', organism = 9606):
"""
Downloads either the ligand-receptor or the small molecule ligand-receptor
dataset from the Cellinker database.
Args
dataset (str): Either `lr` or `smol`, meainng protein-protein or
small molecule-protein ligand-receptor interactions.
organism (int,str): Name or identifier of the organism. Only mouse
and human are available.
Returns
(list): A list of dicts, each representing an interaction records
as it is provided by the database.
"""
if dataset not in {'lr', 'smol'}:
msg = 'Unknown Cellinker interaction dataset: `%s`.' % str(dataset)
_log(msg)
raise ValueError(msg)
org_name_type = 'latin' if dataset == 'lr' else 'common'
organisms_allowed = (
{'Homo sapiens', 'Mus musculus'}
if org_name_type == 'latin' else
{'Human', 'Mouse'}
)
_organism = getattr(taxonomy, 'ensure_%s_name' % org_name_type)(organism)
if _organism not in organisms_allowed:
msg = (
'Unknown organism: %s (%s). Only human and mouse '
'are available.' % (str(_organism), str(organism))
)
_log(msg)
raise ValueError(msg)
if org_name_type == 'common': _organism = _organism.lower()
url = urls.urls['cellinker_rescued'][dataset] % _organism
c = curl.Curl(url, large = True, silent = False)
result = list(csv.DictReader(c.result, delimiter = '\t'))
return result
[docs]
def cellinker_lr_interactions(organism = 9606):
"""
Ligand-receptor interactions from the Cellinker database
(http://www.rna-society.org/cellinker/).
Args
organism (int,str): Name or identifier of the organism. Only mouse
and human are available.
Returns
(set): A set of tuples, each representing a preprocessed Cellinker
interaction. The proteins are represented by their UniProt IDs,
while the protein complexes by `Complex` objects.
"""
db_names = {
'IUPHAR': 'Guide2Pharma',
'CellphoneDB': 'CellPhoneDB',
}
result = set()
raw = cellinker_lr_interactions_raw(organism = organism)
ncbi_tax_id = taxonomy.ensure_ncbi_tax_id(organism)
complexes = dict(
(
c.cellinker_id,
components_to_complex(c.components, organism = ncbi_tax_id)
)
for c in cellinker_complexes_raw(organism = organism)
)
for r in raw:
ligands = _cellinker_uniprots(
r['Ligand_symbol'],
r['Ligand_id'],
ncbi_tax_id,
complexes = complexes,
)
receptors = _cellinker_uniprots(
r['Receptor_symbol'],
r['Receptor_id'],
ncbi_tax_id,
complexes = complexes,
)
resources = ';'.join(
db_names.get(db, db)
for db in r['Other.DB'].split(';')
) or None
for ligand, receptor in itertools.product(ligands, receptors):
result.add(
CellinkerInteraction(
ligand = ligand,
receptor = receptor,
ligand_location = r['Ligand_location'],
# yes, labels are not consistent
receptor_location = r['Receptor.location'],
resources = resources,
pmids = r['Pmubmed.ID'] or None, # typo
type = r['Type'],
)
)
return result
[docs]
def cellinker_smol_interactions(organism = 9606):
"""
Small molecule ligand-protein receptor interactions from the Cellinker
database (http://www.rna-society.org/cellinker/).
Args
organism (int,str): Name or identifier of the organism. Only mouse
and human are available.
Returns
(set): A set of tuples, each representing a preprocessed Cellinker
interaction. The proteins are represented by their UniProt IDs,
the small molecules by PubChem CIDs, while the protein complexes
by `Complex` objects.
"""
db_names = {
'IUPHAR': 'Guide2Pharma',
'CellphoneDB': 'CellPhoneDB',
}
result = set()
raw = cellinker_smol_interactions_raw(organism = organism)
ncbi_tax_id = taxonomy.ensure_ncbi_tax_id(organism)
complexes = dict(
(
c.cellinker_id,
components_to_complex(c.components, organism = ncbi_tax_id)
)
for c in cellinker_complexes_raw(organism = organism)
)
for r in raw:
if not r['ligand_pubchem_cid']:
continue
ligands = (r['ligand_pubchem_cid'],)
receptors = _cellinker_uniprots(
r['Receptor_symbol'],
r['Receptor_id'],
ncbi_tax_id,
complexes = complexes,
)
resources = ';'.join(
db_names.get(db, db)
for db in r['Other.DB'].split(';')
) or None
for ligand, receptor in itertools.product(ligands, receptors):
result.add(
CellinkerInteraction(
ligand = ligand,
receptor = receptor,
ligand_location = None,
receptor_location = r['Receptor_location'],
resources = resources,
pmids = r['pubmed_id'] or None,
type = r['Type'],
)
)
return result
[docs]
def cellinker_annotations(organism = 9606, entity_type = None):
"""
Ligand and receptor annotations from the Cellinker database
(http://www.rna-society.org/cellinker/).
Args
organism (int,str): Name or identifier of the organism. Only mouse
and human are available.
entity_type (str): Either `protein` or `complex`. If `None`, both
proteins and protein complexes will be included.
Returns
(dict): A dict of sets of tuples, keys are UniProt IDs for proteins
and `Complex` objects for protein complexes. The tuples are
annotations with ligand or receptor role, localization and
type.
"""
CellinkerAnnotation = collections.namedtuple(
'CellinkerAnnotation',
(
'role',
'location',
'type',
),
)
ia = cellinker_lr_interactions(organism = organism)
result = collections.defaultdict(set)
for i in ia:
for role in ('ligand', 'receptor'):
this_entity = getattr(i, role)
this_entity_type = entity.Entity._get_entity_type(this_entity)
if not entity_type or entity_type == this_entity_type:
result[this_entity].add(
CellinkerAnnotation(
role = role,
location = getattr(i, '%s_location' % role),
type = i.type,
)
)
return dict(result)
[docs]
def cellinker_protein_annotations(organism = 9606):
"""
Ligand and receptor annotations from the Cellinker database
(http://www.rna-society.org/cellinker/).
Args
organism (int,str): Name or identifier of the organism. Only mouse
and human are available.
Returns
(dict): A dict of sets of tuples, keys are UniProt IDs. The tuples
are annotations with ligand or receptor role, localization and
type.
"""
return cellinker_annotations(organism = organism, entity_type = 'protein')
[docs]
def cellinker_complex_annotations(organism = 9606):
"""
Ligand and receptor annotations from the Cellinker database
(http://www.rna-society.org/cellinker/).
Args
organism (int,str): Name or identifier of the organism. Only mouse
and human are available.
Returns
(dict): A dict of sets of tuples, keys are `Complex` objects.
The tuples are annotations with ligand or receptor role,
localization and type.
"""
return cellinker_annotations(organism = organism, entity_type = 'complex')
def _cellinker_uniprots(gsymbol, entrez, ncbi_tax_id, complexes = None):
"""
Translates the Gene Symbols and Entrez Gene IDs to UniProt IDs.
Returns
(set): Set of UniProt IDs.
"""
return (
complexes[entrez]
if complexes and entrez in complexes else
(
mapping.map_name(
gsymbol,
'genesymbol',
'uniprot',
ncbi_tax_id = ncbi_tax_id,
) |
mapping.map_name(
entrez,
'entrez',
'uniprot',
ncbi_tax_id = ncbi_tax_id,
)
)
)
