nichenetpy.network

  1from nichenetpy.io import read_network, read_weighted_network
  2from nichenetpy.typing import gene_t
  3
  4from collections.abc import Collection, Iterator
  5from itertools import chain
  6
  7import pandas as pd
  8
  9
 10class Network:
 11    '''
 12    A network with links. This is in essence a one to many mapping. 
 13
 14    Parameters
 15    ----------
 16    mapping : list or pandas.DataFrame or None
 17        sorted list of tuples (from, to) or pandas dataframe with keys ("from", "to")
 18    filename : str or None
 19        name of the file to read the network from
 20
 21    Raises
 22    ------
 23    TypeError
 24        if the arguments have the wrong type
 25    ValueError
 26        if neither mapping nor filename is provided
 27    
 28    Attributes
 29    ----------
 30    mapping : list
 31        sorted list of tuples (from, to)
 32    _index : dict
 33        index for the mapping
 34    
 35    Notes
 36    -----
 37    You must pass a list SORTED by "from" as mapping, a pandas dataframe with keys ("from", "to") or the name of a file to read from. 
 38    '''
 39    def __init__(self, mapping:list|pd.DataFrame|None=None, filename:str|None=None):
 40        if mapping is not None:
 41            if type(mapping) is pd.DataFrame:
 42                mapping = sorted(
 43                    zip(mapping["from"].tolist(), mapping["to"].tolist()),
 44                    key=lambda x : x[0]
 45                )
 46            elif type(mapping) is not list:
 47                raise TypeError(f"mapping should have type list or pandas.DataFrame, was {type(mapping)}")
 48            self._mapping = mapping
 49        elif filename is not None:
 50            if type(filename) is not str:
 51                raise TypeError(f"filename should have type str, was {type(filename)}")
 52            self._mapping = sorted(
 53                read_network(filename),
 54                key=lambda x : x[0]
 55            )
 56        else:
 57            raise ValueError("either mapping or filename must be provided as arguments")
 58        self._index = dict()
 59        self._build_index()
 60    
 61    def __str__(self) -> str:
 62        return self._mapping.__str__()
 63
 64    def __getitem__(self, key) -> set:
 65        return set(self.mapping_iter(key))
 66    
 67    def __len__(self):
 68        return len(self._mapping)
 69    
 70    def __iter__(self):
 71        return self._mapping.__iter__()
 72    
 73    def __contains__(self, item:tuple):
 74        start, count = self._index[item[0]]
 75        return item in self._mapping[start:start+count]
 76    
 77    def _build_index(self):
 78        self._index.clear()
 79        for i, item in enumerate(self._mapping):
 80            if item[0] in self._index:
 81                self._index[item[0]][1] += 1
 82            else:
 83                self._index[item[0]] = [i, 1]
 84
 85    def key_iter(self):
 86        '''
 87        Iterates over the "from" values in the mapping. 
 88        
 89        Yields
 90        ------
 91        gene_t
 92            the "from" values in the mapping
 93        '''
 94        return (self._mapping[start][0] for start, _ in self._index.values())
 95
 96    def item_iter(self):
 97        '''
 98        Iterates over the "from" values in the mapping along with the corresponding "to" values. 
 99        
100        Yields
101        ------
102        tuple
103            the "from" values in the mapping and a list of corresponding "to" values
104        '''
105        return ((key, self[key]) for key in self.key_iter())
106    
107    def mapping_iter(self, key) -> Iterator:
108        '''
109        Iterates over the "to" values that correspond with the specified "from" value. 
110        
111        Yields
112        ------
113        tuple
114            the "to" values in the mapping
115        '''
116        try:
117            start, count = self._index[key]
118        except KeyError:
119            raise KeyError(f"there is no edge with '{key}' as source")
120        for item in self._mapping[start:start+count]:
121            yield item[1]
122    
123    def get_all(self) -> set:
124        '''
125        Return all values that are present in the network. 
126        
127        Yields
128        ------
129        set
130            all values present in the network
131        '''
132        return set(chain(*zip(*self._mapping)))
133    
134    def subset(self, from_to:Collection[tuple[gene_t, gene_t]]):
135        '''
136        Subset the network by the provided links. 
137
138        Parameters
139        ----------
140        from_to : Collection
141            collection of tuples (from, to) to subset by
142
143        Returns
144        -------
145        Network
146            the subsetted network
147        
148        Raises
149        ------
150        TypeError
151            if the arguments have the wrong type
152        '''
153        if not isinstance(from_to, Collection):
154            raise TypeError(f"from_to should be a Collection of tuple[gene_t, gene_t], was {type(from_to)}")
155        return type(self)(mapping=[tup for tup in self._mapping if (tup[0], tup[1]) in from_to])
156
157    def subset_sep(self, fr:Collection[gene_t]|None=None, to:Collection[gene_t]|None=None):
158        '''
159        Subset the network by the provided "from" and "to" values. 
160
161        Parameters
162        ----------
163        from : Collection or None
164            collection of "from" values to subset by
165        to : Collection or None
166            collection of "to" values to subset by
167
168        Returns
169        -------
170        Network
171            the subsetted network
172        
173        Raises
174        ------
175        TypeError
176            if the arguments have the wrong type
177        '''
178        if fr is None:
179            fr = set(self.key_iter())
180        if to is None:
181            to = set(e for _, e in self._mapping)
182        if not isinstance(fr, Collection):
183            raise TypeError(f"fr should be a Collection of gene_t, was {type(fr)}")
184        if not isinstance(to, Collection):
185            raise TypeError(f"to should be a Collection of gene_t, was {type(to)}")
186        return type(self)(mapping=[tup for tup in self._mapping if tup[0] in fr and tup[1] in to])
187    
188    def to_dataframe(self):
189        '''
190        Convert the network to a dataframe
191
192        Returns
193        -------
194        pandas.DataFrame
195            the network as a dataframe
196        '''
197        return pd.concat([
198            pd.DataFrame({"from": fr, "to": list(tos)})
199            for fr, tos in self.item_iter()
200        ])
201
202class LigandReceptorNetwork(Network):
203    '''
204    A ligand-receptor network without weights. This is in essence a one to many mapping. 
205
206    Parameters
207    ----------
208    mapping : list
209        sorted list of tuples (from, to)
210    filename : str
211        name of the file to read the network from
212    
213    Raises
214    ------
215    TypeError
216        if the arguments have the wrong type
217    ValueError
218        if neither mapping nor filename is provided
219    
220    Attributes
221    ----------
222    mapping : list
223        sorted list of tuples (from, to)
224    _index : dict
225        index for the mapping
226    
227    Notes
228    -----
229    You must pass a list SORTED by "from" as mapping or the name of a file to read from. 
230    '''
231    def get_ligands(self) -> set[gene_t]:
232        '''
233        Get all the ligands present in the network. 
234        
235        Returns
236        -------
237        set
238            set of ligands present in the network
239        '''
240        return set(self.key_iter())
241    
242    def get_receptors(self) -> set[gene_t]:
243        '''
244        Get all the receptors present in the network. 
245        
246        Returns
247        -------
248        set
249            set of receptors present in the network
250        '''
251        return set(receptor for _, receptor in self._mapping)
252
253class WeightedNetwork(Network):
254    '''
255    A ligand-receptor network with weighted links. This is in essence a one to many mapping. 
256
257    Parameters
258    ----------
259    mapping : list or pandas.DataFrame or None
260        sorted list of tuples (from, to, weight) or pandas dataframe with keys ("from", "to", "weight")
261    filename : str or None
262        name of the file to read the network from
263    
264    Raises
265    ------
266    TypeError
267        if the arguments have the wrong type
268    
269    Attributes
270    ----------
271    mapping : list
272        sorted list of tuples (from, to, weight)
273    _index : dict
274        index for the mapping
275    '''
276    def __init__(self, mapping:list|pd.DataFrame|None=None, filename:str=None):
277        if filename is not None:
278            if type(filename) is not str:
279                raise TypeError(f"filename should have type str, was {type(filename)}")
280            mapping = sorted(
281                read_weighted_network(filename),
282                key=lambda x : x[0]
283            )
284        elif type(mapping) is pd.DataFrame:
285            mapping = sorted(
286                zip(mapping["from"], mapping["to"], mapping["weight"]),
287                key=lambda x : x[0]
288            )
289        super().__init__(mapping=mapping)
290    
291    def __getitem__(self, key:gene_t) -> dict[gene_t, float]:
292        start, count = self._index[key]
293        return dict(item[1:3] for item in self._mapping[start:start+count])
294    
295    def get_ligands(self) -> set[gene_t]:
296        '''
297        Get all the ligands present in the network. 
298        
299        Returns
300        -------
301        set
302            set of ligands present in the network
303        '''
304        return set(self.key_iter())
305    
306    def get_receptors(self) -> set[gene_t]:
307        '''
308        Get all the receptors present in the network. 
309        
310        Returns
311        -------
312        set
313            set of receptors present in the network
314        '''
315        return set(receptor for _, receptor, _ in self._mapping)
316    
317    def to_dataframe(self):
318        '''
319        Convert the network to a dataframe
320
321        Returns
322        -------
323        pandas.DataFrame
324            the network as a dataframe
325        '''
326        temp = []
327        for fr, mapping in self.item_iter():
328            tos, ws = zip(*mapping.items())
329            temp.append(pd.DataFrame({"from": fr, "to": tos, "weight": ws}))
330        return pd.concat(temp)