Skip to content

ToxRefDBEffects API Reference

pycomptox.hazard.toxrefdbeffects.ToxRefDBEffects

Bases: CachedAPIClient

Client for accessing ToxRefDB effects data from EPA CompTox Dashboard.

ToxRefDB (Toxicity Reference Database) contains detailed toxicity study data extracted from standardized animal testing studies. This class provides access to dose-treatment group-effect information including:

  • Effect levels (LEL, LOAEL, NEL, NOAEL)
  • Study types (developmental, reproductive, chronic, etc.)
  • Treatment group information
  • Organ and system effects
  • Dose-response relationships

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).

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 ToxRefDBEffects toxref = ToxRefDBEffects()

Get effects data for a chemical

effects = toxref.get_data_by_dtxsid("DTXSID1037806") if effects: ... print(f"Found {len(effects)} effect records")

Source code in src/pycomptox/hazard/toxrefdbeffects.py 
 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
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
class ToxRefDBEffects(CachedAPIClient):
    """
    Client for accessing ToxRefDB effects data from EPA CompTox Dashboard.

    ToxRefDB (Toxicity Reference Database) contains detailed toxicity study data 
    extracted from standardized animal testing studies. This class provides access to 
    dose-treatment group-effect information including:

    - Effect levels (LEL, LOAEL, NEL, NOAEL)
    - Study types (developmental, reproductive, chronic, etc.)
    - Treatment group information
    - Organ and system effects
    - Dose-response relationships

    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).

    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 ToxRefDBEffects
        >>> toxref = ToxRefDBEffects()
        >>> 
        >>> # Get effects data for a chemical
        >>> effects = toxref.get_data_by_dtxsid("DTXSID1037806")
        >>> if effects:
        ...     print(f"Found {len(effects)} effect 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 ToxRefDBEffects 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_study_type(self, study_type: str, page_number: int = 1, 
                               use_cache: Optional[bool] = None) -> Dict[str, Any]:
        """
        Get ToxRefDB effects data by study type.

        Export of all extracted dose-treatment group-effect information from ToxRefDB 
        for a specific study type. This view is available as an enhanced data sheet 
        from batch search on the CompTox Chemicals Dashboard.

        Common study types include:
        - DEV: Developmental toxicity studies
        - REP: Reproductive toxicity studies
        - CHR: Chronic toxicity studies
        - SUB: Subchronic toxicity studies
        - DNT: Developmental neurotoxicity
        - MLT: Multigenerational reproductive toxicity

        Args:
            study_type: Study type code (e.g., 'DEV', 'REP', 'CHR')
            page_number: Optional page number for paginated results (default: 1)
            use_cache: Whether to use cache for this request. If None, uses
                the instance default setting.

        Returns:
            Dictionary containing paginated effects data with fields such as:
                - data (List[Dict]): List of effect records
                - page (int): Current page number
                - totalPages (int): Total number of pages
                - totalRecords (int): Total number of records

            Each effect record may include:
                - dtxsid (str): Chemical identifier
                - studyId (int): Study identifier
                - studyType (str): Type of study
                - effectLevel (str): Effect level (LEL, LOAEL, etc.)
                - dose (float): Dose value
                - doseUnits (str): Dose units
                - effect (str): Observed effect
                - organ (str): Target organ/system
                - species (str): Test species
                - Notes: Exact fields vary by study

        Raises:
            ValueError: If study_type is not a valid non-empty string
            PermissionError: If API key is invalid
            RuntimeError: For other API errors

        Example:
            >>> from pycomptox.hazard import ToxRefDBEffects
            >>> toxref = ToxRefDBEffects()
            >>> 
            >>> # Get developmental toxicity study data
            >>> dev_data = toxref.get_data_by_study_type("DEV")
            >>> 
            >>> if 'data' in dev_data:
            ...     effects = dev_data['data']
            ...     print(f"Found {len(effects)} developmental effects on page 1")
            ...     print(f"Total pages: {dev_data.get('totalPages', 'N/A')}")
            ...     
            ...     # Display first effect
            ...     if effects:
            ...         effect = effects[0]
            ...         print(f"Chemical: {effect.get('dtxsid')}")
            ...         print(f"Effect: {effect.get('effect')}")
            ...         print(f"Dose: {effect.get('dose')} {effect.get('doseUnits')}")
            >>> 
            >>> # Get next page
            >>> page2 = toxref.get_data_by_study_type("DEV", page_number=2)

        Note:
            - Results are paginated to manage large datasets
            - Study type codes are case-sensitive
            - Not all chemicals have data for all study types
        """
        if not study_type or not isinstance(study_type, str):
            raise ValueError("study_type must be a non-empty string")

        if not isinstance(page_number, int) or page_number < 1:
            raise ValueError("page_number must be a positive integer")

        endpoint = f"hazard/toxref/effects/search/by-study-type/{study_type}"
        params = {"page_number": page_number} if page_number > 1 else None

        return self._make_cached_request(
            endpoint, 
            params=params, 
            use_cache=use_cache
        )

    def get_data_by_study_id(self, study_id: int, 
                             use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
        """
        Get ToxRefDB effects data by study ID.

        Export of all extracted dose-treatment group-effect information from ToxRefDB 
        for a specific study. Each study ID represents a unique toxicity study with 
        detailed dose-response information.

        Args:
            study_id: ToxRefDB study identifier (positive integer)
            use_cache: Whether to use cache for this request. If None, uses
                the instance default setting.

        Returns:
            List of dictionaries containing effect records from the study, with fields:
                - 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
                - organ (str): Target organ/system
                - species (str): Test species
                - sex (str): Sex of test animals
                - duration (str): Study duration
                - Notes: Exact fields vary by study

        Raises:
            ValueError: If study_id is not a positive integer
            PermissionError: If API key is invalid
            RuntimeError: For other API errors

        Example:
            >>> from pycomptox.hazard import ToxRefDBEffects
            >>> toxref = ToxRefDBEffects()
            >>> 
            >>> # Get effects data for study ID 63
            >>> study_effects = toxref.get_data_by_study_id(63)
            >>> 
            >>> if study_effects:
            ...     print(f"Study contains {len(study_effects)} effect records")
            ...     
            ...     # Group by dose level
            ...     by_dose = {}
            ...     for effect in study_effects:
            ...         dose = effect.get('dose', 'Unknown')
            ...         if dose not in by_dose:
            ...             by_dose[dose] = []
            ...         by_dose[dose].append(effect)
            ...     
            ...     # Show effects by dose
            ...     for dose, effects in sorted(by_dose.items()):
            ...         print(f"\nDose {dose} {effects[0].get('doseUnits', '')}:")
            ...         for e in effects:
            ...             print(f"  - {e.get('effect')} in {e.get('organ')}")

        Note:
            - Each study typically contains multiple dose groups and effects
            - Study IDs are internal ToxRefDB identifiers
            - Effects are reported at different dose levels (control, low, mid, high)
        """
        if not isinstance(study_id, int) or study_id < 1:
            raise ValueError("study_id must be a positive integer")

        endpoint = f"hazard/toxref/effects/search/by-study-id/{study_id}"
        return self._make_cached_request(endpoint, use_cache=use_cache)

    def get_data_by_dtxsid(self, dtxsid: str, 
                           use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
        """
        Get ToxRefDB effects data by DTXSID.

        Export of all extracted dose-treatment group-effect information from ToxRefDB 
        for a specific chemical identified by its DSSTox Substance Identifier. Returns 
        all effects observed across all studies for the chemical.

        Args:
            dtxsid: DSSTox Substance Identifier (e.g., 'DTXSID1037806')
            use_cache: Whether to use cache for this request. If None, uses
                the instance default setting.

        Returns:
            List of dictionaries containing effect records with fields such as:
                - dtxsid (str): Chemical identifier
                - studyId (int): Study identifier
                - studyType (str): Type of study
                - treatmentGroup (str): Treatment group
                - dose (float): Dose value
                - doseUnits (str): Dose units
                - effect (str): Observed effect description
                - effectLevel (str): Effect level (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
                - Notes: Exact fields vary by study

        Raises:
            ValueError: If dtxsid is not a valid non-empty string
            PermissionError: If API key is invalid
            RuntimeError: For other API errors

        Example:
            >>> from pycomptox.hazard import ToxRefDBEffects
            >>> toxref = ToxRefDBEffects()
            >>> 
            >>> # Get all ToxRefDB effects for a chemical
            >>> effects = toxref.get_data_by_dtxsid("DTXSID1037806")
            >>> 
            >>> if effects:
            ...     print(f"Found {len(effects)} effect records")
            ...     
            ...     # Get unique study types
            ...     study_types = set(e.get('studyType') for e in effects if e.get('studyType'))
            ...     print(f"Study types: {', '.join(sorted(study_types))}")
            ...     
            ...     # Find lowest effect levels
            ...     loaels = [e for e in effects if e.get('effectLevel') == 'LOAEL']
            ...     if loaels:
            ...         print(f"\nFound {len(loaels)} LOAEL records")
            ...         for loael in loaels[:5]:  # Show first 5
            ...             print(f"  {loael.get('studyType')}: {loael.get('dose')} "
            ...                   f"{loael.get('doseUnits')} - {loael.get('effect')}")
            ...     
            ...     # Group by organ system
            ...     by_organ = {}
            ...     for effect in effects:
            ...         organ = effect.get('organ', 'Unknown')
            ...         by_organ[organ] = by_organ.get(organ, 0) + 1
            ...     
            ...     print(f"\nEffects by organ system:")
            ...     for organ, count in sorted(by_organ.items(), 
            ...                                key=lambda x: x[1], reverse=True)[:10]:
            ...         print(f"  {organ}: {count}")
            >>> else:
            ...     print("No ToxRefDB data available for this chemical")

        Note:
            - Not all chemicals have ToxRefDB data
            - ToxRefDB focuses on standardized guideline studies
            - Data includes both adverse and non-adverse effects
            - Effect levels help identify critical doses for risk assessment
        """
        if not dtxsid or not isinstance(dtxsid, str):
            raise ValueError("dtxsid must be a non-empty string")

        endpoint = f"hazard/toxref/effects/search/by-dtxsid/{dtxsid}"
        return self._make_cached_request(endpoint, 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 ToxRefDBEffects 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/toxrefdbeffects.py 
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
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 ToxRefDBEffects 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(dtxsid, use_cache=None) 

    Get ToxRefDB effects data by DTXSID.

    Export of all extracted dose-treatment group-effect information from ToxRefDB 
    for a specific chemical identified by its DSSTox Substance Identifier. Returns 
    all effects observed across all studies for the chemical.

    Args:
        dtxsid: DSSTox Substance Identifier (e.g., 'DTXSID1037806')
        use_cache: Whether to use cache for this request. If None, uses
            the instance default setting.

    Returns:
        List of dictionaries containing effect records with fields such as:
            - dtxsid (str): Chemical identifier
            - studyId (int): Study identifier
            - studyType (str): Type of study
            - treatmentGroup (str): Treatment group
            - dose (float): Dose value
            - doseUnits (str): Dose units
            - effect (str): Observed effect description
            - effectLevel (str): Effect level (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
            - Notes: Exact fields vary by study

    Raises:
        ValueError: If dtxsid is not a valid non-empty string
        PermissionError: If API key is invalid
        RuntimeError: For other API errors

    Example:
        >>> from pycomptox.hazard import ToxRefDBEffects
        >>> toxref = ToxRefDBEffects()
        >>> 
        >>> # Get all ToxRefDB effects for a chemical
        >>> effects = toxref.get_data_by_dtxsid("DTXSID1037806")
        >>> 
        >>> if effects:
        ...     print(f"Found {len(effects)} effect records")
        ...     
        ...     # Get unique study types
        ...     study_types = set(e.get('studyType') for e in effects if e.get('studyType'))
        ...     print(f"Study types: {', '.join(sorted(study_types))}")
        ...     
        ...     # Find lowest effect levels
        ...     loaels = [e for e in effects if e.get('effectLevel') == 'LOAEL']
        ...     if loaels:
        ...         print(f"

Found {len(loaels)} LOAEL records") ... for loael in loaels[:5]: # Show first 5 ... print(f" {loael.get('studyType')}: {loael.get('dose')} " ... f"{loael.get('doseUnits')} - {loael.get('effect')}") ...
... # Group by organ system ... by_organ = {} ... for effect in effects: ... organ = effect.get('organ', 'Unknown') ... by_organ[organ] = by_organ.get(organ, 0) + 1 ...
... print(f" Effects by organ system:") ... for organ, count in sorted(by_organ.items(), ... key=lambda x: x[1], reverse=True)[:10]: ... print(f" {organ}: {count}") >>> else: ... print("No ToxRefDB data available for this chemical")

    Note:
        - Not all chemicals have ToxRefDB data
        - ToxRefDB focuses on standardized guideline studies
        - Data includes both adverse and non-adverse effects
        - Effect levels help identify critical doses for risk assessment
Source code in src/pycomptox/hazard/toxrefdbeffects.py 
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
def get_data_by_dtxsid(self, dtxsid: str, 
                       use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
    """
    Get ToxRefDB effects data by DTXSID.

    Export of all extracted dose-treatment group-effect information from ToxRefDB 
    for a specific chemical identified by its DSSTox Substance Identifier. Returns 
    all effects observed across all studies for the chemical.

    Args:
        dtxsid: DSSTox Substance Identifier (e.g., 'DTXSID1037806')
        use_cache: Whether to use cache for this request. If None, uses
            the instance default setting.

    Returns:
        List of dictionaries containing effect records with fields such as:
            - dtxsid (str): Chemical identifier
            - studyId (int): Study identifier
            - studyType (str): Type of study
            - treatmentGroup (str): Treatment group
            - dose (float): Dose value
            - doseUnits (str): Dose units
            - effect (str): Observed effect description
            - effectLevel (str): Effect level (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
            - Notes: Exact fields vary by study

    Raises:
        ValueError: If dtxsid is not a valid non-empty string
        PermissionError: If API key is invalid
        RuntimeError: For other API errors

    Example:
        >>> from pycomptox.hazard import ToxRefDBEffects
        >>> toxref = ToxRefDBEffects()
        >>> 
        >>> # Get all ToxRefDB effects for a chemical
        >>> effects = toxref.get_data_by_dtxsid("DTXSID1037806")
        >>> 
        >>> if effects:
        ...     print(f"Found {len(effects)} effect records")
        ...     
        ...     # Get unique study types
        ...     study_types = set(e.get('studyType') for e in effects if e.get('studyType'))
        ...     print(f"Study types: {', '.join(sorted(study_types))}")
        ...     
        ...     # Find lowest effect levels
        ...     loaels = [e for e in effects if e.get('effectLevel') == 'LOAEL']
        ...     if loaels:
        ...         print(f"\nFound {len(loaels)} LOAEL records")
        ...         for loael in loaels[:5]:  # Show first 5
        ...             print(f"  {loael.get('studyType')}: {loael.get('dose')} "
        ...                   f"{loael.get('doseUnits')} - {loael.get('effect')}")
        ...     
        ...     # Group by organ system
        ...     by_organ = {}
        ...     for effect in effects:
        ...         organ = effect.get('organ', 'Unknown')
        ...         by_organ[organ] = by_organ.get(organ, 0) + 1
        ...     
        ...     print(f"\nEffects by organ system:")
        ...     for organ, count in sorted(by_organ.items(), 
        ...                                key=lambda x: x[1], reverse=True)[:10]:
        ...         print(f"  {organ}: {count}")
        >>> else:
        ...     print("No ToxRefDB data available for this chemical")

    Note:
        - Not all chemicals have ToxRefDB data
        - ToxRefDB focuses on standardized guideline studies
        - Data includes both adverse and non-adverse effects
        - Effect levels help identify critical doses for risk assessment
    """
    if not dtxsid or not isinstance(dtxsid, str):
        raise ValueError("dtxsid must be a non-empty string")

    endpoint = f"hazard/toxref/effects/search/by-dtxsid/{dtxsid}"
    return self._make_cached_request(endpoint, use_cache=use_cache)

get_data_by_study_id(study_id, use_cache=None) 

    Get ToxRefDB effects data by study ID.

    Export of all extracted dose-treatment group-effect information from ToxRefDB 
    for a specific study. Each study ID represents a unique toxicity study with 
    detailed dose-response information.

    Args:
        study_id: ToxRefDB study identifier (positive integer)
        use_cache: Whether to use cache for this request. If None, uses
            the instance default setting.

    Returns:
        List of dictionaries containing effect records from the study, with fields:
            - 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
            - organ (str): Target organ/system
            - species (str): Test species
            - sex (str): Sex of test animals
            - duration (str): Study duration
            - Notes: Exact fields vary by study

    Raises:
        ValueError: If study_id is not a positive integer
        PermissionError: If API key is invalid
        RuntimeError: For other API errors

    Example:
        >>> from pycomptox.hazard import ToxRefDBEffects
        >>> toxref = ToxRefDBEffects()
        >>> 
        >>> # Get effects data for study ID 63
        >>> study_effects = toxref.get_data_by_study_id(63)
        >>> 
        >>> if study_effects:
        ...     print(f"Study contains {len(study_effects)} effect records")
        ...     
        ...     # Group by dose level
        ...     by_dose = {}
        ...     for effect in study_effects:
        ...         dose = effect.get('dose', 'Unknown')
        ...         if dose not in by_dose:
        ...             by_dose[dose] = []
        ...         by_dose[dose].append(effect)
        ...     
        ...     # Show effects by dose
        ...     for dose, effects in sorted(by_dose.items()):
        ...         print(f"

Dose {dose} {effects[0].get('doseUnits', '')}:") ... for e in effects: ... print(f" - {e.get('effect')} in {e.get('organ')}")

    Note:
        - Each study typically contains multiple dose groups and effects
        - Study IDs are internal ToxRefDB identifiers
        - Effects are reported at different dose levels (control, low, mid, high)
Source code in src/pycomptox/hazard/toxrefdbeffects.py 
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
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
def get_data_by_study_id(self, study_id: int, 
                         use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
    """
    Get ToxRefDB effects data by study ID.

    Export of all extracted dose-treatment group-effect information from ToxRefDB 
    for a specific study. Each study ID represents a unique toxicity study with 
    detailed dose-response information.

    Args:
        study_id: ToxRefDB study identifier (positive integer)
        use_cache: Whether to use cache for this request. If None, uses
            the instance default setting.

    Returns:
        List of dictionaries containing effect records from the study, with fields:
            - 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
            - organ (str): Target organ/system
            - species (str): Test species
            - sex (str): Sex of test animals
            - duration (str): Study duration
            - Notes: Exact fields vary by study

    Raises:
        ValueError: If study_id is not a positive integer
        PermissionError: If API key is invalid
        RuntimeError: For other API errors

    Example:
        >>> from pycomptox.hazard import ToxRefDBEffects
        >>> toxref = ToxRefDBEffects()
        >>> 
        >>> # Get effects data for study ID 63
        >>> study_effects = toxref.get_data_by_study_id(63)
        >>> 
        >>> if study_effects:
        ...     print(f"Study contains {len(study_effects)} effect records")
        ...     
        ...     # Group by dose level
        ...     by_dose = {}
        ...     for effect in study_effects:
        ...         dose = effect.get('dose', 'Unknown')
        ...         if dose not in by_dose:
        ...             by_dose[dose] = []
        ...         by_dose[dose].append(effect)
        ...     
        ...     # Show effects by dose
        ...     for dose, effects in sorted(by_dose.items()):
        ...         print(f"\nDose {dose} {effects[0].get('doseUnits', '')}:")
        ...         for e in effects:
        ...             print(f"  - {e.get('effect')} in {e.get('organ')}")

    Note:
        - Each study typically contains multiple dose groups and effects
        - Study IDs are internal ToxRefDB identifiers
        - Effects are reported at different dose levels (control, low, mid, high)
    """
    if not isinstance(study_id, int) or study_id < 1:
        raise ValueError("study_id must be a positive integer")

    endpoint = f"hazard/toxref/effects/search/by-study-id/{study_id}"
    return self._make_cached_request(endpoint, use_cache=use_cache)

get_data_by_study_type(study_type, page_number=1, use_cache=None)

Get ToxRefDB effects data by study type.

Export of all extracted dose-treatment group-effect information from ToxRefDB for a specific study type. This view is available as an enhanced data sheet from batch search on the CompTox Chemicals Dashboard.

Common study types include: - DEV: Developmental toxicity studies - REP: Reproductive toxicity studies - CHR: Chronic toxicity studies - SUB: Subchronic toxicity studies - DNT: Developmental neurotoxicity - MLT: Multigenerational reproductive toxicity

Parameters:

Name Type Description Default
study_type str

Study type code (e.g., 'DEV', 'REP', 'CHR')

 required
page_number int

Optional page number for paginated results (default: 1)

 1
use_cache Optional[bool]

Whether to use cache for this request. If None, uses the instance default setting.

 None

Returns:

Type Description
Dict[str, Any]

Dictionary containing paginated effects data with fields such as: - data (List[Dict]): List of effect records - page (int): Current page number - totalPages (int): Total number of pages - totalRecords (int): Total number of records
Dict[str, Any]

Each effect record may include: - dtxsid (str): Chemical identifier - studyId (int): Study identifier - studyType (str): Type of study - effectLevel (str): Effect level (LEL, LOAEL, etc.) - dose (float): Dose value - doseUnits (str): Dose units - effect (str): Observed effect - organ (str): Target organ/system - species (str): Test species - Notes: Exact fields vary by study

Raises:

Type Description
ValueError

If study_type is not a valid non-empty string
PermissionError

If API key is invalid
RuntimeError

For other API errors
Example

from pycomptox.hazard import ToxRefDBEffects toxref = ToxRefDBEffects()

Get developmental toxicity study data

dev_data = toxref.get_data_by_study_type("DEV")

if 'data' in dev_data: ... effects = dev_data['data'] ... print(f"Found {len(effects)} developmental effects on page 1") ... print(f"Total pages: {dev_data.get('totalPages', 'N/A')}") ...
... # Display first effect ... if effects: ... effect = effects[0] ... print(f"Chemical: {effect.get('dtxsid')}") ... print(f"Effect: {effect.get('effect')}") ... print(f"Dose: {effect.get('dose')} {effect.get('doseUnits')}")

Get next page

page2 = toxref.get_data_by_study_type("DEV", page_number=2)

Note
  • Results are paginated to manage large datasets
  • Study type codes are case-sensitive
  • Not all chemicals have data for all study types
Source code in src/pycomptox/hazard/toxrefdbeffects.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
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
def get_data_by_study_type(self, study_type: str, page_number: int = 1, 
                           use_cache: Optional[bool] = None) -> Dict[str, Any]:
    """
    Get ToxRefDB effects data by study type.

    Export of all extracted dose-treatment group-effect information from ToxRefDB 
    for a specific study type. This view is available as an enhanced data sheet 
    from batch search on the CompTox Chemicals Dashboard.

    Common study types include:
    - DEV: Developmental toxicity studies
    - REP: Reproductive toxicity studies
    - CHR: Chronic toxicity studies
    - SUB: Subchronic toxicity studies
    - DNT: Developmental neurotoxicity
    - MLT: Multigenerational reproductive toxicity

    Args:
        study_type: Study type code (e.g., 'DEV', 'REP', 'CHR')
        page_number: Optional page number for paginated results (default: 1)
        use_cache: Whether to use cache for this request. If None, uses
            the instance default setting.

    Returns:
        Dictionary containing paginated effects data with fields such as:
            - data (List[Dict]): List of effect records
            - page (int): Current page number
            - totalPages (int): Total number of pages
            - totalRecords (int): Total number of records

        Each effect record may include:
            - dtxsid (str): Chemical identifier
            - studyId (int): Study identifier
            - studyType (str): Type of study
            - effectLevel (str): Effect level (LEL, LOAEL, etc.)
            - dose (float): Dose value
            - doseUnits (str): Dose units
            - effect (str): Observed effect
            - organ (str): Target organ/system
            - species (str): Test species
            - Notes: Exact fields vary by study

    Raises:
        ValueError: If study_type is not a valid non-empty string
        PermissionError: If API key is invalid
        RuntimeError: For other API errors

    Example:
        >>> from pycomptox.hazard import ToxRefDBEffects
        >>> toxref = ToxRefDBEffects()
        >>> 
        >>> # Get developmental toxicity study data
        >>> dev_data = toxref.get_data_by_study_type("DEV")
        >>> 
        >>> if 'data' in dev_data:
        ...     effects = dev_data['data']
        ...     print(f"Found {len(effects)} developmental effects on page 1")
        ...     print(f"Total pages: {dev_data.get('totalPages', 'N/A')}")
        ...     
        ...     # Display first effect
        ...     if effects:
        ...         effect = effects[0]
        ...         print(f"Chemical: {effect.get('dtxsid')}")
        ...         print(f"Effect: {effect.get('effect')}")
        ...         print(f"Dose: {effect.get('dose')} {effect.get('doseUnits')}")
        >>> 
        >>> # Get next page
        >>> page2 = toxref.get_data_by_study_type("DEV", page_number=2)

    Note:
        - Results are paginated to manage large datasets
        - Study type codes are case-sensitive
        - Not all chemicals have data for all study types
    """
    if not study_type or not isinstance(study_type, str):
        raise ValueError("study_type must be a non-empty string")

    if not isinstance(page_number, int) or page_number < 1:
        raise ValueError("page_number must be a positive integer")

    endpoint = f"hazard/toxref/effects/search/by-study-type/{study_type}"
    params = {"page_number": page_number} if page_number > 1 else None

    return self._make_cached_request(
        endpoint, 
        params=params, 
        use_cache=use_cache
    )