@datagrok/hit-triage 1.1.3 → 1.1.5

package/.eslintrc.json

@@ -26,6 +26,7 @@
       120
     ],
     "require-jsdoc": "off",
+    "valid-jsdoc": "off",
     "spaced-comment": "off",
     "linebreak-style": "off",
     "curly": [

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # HitTriage changelog
 
+## 1.1.4 (2024-01-17)
+
+* Add ability to use queries directly as source functions.
+* Fixed bugs with hit triage, including incorrect saving and addition of calculated properties.
+
 ## 1.1.3 (2023-12-27)
 
 Fix incompatibility with old api version

package/README.md

@@ -1,26 +1,9 @@
 # HitTriage
 
-The HitTriage package is a powerful tool designed for molecule analysis and campaign management within the Datagrok environment. It consists of two applications: HitTriage and HitDesign. This README provides an overview of the package's functionalities, and subsequent readmes will dive deeper into each application's usage.
+The **HitTriage** package is a powerful tool designed for molecule analysis and campaign management within the Datagrok environment. It consists of two applications: [HitTriage](https://github.com/datagrok-ai/public/blob/master/packages/HitTriage/README_HT.md) and [HitDesign](https://github.com/datagrok-ai/public/blob/master/packages/HitTriage/README_HD.md).
 
-## Features
+- The **HitTriage** application is designed for molecule analysis and filtering. It allows users to upload a dataset, filter it, calculate molecular properties, submit the results to any chosen function or query and share campaigns between users. More about HitTriage can be found [here](https://github.com/datagrok-ai/public/blob/master/packages/HitTriage/README_HT.md).
 
-Common Workflow
+- The **HitDesign** application is similar in terms of campaign management, but instead of uploading a dataset, users can sketch molecules, calculate molecular properties, filter and organize them in stages. More about HitDesign can be found [here](https://github.com/datagrok-ai/public/blob/master/packages/HitTriage/README_HT.md).
 
-1. **Template Creation:**
-
-    Define a template specifying the data source for molecules, name, key, additional needed information and compute functions. This source can be a file upload or a query in any other package tagged with `HitTriageDataSource` tag.
-    The Compute functions are collected from any package with a tag `HitTriageFunction`.
-
-    ![template](https://github.com/datagrok-ai/public/blob/master/help/uploads/hittriage/template.png?raw=true)
-
-2. **Campaign Building**:
-
-    Create campaigns based on the template.
-    Provide a campaign name, select the data source, provide additional information and initiate the campaign.
-    During the campaign run, the specified compute functions are executed, and their results are appended to the dataframe. For example, you can compute molecular descriptors, toxicity risks, structural alerts and more.
-
-    ![template](https://github.com/datagrok-ai/public/blob/master/help/uploads/hittriage/campaign.png?raw=true)
-
-After running a campaign, you can submit the dataframe to any chosen function or query. or
-save the campaign for later use. Saved campaigns can be reloaded and run again by any user on the platform usign the link or the campaigns table on the first page.
 

package/README_HD.md

@@ -68,7 +68,7 @@ Hit design campaign consists of two views, a main design view and a tiles view.
 
 HitDesign allows users to define custom compute and submit functions, and these functions can be written in any Datagrok package that is installed in the environment. 
 
-** Compute functions **
+### Compute functions
 
 Compute functions are used to calculate molecular properties. For example, mass, solubility, mutagenicity, partial charges, toxicity risks, etc. By default, Hit design will include compute functions from `Chem` package, which are molecular descriptors, Structural alerts, Toxicity risks and Chemical properties. Users can add additional compute functions by tagging them with `HitDesignFunction` tag and writing them in normal datagrok style. The First two inputs of these functions should be `Dataframe` `table` and `Column` `molecule`, and rest can be any other input. Function should perform a certain task, modify the dataframe in desired way and return the modified dataframe. For example, we can create a function that retrieves the `Chembl` mol registration number by smiles string:
 
@@ -98,7 +98,51 @@ export async function chemblMolregno(table: DG.DataFrame, molecules: DG.Column):
 
 This function will go through every molecule in the dataframe, convert them to canonical smiles and call the query from Chembl database, that will retrieve the molregno number. The result will be added as a new column to the dataframe. If this function is defined in the `Chembl` package, after building and deploying it to stand, it will be automatically added to the compute functions list in HitDesign.
 
-** Submit functions **
+Datagrok scripts can also be used as compute functions. For example, you can create a js script that adds a new column to the dataframe. This script also needs to have `HitTriageFunction` tag and should accept `Dataframe` `table` and `Column` `molecules` as first two inputs:
+
+```
+//name: Demo script HT
+//description: Hello world script
+//language: javascript
+//input: dataframe df
+//input: column col
+//input: int a
+//tags: HitTriageFunction
+//output: dataframe res
+
+df.columns.addNewInt('Some number col').init(() => a)
+res = df
+
+```
+
+Similarly, queries with same `HitTriageFunction` tag will be added to the compute functions list. The query needs to have at least one input, first of which must be `list<string>`, representing the list of molecules. The query must return a dataframe, which should contain column `molecules` in order to join result with initial dataframe. `molecules` column will be used as key for joining tables. For example, you can create a query that looks for the molecule in Chembl database and returns the molregno number:
+
+```
+--name: ChemblMolregNoBySmiles
+--friendlyName: Chembl Molregno by smiles
+--input: list<string> molecules
+--tags: HitTriageFunction
+--connection: Chembl
+select molregno, molecules from compound_structures c
+	INNER JOIN unnest(@molecules) molecules
+    ON molecules.molecules
+ = c.canonical_smiles
+```
+
+Or a query that calculates fraction of sp3 hybridized carbons in the molecule using RDKit SQL cartridge:
+
+```
+--name: SP3Fraction
+--friendlyName: SP3 fraction of carbons
+--input: list<string> molecules
+--tags: HitTriageFunction
+--connection: Chembl
+select molecules, mol_fractioncsp3(Cast(molecules as mol))
+from unnest(@molecules) as molecules
+where is_valid_smiles(Cast(molecules as cstring))
+```
+
+### Submit functions
 
 Submit functions are used to save or submit the filtered and computed dataset. This could include saving to a private database or additional calculations. Submit functions are defined in the same way as compute functions, but they are tagged with `HitTriageSubmitFunction` tag. The function should accept only two inputs, `Dataframe` `df` and `String` `molecules`, which are the resulting dataframe and name of molecules column respectively. For example, we can create a function that saves the filtered and computed dataset to a database:
 

package/README_HT.md

@@ -10,27 +10,113 @@ Templates in HitTriage contain essential configurations for conducting a campaig
 
 - **Campaign Prefix** : A code used as a prefix for campaign names (e.g., TMP-1, TMP-2).
 
-- **Data Ingestion Settings** : Controls how molecular data is ingested into the template. Users can choose between file upload or a query option. For the query, HitTriage searches for functions in any Datagrok package tagged with `HitTriageDataSource`. For example:
-
-    ```//name: Demo File Ingestion
-    //input: int numberOfMolecules [Molecules count]
-    //tags: HitTriageDataSource
-    //output: dataframe result
-    export async function demoFileIngest(numberOfMolecules: number): Promise<DG.DataFrame> {
-    const df = grok.data.demo.molecules(numberOfMolecules);
-    df.name = 'Variable Molecules number';
-    return df;
-    }
-    ```
-    The application will detect that the function requeires an input parameter and will prompt the user to provide it in campaigns form. The function must return a dataframe with a column containing molecules
+- **Data Ingestion Settings** : Controls how molecular data is ingested into the template. Users can choose between file upload or a query option. For the query, HitTriage searches for functions in any Datagrok package tagged with `HitTriageDataSource` and queries with same tag. For example, a package can export the following function:
+
+```//name: Demo File Ingestion
+//input: int numberOfMolecules [Molecules count]
+//tags: HitTriageDataSource
+//output: dataframe result
+export async function demoFileIngest(numberOfMolecules: number): Promise<DG.DataFrame> {
+const df = grok.data.demo.molecules(numberOfMolecules);
+df.name = 'Variable Molecules number';
+return df;
+}
+```
+Or users can write a query in the query editor, save it and share with others. Example for loading molecules from Chembl database:
+
+```--name: _someChemblStructure
+    --friendlyName: Load Some Chembl structures
+    --input: int numberOfMolecules = 1000
+    --tags: HitTriageDataSource
+    --connection: Chembl
+    select
+    canonical_smiles, molregno
+    from
+    compound_structures
+    limit @numberOfMolecules
+```
+
+The application will detect that the function/query requeires an input parameter and will prompt the user to provide it in campaigns form. The function\query must return a dataframe with a column containing molecules.
 
 - **Additional fields** : Users can configure additional fields for the template, which will be prompted for input during campaign creation. These fields include name, type, and whether they are required or not. For example, additional field for a campaign can be a target protein name, Head scientist name, deadlile, etc.
 
-- **Compute functions** : HitTriage aggregates compute functions tagged with `HitTriageFunction` from Datagrok packages. Users can select from these functions to perform calculations (e.g., mass, solubility, mutagenicity, partial charges, toxicity risks, etc.) on the dataset.
+- **Compute functions**
+
+Compute functions are used to calculate molecular properties. For example, mass, solubility, mutagenicity, partial charges, toxicity risks, etc. By default, Hit design will include compute functions from `Chem` package, which are molecular descriptors, Structural alerts, Toxicity risks and Chemical properties. Users can add additional compute functions by tagging them with `HitDesignFunction` tag and writing them in normal datagrok style. The First two inputs of these functions should be `Dataframe` `table` and `Column` `molecule`, and rest can be any other input. Function should perform a certain task, modify the dataframe in desired way and return the modified dataframe. For example, we can create a function that retrieves the `Chembl` mol registration number by smiles string:
+
+```
+//name: Chembl molregno
+//tags: HitTriageFunction
+//input: dataframe table [Input data table] {caption: Table}
+//input: column molecules {caption: Molecules; semType: Molecule}
+//output: dataframe result
+export async function chemblMolregno(table: DG.DataFrame, molecules: DG.Column): Promise<DG.DataFrame> {
+  const name = table.columns.getUnusedName('CHEMBL molregno');
+  table.columns.addNewInt(name);
+  for (let i = 0; i < molecules.length; i++) {
+    const smile = molecules.get(i);
+    if (!smile) {
+      table.set(name, i, null);
+      continue;
+    }
+    const canonical = grok.chem.convert(smile, DG.chem.Notation.Unknown, DG.chem.Notation.Smiles);
+    const resDf: DG.DataFrame = await grok.data.query('Chembl:ChemblMolregNoBySmiles', {smiles: canonical});
+    const res: number = resDf.getCol('molregno').toList()[0];
+    table.set(name, i, res);
+  }
+  return table;
+}
+```
+
+This function will go through every molecule in the dataframe, convert them to canonical smiles and call the query from Chembl database, that will retrieve the molregno number. The result will be added as a new column to the dataframe. If this function is defined in the `Chembl` package, after building and deploying it to stand, it will be automatically added to the compute functions list in HitDesign.
+
+Datagrok scripts can also be used as compute functions. For example, you can create a js script that adds a new column to the dataframe. This script also needs to have `HitTriageFunction` tag and should accept `Dataframe` `table` and `Column` `molecules` as first two inputs:
+
+```
+//name: Demo script HT
+//description: Hello world script
+//language: javascript
+//input: dataframe df
+//input: column col
+//input: int a
+//tags: HitTriageFunction
+//output: dataframe res
+
+df.columns.addNewInt('Some number col').init(() => a)
+res = df
+
+```
+
+Similarly, queries with same `HitTriageFunction` tag will be added to the compute functions list. The query needs to have at least one input, first of which must be `list<string>`, representing the list of molecules. The query must return a dataframe, which should contain column `molecules` in order to join result with initial dataframe. `molecules` column will be used as key for joining tables. For example, we can create a query that looks for the molecule in Chembl database and returns the molregno number:
+
+```
+--name: ChemblMolregNoBySmilesDirect
+--friendlyName: Chembl Molregno by smiles direct
+--input: list<string> molecules
+--tags: HitTriageFunction
+--connection: Chembl
+select molregno, molecules from compound_structures c
+	INNER JOIN unnest(@molecules) molecules
+    ON molecules.molecules
+ = c.canonical_smiles
+```
+
+Or a query that calculates fraction of sp3 hybridized carbons in the molecule using RDKit SQL cartridge:
+
+```
+--name: SP3Fraction
+--friendlyName: SP3 fraction of carbons
+--input: list<string> molecules
+--tags: HitTriageFunction
+--connection: Chembl
+select molecules, mol_fractioncsp3(Cast(molecules as mol))
+from unnest(@molecules) as molecules
+where is_valid_smiles(Cast(molecules as cstring))
+```
 
 - **Submit function** : Users can define custom submit functions (tagged with `HitTriageSubmitFunction`) to further process or save the filtered and computed dataset. This could include saving to a private database or additional calculations.
 
-![template](https://datagrok.ai/help/uploads/hittriage/files/images/template.png)
+![hitDesignReadmeImg](https://github.com/datagrok-ai/public/blob/master/help/uploads/hittriage/template.png?raw=true)
 
 ## Campaigns
 
@@ -42,22 +128,22 @@ Campaigns are built based on templates and encompass the actual hit triage proce
 
 - **Functionality**: Once a campaign starts, you can add extra calculated columns, apply changes, fileter, save or submit the campaign.
 
-![template](https://datagrok.ai/help/uploads/hittriage/files/images/campaign.png)
+![hitDesignReadmeImg](https://github.com/datagrok-ai/public/blob/master/help/uploads/hittriage/campaign.png?raw=true)
 
 ## Getting started
 
 Users can continue ongoing campaigns either directly by a link or by selecting it from the campaigns table.
 
-![template](https://datagrok.ai/help/uploads/hittriage/files/images/HT_Continue_campaign.gif)
+![hitDesignReadmeImg](https://github.com/datagrok-ai/public/blob/master/help/uploads/hittriage/HT_Continue_campaign.gif?raw=true)
 
 Users can create a new template by clicking on the `New Template` button in the `Templates` dropdown.
 
-![template](https://datagrok.ai/help/uploads/hittriage/files/images/HT_create_template.gif)
+![hitDesignReadmeImg](https://github.com/datagrok-ai/public/blob/master/help/uploads/hittriage/HT_create_template.gif?raw=true)
 
 Users can start a new campaign by choosing a template and filling out the required information. 
 
-![template](https://datagrok.ai/help/uploads/hittriage/files/images/HT_create_campaign.gif)
+![hitDesignReadmeImg](https://github.com/datagrok-ai/public/blob/master/help/uploads/hittriage/HT_create_campaign.gif?raw=true)
 
-After the campaign starts, users can filter, modify or add viewers to the campaign and then save them. once saved, reloading the campaign will restore the saved state.
+After the campaign starts, new calculated columns will be added. Users can filter, modify or add viewers to the campaign and then save them. Once saved, reloading the campaign will restore the saved state.
 
-![template](https://datagrok.ai/help/uploads/hittriage/files/images/HT_save_campaign.gif)
+![hitDesignReadmeImg](https://github.com/datagrok-ai/public/blob/master/help/uploads/hittriage/HT_save_campaign.gif?raw=true)

package/css/hit-triage.css

@@ -66,7 +66,7 @@ table.hit-triage-table {
 
 .hit-triage-compute-dialog-host {
     max-height: 550px;
-    max-width: 500px;
+    max-width: 700px;
 }
 
 .hit-triage-compute-dialog-descriptors-group {