Skip to content

ChemSynonym

pycomptox.chemical.chemsynonym.ChemSynonym

Bases: CachedAPIClient

Client for accessing chemical synonym data from EPA CompTox Dashboard.

This class provides methods for retrieving chemical synonyms and alternative identifiers including: - Beilstein registry numbers - Alternate CAS Registry Numbers - Valid and good quality synonyms - Other synonym categories - Flat list or structured views

Parameters:

Name Type Description Default
api_key str

CompTox API key. If not provided, will attempt to load from saved configuration or COMPTOX_API_KEY environment variable.

 None
base_url str

Base URL for the CompTox API. Defaults to EPA's endpoint.

 'https://comptox.epa.gov/ctx-api/'
time_delay_between_calls float, **kwargs

Delay in seconds between API calls for rate limiting. Default is 0.0 (no delay).

 0.0
Example

from pycomptox import ChemSynonym synonym_client = ChemSynonym()

Get synonyms for Bisphenol A

synonyms = synonym_client.get_synonyms_by_dtxsid("DTXSID7020182") print(f"Valid names: {synonyms['valid']}")

Get flat list of synonyms

flat_synonyms = synonym_client.get_synonyms_by_dtxsid( ... "DTXSID7020182", ... projection="ccd-synonyms" ... )

Source code in src/pycomptox/chemical/chemsynonym.py 
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
class ChemSynonym(CachedAPIClient):
    """
    Client for accessing chemical synonym data from EPA CompTox Dashboard.

    This class provides methods for retrieving chemical synonyms and alternative
    identifiers including:
    - Beilstein registry numbers
    - Alternate CAS Registry Numbers
    - Valid and good quality synonyms
    - Other synonym categories
    - Flat list or structured views

    Args:
        api_key (str, optional): CompTox API key. If not provided, will attempt
            to load from saved configuration or COMPTOX_API_KEY environment variable.
        base_url (str): Base URL for the CompTox API. Defaults to EPA's endpoint.
        time_delay_between_calls (float, **kwargs): Delay in seconds between API calls for
            rate limiting. Default is 0.0 (no delay).

    Example:
        >>> from pycomptox import ChemSynonym
        >>> synonym_client = ChemSynonym()
        >>> 
        >>> # Get synonyms for Bisphenol A
        >>> synonyms = synonym_client.get_synonyms_by_dtxsid("DTXSID7020182")
        >>> print(f"Valid names: {synonyms['valid']}")
        >>> 
        >>> # Get flat list of synonyms
        >>> flat_synonyms = synonym_client.get_synonyms_by_dtxsid(
        ...     "DTXSID7020182", 
        ...     projection="ccd-synonyms"
        ... )
    """

    def __init__(
        self,
        api_key: Optional[str] = None,
        base_url: str = "https://comptox.epa.gov/ctx-api/",
        time_delay_between_calls: float = 0.0
    , **kwargs):
        """
        Initialize the ChemSynonym client.

        Args:
            api_key: CompTox API key (optional, will be loaded from config if not provided)
            base_url: Base URL for the CompTox API
            time_delay_between_calls: Delay between API calls in seconds

        Raises:
            ValueError: If no API key is provided or found in configuration
        """
        super().__init__(
            api_key=api_key,
            base_url=base_url,
            time_delay_between_calls=time_delay_between_calls,
            **kwargs
        )

    def get_synonyms_by_dtxsid(
        self,
        dtxsid: str,
        projection: Optional[str] = None
    , use_cache: Optional[bool] = None) -> Dict[str, Any]:
        """
        Get synonyms for a chemical by DTXSID with optional projection.

        Fetches synonyms based on the specified projection. Available projections:
        - `ccd-synonyms`: Returns a flat list of synonym objects with quality ratings
        - `chemical-synonym-all` (default): Returns structured view with categorized synonyms

        GET /chemical/synonym/search/by-dtxsid/{dtxsid}

        Args:
            dtxsid (str): DSSTox Substance Identifier (e.g., "DTXSID7020182")
            projection (str, optional): Projection type ("ccd-synonyms" or None for default)

        Returns:
            Dict[str, Any]: Synonym data. Structure depends on projection:

            Default projection returns:
                - `beilstein` (List[str]): Beilstein registry numbers
                - `alternateCasrn` (List[str]): Alternate CAS Registry Numbers
                - `dtxsid` (str): DSSTox Substance Identifier
                - `pcCode` (str): PC code
                - `deletedCasrn` (List[str]): Deleted CAS Registry Numbers
                - `other` (List[str]): Other synonyms
                - `valid` (List[str]): Valid synonyms
                - `good` (List[str]): Good quality synonyms

            ccd-synonyms projection returns a list of:
                - `synonym` (str): Synonym text
                - `quality` (str): Quality rating

        Raises:
            ValueError: If DTXSID is not found or request fails
            PermissionError: If API key is invalid
            RuntimeError: For other API errors

        Example:
            >>> synonym_client = ChemSynonym()
            >>> 
            >>> # Get structured synonyms
            >>> data = synonym_client.get_synonyms_by_dtxsid("DTXSID7020182")
            >>> print(f"Valid names: {data.get('valid', [])}")
            >>> print(f"Alternate CAS: {data.get('alternateCasrn', [])}")
            >>> 
            >>> # Get flat list with quality ratings
            >>> flat_data = synonym_client.get_synonyms_by_dtxsid(
            ...     "DTXSID7020182",
            ...     projection="ccd-synonyms"
            ... )
            >>> for item in flat_data[:5]:
            ...     print(f"{item.get('synonym')}: {item.get('quality')}")
        """
        params = {}
        if projection:
            params["projection"] = projection

        endpoint = f"chemical/synonym/search/by-dtxsid/{dtxsid}"
        return self._make_cached_request(endpoint, params=params, use_cache=use_cache)

    def get_synonyms_by_dtxsid_batch(
        self,
        dtxsid_list: List[str]
    , use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
        """
        Get synonyms for multiple chemicals in a single batch request.

        Batch retrieval of synonym data for up to 1000 chemicals. More efficient
        than making individual requests when querying multiple chemicals.

        POST /chemical/synonym/search/by-dtxsid/

        Args:
            dtxsid_list (List[str]): List of DSSTox Substance Identifiers
                (maximum 1000 DTXSIDs)

        Returns:
            List[Dict[str, Any]]: List of synonym data dictionaries, each containing:
                - `beilstein` (List[str]): Beilstein registry numbers
                - `alternateCasrn` (List[str]): Alternate CAS Registry Numbers
                - `dtxsid` (str): DSSTox Substance Identifier
                - `pcCode` (str): PC code
                - `deletedCasrn` (List[str]): Deleted CAS Registry Numbers
                - `other` (List[str]): Other synonyms
                - `valid` (List[str]): Valid synonyms
                - `good` (List[str]): Good quality synonyms

        Raises:
            ValueError: If more than 1000 DTXSIDs provided or request fails
            PermissionError: If API key is invalid
            RuntimeError: For other API errors

        Example:
            >>> synonym_client = ChemSynonym()
            >>> dtxsids = ["DTXSID7020182", "DTXSID2021315", "DTXSID5020001"]
            >>> results = synonym_client.get_synonyms_by_dtxsid_batch(dtxsids)
            >>> 
            >>> for data in results:
            ...     dtxsid = data.get("dtxsid", "")
            ...     valid_names = data.get("valid", [])
            ...     print(f"{dtxsid}: {len(valid_names)} valid synonyms")
            >>> 
            >>> # Find chemicals with alternate CAS numbers
            >>> for data in results:
            ...     alt_cas = data.get("alternateCasrn", [])
            ...     if alt_cas:
            ...         print(f"{data.get('dtxsid')}: {alt_cas}")
        """
        if len(dtxsid_list) > 1000:
            raise ValueError(f"Maximum 1000 DTXSIDs allowed, got {len(dtxsid_list)}")

        endpoint = "chemical/synonym/search/by-dtxsid/"
        return self._make_cached_request(endpoint, method='POST', json=dtxsid_list, use_cache=use_cache)

__init__(api_key=None, base_url='https://comptox.epa.gov/ctx-api/', time_delay_between_calls=0.0, **kwargs)

Initialize the ChemSynonym client.

Parameters:

Name Type Description Default
api_key Optional[str]

CompTox API key (optional, will be loaded from config if not provided)

 None
base_url str

Base URL for the CompTox API

 'https://comptox.epa.gov/ctx-api/'
time_delay_between_calls float

Delay between API calls in seconds

 0.0

Raises:

Type Description
ValueError

If no API key is provided or found in configuration
Source code in src/pycomptox/chemical/chemsynonym.py 
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
def __init__(
    self,
    api_key: Optional[str] = None,
    base_url: str = "https://comptox.epa.gov/ctx-api/",
    time_delay_between_calls: float = 0.0
, **kwargs):
    """
    Initialize the ChemSynonym client.

    Args:
        api_key: CompTox API key (optional, will be loaded from config if not provided)
        base_url: Base URL for the CompTox API
        time_delay_between_calls: Delay between API calls in seconds

    Raises:
        ValueError: If no API key is provided or found in configuration
    """
    super().__init__(
        api_key=api_key,
        base_url=base_url,
        time_delay_between_calls=time_delay_between_calls,
        **kwargs
    )

get_synonyms_by_dtxsid(dtxsid, projection=None, use_cache=None)

Get synonyms for a chemical by DTXSID with optional projection.

Fetches synonyms based on the specified projection. Available projections: - ccd-synonyms: Returns a flat list of synonym objects with quality ratings - chemical-synonym-all (default): Returns structured view with categorized synonyms

GET /chemical/synonym/search/by-dtxsid/{dtxsid}

Parameters:

Name Type Description Default
dtxsid str

DSSTox Substance Identifier (e.g., "DTXSID7020182")

 required
projection str

Projection type ("ccd-synonyms" or None for default)

 None

Returns:

Type Description
Dict[str, Any]

Dict[str, Any]: Synonym data. Structure depends on projection:
Dict[str, Any]

Default projection returns: - beilstein (List[str]): Beilstein registry numbers - alternateCasrn (List[str]): Alternate CAS Registry Numbers - dtxsid (str): DSSTox Substance Identifier - pcCode (str): PC code - deletedCasrn (List[str]): Deleted CAS Registry Numbers - other (List[str]): Other synonyms - valid (List[str]): Valid synonyms - good (List[str]): Good quality synonyms
Dict[str, Any]

ccd-synonyms projection returns a list of: - synonym (str): Synonym text - quality (str): Quality rating

Raises:

Type Description
ValueError

If DTXSID is not found or request fails
PermissionError

If API key is invalid
RuntimeError

For other API errors
Example

synonym_client = ChemSynonym()

Get structured synonyms

data = synonym_client.get_synonyms_by_dtxsid("DTXSID7020182") print(f"Valid names: {data.get('valid', [])}") print(f"Alternate CAS: {data.get('alternateCasrn', [])}")

Get flat list with quality ratings

flat_data = synonym_client.get_synonyms_by_dtxsid( ... "DTXSID7020182", ... projection="ccd-synonyms" ... ) for item in flat_data[:5]: ... print(f"{item.get('synonym')}: {item.get('quality')}")

Source code in src/pycomptox/chemical/chemsynonym.py 
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
def get_synonyms_by_dtxsid(
    self,
    dtxsid: str,
    projection: Optional[str] = None
, use_cache: Optional[bool] = None) -> Dict[str, Any]:
    """
    Get synonyms for a chemical by DTXSID with optional projection.

    Fetches synonyms based on the specified projection. Available projections:
    - `ccd-synonyms`: Returns a flat list of synonym objects with quality ratings
    - `chemical-synonym-all` (default): Returns structured view with categorized synonyms

    GET /chemical/synonym/search/by-dtxsid/{dtxsid}

    Args:
        dtxsid (str): DSSTox Substance Identifier (e.g., "DTXSID7020182")
        projection (str, optional): Projection type ("ccd-synonyms" or None for default)

    Returns:
        Dict[str, Any]: Synonym data. Structure depends on projection:

        Default projection returns:
            - `beilstein` (List[str]): Beilstein registry numbers
            - `alternateCasrn` (List[str]): Alternate CAS Registry Numbers
            - `dtxsid` (str): DSSTox Substance Identifier
            - `pcCode` (str): PC code
            - `deletedCasrn` (List[str]): Deleted CAS Registry Numbers
            - `other` (List[str]): Other synonyms
            - `valid` (List[str]): Valid synonyms
            - `good` (List[str]): Good quality synonyms

        ccd-synonyms projection returns a list of:
            - `synonym` (str): Synonym text
            - `quality` (str): Quality rating

    Raises:
        ValueError: If DTXSID is not found or request fails
        PermissionError: If API key is invalid
        RuntimeError: For other API errors

    Example:
        >>> synonym_client = ChemSynonym()
        >>> 
        >>> # Get structured synonyms
        >>> data = synonym_client.get_synonyms_by_dtxsid("DTXSID7020182")
        >>> print(f"Valid names: {data.get('valid', [])}")
        >>> print(f"Alternate CAS: {data.get('alternateCasrn', [])}")
        >>> 
        >>> # Get flat list with quality ratings
        >>> flat_data = synonym_client.get_synonyms_by_dtxsid(
        ...     "DTXSID7020182",
        ...     projection="ccd-synonyms"
        ... )
        >>> for item in flat_data[:5]:
        ...     print(f"{item.get('synonym')}: {item.get('quality')}")
    """
    params = {}
    if projection:
        params["projection"] = projection

    endpoint = f"chemical/synonym/search/by-dtxsid/{dtxsid}"
    return self._make_cached_request(endpoint, params=params, use_cache=use_cache)

get_synonyms_by_dtxsid_batch(dtxsid_list, use_cache=None)

Get synonyms for multiple chemicals in a single batch request.

Batch retrieval of synonym data for up to 1000 chemicals. More efficient than making individual requests when querying multiple chemicals.

POST /chemical/synonym/search/by-dtxsid/

Parameters:

Name Type Description Default
dtxsid_list List[str]

List of DSSTox Substance Identifiers (maximum 1000 DTXSIDs)

 required

Returns:

Type Description
List[Dict[str, Any]]

List[Dict[str, Any]]: List of synonym data dictionaries, each containing: - beilstein (List[str]): Beilstein registry numbers - alternateCasrn (List[str]): Alternate CAS Registry Numbers - dtxsid (str): DSSTox Substance Identifier - pcCode (str): PC code - deletedCasrn (List[str]): Deleted CAS Registry Numbers - other (List[str]): Other synonyms - valid (List[str]): Valid synonyms - good (List[str]): Good quality synonyms

Raises:

Type Description
ValueError

If more than 1000 DTXSIDs provided or request fails
PermissionError

If API key is invalid
RuntimeError

For other API errors
Example

synonym_client = ChemSynonym() dtxsids = ["DTXSID7020182", "DTXSID2021315", "DTXSID5020001"] results = synonym_client.get_synonyms_by_dtxsid_batch(dtxsids)

for data in results: ... dtxsid = data.get("dtxsid", "") ... valid_names = data.get("valid", []) ... print(f"{dtxsid}: {len(valid_names)} valid synonyms")

Find chemicals with alternate CAS numbers

for data in results: ... alt_cas = data.get("alternateCasrn", []) ... if alt_cas: ... print(f"{data.get('dtxsid')}: {alt_cas}")

Source code in src/pycomptox/chemical/chemsynonym.py 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
def get_synonyms_by_dtxsid_batch(
    self,
    dtxsid_list: List[str]
, use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
    """
    Get synonyms for multiple chemicals in a single batch request.

    Batch retrieval of synonym data for up to 1000 chemicals. More efficient
    than making individual requests when querying multiple chemicals.

    POST /chemical/synonym/search/by-dtxsid/

    Args:
        dtxsid_list (List[str]): List of DSSTox Substance Identifiers
            (maximum 1000 DTXSIDs)

    Returns:
        List[Dict[str, Any]]: List of synonym data dictionaries, each containing:
            - `beilstein` (List[str]): Beilstein registry numbers
            - `alternateCasrn` (List[str]): Alternate CAS Registry Numbers
            - `dtxsid` (str): DSSTox Substance Identifier
            - `pcCode` (str): PC code
            - `deletedCasrn` (List[str]): Deleted CAS Registry Numbers
            - `other` (List[str]): Other synonyms
            - `valid` (List[str]): Valid synonyms
            - `good` (List[str]): Good quality synonyms

    Raises:
        ValueError: If more than 1000 DTXSIDs provided or request fails
        PermissionError: If API key is invalid
        RuntimeError: For other API errors

    Example:
        >>> synonym_client = ChemSynonym()
        >>> dtxsids = ["DTXSID7020182", "DTXSID2021315", "DTXSID5020001"]
        >>> results = synonym_client.get_synonyms_by_dtxsid_batch(dtxsids)
        >>> 
        >>> for data in results:
        ...     dtxsid = data.get("dtxsid", "")
        ...     valid_names = data.get("valid", [])
        ...     print(f"{dtxsid}: {len(valid_names)} valid synonyms")
        >>> 
        >>> # Find chemicals with alternate CAS numbers
        >>> for data in results:
        ...     alt_cas = data.get("alternateCasrn", [])
        ...     if alt_cas:
        ...         print(f"{data.get('dtxsid')}: {alt_cas}")
    """
    if len(dtxsid_list) > 1000:
        raise ValueError(f"Maximum 1000 DTXSIDs allowed, got {len(dtxsid_list)}")

    endpoint = "chemical/synonym/search/by-dtxsid/"
    return self._make_cached_request(endpoint, method='POST', json=dtxsid_list, use_cache=use_cache)