Aggregate Transforms

Obtain MMP transform-level data, including statistics, e.g. median change in a specified property for each MMP transform found by the query. The matcher frontend uses this data to populate the table of transforms in the frontend results.

Body Parameters:

• query_id: Number returned by /start_query endpoint to run the query of interest
• aggregation_type: "individual_transforms" or "group_by_fragment": "individual_transforms" is the default and will return statistics on a per-transform basis. Alternatively, "group_by_fragment" is useful for queries where mol1_variable and mol2_variable fragments are similar or identical, for example searching for "privileged" fragments with a specific substructure. Each row returned by "group_by_fragment" will show how a specific fragment compares to all other fragments found in the query to which that fragment is related.
• statistics: list of statistics of interest, with below parameters:
  • statistic: currently only "median" is implemented, and is implemented at the database level for best performance. For example, obtain the median change in a specific property for all transforms found by the query.
  • property_name: must match one of the property_names in the database property_name table, which were specified with data that was input to the mmpdb loadprops command during database initialization
  • change_type: "fold_change" or "delta", "fold_change" returns a quotient (B / A), "delta" returns a difference (B - A), where B is the property value of the right-hand-side compound in the MMP, and A is the property value of the left-hand-side compound in the MMP.
  • base: OPTIONAL: "raw" or "log": "raw" is the default and should be used, unless metadata was provided to the mmpdb loadprops command during database initialization. In the latter case, this parameter enables customization of what data statistics are performed upon. Example: a property is stored in the DB as "log" units (as defined in the metadata), but we wish to perform statistics on the non-log, "raw" units, then specify "raw". If no metadata was provided, "raw" will use the raw data that was loaded with mmpdb loadprops.
  • units: OPTIONAL: omit this field to use data as-is. Other options are "M" or "uM". Similar to base above, if metadata was provided, this parameter can be used to transform values e.g. from molar values stored in the DB, to micromolar values that is more digestible by certain users.
• range_filters: OPTIONAL list of range_filter objects containing the below items, used to filter MMPs prior to statistical aggregation, based on the below criteria, e.g. every 'A' (i.e. left-hand-side) compound in an MMP must have a property_value <= x
  • compound: either 'A' or 'B', referring to LHS or RHS of the MMP
  • property_name: same description as property_name above
  • operator: '<', '>', '<=', '>=', '=', '!='
  • base: OPTIONAL: same description as base above
  • units: OPTIONAL: same description as units above
  • value: value to filter by

Returns JSON with following items:

• minmax: minimum and maximum values for properties and their statistics.
• column_headers: Array of strings (i.e., headers) matching elements in below rows. The specific headers depend on aggregation_type. For example, when aggregation_type = "individual_transforms", below are the column_headers (details about what these headers refer to is provided):
  • "rule_id": id for the transform that defines the difference between the two compounds in MMPs
  • "from_smiles": SMILES for the left-hand-side fragment in the transform
  • "to_smiles": SMILES for the right-hand-side fragment in the transform
  • "pair_count": number of MMPs belonging to this transform
  • label of the form statistic + property_name + change_type
• rows: array of arrays (i.e., rows), with elements matching column_headers, where each row correspond to either a transform (when aggregation_type = "individual_transforms"), or a fragment (when aggregation_type = "group_by_fragment")
• grouped_by_environment: false or true: whether or not the transforms are grouped by environment. Use this value as input to /get_plot_data endpoint. Only relevant for some queries with multiple points of attachment between variable and environment atoms, depending on symmetry