1'''
  2# Basket
  3
  4Various examples of how can you manage your Baskets and clones within those Baskets.
  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##Create Baskets
 12
 13This example showcases how to create a new Basket,
 14both a public one (shared to all members of organization) and a private one.
 15```python
 16from enpi_api.l2.client.enpi_api_client import EnpiApiClient
 17
 18with EnpiApiClient() as enpi_client:
 19    # First, we will create a new Basket
 20    first_basket = enpi_client.basket_api.create_basket(
 21        name="First Basket (shared)",  # Basket's name, must be unique in regard to other existing Baskets
 22        shared=True,  # This will make the Basket visible to all members of your organization
 23    )
 24    print(first_basket)
 25
 26    # By default newly created Baskets are shared to organization, `shared=True` is not required
 27    # for this to happen
 28    second_basket = enpi_client.basket_api.create_basket(
 29        name="Second Basket (also shared)",
 30    )
 31    print(second_basket)
 32
 33    # Now we will create a private, not shared Basket
 34    third_basket = enpi_client.basket_api.create_basket(
 35        name="Third Basket (private)",
 36        shared=False,  # This will make the Basket visible only to you
 37    )
 38    print(third_basket)
 39
 40```
 41##Get Baskets
 42
 43This example showcases how to receive one or all of the
 44available Baskets.
 45```python
 46from enpi_api.l2.client.enpi_api_client import EnpiApiClient
 47
 48with EnpiApiClient() as enpi_client:
 49    # First we will get all available Baskets - the ones that you own and the ones that were shared to you
 50    # by other members of your organization
 51    baskets = enpi_client.basket_api.get_baskets()
 52    print(baskets)
 53
 54    # Now we will get a single Basket with the first Basket's ID from
 55    # the result list above. Make sure at least one Basket is present in that list
 56    assert len(baskets) > 0, """At least one Basket is required to be present.
 57        You can use `enpi_client.basket_api.create_basket()` to create one."""
 58
 59    basket_id = baskets[0].id
 60    basket = enpi_client.basket_api.get_basket(
 61        basket_id=basket_id,
 62    )
 63    print(basket)
 64
 65```
 66##Edit and delete Baskets
 67
 68This example showcases how to update name and visibility
 69of an existing Basket, as well as how to delete a Basket.
 70```python
 71from enpi_api.l2.client.enpi_api_client import EnpiApiClient
 72from enpi_api.l2.types.basket import BasketId
 73
 74with EnpiApiClient() as enpi_client:
 75    """We are assuming that the basket referenced below exists"""
 76
 77    basket_id = BasketId(123)
 78
 79    # Basket's name can be modified...
 80    enpi_client.basket_api.update_basket(
 81        basket_id=basket_id,
 82        name="New Basket name (modified)",  # New name has to be unique
 83    )
 84
 85    # ...as well as it's visibility to other users
 86    enpi_client.basket_api.update_basket(
 87        basket_id=basket_id,
 88        shared=False,  # Make Basket private
 89    )
 90
 91    # Finally, an owned Basket can be deleted
 92    enpi_client.basket_api.delete_basket(
 93        basket_id=basket_id,
 94    )
 95
 96```
 97##Add clones to Basket via clone IDs
 98
 99This example showcases how
100to insert clones present in the ENPICOM-Platform into a target Basket with use of clone IDs.
101```python
102from enpi_api.l2.client.enpi_api_client import EnpiApiClient
103from enpi_api.l2.types.basket import BasketId
104from enpi_api.l2.types.clone import CloneId
105
106with EnpiApiClient() as enpi_client:
107    """We are assuming that the basket and clones defined below exist"""
108
109    example_basket_id = BasketId(1)
110    example_clone_ids = [
111        CloneId("ddb55542-e3ef-4cd1-affc-a4e99ac0727f"),
112        CloneId("51056391-f69b-4966-b7a3-568666761cc3"),
113    ]
114
115    # Add clones to the Basket using clone IDs
116    enpi_client.basket_api.add_clones_to_basket(
117        basket_id=example_basket_id,
118        clone_ids=example_clone_ids,  # Clones matched with those IDs will be resolved
119        # and then inserted into the Basket. Resolving means that maximum of two sequences
120        # per each clone will be picked, one `Heavy` and one `Light` chain. Picked sequences
121        # are the most abundant ones for their chain size
122    ).wait()
123
124    # If we try to insert the same clones again, only the new clones will be added
125    example_clone_ids = [
126        CloneId("ddb55542-e3ef-4cd1-affc-a4e99ac0727f"),  # Already present in the Basket
127        CloneId("51056391-f69b-4966-b7a3-568666761cc3"),  # Already present in the Basket
128        CloneId("44328fff-6023-46ee-a5ce-9d3594403139"),  # Not present in the Basket, will get added
129    ]
130
131    enpi_client.basket_api.add_clones_to_basket(
132        basket_id=example_basket_id,
133        clone_ids=example_clone_ids,  # Only one clone should be added
134    ).wait()
135
136```
137##Add clones to Basket via sequence IDs
138
139This example showcases how
140to insert clones present in the ENPICOM-Platform into a target Basket with use of sequence IDs (also referred to as "forced sequence IDs"),
141which guarantees that the target sequence will be picked during the clone resolving and will be present in the clone added to Basket.
142```python
143from enpi_api.l2.client.enpi_api_client import EnpiApiClient
144from enpi_api.l2.types.basket import BasketId
145from enpi_api.l2.types.clone import CloneId
146from enpi_api.l2.types.sequence import SequenceId
147
148with EnpiApiClient() as enpi_client:
149    """We are assuming that the basket, clone and sequences referenced below exist"""
150
151    example_basket_id = BasketId(1)
152    example_clone_id = CloneId("ddb55542-e3ef-4cd1-affc-a4e99ac0727f")  # Example clone
153    example_heavy_sequence_id = SequenceId(123)  # Heavy sequence of the example clone
154    example_lambda_sequence_id = SequenceId(124)  # Lambda sequecne of the example clone
155    example_kappa_sequence_id = SequenceId(125)  # Kappa sequence of the example clone
156
157    """Let us also assume that Lambda sequence `124` is more abundant
158    than Kappa Sequence `125`, which means that Lambda sequence `124` would be picked
159    as the preferred Light sequence for the resolved clone:
160
161    enpi_client.basket_api.add_clones_to_basket(
162        basket_id=example_basket_id, # Target Basket ID
163        clone_ids=[example_clone_id], # ID of the clone to be resolved and added into the Basket
164    ).wait()
165
166    Snippet above would result in a resolved clone consisting of Heavy sequence `123` and Lambda
167    sequence `124` being added into the Basket
168    """
169
170    # However, we can force the Kappa sequence `125` as the preferred Light for the resolved clone,
171    # even though it is less abundant than Lambda `124`:
172    enpi_client.basket_api.add_clones_to_basket(
173        basket_id=example_basket_id,
174        clone_ids=[example_clone_id],
175        sequence_ids=[example_kappa_sequence_id],  # ID of a sequence we want to force into the resolved
176        # clone. Even though less abundant than Lambda, now Kappa will be picked for the resolved clone
177    ).wait()
178
179    """Same result could be achieved by passing just the Kappa sequence ID:
180
181    enpi_client.basket_api.add_clones_to_basket(
182        basket_id=example_basket_id,
183        sequence_ids=[example_kappa_sequence_id], # Only `sequence_ids` passed, no `clone_ids` provided
184    ).wait()
185
186    In this case the most abundant Heavy sequence (in our example only one is available) from the clone
187    that contains Kappa sequence `124` will be picked during the clone resolving. Together, those two
188    sequences will create a resolved clone, which will be added into the Basket
189    """
190
191```
192##Remove clones from Basket
193
194This example showcases how to
195remove clones from a target Basket with use of clone IDs.
196```python
197from enpi_api.l2.client.enpi_api_client import EnpiApiClient
198from enpi_api.l2.types.basket import BasketId
199from enpi_api.l2.types.clone import CloneId
200
201with EnpiApiClient() as enpi_client:
202    """We are assuming that the basket referenced below exists and it contains the referenced clones"""
203
204    example_basket_id = BasketId(1)
205    example_clone_ids = [
206        CloneId("ddb55542-e3ef-4cd1-affc-a4e99ac0727f"),
207        CloneId("1a076a09-052e-4529-9b5e-468746448fb3"),
208    ]
209
210    # Remove clones from the Basket
211    enpi_client.basket_api.remove_clones_from_basket(
212        basket_id=example_basket_id,  # ID of the target Basket from which the clones will be removed
213        clone_ids=example_clone_ids,  # IDs of clones to remove
214    ).wait()
215
216```
217##Export Basket clones as TSV
218
219This example showcases how to
220export all clones present in a Basket into a TSV file or a Pandas DataFrame.
221```python
222from enpi_api.l2.client.enpi_api_client import EnpiApiClient
223from enpi_api.l2.types.basket import BasketId
224
225with EnpiApiClient() as enpi_client:
226    """We are assuming that the basket referenced below exists and it contains some clones"""
227
228    example_basket_id = BasketId(1)
229
230    path = enpi_client.basket_api.export_basket_clones_as_tsv(
231        basket_id=example_basket_id,  # ID of the target Basket from which the clones will be exported
232        output_directory="/home/example_user/",  # Directory in which the exported file will be located
233    ).wait()
234    print(path)
235
236    """Alternatively, clones could be exported as a pandas DataFrame:
237
238    df = enpi_client.basket_api.export_basket_clones_as_df(
239        basket_id=example_basket_id,  # ID of the target Basket from which the clones will be exported
240    ).wait()
241    print(df)
242
243    """
244
245```
246##Export Basket clones as FASTA
247
248This example showcases how to
249configure and run a FASTA clones export from a target Basket.
250```python
251from enpi_api.l2.client.enpi_api_client import EnpiApiClient
252from enpi_api.l2.tags import CollectionTags, SequenceTags
253from enpi_api.l2.types.basket import BasketId, fasta_config
254from enpi_api.l2.types.sequence import Chain
255
256with EnpiApiClient() as enpi_client:
257    """We are assuming that the basket referenced below exists and it contains some clones"""
258
259    example_basket_id = BasketId(1)
260
261    path = enpi_client.basket_api.export_basket_clones_as_fasta(
262        basket_id=example_basket_id,
263        fasta_config=fasta_config(  # An util function that can be used to set up FASTA export configuration
264            include_unique_clone_id_header=True,  # Unique Clone IDs will be present in the FASTA headers
265            include_unique_sequence_id_header=True,  # Unique Sequence IDs will be present in the FASTA headers
266            include_chain_header=True,  # Chain type will be present in the FASTA headers
267            headers=[  # Additional tag values to be included in the FASTA headers. FASTA headers are the same for all
268                # sequences belonging to the same clone
269                SequenceTags.FullSequenceAminoAcids,
270                CollectionTags.Organism,
271            ],
272            chains=[Chain.HEAVY, Chain.KAPPA],
273            # For every clone present in the target Basket, we will try to get a Heavy sequence.
274            # If a Heavy sequence is present for a given clone, we will try to get CDR3 Amino Acids and Receptor
275            # Amino Acids tag values and write it as a FASTA sequence under it's clone's FASTA header.
276            # If both values are present at the same time, they'll be concatenated
277            # The same will be done for the Kappa chain on a different line (if found)
278            sequence=[SequenceTags.Cdr3AminoAcids, SequenceTags.ReceptorAminoAcids],
279        ),
280        output_directory="/home/example_user/",
281    ).wait()
282
283    print(path)
284
285```
286'''