1'''
 2# Liabilities
 3
 4Liabilities leverages the scientifically-validated SAbPred toolbox to add developmental liabilities tags to your clones.
 5
 6Some of the examples in this section mention the mechanism of **clone resolving**. Resolving means that maximum of two sequences
 7will be picked per each given clone, one `Heavy` chain sequence and one `Light` chain sequence. Picked sequences are the most abundant ones for
 8their chain size. All clones sent to Basket get resolved before they're inserted into the target Basket. 
 9
10
11##Run Liabilities via clone IDs
12
13Run an example liabilities computation run with Liabilities on a set of clones. Clones matched with provided clone IDs will get
14resolved first and then passed to Liabilities The result of this script is new set of tags added to the target clones / sequences.
15
16```python
17from enpi_api.l2.client.enpi_api_client import EnpiApiClient
18from enpi_api.l2.types.clone import CloneId
19
20with EnpiApiClient() as enpi_client:
21    """We are assuming that the Basket and clones defined below exist"""
22
23    example_clone_ids = [
24        CloneId("ddb55542-e3ef-4cd1-affc-a4e99ac0727f"),
25        CloneId("51056391-f69b-4966-b7a3-568666761cc3"),
26    ]
27
28    # Pass example clones for liabilities computation
29    enpi_client.liabilities_api.start(
30        clone_ids=example_clone_ids,  # Clones matched with those IDs will be resolved
31        # and then passed to Liabilities. Resolving means that maximum of two sequences
32        # per each clone will be picked, e.g., one `Heavy` and one `Light` chain. Picked sequences
33        # are the most abundant ones for their chain type.
34    ).wait()
35
36    # As a result of the liabilities computation, new tags will be added to the clones passed above,
37    # which can be fetched e.g. with `enpi_client.collection_api.get_as_df`
38
39```
40##Run Liabilities via sequence IDs
41
42Run an example liabilities computation run with Liabilities on a set of clones. This example showcases how you can force your target
43sequences to be picked during the clone resolving process by using `sequence_ids` param. After clones are resolved, they're
44passed to Liabilities as per usual. The result of this script is new set of tags added to the target clones / sequences.
45
46```python
47from enpi_api.l2.client.enpi_api_client import EnpiApiClient
48from enpi_api.l2.types.clone import CloneId
49from enpi_api.l2.types.sequence import SequenceId
50
51with EnpiApiClient() as enpi_client:
52    """We are assuming that the clone and sequences referenced below exist"""
53
54    example_clone_id = CloneId("ddb55542-e3ef-4cd1-affc-a4e99ac0727f")  # Example clone
55    example_heavy_sequence_id = SequenceId(123)  # Heavy sequence of the example clone
56    example_lambda_sequence_id = SequenceId(124)  # Lambda sequence of the example clone
57    example_kappa_sequence_id = SequenceId(125)  # Kappa sequence of the example clone
58
59    """Let us also assume that Lambda sequence `124` is more abundant
60    than Kappa Sequence `125`, which means that Lambda sequence `124` would be picked
61    as the preferred Light sequence for the resolved clone during the clone resolving:
62
63    enpi_client.liabilities_api.start(
64        clone_ids=[example_clone_id],  # More clones can be passed here
65    ).wait()
66
67    Snippet above would result in a resolved clone consisting of Heavy sequence `123` and Lambda
68    sequence `124` which would then be passed to Liabilities
69    """
70
71    # However, we can force the Kappa sequence `125` as the preferred Light for the resolved clone,
72    # even though it is less abundant than Lambda `124`:
73    enpi_client.liabilities_api.start(
74        clone_ids=[example_clone_id],  # More clones can be passed here
75        sequence_ids=[example_kappa_sequence_id],  # ID of a sequence we want to force into the resolved
76        # clone. Even though less abundant than Lambda, now Kappa will be picked for the resolved clone
77    ).wait()  # The resolved clone will consist of Heavy sequence `123` and Lambda sequence `125`
78
79    """Same result could be achieved by passing just the Kappa sequence ID:
80
81    enpi_client.liabilities_api.start(
82        sequence_ids=[example_kappa_sequence_id], # Only `sequence_ids` passed, no `clone_ids` provided
83    ).wait()
84
85    In this case the most abundant Heavy sequence (in our example only one is available) from the clone
86    that contains Kappa sequence `124` will be picked during the clone resolving. Together, those two
87    sequences will create a resolved clone, which will be passed to Liabilities.
88    """
89
90```
91'''