Skip to content

ToxRefDBData API Reference

pycomptox.hazard.toxrefdbdata.ToxRefDBData

Bases: CachedAPIClient

Client for accessing ToxRefDB dose-treatment group-effect data from EPA CompTox Dashboard.

This class provides access to all extracted dose-treatment group-effect information as well as doses not eliciting effects from ToxRefDB for specified chemicals, studies, or study types.

ToxRefDB contains comprehensive toxicology study information that is also summarized in ToxValDB, including: - Dose-response data for treatment groups - Effect levels (LEL, LOAEL) - No-effect levels (NEL, NOAEL - inferred) - Study-specific toxicological endpoints

Data can be retrieved by: - Study type (e.g., DEV for developmental toxicity studies) - Study ID (individual study identifier) - DTXSID (chemical substance identifier)

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

Get data for developmental toxicity studies

dev_data = toxref.get_data_by_study_type("DEV") print(f"Page {dev_data['page']} of {dev_data['totalPages']}") print(f"Found {len(dev_data['content'])} records on this page")

Source code in src/pycomptox/hazard/toxrefdbdata.py 
 17
 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
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
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
class ToxRefDBData(CachedAPIClient):
    """
    Client for accessing ToxRefDB dose-treatment group-effect data from EPA CompTox Dashboard.

    This class provides access to all extracted dose-treatment group-effect information 
    as well as doses not eliciting effects from ToxRefDB for specified chemicals, studies, 
    or study types.

    ToxRefDB contains comprehensive toxicology study information that is also summarized 
    in ToxValDB, including:
    - Dose-response data for treatment groups
    - Effect levels (LEL, LOAEL)
    - No-effect levels (NEL, NOAEL - inferred)
    - Study-specific toxicological endpoints

    Data can be retrieved by:
    - Study type (e.g., DEV for developmental toxicity studies)
    - Study ID (individual study identifier)
    - DTXSID (chemical substance identifier)

    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 ToxRefDBData
        >>> toxref = ToxRefDBData()
        >>> 
        >>> # Get data for developmental toxicity studies
        >>> dev_data = toxref.get_data_by_study_type("DEV")
        >>> print(f"Page {dev_data['page']} of {dev_data['totalPages']}")
        >>> print(f"Found {len(dev_data['content'])} records on this page")
    """

    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 ToxRefDBData 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 data by study type with pagination.

        Retrieves dose-treatment group-effect information for all studies of a 
        specified type. Results are paginated to handle large datasets.

        Common study types include:
        - DEV: Developmental toxicity studies
        - REP: Reproductive toxicity studies
        - DNT: Developmental neurotoxicity studies
        - CHRON: Chronic toxicity studies
        - SUBCHRON: Subchronic toxicity studies
        - ACUTE: Acute toxicity studies
        - NEURO: Neurotoxicity studies

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

        Returns:
            Dictionary containing paginated results with fields:
                - data (list): List of data records for this page
                - pageNumber (int): Current page number
                - recordsOnPage (int): Number of records on this page
                - studyType (str): The requested study type

            Each record in 'data' contains fields such as:
                - dtxsid (str): Chemical identifier
                - studyId (int): Study identifier
                - studyType (str): Type of study
                - effectLevel (str): Effect level (LEL, LOAEL, etc.)
                - dose (float): Dose amount
                - doseUnits (str): Dose units
                - effect (str): Observed effect
                - target (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 or page_number < 1
            PermissionError: If API key is invalid
            RuntimeError: For other API errors

        Example:
            >>> from pycomptox.hazard import ToxRefDBData
            >>> toxref = ToxRefDBData()
            >>> 
            >>> # Get developmental toxicity study data
            >>> dev_data = toxref.get_data_by_study_type("DEV", page_number=1)
            >>> 
            >>> print(f"Page {dev_data['pageNumber']}")
            >>> print(f"Records on this page: {dev_data['recordsOnPage']}")
            >>> print(f"Total records: {len(dev_data['data'])}")
            >>> 
            >>> # Process records
            >>> for record in dev_data['data'][:5]:  # First 5 records
            ...     print(f"\nStudy ID: {record.get('studyId')}")
            ...     print(f"Chemical: {record.get('dtxsid')}")
            ...     print(f"Effect: {record.get('effect', 'N/A')}")
            ...     if record.get('dose'):
            ...         print(f"Dose: {record['dose']} {record.get('doseUnits', '')}")
            >>> 
            >>> # Iterate through pages
            >>> page = 1
            >>> while True:
            ...     page_data = toxref.get_data_by_study_type("DEV", page_number=page)
            ...     # Process page_data['data']
            ...     if len(page_data['data']) < page_data['recordsOnPage']:
            ...         break  # Last page
            ...     page += 1

        Note:
            - Results are paginated; use page_number to navigate through pages
            - Check if data length is less than recordsOnPage to detect last page
            - Data includes both effect levels and no-effect levels
        """
        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/data/search/by-study-type/{study_type}"
        params = {"page": page_number}

        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 data by study ID.

        Retrieves all dose-treatment group-effect information for a specific study.
        Each study may have multiple dose groups and endpoints.

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

        Returns:
            List of dictionaries containing dose-effect data with fields such as:
                - dtxsid (str): Chemical identifier
                - studyId (int): Study identifier
                - studyType (str): Type of study
                - effectLevel (str): Effect level (LEL, LOAEL, NEL, NOAEL)
                - dose (float): Dose amount
                - doseUnits (str): Dose units (mg/kg/day, ppm, etc.)
                - effect (str): Observed effect description
                - target (str): Target organ or system
                - species (str): Test species (rat, mouse, etc.)
                - sex (str): Sex of test animals
                - exposureDuration (str): Duration of exposure
                - exposureRoute (str): Route of exposure
                - generation (str): Generation studied (for reproductive studies)
                - Notes: Exact fields vary by study type

        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 ToxRefDBData
            >>> toxref = ToxRefDBData()
            >>> 
            >>> # Get data for a specific study
            >>> study_data = toxref.get_data_by_study_id(63)
            >>> 
            >>> if study_data:
            ...     print(f"Found {len(study_data)} dose-effect records")
            ...     
            ...     # Get study metadata from first record
            ...     first = study_data[0]
            ...     print(f"\nStudy ID: {first.get('studyId')}")
            ...     print(f"Chemical: {first.get('dtxsid')}")
            ...     print(f"Study Type: {first.get('studyType')}")
            ...     print(f"Species: {first.get('species')}")
            ...     print(f"Exposure Route: {first.get('exposureRoute')}")
            ...     
            ...     # Group by effect level
            ...     by_level = {}
            ...     for record in study_data:
            ...         level = record.get('effectLevel', 'Unknown')
            ...         if level not in by_level:
            ...             by_level[level] = []
            ...         by_level[level].append(record)
            ...     
            ...     print(f"\nEffect levels found:")
            ...     for level, records in sorted(by_level.items()):
            ...         print(f"  {level}: {len(records)} record(s)")
            ...     
            ...     # Show LOAELs
            ...     if 'LOAEL' in by_level:
            ...         print(f"\nLOAEL values:")
            ...         for rec in by_level['LOAEL'][:3]:
            ...             print(f"  {rec.get('dose')} {rec.get('doseUnits')} - {rec.get('effect')}")

        Note:
            - A single study may have multiple dose groups and endpoints
            - Data includes both observed effects and no-effect doses
            - Effect levels may include LEL, LOAEL, NEL, NOAEL
        """
        if not isinstance(study_id, int) or study_id < 1:
            raise ValueError("study_id must be a positive integer")

        endpoint = f"hazard/toxref/data/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 data by DTXSID.

        Retrieves all dose-treatment group-effect information for a chemical across 
        all studies in ToxRefDB. This provides a comprehensive view of toxicological 
        data for a specific substance.

        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 dose-effect data across all studies 
            for the chemical. Each entry includes fields such as:
                - dtxsid (str): Chemical identifier
                - studyId (int): Study identifier
                - studyType (str): Type of study
                - effectLevel (str): Effect level classification
                - dose (float): Dose amount
                - doseUnits (str): Dose units
                - effect (str): Observed effect
                - target (str): Target organ/system
                - species (str): Test species
                - sex (str): Sex of test animals
                - exposureDuration (str): Duration of exposure
                - exposureRoute (str): Route of exposure
                - reference (str): Study reference
                - 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 ToxRefDBData
            >>> toxref = ToxRefDBData()
            >>> 
            >>> # Get all ToxRefDB data for a chemical
            >>> data = toxref.get_data_by_dtxsid("DTXSID1037806")
            >>> 
            >>> if data:
            ...     print(f"Found {len(data)} dose-effect records")
            ...     
            ...     # Group by study type
            ...     by_type = {}
            ...     for record in data:
            ...         stype = record.get('studyType', 'Unknown')
            ...         if stype not in by_type:
            ...             by_type[stype] = []
            ...         by_type[stype].append(record)
            ...     
            ...     print(f"\nStudy types represented:")
            ...     for stype, records in sorted(by_type.items()):
            ...         print(f"  {stype}: {len(records)} record(s)")
            ...     
            ...     # Find lowest LOAEL across all studies
            ...     loaels = [r for r in data if r.get('effectLevel') == 'LOAEL' and r.get('dose')]
            ...     if loaels:
            ...         # Group by units for comparison
            ...         by_units = {}
            ...         for rec in loaels:
            ...             units = rec.get('doseUnits', 'unknown')
            ...             dose = rec.get('dose')
            ...             if units not in by_units:
            ...                 by_units[units] = []
            ...             by_units[units].append(dose)
            ...         
            ...         print(f"\nLowest LOAELs by unit:")
            ...         for units, doses in by_units.items():
            ...             print(f"  {min(doses)} {units}")
            ...     
            ...     # List unique targets
            ...     targets = set(r.get('target') for r in data if r.get('target'))
            ...     print(f"\nTarget organs/systems: {', '.join(sorted(targets))}")

        Note:
            - Returns data from all available studies for the chemical
            - May include multiple study types and species
            - Useful for comprehensive hazard assessment
        """
        if not dtxsid or not isinstance(dtxsid, str):
            raise ValueError("dtxsid must be a non-empty string")

        endpoint = f"hazard/toxref/data/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 ToxRefDBData 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/toxrefdbdata.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 ToxRefDBData 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 data by DTXSID.

    Retrieves all dose-treatment group-effect information for a chemical across 
    all studies in ToxRefDB. This provides a comprehensive view of toxicological 
    data for a specific substance.

    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 dose-effect data across all studies 
        for the chemical. Each entry includes fields such as:
            - dtxsid (str): Chemical identifier
            - studyId (int): Study identifier
            - studyType (str): Type of study
            - effectLevel (str): Effect level classification
            - dose (float): Dose amount
            - doseUnits (str): Dose units
            - effect (str): Observed effect
            - target (str): Target organ/system
            - species (str): Test species
            - sex (str): Sex of test animals
            - exposureDuration (str): Duration of exposure
            - exposureRoute (str): Route of exposure
            - reference (str): Study reference
            - 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 ToxRefDBData
        >>> toxref = ToxRefDBData()
        >>> 
        >>> # Get all ToxRefDB data for a chemical
        >>> data = toxref.get_data_by_dtxsid("DTXSID1037806")
        >>> 
        >>> if data:
        ...     print(f"Found {len(data)} dose-effect records")
        ...     
        ...     # Group by study type
        ...     by_type = {}
        ...     for record in data:
        ...         stype = record.get('studyType', 'Unknown')
        ...         if stype not in by_type:
        ...             by_type[stype] = []
        ...         by_type[stype].append(record)
        ...     
        ...     print(f"

Study types represented:") ... for stype, records in sorted(by_type.items()): ... print(f" {stype}: {len(records)} record(s)") ...
... # Find lowest LOAEL across all studies ... loaels = [r for r in data if r.get('effectLevel') == 'LOAEL' and r.get('dose')] ... if loaels: ... # Group by units for comparison ... by_units = {} ... for rec in loaels: ... units = rec.get('doseUnits', 'unknown') ... dose = rec.get('dose') ... if units not in by_units: ... by_units[units] = [] ... by_units[units].append(dose) ...
... print(f" Lowest LOAELs by unit:") ... for units, doses in by_units.items(): ... print(f" {min(doses)} {units}") ...
... # List unique targets ... targets = set(r.get('target') for r in data if r.get('target')) ... print(f" Target organs/systems: {', '.join(sorted(targets))}")

    Note:
        - Returns data from all available studies for the chemical
        - May include multiple study types and species
        - Useful for comprehensive hazard assessment
Source code in src/pycomptox/hazard/toxrefdbdata.py 
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
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
def get_data_by_dtxsid(
    self,
    dtxsid: str,
    use_cache: Optional[bool] = None
) -> List[Dict[str, Any]]:
    """
    Get ToxRefDB data by DTXSID.

    Retrieves all dose-treatment group-effect information for a chemical across 
    all studies in ToxRefDB. This provides a comprehensive view of toxicological 
    data for a specific substance.

    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 dose-effect data across all studies 
        for the chemical. Each entry includes fields such as:
            - dtxsid (str): Chemical identifier
            - studyId (int): Study identifier
            - studyType (str): Type of study
            - effectLevel (str): Effect level classification
            - dose (float): Dose amount
            - doseUnits (str): Dose units
            - effect (str): Observed effect
            - target (str): Target organ/system
            - species (str): Test species
            - sex (str): Sex of test animals
            - exposureDuration (str): Duration of exposure
            - exposureRoute (str): Route of exposure
            - reference (str): Study reference
            - 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 ToxRefDBData
        >>> toxref = ToxRefDBData()
        >>> 
        >>> # Get all ToxRefDB data for a chemical
        >>> data = toxref.get_data_by_dtxsid("DTXSID1037806")
        >>> 
        >>> if data:
        ...     print(f"Found {len(data)} dose-effect records")
        ...     
        ...     # Group by study type
        ...     by_type = {}
        ...     for record in data:
        ...         stype = record.get('studyType', 'Unknown')
        ...         if stype not in by_type:
        ...             by_type[stype] = []
        ...         by_type[stype].append(record)
        ...     
        ...     print(f"\nStudy types represented:")
        ...     for stype, records in sorted(by_type.items()):
        ...         print(f"  {stype}: {len(records)} record(s)")
        ...     
        ...     # Find lowest LOAEL across all studies
        ...     loaels = [r for r in data if r.get('effectLevel') == 'LOAEL' and r.get('dose')]
        ...     if loaels:
        ...         # Group by units for comparison
        ...         by_units = {}
        ...         for rec in loaels:
        ...             units = rec.get('doseUnits', 'unknown')
        ...             dose = rec.get('dose')
        ...             if units not in by_units:
        ...                 by_units[units] = []
        ...             by_units[units].append(dose)
        ...         
        ...         print(f"\nLowest LOAELs by unit:")
        ...         for units, doses in by_units.items():
        ...             print(f"  {min(doses)} {units}")
        ...     
        ...     # List unique targets
        ...     targets = set(r.get('target') for r in data if r.get('target'))
        ...     print(f"\nTarget organs/systems: {', '.join(sorted(targets))}")

    Note:
        - Returns data from all available studies for the chemical
        - May include multiple study types and species
        - Useful for comprehensive hazard assessment
    """
    if not dtxsid or not isinstance(dtxsid, str):
        raise ValueError("dtxsid must be a non-empty string")

    endpoint = f"hazard/toxref/data/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 data by study ID.

    Retrieves all dose-treatment group-effect information for a specific study.
    Each study may have multiple dose groups and endpoints.

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

    Returns:
        List of dictionaries containing dose-effect data with fields such as:
            - dtxsid (str): Chemical identifier
            - studyId (int): Study identifier
            - studyType (str): Type of study
            - effectLevel (str): Effect level (LEL, LOAEL, NEL, NOAEL)
            - dose (float): Dose amount
            - doseUnits (str): Dose units (mg/kg/day, ppm, etc.)
            - effect (str): Observed effect description
            - target (str): Target organ or system
            - species (str): Test species (rat, mouse, etc.)
            - sex (str): Sex of test animals
            - exposureDuration (str): Duration of exposure
            - exposureRoute (str): Route of exposure
            - generation (str): Generation studied (for reproductive studies)
            - Notes: Exact fields vary by study type

    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 ToxRefDBData
        >>> toxref = ToxRefDBData()
        >>> 
        >>> # Get data for a specific study
        >>> study_data = toxref.get_data_by_study_id(63)
        >>> 
        >>> if study_data:
        ...     print(f"Found {len(study_data)} dose-effect records")
        ...     
        ...     # Get study metadata from first record
        ...     first = study_data[0]
        ...     print(f"

Study ID: {first.get('studyId')}") ... print(f"Chemical: {first.get('dtxsid')}") ... print(f"Study Type: {first.get('studyType')}") ... print(f"Species: {first.get('species')}") ... print(f"Exposure Route: {first.get('exposureRoute')}") ...
... # Group by effect level ... by_level = {} ... for record in study_data: ... level = record.get('effectLevel', 'Unknown') ... if level not in by_level: ... by_level[level] = [] ... by_level[level].append(record) ...
... print(f" Effect levels found:") ... for level, records in sorted(by_level.items()): ... print(f" {level}: {len(records)} record(s)") ...
... # Show LOAELs ... if 'LOAEL' in by_level: ... print(f" LOAEL values:") ... for rec in by_level['LOAEL'][:3]: ... print(f" {rec.get('dose')} {rec.get('doseUnits')} - {rec.get('effect')}")

    Note:
        - A single study may have multiple dose groups and endpoints
        - Data includes both observed effects and no-effect doses
        - Effect levels may include LEL, LOAEL, NEL, NOAEL
Source code in src/pycomptox/hazard/toxrefdbdata.py 
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
def get_data_by_study_id(
    self,
    study_id: int,
    use_cache: Optional[bool] = None
) -> List[Dict[str, Any]]:
    """
    Get ToxRefDB data by study ID.

    Retrieves all dose-treatment group-effect information for a specific study.
    Each study may have multiple dose groups and endpoints.

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

    Returns:
        List of dictionaries containing dose-effect data with fields such as:
            - dtxsid (str): Chemical identifier
            - studyId (int): Study identifier
            - studyType (str): Type of study
            - effectLevel (str): Effect level (LEL, LOAEL, NEL, NOAEL)
            - dose (float): Dose amount
            - doseUnits (str): Dose units (mg/kg/day, ppm, etc.)
            - effect (str): Observed effect description
            - target (str): Target organ or system
            - species (str): Test species (rat, mouse, etc.)
            - sex (str): Sex of test animals
            - exposureDuration (str): Duration of exposure
            - exposureRoute (str): Route of exposure
            - generation (str): Generation studied (for reproductive studies)
            - Notes: Exact fields vary by study type

    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 ToxRefDBData
        >>> toxref = ToxRefDBData()
        >>> 
        >>> # Get data for a specific study
        >>> study_data = toxref.get_data_by_study_id(63)
        >>> 
        >>> if study_data:
        ...     print(f"Found {len(study_data)} dose-effect records")
        ...     
        ...     # Get study metadata from first record
        ...     first = study_data[0]
        ...     print(f"\nStudy ID: {first.get('studyId')}")
        ...     print(f"Chemical: {first.get('dtxsid')}")
        ...     print(f"Study Type: {first.get('studyType')}")
        ...     print(f"Species: {first.get('species')}")
        ...     print(f"Exposure Route: {first.get('exposureRoute')}")
        ...     
        ...     # Group by effect level
        ...     by_level = {}
        ...     for record in study_data:
        ...         level = record.get('effectLevel', 'Unknown')
        ...         if level not in by_level:
        ...             by_level[level] = []
        ...         by_level[level].append(record)
        ...     
        ...     print(f"\nEffect levels found:")
        ...     for level, records in sorted(by_level.items()):
        ...         print(f"  {level}: {len(records)} record(s)")
        ...     
        ...     # Show LOAELs
        ...     if 'LOAEL' in by_level:
        ...         print(f"\nLOAEL values:")
        ...         for rec in by_level['LOAEL'][:3]:
        ...             print(f"  {rec.get('dose')} {rec.get('doseUnits')} - {rec.get('effect')}")

    Note:
        - A single study may have multiple dose groups and endpoints
        - Data includes both observed effects and no-effect doses
        - Effect levels may include LEL, LOAEL, NEL, NOAEL
    """
    if not isinstance(study_id, int) or study_id < 1:
        raise ValueError("study_id must be a positive integer")

    endpoint = f"hazard/toxref/data/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 data by study type with pagination.

    Retrieves dose-treatment group-effect information for all studies of a 
    specified type. Results are paginated to handle large datasets.

    Common study types include:
    - DEV: Developmental toxicity studies
    - REP: Reproductive toxicity studies
    - DNT: Developmental neurotoxicity studies
    - CHRON: Chronic toxicity studies
    - SUBCHRON: Subchronic toxicity studies
    - ACUTE: Acute toxicity studies
    - NEURO: Neurotoxicity studies

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

    Returns:
        Dictionary containing paginated results with fields:
            - data (list): List of data records for this page
            - pageNumber (int): Current page number
            - recordsOnPage (int): Number of records on this page
            - studyType (str): The requested study type

        Each record in 'data' contains fields such as:
            - dtxsid (str): Chemical identifier
            - studyId (int): Study identifier
            - studyType (str): Type of study
            - effectLevel (str): Effect level (LEL, LOAEL, etc.)
            - dose (float): Dose amount
            - doseUnits (str): Dose units
            - effect (str): Observed effect
            - target (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 or page_number < 1
        PermissionError: If API key is invalid
        RuntimeError: For other API errors

    Example:
        >>> from pycomptox.hazard import ToxRefDBData
        >>> toxref = ToxRefDBData()
        >>> 
        >>> # Get developmental toxicity study data
        >>> dev_data = toxref.get_data_by_study_type("DEV", page_number=1)
        >>> 
        >>> print(f"Page {dev_data['pageNumber']}")
        >>> print(f"Records on this page: {dev_data['recordsOnPage']}")
        >>> print(f"Total records: {len(dev_data['data'])}")
        >>> 
        >>> # Process records
        >>> for record in dev_data['data'][:5]:  # First 5 records
        ...     print(f"

Study ID: {record.get('studyId')}") ... print(f"Chemical: {record.get('dtxsid')}") ... print(f"Effect: {record.get('effect', 'N/A')}") ... if record.get('dose'): ... print(f"Dose: {record['dose']} {record.get('doseUnits', '')}") >>> >>> # Iterate through pages >>> page = 1 >>> while True: ... page_data = toxref.get_data_by_study_type("DEV", page_number=page) ... # Process page_data['data'] ... if len(page_data['data']) < page_data['recordsOnPage']: ... break # Last page ... page += 1

    Note:
        - Results are paginated; use page_number to navigate through pages
        - Check if data length is less than recordsOnPage to detect last page
        - Data includes both effect levels and no-effect levels
Source code in src/pycomptox/hazard/toxrefdbdata.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
169
170
171
172
173
174
def get_data_by_study_type(
    self,
    study_type: str,
    page_number: int = 1,
    use_cache: Optional[bool] = None
) -> Dict[str, Any]:
    """
    Get ToxRefDB data by study type with pagination.

    Retrieves dose-treatment group-effect information for all studies of a 
    specified type. Results are paginated to handle large datasets.

    Common study types include:
    - DEV: Developmental toxicity studies
    - REP: Reproductive toxicity studies
    - DNT: Developmental neurotoxicity studies
    - CHRON: Chronic toxicity studies
    - SUBCHRON: Subchronic toxicity studies
    - ACUTE: Acute toxicity studies
    - NEURO: Neurotoxicity studies

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

    Returns:
        Dictionary containing paginated results with fields:
            - data (list): List of data records for this page
            - pageNumber (int): Current page number
            - recordsOnPage (int): Number of records on this page
            - studyType (str): The requested study type

        Each record in 'data' contains fields such as:
            - dtxsid (str): Chemical identifier
            - studyId (int): Study identifier
            - studyType (str): Type of study
            - effectLevel (str): Effect level (LEL, LOAEL, etc.)
            - dose (float): Dose amount
            - doseUnits (str): Dose units
            - effect (str): Observed effect
            - target (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 or page_number < 1
        PermissionError: If API key is invalid
        RuntimeError: For other API errors

    Example:
        >>> from pycomptox.hazard import ToxRefDBData
        >>> toxref = ToxRefDBData()
        >>> 
        >>> # Get developmental toxicity study data
        >>> dev_data = toxref.get_data_by_study_type("DEV", page_number=1)
        >>> 
        >>> print(f"Page {dev_data['pageNumber']}")
        >>> print(f"Records on this page: {dev_data['recordsOnPage']}")
        >>> print(f"Total records: {len(dev_data['data'])}")
        >>> 
        >>> # Process records
        >>> for record in dev_data['data'][:5]:  # First 5 records
        ...     print(f"\nStudy ID: {record.get('studyId')}")
        ...     print(f"Chemical: {record.get('dtxsid')}")
        ...     print(f"Effect: {record.get('effect', 'N/A')}")
        ...     if record.get('dose'):
        ...         print(f"Dose: {record['dose']} {record.get('doseUnits', '')}")
        >>> 
        >>> # Iterate through pages
        >>> page = 1
        >>> while True:
        ...     page_data = toxref.get_data_by_study_type("DEV", page_number=page)
        ...     # Process page_data['data']
        ...     if len(page_data['data']) < page_data['recordsOnPage']:
        ...         break  # Last page
        ...     page += 1

    Note:
        - Results are paginated; use page_number to navigate through pages
        - Check if data length is less than recordsOnPage to detect last page
        - Data includes both effect levels and no-effect levels
    """
    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/data/search/by-study-type/{study_type}"
    params = {"page": page_number}

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