Combinatorial peptide pooling

Intro

Task

Algorithm

Installation

You can install the package with pip:

pip install combinatorial_peptide_pooling

Or with conda:

conda install -c vasilisa.kovaleva combinatorial_peptide_pooling

Usage

import combinatorial_peptide_pooling as cpp

To use the package for basic tasks, the Quickstart section is enough. To read more about used functions, check other sections.

Quickstart

*[optional] Check your peptide list for overlap consistency.

Uncosistent overlap length can lead to hindered results interpretation.

You can check all peptides for their overlap length with the next peptide (list of peptides should be ordered):

cpp.all_overlaps(lst)

Parameters:

lst : list, list of peptides (ordered)

The function returns the Counter object with the dictionary, where the key is the overlap length and the value is the number of pairs with such overlap.

cpp.all_overlaps(lst)

Counter({12: 251, 16: 1})

=> 251 pairs of peptides with an overlap of length of 12 amino acids, and 1 pair with an overlap of length 16 amino acids.

Also, you can check which peptides have such an overlap with the next peptide:

cpp.find_pair_with_overlap(lst, target_overlap)

Parameters:

lst : list of peptides (ordered)

target_overlap : int, overlap length

cpp.find_pair_with_overlap(lst, 16)

[['FDEDDSEPVLKGVKLHY', 'DEDDSEPVLKGVKLHYT']]

Also, you can check what number of peptides share the same epitope. It might help to interpret the results later.

cpp.how_many_peptides(lst, ep_length)

Parameters :

lst : list, list of peptides (ordered)

ep_length : int, expected epitope length

The function returns 1) the Counter object with the number of epitopes shared across the number of peptides; 2) the dictionary with all possible epitopes of expected length as keys and the number of peptides where these epitopes are present as values.

t,r = how_many_peptides(lst, 8)

t

Counter({1: 6, 2: 1256, 3: 4})

r

{'MFVFLVLL': 1,``'FVFLVLLP': 1,``VFLVLLPL': 1,``'FLVLLPLV': 1,``'LVLLPLVS': 1,``'VLLPLVSS': 2, ..., }
*[optional] Then you need to determine peptide occurrence across pools, i.e. to how many pools one peptide would be added.

cpp.find_possible_k_values(n, l)

Parameters:

n : int, number of pools

l : int, number of peptides

The function returns a list with possible occurrences given such parameters.

cpp.find_possible_k_values(12, 250)

[4, 5, 6, 7, 8]

Choose one occurrence value appropriate for your task and proceed.
Now, you need to find the address arrangement given your number of pools (n_pools), number of peptides (len_list), and peptide occurrence (iters).

We suggest you use the address_arrangement_AU function. In the section “Address arrangement” you can find other functions that can perform such a task (based on Gray codes and based on trivial Hamiltonian path search).

b, lines = cpp.address_rearrangement_AU(n_pools, iters, len_lst)

Parameters:

n_pools : int, number of pools

iters : int, peptide occurrence

len_lst : int, number of peptides

With large parameters, the algorithm needs some time to finish the arrangement. If the arrangement fails, try with other parameters.

The function returns b — the expected number of peptides in each pool and lines — address arrangement in the list.

b, lines = cpp.address_rearrangement_AU(n_pools=12, iters=4, len_lst=250)

b

[81, 85, 85, 85, 81, 82, 87, 81, 85, 81, 84, 83]

lines

[[0, 1, 2, 3],``[0, 1, 3, 6],``[0, 1, 6, 8],``[1, 6, 8, 9],``[6, 8, 9, 11], ... ]
Now, you can distribute peptides across pools using the produced address arrangement. One peptide will be added to one produced address. Keep in mind that peptides should be ordered as they overlap.

pools, peptide_address = cpp.pooling(lst, addresses, n_pools)

Parameters:

lst : list, list with peptides (ordered)

addresses : list, produced address arrangement, in lines

n_pools : int, number of pools

The function returns pools — dictionary with keys as pool indices and values as peptides that should be added to this pool and peptide_address — dictionary with peptides as keys and corresponding addresses as values.

pools, peptide_address = cpp.pooling(lst=lst, addresses=lines, n_pools=12)

pools

{0: ['MFVFLVLLPLVSSQCVN',``'VLLPLVSSQCVNLTTRT',``VSSQCVNLTTRTQLPPA', ...], 1: ['MFVFLVLLPLVSSQCVN', 'VLLPLVSSQCVNLTTRT',``'TQDLFLPFFSNVTWFHA', ...], ... }

peptide_address

{'MFVFLVLLPLVSSQCVN': [0, 1, 2, 3],``'VLLPLVSSQCVNLTTRT': [0, 1, 2, 10], ... }

Now, you can run the simulation using produced pools and peptide_address. The simulation produces a DataFrame with every possible epitope of the provided length and all pools where this epitope is present. This table can be used to interpret the results.

The function has two regimes: with and without drop-outs. Without drop-outs, it returns a table as there were no mistakes, and all pools that should be activated were activated. With drop-outs, it returns a table with all possible mistakes (i.e. all possible non-activated pools). This option will need time to be generated, usually several minutes, although it depends on the number of peptides and on occurrence.

cpp.run_experiment(lst, peptide_address, ep_length, pools, iters, n_pools, regime)

Parameters:

lst : list, list with peptides (ordered)

peptide_address : dictionary, peptides addresses produced by pooling

ep_length : int, expected epitope length, should be less the length of peptide, we recommend using 8

pools : dictionary, pools produced by pooling

iters : int, peptide occurrence

n_pools : int, number of pools

regime: “with dropouts” or “without dropouts”

df = cpp.run_experiment(lst=lst, peptide_address=peptide_address, ep_length=8, pools=pools, iters=iters, n_pools=n_pools, regime='without dropouts')

df

Peptide	Address	Epitope	Act Pools	# of pools	# of epitopes	# of peptides	Remained	# of lost	Right peptide	Right epitope
MFVFLVLLPLVSSQCVN	[0, 1, 2, 3]	MFVFLVLL	[0, 1, 2, 3]	4	5	1	-	0	True	True
MFVFLVLLPLVSSQCVN	[0, 1, 2, 3]	MFVFLVLL	[0, 1, 2, 3]	4	5	1	-	0	True	True
…
MFVFLVLLPLVSSQCVN	[0, 1, 2, 3]	VLLPLVSS	[0, 1, 2, 3, 10]	5	5	2	-	0	True	True
…
VLLPLVSSQCVNLTTRT	[0, 1, 2, 10]	VLLPLVSS	[0, 1, 2, 3, 10]	5	5	2	-	0	True	True
…

"Peptide" — peptide sequence

"Address" — pool indices where this peptide should be added

"Epitope" — checked epitope from this peptide

"Act pools" — list with pool indices where this epitope is present

"# of pools" — number of pools where this epitope is present

"# of epitopes" — number of epitopes that are present in the same pools (= number of possible peptides upon activation of such pools)

"# of peptides" — number of peptides in which there are epitopes that are present in the same pools (= number of possible peptides upon activation of such pools)

"Remained" — only upon regime=”with dropouts”, list of pools remained after mistake

"# of lost" — only upon regime=”with dropouts”, number of dropped pools due to mistake

"Right peptide" — Boolean, whether the peptide is present in the list of possible peptides

"Right epitope" — Boolean, whether the peptide is present in the list of possible peptides

To interpret the results of the experiment, you need to find all rows where the “Act Pools” column contains your combination of activated pools. Then, you will know all possible peptides and epitopes that could lead to the activation of such a combination of pools.

If you can not find your combination of activated pools in the table, here is the sequence of actions.

After the experiment, you will know the number of activated pools. This number depends on the length of overlap and the length of the expected epitope. You can check the distribution of epitope presence in your peptides using cpp.how_many_peptides(lst, ep_length) function. The number of activated pools would be equal to peptide occurrence plus one per additional peptide sharing this epitope.

This way, if the epitope is present only in 1 peptide (usually, it is the case for epitopes at the ends of the protein), then the number of activated pools is equal to peptide occurrence. If the epitope is present in two peptides, then the number of activated pools is equal to peptide occurrence +1.

If overlap length is consistent across all peptides, then the number of activated pools would be the same for almost all epitopes (except for the epitopes at the ends of the protein). Although even if the overlap is inconsistent, you can use the analysis, but it will hinder the interpretation of the results in some cases.

If a shift length between two peptides is equal to or less than the expected epitope length divided by two, then the number of activated pools should be equal to the peptide occurrence value + 1.

If the number of activated pools is less than according to the rule described above, then three options are possible:

The target peptide is the peptide at the end of your peptide list, and the target epitope is located not in an overlap of this peptide with the next one. This could be checked easily: if your activated pools are not the same as the activated pools for any epitope from the first or last peptide, then you should check our second option.
For the target peptide, overlap with its neighbor is less than usual, and therefore target epitope is not shared by the usual number of peptides. You can check that using cpp.all_overlaps(lst) or cpp.how_many_peptides(lst, ep_length). Nevertheless, given the absence of drop-outs, you still should be able to find the target peptide in the table with simulation results by searching for all rows where the “Act Pools” column contains your combination of activated pools.
Some pools were not activated, although they should be; then, we recommend using the “with drop-outs” regime of the simulation. It imitates drop-outs of all possible pools, so you should be able to find your case in the resulting table.

If the number of activated pools is higher than according to the rule described above, then two options are possible:

For the target peptide, overlap with its neighbor is bigger than usual, and therefore target epitope is shared between more peptides. You can check that using cpp.all_overlaps(lst) or cpp.how_many_peptides(lst, ep_length). Nevertheless, given the absence of drop-outs, you still should be able to find the target peptide in the table with simulation results by searching for all rows where the “Act Pools” column contains your combination of activated pools.
Some pools were activated, although they should not be. This issue is not addressed in the package.

df = cpp.run_experiment(lst=lst, peptide_address=peptide_address, ep_length=8, pools=pools, iters=iters, n_pools=n_pools, regime='with dropouts')

df

Peptide	Address	Epitope	Act Pools	# of pools	# of epitopes	# of peptides	Remained	# of lost	Right peptide	Right epitope
MFVFLVLLPLVSSQCVN	[0, 1, 2, 3]	MFVFLVLL	[0, 1, 2, 3]	4	40	12	[0, 1, 2]	1	True	False
MFVFLVLLPLVSSQCVN	[0, 1, 2, 3]	MFVFLVLL	[0, 1, 2, 3]	4	76	25	[0, 1, 3]	1	True	False
…
RTQLPPAYTNSFTRGVY	[8, 9, 10, 11]	RTQLPPAY	[0, 8, 9, 10, 11]	5	5	2	[0, 8, 9, 10, 11]	0	True	True
…
RTQLPPAYTNSFTRGVY	[8, 9, 10, 11]	TQLPPAYT	[0, 8, 9, 10, 11]	5	190	53	[8, 9]	3	True	True