1'''
  2# Retrieve clones and download them
  3
  4Various examples showcasing how you can retrieve clones from the ENPICOM Platform and download them to your local machine.
  5
  6##Export all clones from a clone collection
  7
  8This example shows how you can export all clones from a target clone collection into an archived CSV file or a Pandas DataFrame.
  9```python
 10from enpi_api.l2.client.enpi_api_client import EnpiApiClient
 11from enpi_api.l2.tags import CollectionTags, SequenceTags
 12from enpi_api.l2.types.collection import CollectionId
 13
 14with EnpiApiClient() as enpi_client:
 15    """We are assuming that the collection below exists"""
 16    collection_id = CollectionId(123)
 17
 18    # Export the collections into a Pandas DataFrame object.
 19    # We are not providing any `filter` object into the function because we want to export all the clones.
 20    # to store the exported clones in a file
 21    exported_data_df = enpi_client.collection_api.get_as_df(
 22        collection_ids=[collection_id],  # More collection IDs can be inserted here
 23        tag_ids=[  # We specify the tags that we want to export. The fewer tags we specify, the faster the export will be
 24            CollectionTags.Name,
 25            CollectionTags.Organism,
 26            CollectionTags.Complexity,
 27            CollectionTags.Receptor,
 28            SequenceTags.Chain,
 29            SequenceTags.Productive,
 30        ],
 31    ).wait()  # This starts a long-running operation, we need to wait for it if we want to use it further down in the script
 32
 33    # The result dataframe will contain all clones present in our target collection
 34    print(exported_data_df)
 35
 36```
 37##Export all clones from multiple clone collections
 38
 39This example shows how you can export all clones from multiple target clone collections at once into an archived CSV files or a Pandas DataFrame.
 40```python
 41from enpi_api.l2.client.enpi_api_client import EnpiApiClient
 42from enpi_api.l2.tags import CollectionTags, SequenceTags
 43from enpi_api.l2.types.collection import CollectionId
 44
 45with EnpiApiClient() as enpi_client:
 46    """We are assuming the collections referenced below exist"""
 47
 48    collection_ids = [CollectionId(123), CollectionId(124)]
 49
 50    # Export the collections into archived TSV files.
 51    # We are not providing any `filter` object into the function because we want to export all the clones.
 52    # Function `get_as_df` could be used alternatively to store the exported clones in a DataFrame
 53    exported_data_path = enpi_client.collection_api.get_as_zip(
 54        collection_ids=collection_ids,  # Both collection IDs provided
 55        tag_ids=[  # We specify the tags that we want to export. The fewer tags we specify, the faster the export will be
 56            CollectionTags.Name,
 57            CollectionTags.Organism,
 58            CollectionTags.Complexity,
 59            CollectionTags.Receptor,
 60            SequenceTags.Chain,
 61            SequenceTags.Productive,
 62        ],
 63        output_directory="/home/example_user/",
 64    ).wait()  # This starts a long-running operation, we need to wait for it if we want to use it further down in the script
 65
 66    # The result DataFrame will contain all clones present in our target collection
 67    print(exported_data_path)
 68
 69```
 70##Export only clones containing a kappa chain
 71
 72This example shows how you can filter clones to include only those that match certain tags, and then download those to a Pandas 
 73DataFrame This configuration showcases how to retrieve only sequences that have a **Kappa** chain present.
 74```python
 75from enpi_api.l2.client.enpi_api_client import EnpiApiClient
 76from enpi_api.l2.tags import CollectionTags, SequenceTags
 77from enpi_api.l2.types.collection import CollectionId
 78from enpi_api.l2.types.filter import MatchTag, MatchTagRule, MatchTagRuleType
 79
 80with EnpiApiClient() as enpi_client:
 81    """We are assuming that the collection referenced below exists and it contains - among others - Kappa sequences"""
 82    collection_id = CollectionId(123)
 83
 84    # This filter will allow only sequences with `Kappa` chain through
 85    kappa_filter = enpi_client.filter_api.create_filter(
 86        name="only_kappa_sequences_filter",
 87        condition=MatchTag(
 88            tag_id=SequenceTags.Chain,
 89            rule=MatchTagRule(
 90                type=MatchTagRuleType.EQUALS,
 91                value="Kappa",
 92            ),
 93        ),
 94    )
 95
 96    # Run export with the filter created above
 97    exported_data_df = enpi_client.collection_api.get_as_df(
 98        collection_ids=[collection_id],  # More collection IDs can be inserted here
 99        filter=kappa_filter,
100        # We specify the tags that we want to export, the fewer tags we specify, the faster the export will be
101        tag_ids=[
102            CollectionTags.Name,
103            CollectionTags.Organism,
104            CollectionTags.Complexity,
105            CollectionTags.Receptor,
106            SequenceTags.Chain,
107            SequenceTags.Productive,
108        ],
109    ).wait()  # This starts a long-running operation, we need to wait for it if we want to use it further down in the script
110
111    # The result dataframe will contain only `Kappa` sequences
112    print(exported_data_df)
113
114```
115##Export only clones with both heavy and light chains
116
117This export example showcases how to retrieve only clones that have both a **Heavy** and a **Light** (Lambda/Kappa) chain.
118```python
119from enpi_api.l2.client.enpi_api_client import EnpiApiClient
120from enpi_api.l2.tags import CloneTags, CollectionTags, SequenceTags
121from enpi_api.l2.types.filter import MatchClone, MatchCloneOperatorType, MatchTag, MatchTagRule, MatchTagRuleType, Operator, OperatorType
122
123with EnpiApiClient() as enpi_client:
124    # To find all clones that have both a heavy and a light chain, we will first need to create a `Filter`
125    filter = enpi_client.filter_api.create_filter(
126        name="Find clones that have a Heavy and a Light chain",
127        shared=False,  # Indicates whether other people in the same organization can use this filter
128        condition=Operator(
129            operator=OperatorType.AND,
130            conditions=[
131                # We will now add the condition to narrow down the clones to at least have a Heavy chain
132                MatchClone(
133                    # The `ANY_SEQUENCE` operator means that at least one sequence in the clone must match the conditions
134                    operator=MatchCloneOperatorType.ANY_SEQUENCE,
135                    conditions=[MatchTag(tag_id=SequenceTags.Chain, rule=MatchTagRule(type=MatchTagRuleType.EQUALS, value="Heavy"))],
136                ),
137                # We will now add the condition to narrow down the clones to at least have a Light chain
138                # Since that can be either a Kappa or a Lambda chain, we will need to use another operator inside the
139                # `MatchClone` condition to match either Kappa OR Lambda chains
140                MatchClone(
141                    # The `ANY_SEQUENCE` operator means that at least one sequence in the clone must match the conditions
142                    operator=MatchCloneOperatorType.ANY_SEQUENCE,
143                    conditions=[
144                        # This is our `OR` operator
145                        Operator(
146                            operator=OperatorType.OR,
147                            conditions=[
148                                # Looking for either a Kappa chain
149                                MatchTag(tag_id=SequenceTags.Chain, rule=MatchTagRule(type=MatchTagRuleType.EQUALS, value="Kappa")),
150                                # Or a Lambda chain
151                                MatchTag(tag_id=SequenceTags.Chain, rule=MatchTagRule(type=MatchTagRuleType.EQUALS, value="Lambda")),
152                            ],
153                        )
154                    ],
155                ),
156            ],
157        ),
158    )
159
160    # Now that we have a filter, we can use this in multiple places in the platform, for example when exporting
161    # data straight from collections.
162
163    # We will now fetch the filtered clones into a Pandas DataFrame using the `collection_api.get_as_df` method
164
165    # For exporting from the collections, we will need to specify the collection ID explicitly to avoid accidentally querying too much data.
166
167    filtered_collections = [collection for collection in enpi_client.collection_api.get_collections_metadata() if collection.name() == "My collection name"]
168    collection = filtered_collections[0]  # We assume that this name is unique here
169
170    data_frame = enpi_client.collection_api.get_as_df(
171        # Specify the collection ID explicitly to avoid accidentally querying too much data
172        collection_ids=[collection.id],
173        # Specify the filter we just created
174        filter=filter,
175        # Specify the tags we want to export
176        tag_ids=[CollectionTags.Name, CloneTags.TenXBarcode, SequenceTags.Chain, SequenceTags.Cdr3AminoAcids],
177    ).wait()  # Since this is a long-running operation, we need to wait for the result if we want to use it further down
178
179    print(data_frame.head())
180
181```
182'''