Skip to content

ToxRefDBBatch API Reference

pycomptox.hazard.toxrefdbbatch.ToxRefDBBatch

Bases: CachedAPIClient

Client for batch access to ToxRefDB data from EPA CompTox Dashboard.

ToxRefDB (Toxicity Reference Database) batch endpoint provides efficient retrieval of all extracted dose-treatment group-effect information as well as doses not eliciting effects for multiple chemicals in a single request.

This includes: - All dose-response data from ToxRefDB studies - Treatment group information - Effect observations at various doses - Doses not eliciting effects (NEL) - Effect level classifications (LEL, LOAEL)

Data from ToxRefDB is also summarized in ToxValDB, including inferred NEL (No Effect Level) and NOAEL (No Observed Adverse Effect Level) based on reported LEL (Lowest Effect Level) and LOAEL (Lowest Observed Adverse Effect Level).

This batch endpoint is more efficient than making individual requests when querying multiple chemicals for ToxRefDB data.

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

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

 0.0
use_cache bool

Whether to use caching by default. Default is True.

 required
Example

from pycomptox.hazard import ToxRefDBBatch toxref_batch = ToxRefDBBatch()

Get ToxRefDB data for multiple chemicals

dtxsids = ["DTXSID1037806", "DTXSID0021125"] data = toxref_batch.get_data_by_dtxsid_batch(dtxsids) if data: ... print(f"Found {len(data)} ToxRefDB records")

Source code in src/pycomptox/hazard/toxrefdbbatch.py 
 18
 19
 20
 21
 22
 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
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
class ToxRefDBBatch(CachedAPIClient):
    """
    Client for batch access to ToxRefDB data from EPA CompTox Dashboard.

    ToxRefDB (Toxicity Reference Database) batch endpoint provides efficient 
    retrieval of all extracted dose-treatment group-effect information as well as 
    doses not eliciting effects for multiple chemicals in a single request.

    This includes:
    - All dose-response data from ToxRefDB studies
    - Treatment group information
    - Effect observations at various doses
    - Doses not eliciting effects (NEL)
    - Effect level classifications (LEL, LOAEL)

    Data from ToxRefDB is also summarized in ToxValDB, including inferred NEL 
    (No Effect Level) and NOAEL (No Observed Adverse Effect Level) based on 
    reported LEL (Lowest Effect Level) and LOAEL (Lowest Observed Adverse Effect Level).

    This batch endpoint is more efficient than making individual requests when 
    querying multiple chemicals for ToxRefDB data.

    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): Delay in seconds between API calls for
            rate limiting. Default is 0.0 (no delay).
        use_cache (bool): Whether to use caching by default. Default is True.

    Example:
        >>> from pycomptox.hazard import ToxRefDBBatch
        >>> toxref_batch = ToxRefDBBatch()
        >>> 
        >>> # Get ToxRefDB data for multiple chemicals
        >>> dtxsids = ["DTXSID1037806", "DTXSID0021125"]
        >>> data = toxref_batch.get_data_by_dtxsid_batch(dtxsids)
        >>> if data:
        ...     print(f"Found {len(data)} ToxRefDB records")
    """

    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: Any
    ):
        """
        Initialize the ToxRefDBBatch 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
            kwargs: Additional arguments for CachedAPIClient (cache_manager, use_cache)

        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_data_by_dtxsid_batch(
        self, 
        dtxsids: List[str], 
        use_cache: Optional[bool] = None
    ) -> List[Dict[str, Any]]:
        """
        Get ToxRefDB data for multiple chemicals in a single batch request.

        Exports all extracted dose-treatment group-effect information as well as 
        doses not eliciting effects from ToxRefDB for the chemicals listed in the 
        input. This provides comprehensive dose-response data for up to 200 chemicals 
        in a single efficient request.

        Args:
            dtxsids: List of DSSTox Substance Identifiers (max 200)
            use_cache: Whether to use cache for this request. If None, uses
                the instance default setting.

        Returns:
            List of dictionaries containing ToxRefDB data for all requested 
            chemicals. Each record includes fields such as:
                - dtxsid (str): Chemical identifier
                - studyId (int): Study identifier
                - studyType (str): Type of study
                - treatmentGroup (str): Treatment group identifier
                - dose (float): Dose administered
                - doseUnits (str): Units of dose
                - effect (str): Observed effect
                - effectLevel (str): Effect level classification (LEL, LOAEL, NEL, NOAEL)
                - organ (str): Target organ or system
                - species (str): Test species
                - sex (str): Sex of test animals
                - route (str): Exposure route
                - duration (str): Study duration
                - effectType (str): Type of effect
                - severity (str): Severity of effect
                - notes (str): Additional notes
                - Notes: Exact fields vary by study and effect

        Raises:
            ValueError: If dtxsids list is empty or contains more than 200 entries
            PermissionError: If API key is invalid
            RuntimeError: For other API errors

        Example:
            >>> from pycomptox.hazard import ToxRefDBBatch
            >>> toxref_batch = ToxRefDBBatch()
            >>> 
            >>> # Get ToxRefDB data for multiple chemicals
            >>> dtxsids = ["DTXSID1037806", "DTXSID0021125", "DTXSID7020182"]
            >>> batch_data = toxref_batch.get_data_by_dtxsid_batch(dtxsids)
            >>> 
            >>> if batch_data:
            ...     print(f"Retrieved {len(batch_data)} ToxRefDB records")
            ...     
            ...     # Group by chemical
            ...     by_chemical = {}
            ...     for record in batch_data:
            ...         dtxsid = record['dtxsid']
            ...         if dtxsid not in by_chemical:
            ...             by_chemical[dtxsid] = []
            ...         by_chemical[dtxsid].append(record)
            ...     
            ...     # Display summary for each chemical
            ...     for dtxsid, records in by_chemical.items():
            ...         print(f"\n{dtxsid}: {len(records)} record(s)")
            ...         
            ...         # Get unique study types
            ...         study_types = set(r.get('studyType') for r in records if r.get('studyType'))
            ...         print(f"  Study types: {', '.join(sorted(study_types))}")
            ...         
            ...         # Count effect levels
            ...         effect_levels = {}
            ...         for rec in records:
            ...             level = rec.get('effectLevel', 'Unknown')
            ...             effect_levels[level] = effect_levels.get(level, 0) + 1
            ...         
            ...         print(f"  Effect levels:")
            ...         for level, count in sorted(effect_levels.items()):
            ...             print(f"    {level}: {count}")
            ...         
            ...         # Find LOAELs
            ...         loaels = [r for r in records if r.get('effectLevel') == 'LOAEL']
            ...         if loaels:
            ...             print(f"  LOAELs found: {len(loaels)}")
            ...             # Show lowest LOAEL
            ...             numeric_loaels = [r for r in loaels if r.get('dose')]
            ...             if numeric_loaels:
            ...                 lowest = min(numeric_loaels, key=lambda x: x['dose'])
            ...                 print(f"    Lowest: {lowest['dose']} {lowest.get('doseUnits', '')} - {lowest.get('effect', 'N/A')}")
            >>> 
            >>> # Analyze effects across chemicals
            >>> if batch_data:
            ...     # Get all unique organs affected
            ...     organs = set(r.get('organ') for r in batch_data if r.get('organ'))
            ...     print(f"\nUnique target organs across all chemicals: {len(organs)}")
            ...     
            ...     # Count records by study type
            ...     by_study_type = {}
            ...     for rec in batch_data:
            ...         st = rec.get('studyType', 'Unknown')
            ...         by_study_type[st] = by_study_type.get(st, 0) + 1
            ...     
            ...     print(f"\nRecords by study type:")
            ...     for st, count in sorted(by_study_type.items(), key=lambda x: x[1], reverse=True):
            ...         print(f"  {st}: {count}")

        Note:
            - Maximum 200 DTXSIDs per request
            - This endpoint returns comprehensive dose-response data
            - Results can be very large for chemicals with extensive testing
            - Batch requests are much more efficient than individual queries
            - Data includes both adverse effects and doses not eliciting effects
            - Effect levels help identify critical doses for risk assessment
            - Not all chemicals have ToxRefDB data
            - ToxRefDB focuses on standardized guideline studies
        """
        if not dtxsids:
            raise ValueError("dtxsids list cannot be empty")

        if len(dtxsids) > 200:
            raise ValueError(f"Maximum 200 DTXSIDs allowed, got {len(dtxsids)}")

        endpoint = "hazard/toxref/search/by-dtxsid/"
        return self._make_cached_request(
            endpoint, 
            json=dtxsids, 
            method='POST', 
            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 ToxRefDBBatch 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
kwargs Any

Additional arguments for CachedAPIClient (cache_manager, use_cache)

 {}

Raises:

Type Description
ValueError

If no API key is provided or found in configuration
Source code in src/pycomptox/hazard/toxrefdbbatch.py 
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
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: Any
):
    """
    Initialize the ToxRefDBBatch 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
        kwargs: Additional arguments for CachedAPIClient (cache_manager, use_cache)

    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_data_by_dtxsid_batch(dtxsids, use_cache=None) 

    Get ToxRefDB data for multiple chemicals in a single batch request.

    Exports all extracted dose-treatment group-effect information as well as 
    doses not eliciting effects from ToxRefDB for the chemicals listed in the 
    input. This provides comprehensive dose-response data for up to 200 chemicals 
    in a single efficient request.

    Args:
        dtxsids: List of DSSTox Substance Identifiers (max 200)
        use_cache: Whether to use cache for this request. If None, uses
            the instance default setting.

    Returns:
        List of dictionaries containing ToxRefDB data for all requested 
        chemicals. Each record includes fields such as:
            - dtxsid (str): Chemical identifier
            - studyId (int): Study identifier
            - studyType (str): Type of study
            - treatmentGroup (str): Treatment group identifier
            - dose (float): Dose administered
            - doseUnits (str): Units of dose
            - effect (str): Observed effect
            - effectLevel (str): Effect level classification (LEL, LOAEL, NEL, NOAEL)
            - organ (str): Target organ or system
            - species (str): Test species
            - sex (str): Sex of test animals
            - route (str): Exposure route
            - duration (str): Study duration
            - effectType (str): Type of effect
            - severity (str): Severity of effect
            - notes (str): Additional notes
            - Notes: Exact fields vary by study and effect

    Raises:
        ValueError: If dtxsids list is empty or contains more than 200 entries
        PermissionError: If API key is invalid
        RuntimeError: For other API errors

    Example:
        >>> from pycomptox.hazard import ToxRefDBBatch
        >>> toxref_batch = ToxRefDBBatch()
        >>> 
        >>> # Get ToxRefDB data for multiple chemicals
        >>> dtxsids = ["DTXSID1037806", "DTXSID0021125", "DTXSID7020182"]
        >>> batch_data = toxref_batch.get_data_by_dtxsid_batch(dtxsids)
        >>> 
        >>> if batch_data:
        ...     print(f"Retrieved {len(batch_data)} ToxRefDB records")
        ...     
        ...     # Group by chemical
        ...     by_chemical = {}
        ...     for record in batch_data:
        ...         dtxsid = record['dtxsid']
        ...         if dtxsid not in by_chemical:
        ...             by_chemical[dtxsid] = []
        ...         by_chemical[dtxsid].append(record)
        ...     
        ...     # Display summary for each chemical
        ...     for dtxsid, records in by_chemical.items():
        ...         print(f"

{dtxsid}: {len(records)} record(s)") ...
... # Get unique study types ... study_types = set(r.get('studyType') for r in records if r.get('studyType')) ... print(f" Study types: {', '.join(sorted(study_types))}") ...
... # Count effect levels ... effect_levels = {} ... for rec in records: ... level = rec.get('effectLevel', 'Unknown') ... effect_levels[level] = effect_levels.get(level, 0) + 1 ...
... print(f" Effect levels:") ... for level, count in sorted(effect_levels.items()): ... print(f" {level}: {count}") ...
... # Find LOAELs ... loaels = [r for r in records if r.get('effectLevel') == 'LOAEL'] ... if loaels: ... print(f" LOAELs found: {len(loaels)}") ... # Show lowest LOAEL ... numeric_loaels = [r for r in loaels if r.get('dose')] ... if numeric_loaels: ... lowest = min(numeric_loaels, key=lambda x: x['dose']) ... print(f" Lowest: {lowest['dose']} {lowest.get('doseUnits', '')} - {lowest.get('effect', 'N/A')}") >>> >>> # Analyze effects across chemicals >>> if batch_data: ... # Get all unique organs affected ... organs = set(r.get('organ') for r in batch_data if r.get('organ')) ... print(f" Unique target organs across all chemicals: {len(organs)}") ...
... # Count records by study type ... by_study_type = {} ... for rec in batch_data: ... st = rec.get('studyType', 'Unknown') ... by_study_type[st] = by_study_type.get(st, 0) + 1 ...
... print(f" Records by study type:") ... for st, count in sorted(by_study_type.items(), key=lambda x: x[1], reverse=True): ... print(f" {st}: {count}")

    Note:
        - Maximum 200 DTXSIDs per request
        - This endpoint returns comprehensive dose-response data
        - Results can be very large for chemicals with extensive testing
        - Batch requests are much more efficient than individual queries
        - Data includes both adverse effects and doses not eliciting effects
        - Effect levels help identify critical doses for risk assessment
        - Not all chemicals have ToxRefDB data
        - ToxRefDB focuses on standardized guideline studies
Source code in src/pycomptox/hazard/toxrefdbbatch.py 
 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
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
def get_data_by_dtxsid_batch(
    self, 
    dtxsids: List[str], 
    use_cache: Optional[bool] = None
) -> List[Dict[str, Any]]:
    """
    Get ToxRefDB data for multiple chemicals in a single batch request.

    Exports all extracted dose-treatment group-effect information as well as 
    doses not eliciting effects from ToxRefDB for the chemicals listed in the 
    input. This provides comprehensive dose-response data for up to 200 chemicals 
    in a single efficient request.

    Args:
        dtxsids: List of DSSTox Substance Identifiers (max 200)
        use_cache: Whether to use cache for this request. If None, uses
            the instance default setting.

    Returns:
        List of dictionaries containing ToxRefDB data for all requested 
        chemicals. Each record includes fields such as:
            - dtxsid (str): Chemical identifier
            - studyId (int): Study identifier
            - studyType (str): Type of study
            - treatmentGroup (str): Treatment group identifier
            - dose (float): Dose administered
            - doseUnits (str): Units of dose
            - effect (str): Observed effect
            - effectLevel (str): Effect level classification (LEL, LOAEL, NEL, NOAEL)
            - organ (str): Target organ or system
            - species (str): Test species
            - sex (str): Sex of test animals
            - route (str): Exposure route
            - duration (str): Study duration
            - effectType (str): Type of effect
            - severity (str): Severity of effect
            - notes (str): Additional notes
            - Notes: Exact fields vary by study and effect

    Raises:
        ValueError: If dtxsids list is empty or contains more than 200 entries
        PermissionError: If API key is invalid
        RuntimeError: For other API errors

    Example:
        >>> from pycomptox.hazard import ToxRefDBBatch
        >>> toxref_batch = ToxRefDBBatch()
        >>> 
        >>> # Get ToxRefDB data for multiple chemicals
        >>> dtxsids = ["DTXSID1037806", "DTXSID0021125", "DTXSID7020182"]
        >>> batch_data = toxref_batch.get_data_by_dtxsid_batch(dtxsids)
        >>> 
        >>> if batch_data:
        ...     print(f"Retrieved {len(batch_data)} ToxRefDB records")
        ...     
        ...     # Group by chemical
        ...     by_chemical = {}
        ...     for record in batch_data:
        ...         dtxsid = record['dtxsid']
        ...         if dtxsid not in by_chemical:
        ...             by_chemical[dtxsid] = []
        ...         by_chemical[dtxsid].append(record)
        ...     
        ...     # Display summary for each chemical
        ...     for dtxsid, records in by_chemical.items():
        ...         print(f"\n{dtxsid}: {len(records)} record(s)")
        ...         
        ...         # Get unique study types
        ...         study_types = set(r.get('studyType') for r in records if r.get('studyType'))
        ...         print(f"  Study types: {', '.join(sorted(study_types))}")
        ...         
        ...         # Count effect levels
        ...         effect_levels = {}
        ...         for rec in records:
        ...             level = rec.get('effectLevel', 'Unknown')
        ...             effect_levels[level] = effect_levels.get(level, 0) + 1
        ...         
        ...         print(f"  Effect levels:")
        ...         for level, count in sorted(effect_levels.items()):
        ...             print(f"    {level}: {count}")
        ...         
        ...         # Find LOAELs
        ...         loaels = [r for r in records if r.get('effectLevel') == 'LOAEL']
        ...         if loaels:
        ...             print(f"  LOAELs found: {len(loaels)}")
        ...             # Show lowest LOAEL
        ...             numeric_loaels = [r for r in loaels if r.get('dose')]
        ...             if numeric_loaels:
        ...                 lowest = min(numeric_loaels, key=lambda x: x['dose'])
        ...                 print(f"    Lowest: {lowest['dose']} {lowest.get('doseUnits', '')} - {lowest.get('effect', 'N/A')}")
        >>> 
        >>> # Analyze effects across chemicals
        >>> if batch_data:
        ...     # Get all unique organs affected
        ...     organs = set(r.get('organ') for r in batch_data if r.get('organ'))
        ...     print(f"\nUnique target organs across all chemicals: {len(organs)}")
        ...     
        ...     # Count records by study type
        ...     by_study_type = {}
        ...     for rec in batch_data:
        ...         st = rec.get('studyType', 'Unknown')
        ...         by_study_type[st] = by_study_type.get(st, 0) + 1
        ...     
        ...     print(f"\nRecords by study type:")
        ...     for st, count in sorted(by_study_type.items(), key=lambda x: x[1], reverse=True):
        ...         print(f"  {st}: {count}")

    Note:
        - Maximum 200 DTXSIDs per request
        - This endpoint returns comprehensive dose-response data
        - Results can be very large for chemicals with extensive testing
        - Batch requests are much more efficient than individual queries
        - Data includes both adverse effects and doses not eliciting effects
        - Effect levels help identify critical doses for risk assessment
        - Not all chemicals have ToxRefDB data
        - ToxRefDB focuses on standardized guideline studies
    """
    if not dtxsids:
        raise ValueError("dtxsids list cannot be empty")

    if len(dtxsids) > 200:
        raise ValueError(f"Maximum 200 DTXSIDs allowed, got {len(dtxsids)}")

    endpoint = "hazard/toxref/search/by-dtxsid/"
    return self._make_cached_request(
        endpoint, 
        json=dtxsids, 
        method='POST', 
        use_cache=use_cache
    )