seer-pas-sdk 1.1.1__tar.gz → 1.2.1__tar.gz

{seer_pas_sdk-1.1.1 → seer_pas_sdk-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: seer-pas-sdk
-Version: 1.1.1
+Version: 1.2.1
 Summary: SDK for Seer Proteograph Analysis Suite (PAS)
 Author-email: Ryan Sun <rsun@seer.bio>
 License: 

{seer_pas_sdk-1.1.1 → seer_pas_sdk-1.2.1}/docs/index.qmd

@@ -18,12 +18,27 @@ $ pip install seer-pas-sdk
 This page gives an overview of the SDK's feature. Complete documentation for each class / method can be found [here](reference/).
 
 ### Configuration
-PAS has a simple authorization system that just involves your username and password fields like on the web app. You can define your username and password for your own ready reference and convenience as follows:
+The PAS SDK has a simple authorization system that involves your username and password fields like on the web app. You can define your username and password for your own ready reference and convenience as follows:
 ```{python}
 USERNAME = "gnu403"
 PASSWORD = "Test!234567"
 ```
 
+The PAS SDK requires either a `tenant` or `tenant_id` argument in the SDK object constructor.
+  
+`tenant` refers to the user provided name of the tenant.  
+
+`tenant_id` refers to the immutable and unique identifier of the tenant.   
+`tenant_id` is an absolute reference to the tenant, even if the tenant name is changed.  
+
+More details on multi-tenant management can be found in the [Multi Tenant Management](#multi-tenant-management) section below.  
+
+You can define your tenant name or tenant ID as follows:
+```{python}
+TENANT = "My Tenant Name"
+TENANT_ID = "abc1234abc1234"
+```
+
 You may also choose to pass in an `instance` param in the SDK object to instantiate the PAS SDK to the EU or US instance.:
 ```{python}
 INSTANCE = "US"
@@ -38,10 +53,13 @@ After importing the SeerSDK module, you can instantiate an object in the followi
 from seer_pas_sdk import SeerSDK
 
 # Instantiate an SDK object with your credentials:
-sdk = SeerSDK(USERNAME, PASSWORD)
+sdk = SeerSDK(USERNAME, PASSWORD, tenant=TENANT)
 
-# You could alternatively pass your credentials and/or the instance directly into the instantiated object.
-sdk = SeerSDK(USERNAME, PASSWORD, INSTANCE)
+# Instantiate an SDK object with your credentials and instance:
+sdk = SeerSDK(USERNAME, PASSWORD, INSTANCE, tenant=TENANT)
+
+# Instantiate an SDK object with your credentials and tenant ID:
+sdk = SeerSDK(USERNAME, PASSWORD, INSTANCE, tenant_id=TENANT_ID)
 ```
 
 ```{python}
@@ -56,18 +74,16 @@ Additional information and examples can also be found below.
 ### Multi Tenant Management 
 Introduced in version 0.2.0
 
-By default, you will be active in your home tenant upon log in. The home tenant is defined as the organization account that issued the original invitation for the user to join PAS.
-The optional 'tenant' parameter is available in the SeerSDK constructor to navigate directly to a desired tenant.
-A notification message will display upon login.
-
-
 The following tools are available to navigate between tenants:
 ```{python}
 #| eval: false
 from seer_pas_sdk import SeerSDK
 
+# Assume tenant upon login
 sdk = SeerSDK(USERNAME, PASSWORD, INSTANCE, tenant='My Active Tenant')
 
+sdk = SeerSDK(USERNAME, PASSWORD, INSTANCE, tenant_id='myuuidstring-1234')
+
 # Retrieve value of current active tenant
 print(sdk.get_active_tenant())
 
@@ -337,7 +353,7 @@ example = sdk.find_msruns(sample_ids)
 log(example)
 ```
 ```
-[{'id': '81c6a180-15e0-11ee-bdf1-bbaa73585acf', 'sample_id': '812139c0-15e0-11ee-bdf1-bbaa73585acf', 'raw_file_path': '7ec8cad0-15e0-11ee-bdf1-bbaa73585acf/20230628182044224/TestFile2.raw', 'well_location': 'D11', 'nanoparticle': '', 'instrument_name': '', 'created_by': '04936dea-d255-4130-8e82-2f28938a8f9a', 'created_timestamp': '2023-06-28T18:20:49.006Z', 'last_modified_by': '04936dea-d255-4130-8e82-2f28938a8f9a', 'last_modified_timestamp': '2023-06-28T18:20:49.006Z', 'user_group': None, 'sample_id_tracking': 'A112', 'nanoparticle_id': '', 'control': '', 'control_id': '', 'date_sample_prep': '', 'sample_volume': '', 'peptide_concentration': '', 'peptide_mass_sample': '', 'dilution_factor': '', 'kit_id': None, 'injection_timestamp': None, 'ms_instrument_sn': None, 'recon_volume': None, 'gradient': None}, {'id': '816a9ed0-15e0-11ee-bdf1-bbaa73585acf', 'sample_id': '803e05b0-15e0-11ee-bdf1-bbaa73585acf', 'raw_file_path': '7ec8cad0-15e0-11ee-bdf1-bbaa73585acf/20230628182044224/TestFile1.raw', 'well_location': 'C11', 'nanoparticle': 'NONE', 'instrument_name': '', 'created_by': '04936dea-d255-4130-8e82-2f28938a8f9a', 'created_timestamp': '2023-06-28T18:20:48.408Z', 'last_modified_by': '04936dea-d255-4130-8e82-2f28938a8f9a', 'last_modified_timestamp': '2023-06-28T18:20:48.408Z', 'user_group': None, 'sample_id_tracking': 'A111', 'nanoparticle_id': 'NONE', 'control': 'MPE Control', 'control_id': 'MPE Control', 'date_sample_prep': '', 'sample_volume': '20.0', 'peptide_concentration': '59.514', 'peptide_mass_sample': '8.57', 'dilution_factor': '1.0', 'kit_id': None, 'injection_timestamp': None, 'ms_instrument_sn': None, 'recon_volume': None, 'gradient': None}]
+[{'id': '81c6a180-15e0-11ee-bdf1-bbaa73585acf', 'sample_uuid': '812139c0-15e0-11ee-bdf1-bbaa73585acf', 'raw_file_path': '7ec8cad0-15e0-11ee-bdf1-bbaa73585acf/20230628182044224/TestFile2.raw', 'well_location': 'D11', 'nanoparticle': '', 'instrument_name': '', 'created_by': '04936dea-d255-4130-8e82-2f28938a8f9a', 'created_timestamp': '2023-06-28T18:20:49.006Z', 'last_modified_by': '04936dea-d255-4130-8e82-2f28938a8f9a', 'last_modified_timestamp': '2023-06-28T18:20:49.006Z', 'user_group': None, 'sample_id': 'A112', 'nanoparticle_id': '', 'control': '', 'control_id': '', 'date_sample_prep': '', 'sample_volume': '', 'peptide_concentration': '', 'peptide_mass_sample': '', 'dilution_factor': '', 'kit_id': None, 'injection_timestamp': None, 'ms_instrument_sn': None, 'recon_volume': None, 'gradient': None}, {'id': '816a9ed0-15e0-11ee-bdf1-bbaa73585acf', 'sample_uuid': '803e05b0-15e0-11ee-bdf1-bbaa73585acf', 'raw_file_path': '7ec8cad0-15e0-11ee-bdf1-bbaa73585acf/20230628182044224/TestFile1.raw', 'well_location': 'C11', 'nanoparticle': 'NONE', 'instrument_name': '', 'created_by': '04936dea-d255-4130-8e82-2f28938a8f9a', 'created_timestamp': '2023-06-28T18:20:48.408Z', 'last_modified_by': '04936dea-d255-4130-8e82-2f28938a8f9a', 'last_modified_timestamp': '2023-06-28T18:20:48.408Z', 'user_group': None, 'sample_id': 'A111', 'nanoparticle_id': 'NONE', 'control': 'MPE Control', 'control_id': 'MPE Control', 'date_sample_prep': '', 'sample_volume': '20.0', 'peptide_concentration': '59.514', 'peptide_mass_sample': '8.57', 'dilution_factor': '1.0', 'kit_id': None, 'injection_timestamp': None, 'ms_instrument_sn': None, 'recon_volume': None, 'gradient': None}]
 ```
 
 There is also an option to return everything as a DataFrame instead:
@@ -347,7 +363,7 @@ example = sdk.find_msruns(sample_ids, as_df=True)
 log(example)
 ```
 ```
-                    id                                sample_id                                 raw_file_path                    well_location nanoparticle instrument_name               created_by                  created_timestamp                last_modified_by            last_modified_timestamp  space sample_id_tracking nanoparticle_id   control     control_id  date_sample_prep sample_volume peptide_concentration peptide_mass_sample dilution_factor kit_id injection_timestamp ms_instrument_sn recon_volume gradient
+                    id                                sample_uuid                                 raw_file_path                    well_location nanoparticle instrument_name               created_by                  created_timestamp                last_modified_by            last_modified_timestamp  space sample_id nanoparticle_id   control     control_id  date_sample_prep sample_volume peptide_concentration peptide_mass_sample dilution_factor kit_id injection_timestamp ms_instrument_sn recon_volume gradient
 0  81c6a180-15e0-11ee-bdf1-bbaa73585acf  812139c0-15e0-11ee-bdf1-bbaa73585acf  7ec8cad0-15e0-11ee-bdf1-bbaa73585acf/202306281...       D11                                   04936dea-d255-4130-8e82-2f28938a8f9a  2023-06-28T18:20:49.006Z  04936dea-d255-4130-8e82-2f28938a8f9a  2023-06-28T18:20:49.006Z    None           A112                                                                                                                                            None          None              None           None       None
 1  816a9ed0-15e0-11ee-bdf1-bbaa73585acf  803e05b0-15e0-11ee-bdf1-bbaa73585acf  7ec8cad0-15e0-11ee-bdf1-bbaa73585acf/202306281...       C11         NONE                      04936dea-d255-4130-8e82-2f28938a8f9a  2023-06-28T18:20:48.408Z  04936dea-d255-4130-8e82-2f28938a8f9a  2023-06-28T18:20:48.408Z    None           A111              NONE       MPE Control  MPE Control                       20.0             59.514                8.57               1.0       None          None              None           None       None
 ```
@@ -578,10 +594,17 @@ log(analysis)
 
 
 ### Find Analyses
-Returns a list of analyses objects for the authenticated user. If no `analysis_id` is provided, returns all analyses for the authenticated user.
+Returns a list of analyses objects for the authenticated user. If `None` is provided for all query arguments, returns all analyses available to the user within the active tenant.
 
 ###### <u>Params</u>
-`analysis_id`: (`str`, optional) Unique ID of the analysis to be fetched, defaulted to None.
+* `analysis_id`: (`str`, optional) Unique ID of the analysis to be fetched, defaulted to None.
+* `analysis_name`: (`str`, optional) Name of the analysis to be fetched, defaulted to None. Results will be matched on a substring basis.
+* `folder_id`: (`str`, optional) Unique ID of the folder to fetch analyses from, defaulted to None.
+* `folder_name`: (`str`, optional) Name of the folder to fetch analyses from, defaulted to None.
+* `project_id`: (`str`, optional) Unique ID of the project to filter the result set of analyses, defaulted to None.
+* `project_name`: (`str`, optional) Name of the project to filter the result set of analyses, defaulted to None.
+* `plate_name`: (`str`, optional) Name of a plate to filter the result set of analyses, defaulted to None.
+* `as_df`: (`bool`, optional) Whether the result should be converted to a DataFrame, defaulted to False.
 <br>
 
 ###### <u>Returns</u>
@@ -955,11 +978,9 @@ log(sdk.group_analysis_results(group_analysis_id, box_plot_info))
 Downloads the FASTA file(s) associated with an analysis protocol. You can specify an analysis_id (the function will resolve the protocol automatically) or provide an analysis_protocol_id directly.
 
 ###### <u>Params</u>
-* `analysis_protocol_id`: (`str`, optional) ID of the analysis protocol whose FASTA file(s) you want.
-
-* `analysis_id`: (`str`, optional) ID of the analysis whose protocol FASTA file(s) you want.
-
-* `download_path`: (`str`, optional) Directory to save files to. Defaults to the current working directory.
+* `analysis_protocol_id`: (`str`, optional) The unique ID of the analysis protocol associated with the FASTA files to download.
+* `analysis_id`: (`str`, optional) The unique ID of the analysis whose protocol FASTA file(s) will be downloaded.
+* `analysis_name`: (`str`, optional) The name of the analysis whose protocol FASTA file(s) will be downloaded.
 
 Note: Provide either analysis_id or analysis_protocol_id (but not both).
 
@@ -977,6 +998,10 @@ sdk.download_analysis_protocol_fasta(
 )
 ```
 
+```
+['./uniprot_human_2023_08.fasta', './contaminants.fasta']
+```
+
 Download by analysis protocol ID to a specific folder:
 ```{python}
 #| eval: false
@@ -991,16 +1016,20 @@ sdk.download_analysis_protocol_fasta(
 ```
 <br>
 
-### Get Analysis Protocol FASTA link
-Returns signed download links for the FASTA file(s) associated with an analysis protocol. You can specify an analysis_id (the function will resolve the protocol automatically) or provide an analysis_protocol_id directly.
+### Get Analysis Protocol FASTA URLs
+Returns download URLs for the FASTA file(s) associated with an analysis protocol. You can specify an analysis_id (the function will resolve the protocol automatically) or provide an analysis_protocol_id directly.
+
+Download URLs are valid for 15 minutes after generation.
 
 ###### <u>Params</u>
-* `analysis_protocol_id`: (`str`, optional) ID of the analysis protocol whose FASTA file(s) you want.
-* `analysis_id`: (`str`, optional) ID of the analysis whose protocol FASTA file(s) you want.
-Note: Provide either analysis_id or analysis_protocol_id (but not both).
+* `analysis_protocol_id`: (`str`, optional) The unique ID of the analysis protocol associated with the FASTA files.
+* `analysis_id`: (`str`, optional) The unique ID of the analysis whose protocol FASTA file(s) should be retrieved.
+* `analysis_name`: (`str`, optional) The name of the analysis whose protocol FASTA file(s) should be retrieved.
+
+If both parameters are provided, `analysis_protocol_id` takes precedence.
 
 ###### <u>Returns</u>
-* links: (`list[dict]`) List of dictionaries containing filename and signed URL for each FASTA file.
+* links: (`dict`) Dictionary containing filename and signed URL as key-value pairs for the FASTA files linked to the protocol.
 
 ###### <u>Examples</u>
 Get by analysis ID:
@@ -1012,10 +1041,8 @@ sdk.get_analysis_protocol_fasta_link(
 ```
 
 ```
-[
-  {"filename": "uniprot_human_2023_08.fasta", "url": "https://...signed..."},
-  {"filename": "contaminants.fasta", "url": "https://...signed..."}
-]
+  {"uniprot_human_2023_08.fasta" : "https://...signed...",
+  "contaminants.fasta" : "https://...signed..."}
 ```
 Get by analysis protocol ID:
 ```{python}
@@ -1026,8 +1053,8 @@ sdk.get_analysis_protocol_fasta_link(
 ```
 ```
 [
-  {"filename": "uniprot_human_2023_08.fasta", "url": "https://...signed..."},
-  {"filename": "contaminants.fasta", "url": "https://...signed..."}
+  {"uniprot_human_2023_08.fasta" : "https://...signed...",
+   "contaminants.fasta" : "https://...signed..."}
 ]
 ```
 <hr>

{seer_pas_sdk-1.1.1 → seer_pas_sdk-1.2.1}/seer_pas_sdk/common/__init__.py

@@ -99,7 +99,7 @@ def dict_to_df(data):
 
 
 # Most cases appear to be a .tsv file.
-def download_df(url, is_tsv=True, dtype={}):
+def download_df(url, is_tsv=True, dtype={}, usecols=None):
     """
     Fetches a TSV/CSV file from a URL and returns as a Pandas DataFrame.
 
@@ -114,6 +114,9 @@ def download_df(url, is_tsv=True, dtype={}):
     dtype : dict
         Data type conversion when intaking columns. e.g. {'a': str, 'b': np.float64}
 
+    usecols : list
+        Subset of columns to download. If not specified, downloads all columns.
+
     Returns
     -------
     pandas.core.frame.DataFrame
@@ -139,11 +142,9 @@ def download_df(url, is_tsv=True, dtype={}):
 
     if not url:
         return pd.DataFrame()
-    url_content = io.StringIO(requests.get(url).content.decode("utf-8"))
-    if is_tsv:
-        csv = pd.read_csv(url_content, sep="\t", dtype=dtype)
-    else:
-        csv = pd.read_csv(url_content, dtype=dtype)
+    csv = pd.read_csv(
+        url, dtype=dtype, sep="\t" if is_tsv else ",", usecols=usecols
+    )
     return csv
 
 
@@ -679,6 +680,52 @@ def camel_case(s):
     return "".join([s[0].lower(), s[1:]])
 
 
+def validate_d_zip_file(file):
+    """
+    Return True if a .d.zip file aligns with Seer requirements for PAS upload.
+
+    Parameters
+    ----------
+    file : str
+        The name of the zip file.
+
+    Returns
+    -------
+    bool
+        True if the .d.zip file is valid, False otherwise.
+    """
+
+    if not file.lower().endswith(".d.zip"):
+        return False
+
+    basename = os.path.basename(file)
+
+    # Remove the .zip extension to get the .d folder name
+    d_name = basename[:-4]
+
+    try:
+        with zipfile.ZipFile(file, "r") as zf:
+            names = zf.namelist()
+
+    except:
+        return False
+
+    if not names:
+        return False
+
+    # check for files at the root level
+    root_entries = [n for n in names if "/" not in n.rstrip("/")]
+    if root_entries:
+        return False
+
+    # find folders
+    top_level = {n.split("/")[0] for n in names}
+    if len(top_level) != 1 or d_name not in top_level:
+        return False
+
+    return True
+
+
 def rename_d_zip_file(source, destination):
     """
     Renames a .d.zip file. The function extracts the contents of the source zip file, renames the inner .d folder, and rezips the contents into the destination zip file.