sapiopycommons 2024.11.11a364__py3-none-any.whl → 2024.11.18a366__py3-none-any.whl

sapiopycommons/chem/Molecules.py

@@ -1,5 +1,6 @@
 # Author Yechen Qiao
 # Common Molecule Utilities for Molecule Transfers with Sapio
+from typing import cast
 
 from rdkit import Chem
 from rdkit.Chem import Crippen, MolToInchi
@@ -20,6 +21,25 @@ tautomer_params.tautomerReassignStereo = False
 tautomer_params.tautomerRemoveIsotopicHs = True
 enumerator = rdMolStandardize.TautomerEnumerator(tautomer_params)
 
+
+def get_enhanced_stereo_reg_hash(mol: Mol, enhanced_stereo: bool) -> str:
+    """
+    Get the Registration Hash for the molecule by the current registration configuration.
+    When we are running if we are canonicalization of tautomers or cleaning up any other way, do they first before calling.
+    :param mol: The molecule to obtain hash for.
+    :param canonical_tautomer: Whether the registry system canonicalize the tautomers.
+    :param enhanced_stereo: Whether we are computing enhanced stereo at all.
+    :return: The enhanced stereo hash.
+    """
+    if enhanced_stereo:
+        from rdkit.Chem.RegistrationHash import GetMolLayers, GetMolHash, HashScheme
+        layers = GetMolLayers(mol, enable_tautomer_hash_v2=True)
+        hash_scheme: HashScheme = HashScheme.TAUTOMER_INSENSITIVE_LAYERS
+        return GetMolHash(layers, hash_scheme=hash_scheme)
+    else:
+        return ""
+
+
 def neutralize_atoms(mol) -> Mol:
     """
     Neutralize atoms per https://baoilleach.blogspot.com/2019/12/no-charge-simple-approach-to.html
@@ -86,7 +106,6 @@ def mol_to_img(mol_str: str) -> str:
     return renderer.renderToString(mol)
 
 
-
 def mol_to_sapio_partial_pojo(mol: Mol):
     """
     Get the minimum information about molecule to Sapio, just its SMILES, V3000, and image data.
@@ -96,7 +115,7 @@ def mol_to_sapio_partial_pojo(mol: Mol):
     Chem.SanitizeMol(mol)
     mol.UpdatePropertyCache()
     smiles = Chem.MolToSmiles(mol)
-    molBlock = Chem.MolToMolBlock(mol)
+    molBlock = Chem.MolToMolBlock(mol, forceV3000=True)
     img = mol_to_img(mol)
     molecule = dict()
     molecule["smiles"] = smiles
@@ -105,23 +124,52 @@ def mol_to_sapio_partial_pojo(mol: Mol):
     return molecule
 
 
-def mol_to_sapio_substance(mol: Mol, include_stereoisomers: bool = False,
+def get_cxs_smiles_hash(mol: Mol, enhanced_stereo: bool) -> str:
+    """
+    Return the SHA1 CXS Smiles hash for the canonical, isomeric CXS SMILES of the molecule.
+    """
+    if not enhanced_stereo:
+        return ""
+    import hashlib
+    return hashlib.sha1(Chem.MolToCXSmiles(mol, canonical=True, isomericSmiles=True).encode()).hexdigest()
+
+
+def get_has_or_group(mol: Mol, enhanced_stereo: bool) -> bool:
+    """
+    Return true if and only if: enhanced stereochemistry is enabled and there is at least one OR group in mol.
+    """
+    if not enhanced_stereo:
+        return False
+    from rdkit.Chem import StereoGroup_vect, STEREO_OR
+    stereo_groups: StereoGroup_vect = mol.GetStereoGroups()
+    for stereo_group in stereo_groups:
+        if stereo_group.GetGroupType() == STEREO_OR:
+            return True
+    return False
+
+
+def mol_to_sapio_substance(mol: Mol, include_stereoisomers=False,
                            normalize: bool = False, remove_salt: bool = False, make_images: bool = False,
-                           salt_def: str | None = None, canonical_tautomer: bool = True):
+                           salt_def: str | None = None, canonical_tautomer: bool = True,
+                           enhanced_stereo: bool = False, remove_atom_map: bool = True):
     """
     Convert a molecule in RDKit to a molecule POJO in Sapio.
 
     :param mol: The molecule in RDKit.
-    :param include_stereoisomers: If true, will compute all stereoisomer permutations of this molecule.
     :param normalize If true, will normalize the functional groups and return normalized result.
     :param remove_salt If true, we will remove salts iteratively from the molecule before returning their data.
     We will also populate desaltedList with molecules we deleted.
+    :param make_images Whether to make images as part of the result without having another script to resolve it.
     :param salt_def: if not none, specifies custom salt to be used during the desalt process.
     :param canonical_tautomer: if True, we will attempt to compute canonical tautomer for the molecule. Slow!
     This is needed for a registry. Note it stops after enumeration of 1000.
+    :param enhanced_stereo: If enabled, enhanced stereo hash will be produced.
+    :param remove_atom_map: When set, clear all atom AAM maps that were set had it been merged into some reactions earlier.
     :return: The molecule POJO for Sapio.
     """
     molecule = dict()
+    if remove_atom_map:
+        [a.SetAtomMapNum(0) for a in mol.GetAtoms()]
     Chem.SanitizeMol(mol)
     mol.UpdatePropertyCache()
     Chem.GetSymmSSSR(mol)
@@ -157,7 +205,7 @@ def mol_to_sapio_substance(mol: Mol, include_stereoisomers: bool = False,
     exactMass = Descriptors.ExactMolWt(mol)
     molFormula = rdMolDescriptors.CalcMolFormula(mol)
     charge = Chem.GetFormalCharge(mol)
-    molBlock = Chem.MolToMolBlock(mol)
+    molBlock = Chem.MolToMolBlock(mol, forceV3000=True)
 
     molecule["cLogP"] = cLogP
     molecule["tpsa"] = tpsa
@@ -181,27 +229,38 @@ def mol_to_sapio_substance(mol: Mol, include_stereoisomers: bool = False,
     # We need to test the INCHI can be loaded back to indigo.
     indigo_mol = indigo.loadMolecule(molBlock)
     indigo_mol.aromatize()
-    indigo_inchi_str = indigo_inchi.getInchi(indigo_mol)
-    molecule["inchi"] = indigo_inchi_str
-    indigo_inchi_key_str = indigo_inchi.getInchiKey(indigo_inchi_str)
-    molecule["inchiKey"] = indigo_inchi_key_str
+    if enhanced_stereo:
+        # Remove enhanced stereo layer when generating InChI as the stereo hash is generated separately for reg.
+        mol_copy: Mol = Chem.Mol(mol)
+        Chem.CanonicalizeEnhancedStereo(mol_copy)
+        molecule["inchi"] = Chem.MolToInchi(mol_copy)
+        molecule["inchiKey"] = Chem.MolToInchiKey(mol_copy)
+    else:
+        indigo_inchi.resetOptions()
+        indigo_inchi_str = indigo_inchi.getInchi(indigo_mol)
+        molecule["inchi"] = indigo_inchi_str
+        indigo_inchi_key_str = indigo_inchi.getInchiKey(indigo_inchi_str)
+        molecule["inchiKey"] = indigo_inchi_key_str
     molecule["smiles"] = indigo_mol.smiles()
+    molecule["reg_hash"] = get_enhanced_stereo_reg_hash(mol, enhanced_stereo=enhanced_stereo)
+    molecule["cxsmiles_hash"] = get_cxs_smiles_hash(mol, enhanced_stereo=enhanced_stereo)
+    molecule["has_or_group"] = get_has_or_group(mol, enhanced_stereo=enhanced_stereo)
 
-    if include_stereoisomers and has_chiral_centers(mol):
-        stereoisomers = find_all_possible_stereoisomers(mol, only_unassigned=False, try_embedding=False, unique=True)
-        molecule["stereoisomers"] = [mol_to_sapio_partial_pojo(x) for x in stereoisomers]
     return molecule
 
 
-def mol_to_sapio_compound(mol: Mol, include_stereoisomers: bool = False,
+def mol_to_sapio_compound(mol: Mol, include_stereoisomers=False, enhanced_stereo: bool = False,
                           salt_def: str | None = None, resolve_canonical: bool = True,
-                          make_images: bool = False, canonical_tautomer: bool = True):
+                          make_images: bool = False, canonical_tautomer: bool = True,
+                          remove_atom_map: bool = True):
     ret = dict()
-    ret['originalMol'] = mol_to_sapio_substance(mol, include_stereoisomers,
+    ret['originalMol'] = mol_to_sapio_substance(mol, include_stereoisomers=False,
                                                 normalize=False, remove_salt=False, make_images=make_images,
-                                                canonical_tautomer=canonical_tautomer)
+                                                canonical_tautomer=canonical_tautomer,
+                                                enhanced_stereo=enhanced_stereo, remove_atom_map=remove_atom_map)
     if resolve_canonical:
         ret['canonicalMol'] = mol_to_sapio_substance(mol, include_stereoisomers=False,
                                                      normalize=True, remove_salt=True, make_images=make_images,
-                                                     salt_def=salt_def, canonical_tautomer=canonical_tautomer)
+                                                     salt_def=salt_def, canonical_tautomer=canonical_tautomer,
+                                                     enhanced_stereo=enhanced_stereo, remove_atom_map=remove_atom_map)
     return ret

sapiopycommons/customreport/column_builder.py

@@ -0,0 +1,60 @@
+from sapiopylib.rest.pojo.CustomReport import ReportColumn
+from sapiopylib.rest.pojo.datatype.FieldDefinition import FieldType
+
+from sapiopycommons.general.aliases import DataTypeIdentifier, FieldIdentifier, AliasUtil
+from sapiopycommons.general.exceptions import SapioException
+
+# The system fields that every record has and their field types. System fields aren't generated as record model fields
+# for all platform version, hence the need to create a dict for them in the off chance that they're not present on
+# the model wrapper.
+SYSTEM_FIELDS: dict[str, FieldType] = {
+    "DataRecordName": FieldType.IDENTIFIER,
+    "RecordId": FieldType.LONG,
+    "DateCreated": FieldType.DATE,
+    "CreatedBy": FieldType.STRING,
+    "VeloxLastModifiedDate": FieldType.DATE,
+    "VeloxLastModifiedBy": FieldType.STRING
+}
+
+
+class ColumnBuilder:
+    """
+    A class for building report columns for custom reports.
+    """
+    @staticmethod
+    def build_column(data_type: DataTypeIdentifier, field: FieldIdentifier, field_type: FieldType | None = None) \
+            -> ReportColumn:
+        """
+        Build a ReportColumn from a variety of possible inputs.
+
+        :param data_type: An object that can be used to identify a data type.
+        :param field: An object that can be used to identify a data field.
+        :param field_type: The field type of the provided field. This is only required if the field type cannot be
+            determined from the given data type and field, which occurs when the given field is a string and the
+            given data type is not a wrapped record model or record model wrapper.
+        :return: A ReportColumn for the inputs.
+        """
+        # Get the data type and field names from the inputs.
+        data_type_name = AliasUtil.to_data_type_name(data_type)
+        field_name = AliasUtil.to_data_field_name(field)
+        if field_type is None:
+            field_type = ColumnBuilder.__field_type(data_type, field)
+        if field_type is None:
+            raise SapioException("The field_type parameter is required for the provided data_type and field inputs.")
+        return ReportColumn(data_type_name, field_name, field_type)
+
+    @staticmethod
+    def __field_type(data_type: DataTypeIdentifier, field: FieldIdentifier) -> FieldType | None:
+        """
+        Given a record model wrapper and a field name, return the field type for that field. Accounts for system fields.
+
+        :param data_type: The record model wrapper that the field is on.
+        :param field: The field name to return the type of.
+        :return: The field type of the given field name.
+        """
+        # Check if the field name is a system field. If it is, use the field type defined in this file.
+        field_name: str = AliasUtil.to_data_field_name(field)
+        if field_name in SYSTEM_FIELDS:
+            return SYSTEM_FIELDS.get(field_name)
+        # Otherwise, check if the field type can be found from the wrapper.
+        return AliasUtil.to_field_type(field, data_type)

sapiopycommons/customreport/custom_report_builder.py

@@ -0,0 +1,130 @@
+from sapiopylib.rest.pojo.CustomReport import ReportColumn, CustomReportCriteria, AbstractReportTerm, \
+    ExplicitJoinDefinition, RelatedRecordCriteria, QueryRestriction, FieldCompareReportTerm
+from sapiopylib.rest.pojo.datatype.FieldDefinition import FieldType
+
+from sapiopycommons.customreport.column_builder import ColumnBuilder
+from sapiopycommons.general.aliases import DataTypeIdentifier, FieldIdentifier, AliasUtil, SapioRecord
+from sapiopycommons.general.exceptions import SapioException
+
+
+class CustomReportBuilder:
+    """
+    A class used for building custom reports. Look into using the TermBuilder and ColumnBuilder classes for building
+    parts of a custom report.
+    """
+    root_data_type: DataTypeIdentifier
+    data_type_name: str
+    root_term: AbstractReportTerm | None
+    record_criteria: RelatedRecordCriteria
+    column_list: list[ReportColumn]
+    join_list: list[ExplicitJoinDefinition]
+
+    def __init__(self, root_data_type: DataTypeIdentifier):
+        """
+        :param root_data_type: An object that can be used to identify a data type name. Used as the root data type name
+            of this search.
+        """
+        self.root_data_type = root_data_type
+        self.data_type_name = AliasUtil.to_data_type_name(root_data_type)
+        self.root_term = None
+        self.record_criteria = RelatedRecordCriteria(QueryRestriction.QUERY_ALL)
+        self.column_list = []
+        self.join_list = []
+
+    def has_root_term(self) -> bool:
+        """
+        :return: Whether this report builder has had its root term set.
+        """
+        return self.root_term is not None
+
+    def set_root_term(self, term: AbstractReportTerm) -> None:
+        """
+        Set the root term of the report. Use the TermBuilder class to construct the report terms.
+
+        :param term: The term to set as the root term.
+        """
+        self.root_term = term
+
+    def has_columns(self) -> bool:
+        """
+        :return: Whether this report builder has any report columns.
+        """
+        return bool(self.column_list)
+
+    def add_column(self, field: FieldIdentifier, field_type: FieldType = None,
+                   *, data_type: DataTypeIdentifier | None = None) -> None:
+        """
+        Add a column to this report builder.
+
+        :param field: An object that can be used to identify a data field.
+        :param field_type: The field type of the provided field. This is only required if the field type cannot be
+            determined from the given data type and field, which occurs when the given field is a string and the
+            given data type is not a wrapped record model or record model wrapper.
+        :param data_type: An object that can be used to identify a data type. If not provided, uses the root data type
+            provided when this builder was initialized. You'll only want to specify this value when adding a column
+            that is from a different data type than the root data type.
+        """
+        if data_type is None:
+            data_type = self.root_data_type
+        self.column_list.append(ColumnBuilder.build_column(data_type, field, field_type))
+
+    def add_columns(self, fields: list[FieldIdentifier], *, data_type: DataTypeIdentifier | None = None) -> None:
+        """
+        Add columns to this report builder.
+
+        :param fields: A list of objects that can be used to identify data fields.
+        :param data_type: An object that can be used to identify a data type. If not provided, uses the root data type
+            provided when this builder was initialized. You'll only want to specify this value when adding a column
+            that is from a different data type than the root data type.
+        """
+        for field in fields:
+            self.add_column(field, data_type=data_type)
+
+    def set_query_restriction(self, base_record: SapioRecord, search_related: QueryRestriction) -> None:
+        """
+        Set a restriction on the report for this report builder such that the returned results must be related in
+        some way to the provided base record. Without this, the report searches all records in the system that match the
+        root term.
+
+        :param base_record: The base record to run the search from.
+        :param search_related: Determine the relationship of the related records that can appear in the search, be those
+            children, parents, descendants, or ancestors.
+        """
+        if search_related == QueryRestriction.QUERY_ALL:
+            raise SapioException("The search_related must be something other than QUERY_ALL when setting a query restriction.")
+        self.record_criteria = RelatedRecordCriteria(search_related,
+                                                     AliasUtil.to_record_id(base_record),
+                                                     AliasUtil.to_data_type_name(base_record))
+
+    def add_join(self, comparison_term: FieldCompareReportTerm, data_type: DataTypeIdentifier | None = None) -> None:
+        """
+        Add a join statement to this report builder.
+
+        :param comparison_term: The field comparison term to join with.
+        :param data_type: The data type name that this join is on. If not provided, then the left side data type name
+            of the comparison term will be the data type that is joined against.
+        """
+        if data_type is None:
+            data_type: str = comparison_term.left_data_type_name
+        else:
+            data_type: str = AliasUtil.to_data_type_name(data_type)
+        self.join_list.append(ExplicitJoinDefinition(data_type, comparison_term))
+
+    def build_report_criteria(self, page_size: int = 0, page_number: int = -1, case_sensitive: bool = False,
+                              owner_restriction_set: list[str] = None) -> CustomReportCriteria:
+        """
+        Generate a CustomReportCriteria using the column list, root term, and root data type from this report builder.
+        You can use the CustomReportManager or CustomReportUtil to run the constructed report.
+
+        :param page_size: The page size of the custom report.
+        :param page_number: The page number of the current report.
+        :param case_sensitive: When searching texts, should the search be case-sensitive?
+        :param owner_restriction_set: Specifies to only return records if the record is owned by this list of usernames.
+        :return: A CustomReportCriteria from this report builder.
+        """
+        if not self.has_root_term():
+            raise SapioException("Cannot build a report with no root term.")
+        if not self.has_columns():
+            raise SapioException("Cannot build a report with no columns.")
+        return CustomReportCriteria(self.column_list, self.root_term, self.record_criteria, self.data_type_name,
+                                    case_sensitive, page_size, page_number, owner_restriction_set, self.join_list)

sapiopycommons/customreport/term_builder.py

@@ -0,0 +1,299 @@
+from typing import Iterable
+
+from sapiopylib.rest.pojo.CustomReport import RawTermOperation, CompositeTermOperation, RawReportTerm, \
+    CompositeReportTerm, AbstractReportTerm, FieldCompareReportTerm
+
+from sapiopycommons.general.aliases import DataTypeIdentifier, AliasUtil, FieldIdentifier
+
+# Raw term operations, for comparing field values.
+EQ = RawTermOperation.EQUAL_TO_OPERATOR
+NEQ = RawTermOperation.NOT_EQUAL_TO_OPERATOR
+LT = RawTermOperation.LESS_THAN_OPERATOR
+LTE = RawTermOperation.LESS_THAN_OR_EQUAL_OPERATOR
+GT = RawTermOperation.GREATER_THAN_OPERATOR
+GTE = RawTermOperation.GREATER_THAN_OR_EQUAL_OPERATOR
+
+# Composite term operations, for comparing two terms.
+AND = CompositeTermOperation.AND_OPERATOR
+OR = CompositeTermOperation.OR_OPERATOR
+
+# Forms that field term values can take.
+TermValue = str | int | float | bool | Iterable | None
+
+
+class TermBuilder:
+    """
+    A class that allows for the easier constructions of custom report terms.
+    """
+    @staticmethod
+    def all_records_term(data_type: DataTypeIdentifier) -> RawReportTerm:
+        """
+        Create a raw report term that captures all records of the given data type.
+
+        :param data_type: The data type of this term.
+        :return: A raw report term for "data_type.RecordId >= 0".
+        """
+        return RawReportTerm(AliasUtil.to_data_type_name(data_type), "RecordId", GTE, TermBuilder.to_term_val(0))
+
+    @staticmethod
+    def is_term(data_type: DataTypeIdentifier, field: FieldIdentifier, value: TermValue,
+                *, trim: bool = False) -> RawReportTerm:
+        """
+        Create a raw report term for comparing a field value with an equals operation.
+
+        :param data_type: The data type of this term.
+        :param field: The data field of this term.
+        :param value: The value to compare for this term.
+        :param trim: Whether the string of the given value should be trimmed of trailing and leading whitespace.
+        :return: A raw report term for "data_type.field = value".
+        """
+        return RawReportTerm(AliasUtil.to_data_type_name(data_type), AliasUtil.to_data_field_name(field), EQ,
+                             TermBuilder.to_term_val(value), trim)
+
+    @staticmethod
+    def not_term(data_type: DataTypeIdentifier, field: FieldIdentifier, value: TermValue,
+                 *, trim: bool = False) -> RawReportTerm:
+        """
+        Create a raw report term for comparing a field value with a not equals operation.
+
+        :param data_type: The data type of this term.
+        :param field: The data field of this term.
+        :param value: The value to compare for this term.
+        :param trim: Whether the string of the given value should be trimmed of trailing and leading whitespace.
+        :return: A raw report term for "data_type.field != value".
+        """
+        return RawReportTerm(AliasUtil.to_data_type_name(data_type), AliasUtil.to_data_field_name(field), NEQ,
+                             TermBuilder.to_term_val(value), trim)
+
+    @staticmethod
+    def lt_term(data_type: DataTypeIdentifier, field: FieldIdentifier, value: TermValue,
+                *, trim: bool = False) -> RawReportTerm:
+        """
+        Create a raw report term for comparing a field value with a less than operation.
+
+        :param data_type: The data type of this term.
+        :param field: The data field of this term.
+        :param value: The value to compare for this term.
+        :param trim: Whether the string of the given value should be trimmed of trailing and leading whitespace.
+        :return: A raw report term for "data_type.field < value".
+        """
+        return RawReportTerm(AliasUtil.to_data_type_name(data_type), AliasUtil.to_data_field_name(field), LT,
+                             TermBuilder.to_term_val(value), trim)
+
+    @staticmethod
+    def lte_term(data_type: DataTypeIdentifier, field: FieldIdentifier, value: TermValue,
+                 *, trim: bool = False) -> RawReportTerm:
+        """
+        Create a raw report term for comparing a field value with a less than or equal to operation.
+
+        :param data_type: The data type of this term.
+        :param field: The data field of this term.
+        :param value: The value to compare for this term.
+        :param trim: Whether the string of the given value should be trimmed of trailing and leading whitespace.
+        :return: A raw report term for "data_type.field <= value".
+        """
+        return RawReportTerm(AliasUtil.to_data_type_name(data_type), AliasUtil.to_data_field_name(field), LTE,
+                             TermBuilder.to_term_val(value), trim)
+
+    @staticmethod
+    def gt_term(data_type: DataTypeIdentifier, field: FieldIdentifier, value: TermValue,
+                *, trim: bool = False) -> RawReportTerm:
+        """
+        Create a raw report term for comparing a field value with a greater than operation.
+
+        :param data_type: The data type of this term.
+        :param field: The data field of this term.
+        :param value: The value to compare for this term.
+        :param trim: Whether the string of the given value should be trimmed of trailing and leading whitespace.
+        :return: A raw report term for "data_type.field > value".
+        """
+        return RawReportTerm(AliasUtil.to_data_type_name(data_type), AliasUtil.to_data_field_name(field), GT,
+                             TermBuilder.to_term_val(value), trim)
+
+    @staticmethod
+    def gte_term(data_type: DataTypeIdentifier, field: FieldIdentifier, value: TermValue,
+                 *, trim: bool = False) -> RawReportTerm:
+        """
+        Create a raw report term for comparing a field value with a greater than or equal to operation.
+
+        :param data_type: The data type of this term.
+        :param field: The data field of this term.
+        :param value: The value to compare for this term.
+        :param trim: Whether the string of the given value should be trimmed of trailing and leading whitespace.
+        :return: A raw report term for "data_type.field >= value".
+        """
+        return RawReportTerm(AliasUtil.to_data_type_name(data_type), AliasUtil.to_data_field_name(field), GTE,
+                             TermBuilder.to_term_val(value), trim)
+
+    @staticmethod
+    def compare_is_term(data_type_A: DataTypeIdentifier, field_A: FieldIdentifier,
+                        data_type_B: DataTypeIdentifier, field_B: FieldIdentifier,
+                        *, trim: bool = False) -> FieldCompareReportTerm:
+        """
+        Create a field comparison report term for comparing field values between data types with an equals operation.
+
+        :param data_type_A: The data type for the left side of this term.
+        :param field_A: The data field for the left side of this term.
+        :param data_type_B: The data type for the right side of this term.
+        :param field_B: The data field for the right side of this term.
+        :param trim: Whether the field values should be trimmed of trailing and leading whitespace for comparing.
+        :return: A field comparison report term for "data_type_A.field_A = data_type_B.field_B".
+        """
+        return FieldCompareReportTerm(AliasUtil.to_data_type_name(data_type_A), AliasUtil.to_data_field_name(field_A), EQ,
+                                      AliasUtil.to_data_type_name(data_type_B), AliasUtil.to_data_field_name(field_B), trim)
+
+    @staticmethod
+    def compare_not_term(data_type_A: DataTypeIdentifier, field_A: FieldIdentifier,
+                         data_type_B: DataTypeIdentifier, field_B: FieldIdentifier,
+                         *, trim: bool = False) -> FieldCompareReportTerm:
+        """
+        Create a field comparison report term for comparing field values between data types with a not equals operation.
+
+        :param data_type_A: The data type for the left side of this term.
+        :param field_A: The data field for the left side of this term.
+        :param data_type_B: The data type for the right side of this term.
+        :param field_B: The data field for the right side of this term.
+        :param trim: Whether the field values should be trimmed of trailing and leading whitespace for comparing.
+        :return: A field comparison report term for "data_type_A.field_A != data_type_B.field_B".
+        """
+        return FieldCompareReportTerm(AliasUtil.to_data_type_name(data_type_A), AliasUtil.to_data_field_name(field_A), NEQ,
+                                      AliasUtil.to_data_type_name(data_type_B), AliasUtil.to_data_field_name(field_B), trim)
+
+    @staticmethod
+    def compare_lt_term(data_type_A: DataTypeIdentifier, field_A: FieldIdentifier,
+                        data_type_B: DataTypeIdentifier, field_B: FieldIdentifier,
+                        *, trim: bool = False) -> FieldCompareReportTerm:
+        """
+        Create a field comparison report term for comparing field values between data types with a less than operation.
+
+        :param data_type_A: The data type for the left side of this term.
+        :param field_A: The data field for the left side of this term.
+        :param data_type_B: The data type for the right side of this term.
+        :param field_B: The data field for the right side of this term.
+        :param trim: Whether the field values should be trimmed of trailing and leading whitespace for comparing.
+        :return: A field comparison report term for "data_type_A.field_A < data_type_B.field_B".
+        """
+        return FieldCompareReportTerm(AliasUtil.to_data_type_name(data_type_A), AliasUtil.to_data_field_name(field_A), LT,
+                                      AliasUtil.to_data_type_name(data_type_B), AliasUtil.to_data_field_name(field_B), trim)
+
+    @staticmethod
+    def compare_lte_term(data_type_A: DataTypeIdentifier, field_A: FieldIdentifier,
+                         data_type_B: DataTypeIdentifier, field_B: FieldIdentifier,
+                         *, trim: bool = False) -> FieldCompareReportTerm:
+        """
+        Create a field comparison report term for comparing field values between data types with a less than or equal
+        to operation.
+
+        :param data_type_A: The data type for the left side of this term.
+        :param field_A: The data field for the left side of this term.
+        :param data_type_B: The data type for the right side of this term.
+        :param field_B: The data field for the right side of this term.
+        :param trim: Whether the field values should be trimmed of trailing and leading whitespace for comparing.
+        :return: A field comparison report term for "data_type_A.field_A <= data_type_B.field_B".
+        """
+        return FieldCompareReportTerm(AliasUtil.to_data_type_name(data_type_A), AliasUtil.to_data_field_name(field_A), LTE,
+                                      AliasUtil.to_data_type_name(data_type_B), AliasUtil.to_data_field_name(field_B), trim)
+
+    @staticmethod
+    def compare_gt_term(data_type_A: DataTypeIdentifier, field_A: FieldIdentifier,
+                        data_type_B: DataTypeIdentifier, field_B: FieldIdentifier,
+                        *, trim: bool = False) -> FieldCompareReportTerm:
+        """
+        Create a field comparison report term for comparing field values between data types with a greater than
+        operation.
+
+        :param data_type_A: The data type for the left side of this term.
+        :param field_A: The data field for the left side of this term.
+        :param data_type_B: The data type for the right side of this term.
+        :param field_B: The data field for the right side of this term.
+        :param trim: Whether the field values should be trimmed of trailing and leading whitespace for comparing.
+        :return: A field comparison report term for "data_type_A.field_A > data_type_B.field_B".
+        """
+        return FieldCompareReportTerm(AliasUtil.to_data_type_name(data_type_A), AliasUtil.to_data_field_name(field_A), GT,
+                                      AliasUtil.to_data_type_name(data_type_B), AliasUtil.to_data_field_name(field_B), trim)
+
+    @staticmethod
+    def compare_gte_term(data_type_A: DataTypeIdentifier, field_A: FieldIdentifier,
+                         data_type_B: DataTypeIdentifier, field_B: FieldIdentifier,
+                         *, trim: bool = False) -> FieldCompareReportTerm:
+        """
+        Create a field comparison report term for comparing field values between data types with a greater than or
+        equal to operation.
+
+        :param data_type_A: The data type for the left side of this term.
+        :param field_A: The data field for the left side of this term.
+        :param data_type_B: The data type for the right side of this term.
+        :param field_B: The data field for the right side of this term.
+        :param trim: Whether the field values should be trimmed of trailing and leading whitespace for comparing.
+        :return: A field comparison report term for "data_type_A.field_A >= data_type_B.field_B".
+        """
+        return FieldCompareReportTerm(AliasUtil.to_data_type_name(data_type_A), AliasUtil.to_data_field_name(field_A), GTE,
+                                      AliasUtil.to_data_type_name(data_type_B), AliasUtil.to_data_field_name(field_B), trim)
+
+    @staticmethod
+    def or_terms(a: AbstractReportTerm, b: AbstractReportTerm, *, is_negated: bool = False) -> CompositeReportTerm:
+        """
+        Combine two report terms with an OR operation.
+
+        :param a: The first term in the operation.
+        :param b: The second term in the operation.
+        :param is_negated: Whether the returned term should be negated (i.e. turn this into a nor operation).
+        :return: A composite report term for "A or B".
+        """
+        return CompositeReportTerm(a, OR, b, is_negated)
+
+    @staticmethod
+    def and_terms(a: AbstractReportTerm, b: AbstractReportTerm, *, is_negated: bool = False) -> CompositeReportTerm:
+        """
+        Combine two report terms with an AND operation.
+
+        :param a: The first term in the operation.
+        :param b: The second term in the operation.
+        :param is_negated: Whether the returned term should be negated (i.e. turn this into a nand operation).
+        :return: A composite report term for "A and B".
+        """
+        return CompositeReportTerm(a, AND, b, is_negated)
+
+    @staticmethod
+    def xor_terms(a: AbstractReportTerm, b: AbstractReportTerm, *, is_negated: bool = False) -> CompositeReportTerm:
+        """
+        Combine two report terms with a XOR operation. Note that a XOR operation doesn't actually exist for custom
+        reports. This instead constructs a term that is "(A or B) and !(A and B)", which is equivalent to a XOR
+        operation.
+
+        :param a: The first term in the operation.
+        :param b: The second term in the operation.
+        :param is_negated: Whether the returned term should be negated (i.e. turn this into an xnor operation).
+        :return: A composite report term for "A xor B".
+        """
+        return TermBuilder.and_terms(TermBuilder.or_terms(a, b),
+                                     TermBuilder.and_terms(a, b, is_negated=True),
+                                     is_negated=is_negated)
+
+    @staticmethod
+    def to_term_val(value: TermValue) -> str:
+        """
+        Convert the given value to be used in a custom report term to a string. Term values may be strings, integers,
+        floats, booleans, or lists of values.
+
+        :param value: A value to be used in a custom report term.
+        :return: The provided value formatted as a string that can be used
+        """
+        # If the given value is already a string, then nothing needs to be done with it.
+        if not isinstance(value, str):
+            # If the given value is None, then use an empty string for the search instead.
+            if value is None:
+                value = ""
+            # If the given value is an iterable object, then the return value is the contents of that iterable
+            # in a comma separated list surrounded by curly braces.
+            elif isinstance(value, Iterable):
+                # When converting a list of values to a string, values in the list which are already strings should be
+                # put in quotation marks so that strings that contain commas do not get split up. All other value
+                # types can be simply converted to a string, though.
+                def convert_list_value(val: TermValue) -> str:
+                    return f"'{val}'" if isinstance(val, str) else str(val)
+                value = "{" + ",".join([convert_list_value(x) for x in value]) + "}"
+            else:
+                # Otherwise, the value is simply cast to a string.
+                value = str(value)
+        return value