Skip to content

ToxValDBGenetox API Reference

pycomptox.hazard.toxvaldbgenetox.ToxValDBGenetox

Bases: CachedAPIClient

Client for accessing genotoxicity test data from EPA CompTox Dashboard.

Genotoxicity testing, also known as short-term assays, is used to evaluate the potential adverse effects of chemicals on human health. These tests can help identify carcinogens, as about 80% of known human carcinogens are genotoxic.

The results of genotoxicity tests are important because of the irreversible nature and severity of the health effects that may result from genotoxic events.

Common genotoxicity test types include: - Ames test: Comparative genetic analysis using multiple bacterial strains of Salmonella typhimurium - Comet assay: Measurement of DNA strand breaks - Micronucleus test: Cytogenetic assay using fluorescence in situ hybridization and chromosome painting - Chromosomal aberration test: Cytogenetic assay examining in vivo tissues to reflect how chemicals are absorbed, excreted, distributed, and metabolized

This class provides both summary-level and detailed genotoxicity data for chemicals.

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 ToxValDBGenetox genetox = ToxValDBGenetox()

Get genotoxicity summary for a chemical

summary = genetox.get_summary_by_dtxsid("DTXSID0021125") if summary: ... print(f"Found {len(summary)} genotoxicity summary records")

Source code in src/pycomptox/hazard/toxvaldbgenetox.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
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
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
class ToxValDBGenetox(CachedAPIClient):
    """
    Client for accessing genotoxicity test data from EPA CompTox Dashboard.

    Genotoxicity testing, also known as short-term assays, is used to evaluate 
    the potential adverse effects of chemicals on human health. These tests can 
    help identify carcinogens, as about 80% of known human carcinogens are genotoxic.

    The results of genotoxicity tests are important because of the irreversible 
    nature and severity of the health effects that may result from genotoxic events.

    Common genotoxicity test types include:
    - Ames test: Comparative genetic analysis using multiple bacterial strains 
      of Salmonella typhimurium
    - Comet assay: Measurement of DNA strand breaks
    - Micronucleus test: Cytogenetic assay using fluorescence in situ hybridization 
      and chromosome painting
    - Chromosomal aberration test: Cytogenetic assay examining in vivo tissues to 
      reflect how chemicals are absorbed, excreted, distributed, and metabolized

    This class provides both summary-level and detailed genotoxicity data for chemicals.

    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 ToxValDBGenetox
        >>> genetox = ToxValDBGenetox()
        >>> 
        >>> # Get genotoxicity summary for a chemical
        >>> summary = genetox.get_summary_by_dtxsid("DTXSID0021125")
        >>> if summary:
        ...     print(f"Found {len(summary)} genotoxicity summary 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 ToxValDBGenetox 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_summary_by_dtxsid(self, dtxsid: str, 
                              use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
        """
        Get genotoxicity summary data by DTXSID.

        Retrieves summary-level genotoxicity test information for a chemical. 
        Summary data provides an overview of genotoxicity testing results across 
        different assay types.

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

        Returns:
            List of dictionaries containing genotoxicity summary data with fields such as:
                - dtxsid (str): Chemical identifier
                - testType (str): Type of genotoxicity test
                - result (str): Overall test result (positive/negative)
                - callSummary (str): Summary of test calls
                - numberOfPositive (int): Number of positive results
                - numberOfNegative (int): Number of negative results
                - numberOfTests (int): Total number of tests
                - source (str): Data source
                - Notes: Exact fields vary by test type

        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 ToxValDBGenetox
            >>> genetox = ToxValDBGenetox()
            >>> 
            >>> # Get genotoxicity summary for benzene
            >>> summary = genetox.get_summary_by_dtxsid("DTXSID0021125")
            >>> 
            >>> if summary:
            ...     print(f"Found {len(summary)} genotoxicity summary records")
            ...     
            ...     for record in summary:
            ...         test_type = record.get('testType', 'Unknown')
            ...         result = record.get('result', 'N/A')
            ...         print(f"\n{test_type}: {result}")
            ...         
            ...         if record.get('numberOfTests'):
            ...             pos = record.get('numberOfPositive', 0)
            ...             neg = record.get('numberOfNegative', 0)
            ...             total = record.get('numberOfTests', 0)
            ...             print(f"  Tests: {pos} positive, {neg} negative (out of {total} total)")
            >>> else:
            ...     print("No genotoxicity summary data available")

        Note:
            - Not all chemicals have genotoxicity test data
            - Summary provides overview across multiple tests
            - For detailed test results, use get_detail_by_dtxsid()
        """
        if not dtxsid or not isinstance(dtxsid, str):
            raise ValueError("dtxsid must be a non-empty string")

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

    def get_detail_by_dtxsid(self, dtxsid: str, projection: Optional[str] = None,
                           use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
        """
        Get detailed genotoxicity data by DTXSID.

        Retrieves detailed genotoxicity test information for a chemical, including 
        individual test results, experimental conditions, and study details. 
        Optionally use projection for CompTox Dashboard-specific formatting.

        Args:
            dtxsid: DSSTox Substance Identifier (e.g., 'DTXSID7020182')
            projection: Optional projection name. Use 'ccd-genetox-details' for 
                CompTox Dashboard Genetoxicity Details page format. If None, 
                returns default GenetoxDetail data.
            use_cache: Whether to use cache for this request. If None, uses
                the instance default setting.

        Returns:
            List of dictionaries containing detailed genotoxicity data with fields such as:
                - dtxsid (str): Chemical identifier
                - testName (str): Specific test name
                - testType (str): Type of genotoxicity test
                - result (str): Test result (positive/negative/equivocal)
                - strain (str): Biological strain used
                - species (str): Test species
                - metabolicActivation (str): Metabolic activation system used
                - dose (str): Dose information
                - doseUnits (str): Dose units
                - endpoint (str): Measured endpoint
                - reference (str): Study reference
                - source (str): Data source
                - year (int): Study year
                - Notes: Exact fields vary by test type and projection

        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 ToxValDBGenetox
            >>> genetox = ToxValDBGenetox()
            >>> 
            >>> # Get detailed genotoxicity data
            >>> details = genetox.get_detail_by_dtxsid("DTXSID7020182")
            >>> 
            >>> if details:
            ...     print(f"Found {len(details)} detailed genotoxicity test records")
            ...     
            ...     # Group by test type
            ...     by_type = {}
            ...     for detail in details:
            ...         test_type = detail.get('testType', 'Unknown')
            ...         if test_type not in by_type:
            ...             by_type[test_type] = []
            ...         by_type[test_type].append(detail)
            ...     
            ...     # Display results by test type
            ...     for test_type, tests in sorted(by_type.items()):
            ...         print(f"\n{test_type}: {len(tests)} test(s)")
            ...         
            ...         # Count positive/negative results
            ...         pos = sum(1 for t in tests if 'positive' in str(t.get('result', '')).lower())
            ...         neg = sum(1 for t in tests if 'negative' in str(t.get('result', '')).lower())
            ...         print(f"  Positive: {pos}, Negative: {neg}")
            ...         
            ...         # Show example test
            ...         if tests:
            ...             ex = tests[0]
            ...             print(f"  Example: {ex.get('testName', 'N/A')}")
            ...             print(f"    Result: {ex.get('result', 'N/A')}")
            ...             if ex.get('strain'):
            ...                 print(f"    Strain: {ex['strain']}")
            >>> 
            >>> # Get with CompTox Dashboard projection
            >>> ccd_details = genetox.get_detail_by_dtxsid("DTXSID7020182", 
            ...                                             projection="ccd-genetox-details")

        Note:
            - Detailed data includes individual test results
            - Use projection='ccd-genetox-details' for dashboard-formatted data
            - Results may include multiple tests of the same type under different conditions
        """
        if not dtxsid or not isinstance(dtxsid, str):
            raise ValueError("dtxsid must be a non-empty string")

        endpoint = f"hazard/genetox/details/search/by-dtxsid/{dtxsid}"
        params = {"projection": projection} if projection else None

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

    def get_summary_by_dtxsid_batch(self, dtxsids: List[str], 
                              use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
        """
        Get genotoxicity summary data for multiple chemicals in a single batch request.

        Batch retrieval of genotoxicity summary data for up to 200 chemicals.
        More efficient than making individual requests.

        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 genotoxicity summary data for all
            requested chemicals. Each entry includes similar fields as
            get_summary_by_dtxsid().

        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 ToxValDBGenetox
            >>> genetox = ToxValDBGenetox()
            >>> 
            >>> # Get summary for multiple chemicals
            >>> dtxsids = ["DTXSID0021125", "DTXSID7020182", "DTXSID0020032"]
            >>> batch_summary = genetox.get_summary_by_dtxsid_batch(dtxsids)
            >>> 
            >>> # Group by chemical
            >>> by_chemical = {}
            >>> for record in batch_summary:
            ...     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)} test type(s)")
            ...     
            ...     # Check for positive results
            ...     positive = [r for r in records if 'positive' in str(r.get('result', '')).lower()]
            ...     if positive:
            ...         print(f"  WARNING: {len(positive)} positive genotoxicity result(s)")

        Note:
            - Maximum 200 DTXSIDs per request
            - Batch requests are more efficient than individual queries
            - Useful for screening chemical libraries for genotoxicity
        """
        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/genetox/summary/search/by-dtxsid/"
        return self._make_cached_request(
            endpoint, 
            json=dtxsids, 
            method='POST', 
            use_cache=use_cache
        )

    def get_detail_by_dtxsid_batch(self, dtxsids: List[str], projection: Optional[str] = None,
                           use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
        """
        Get detailed genotoxicity data for multiple chemicals in a single batch request.

        Batch retrieval of detailed genotoxicity test data for up to 200 chemicals.
        More efficient than making individual requests.

        Args:
            dtxsids: List of DSSTox Substance Identifiers (max 200)
            projection: Optional projection name. Use 'ccd-genetox-details' for 
                CompTox Dashboard format.
            use_cache: Whether to use cache for this request. If None, uses
                the instance default setting.

        Returns:
            List of dictionaries containing detailed genotoxicity data for all
            requested chemicals. Each entry includes similar fields as
            get_detail_by_dtxsid().

        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 ToxValDBGenetox
            >>> genetox = ToxValDBGenetox()
            >>> 
            >>> # Get detailed data for multiple chemicals
            >>> dtxsids = ["DTXSID0021125", "DTXSID7020182"]
            >>> batch_details = genetox.get_detail_by_dtxsid_batch(dtxsids)
            >>> 
            >>> # Analyze results
            >>> if batch_details:
            ...     print(f"Retrieved {len(batch_details)} detailed test records")
            ...     
            ...     # Count by chemical
            ...     by_chemical = {}
            ...     for record in batch_details:
            ...         dtxsid = record['dtxsid']
            ...         by_chemical[dtxsid] = by_chemical.get(dtxsid, 0) + 1
            ...     
            ...     for dtxsid, count in by_chemical.items():
            ...         print(f"{dtxsid}: {count} detailed test record(s)")
            ...     
            ...     # Count test types across all chemicals
            ...     test_types = set(r.get('testType') for r in batch_details if r.get('testType'))
            ...     print(f"\nTest types represented: {', '.join(sorted(test_types))}")

        Note:
            - Maximum 200 DTXSIDs per request
            - Returns comprehensive test details for all chemicals
            - Batch requests are more efficient than individual queries
            - Results can be large for chemicals with extensive testing
        """
        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/genetox/details/search/by-dtxsid/"
        params = {"projection": projection} if projection else None

        return self._make_cached_request(
            endpoint, 
            json=dtxsids, 
            method='POST',
            params=params,
            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 ToxValDBGenetox 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/toxvaldbgenetox.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 ToxValDBGenetox 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_detail_by_dtxsid(dtxsid, projection=None, use_cache=None) 

    Get detailed genotoxicity data by DTXSID.

    Retrieves detailed genotoxicity test information for a chemical, including 
    individual test results, experimental conditions, and study details. 
    Optionally use projection for CompTox Dashboard-specific formatting.

    Args:
        dtxsid: DSSTox Substance Identifier (e.g., 'DTXSID7020182')
        projection: Optional projection name. Use 'ccd-genetox-details' for 
            CompTox Dashboard Genetoxicity Details page format. If None, 
            returns default GenetoxDetail data.
        use_cache: Whether to use cache for this request. If None, uses
            the instance default setting.

    Returns:
        List of dictionaries containing detailed genotoxicity data with fields such as:
            - dtxsid (str): Chemical identifier
            - testName (str): Specific test name
            - testType (str): Type of genotoxicity test
            - result (str): Test result (positive/negative/equivocal)
            - strain (str): Biological strain used
            - species (str): Test species
            - metabolicActivation (str): Metabolic activation system used
            - dose (str): Dose information
            - doseUnits (str): Dose units
            - endpoint (str): Measured endpoint
            - reference (str): Study reference
            - source (str): Data source
            - year (int): Study year
            - Notes: Exact fields vary by test type and projection

    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 ToxValDBGenetox
        >>> genetox = ToxValDBGenetox()
        >>> 
        >>> # Get detailed genotoxicity data
        >>> details = genetox.get_detail_by_dtxsid("DTXSID7020182")
        >>> 
        >>> if details:
        ...     print(f"Found {len(details)} detailed genotoxicity test records")
        ...     
        ...     # Group by test type
        ...     by_type = {}
        ...     for detail in details:
        ...         test_type = detail.get('testType', 'Unknown')
        ...         if test_type not in by_type:
        ...             by_type[test_type] = []
        ...         by_type[test_type].append(detail)
        ...     
        ...     # Display results by test type
        ...     for test_type, tests in sorted(by_type.items()):
        ...         print(f"

{test_type}: {len(tests)} test(s)") ...
... # Count positive/negative results ... pos = sum(1 for t in tests if 'positive' in str(t.get('result', '')).lower()) ... neg = sum(1 for t in tests if 'negative' in str(t.get('result', '')).lower()) ... print(f" Positive: {pos}, Negative: {neg}") ...
... # Show example test ... if tests: ... ex = tests[0] ... print(f" Example: {ex.get('testName', 'N/A')}") ... print(f" Result: {ex.get('result', 'N/A')}") ... if ex.get('strain'): ... print(f" Strain: {ex['strain']}") >>> >>> # Get with CompTox Dashboard projection >>> ccd_details = genetox.get_detail_by_dtxsid("DTXSID7020182", ... projection="ccd-genetox-details")

    Note:
        - Detailed data includes individual test results
        - Use projection='ccd-genetox-details' for dashboard-formatted data
        - Results may include multiple tests of the same type under different conditions
Source code in src/pycomptox/hazard/toxvaldbgenetox.py 
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
def get_detail_by_dtxsid(self, dtxsid: str, projection: Optional[str] = None,
                       use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
    """
    Get detailed genotoxicity data by DTXSID.

    Retrieves detailed genotoxicity test information for a chemical, including 
    individual test results, experimental conditions, and study details. 
    Optionally use projection for CompTox Dashboard-specific formatting.

    Args:
        dtxsid: DSSTox Substance Identifier (e.g., 'DTXSID7020182')
        projection: Optional projection name. Use 'ccd-genetox-details' for 
            CompTox Dashboard Genetoxicity Details page format. If None, 
            returns default GenetoxDetail data.
        use_cache: Whether to use cache for this request. If None, uses
            the instance default setting.

    Returns:
        List of dictionaries containing detailed genotoxicity data with fields such as:
            - dtxsid (str): Chemical identifier
            - testName (str): Specific test name
            - testType (str): Type of genotoxicity test
            - result (str): Test result (positive/negative/equivocal)
            - strain (str): Biological strain used
            - species (str): Test species
            - metabolicActivation (str): Metabolic activation system used
            - dose (str): Dose information
            - doseUnits (str): Dose units
            - endpoint (str): Measured endpoint
            - reference (str): Study reference
            - source (str): Data source
            - year (int): Study year
            - Notes: Exact fields vary by test type and projection

    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 ToxValDBGenetox
        >>> genetox = ToxValDBGenetox()
        >>> 
        >>> # Get detailed genotoxicity data
        >>> details = genetox.get_detail_by_dtxsid("DTXSID7020182")
        >>> 
        >>> if details:
        ...     print(f"Found {len(details)} detailed genotoxicity test records")
        ...     
        ...     # Group by test type
        ...     by_type = {}
        ...     for detail in details:
        ...         test_type = detail.get('testType', 'Unknown')
        ...         if test_type not in by_type:
        ...             by_type[test_type] = []
        ...         by_type[test_type].append(detail)
        ...     
        ...     # Display results by test type
        ...     for test_type, tests in sorted(by_type.items()):
        ...         print(f"\n{test_type}: {len(tests)} test(s)")
        ...         
        ...         # Count positive/negative results
        ...         pos = sum(1 for t in tests if 'positive' in str(t.get('result', '')).lower())
        ...         neg = sum(1 for t in tests if 'negative' in str(t.get('result', '')).lower())
        ...         print(f"  Positive: {pos}, Negative: {neg}")
        ...         
        ...         # Show example test
        ...         if tests:
        ...             ex = tests[0]
        ...             print(f"  Example: {ex.get('testName', 'N/A')}")
        ...             print(f"    Result: {ex.get('result', 'N/A')}")
        ...             if ex.get('strain'):
        ...                 print(f"    Strain: {ex['strain']}")
        >>> 
        >>> # Get with CompTox Dashboard projection
        >>> ccd_details = genetox.get_detail_by_dtxsid("DTXSID7020182", 
        ...                                             projection="ccd-genetox-details")

    Note:
        - Detailed data includes individual test results
        - Use projection='ccd-genetox-details' for dashboard-formatted data
        - Results may include multiple tests of the same type under different conditions
    """
    if not dtxsid or not isinstance(dtxsid, str):
        raise ValueError("dtxsid must be a non-empty string")

    endpoint = f"hazard/genetox/details/search/by-dtxsid/{dtxsid}"
    params = {"projection": projection} if projection else None

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

get_detail_by_dtxsid_batch(dtxsids, projection=None, use_cache=None) 

    Get detailed genotoxicity data for multiple chemicals in a single batch request.

    Batch retrieval of detailed genotoxicity test data for up to 200 chemicals.
    More efficient than making individual requests.

    Args:
        dtxsids: List of DSSTox Substance Identifiers (max 200)
        projection: Optional projection name. Use 'ccd-genetox-details' for 
            CompTox Dashboard format.
        use_cache: Whether to use cache for this request. If None, uses
            the instance default setting.

    Returns:
        List of dictionaries containing detailed genotoxicity data for all
        requested chemicals. Each entry includes similar fields as
        get_detail_by_dtxsid().

    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 ToxValDBGenetox
        >>> genetox = ToxValDBGenetox()
        >>> 
        >>> # Get detailed data for multiple chemicals
        >>> dtxsids = ["DTXSID0021125", "DTXSID7020182"]
        >>> batch_details = genetox.get_detail_by_dtxsid_batch(dtxsids)
        >>> 
        >>> # Analyze results
        >>> if batch_details:
        ...     print(f"Retrieved {len(batch_details)} detailed test records")
        ...     
        ...     # Count by chemical
        ...     by_chemical = {}
        ...     for record in batch_details:
        ...         dtxsid = record['dtxsid']
        ...         by_chemical[dtxsid] = by_chemical.get(dtxsid, 0) + 1
        ...     
        ...     for dtxsid, count in by_chemical.items():
        ...         print(f"{dtxsid}: {count} detailed test record(s)")
        ...     
        ...     # Count test types across all chemicals
        ...     test_types = set(r.get('testType') for r in batch_details if r.get('testType'))
        ...     print(f"

Test types represented: {', '.join(sorted(test_types))}")

    Note:
        - Maximum 200 DTXSIDs per request
        - Returns comprehensive test details for all chemicals
        - Batch requests are more efficient than individual queries
        - Results can be large for chemicals with extensive testing
Source code in src/pycomptox/hazard/toxvaldbgenetox.py 
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
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
def get_detail_by_dtxsid_batch(self, dtxsids: List[str], projection: Optional[str] = None,
                       use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
    """
    Get detailed genotoxicity data for multiple chemicals in a single batch request.

    Batch retrieval of detailed genotoxicity test data for up to 200 chemicals.
    More efficient than making individual requests.

    Args:
        dtxsids: List of DSSTox Substance Identifiers (max 200)
        projection: Optional projection name. Use 'ccd-genetox-details' for 
            CompTox Dashboard format.
        use_cache: Whether to use cache for this request. If None, uses
            the instance default setting.

    Returns:
        List of dictionaries containing detailed genotoxicity data for all
        requested chemicals. Each entry includes similar fields as
        get_detail_by_dtxsid().

    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 ToxValDBGenetox
        >>> genetox = ToxValDBGenetox()
        >>> 
        >>> # Get detailed data for multiple chemicals
        >>> dtxsids = ["DTXSID0021125", "DTXSID7020182"]
        >>> batch_details = genetox.get_detail_by_dtxsid_batch(dtxsids)
        >>> 
        >>> # Analyze results
        >>> if batch_details:
        ...     print(f"Retrieved {len(batch_details)} detailed test records")
        ...     
        ...     # Count by chemical
        ...     by_chemical = {}
        ...     for record in batch_details:
        ...         dtxsid = record['dtxsid']
        ...         by_chemical[dtxsid] = by_chemical.get(dtxsid, 0) + 1
        ...     
        ...     for dtxsid, count in by_chemical.items():
        ...         print(f"{dtxsid}: {count} detailed test record(s)")
        ...     
        ...     # Count test types across all chemicals
        ...     test_types = set(r.get('testType') for r in batch_details if r.get('testType'))
        ...     print(f"\nTest types represented: {', '.join(sorted(test_types))}")

    Note:
        - Maximum 200 DTXSIDs per request
        - Returns comprehensive test details for all chemicals
        - Batch requests are more efficient than individual queries
        - Results can be large for chemicals with extensive testing
    """
    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/genetox/details/search/by-dtxsid/"
    params = {"projection": projection} if projection else None

    return self._make_cached_request(
        endpoint, 
        json=dtxsids, 
        method='POST',
        params=params,
        use_cache=use_cache
    )

get_summary_by_dtxsid(dtxsid, use_cache=None) 

    Get genotoxicity summary data by DTXSID.

    Retrieves summary-level genotoxicity test information for a chemical. 
    Summary data provides an overview of genotoxicity testing results across 
    different assay types.

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

    Returns:
        List of dictionaries containing genotoxicity summary data with fields such as:
            - dtxsid (str): Chemical identifier
            - testType (str): Type of genotoxicity test
            - result (str): Overall test result (positive/negative)
            - callSummary (str): Summary of test calls
            - numberOfPositive (int): Number of positive results
            - numberOfNegative (int): Number of negative results
            - numberOfTests (int): Total number of tests
            - source (str): Data source
            - Notes: Exact fields vary by test type

    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 ToxValDBGenetox
        >>> genetox = ToxValDBGenetox()
        >>> 
        >>> # Get genotoxicity summary for benzene
        >>> summary = genetox.get_summary_by_dtxsid("DTXSID0021125")
        >>> 
        >>> if summary:
        ...     print(f"Found {len(summary)} genotoxicity summary records")
        ...     
        ...     for record in summary:
        ...         test_type = record.get('testType', 'Unknown')
        ...         result = record.get('result', 'N/A')
        ...         print(f"

{test_type}: {result}") ...
... if record.get('numberOfTests'): ... pos = record.get('numberOfPositive', 0) ... neg = record.get('numberOfNegative', 0) ... total = record.get('numberOfTests', 0) ... print(f" Tests: {pos} positive, {neg} negative (out of {total} total)") >>> else: ... print("No genotoxicity summary data available")

    Note:
        - Not all chemicals have genotoxicity test data
        - Summary provides overview across multiple tests
        - For detailed test results, use get_detail_by_dtxsid()
Source code in src/pycomptox/hazard/toxvaldbgenetox.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
def get_summary_by_dtxsid(self, dtxsid: str, 
                          use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
    """
    Get genotoxicity summary data by DTXSID.

    Retrieves summary-level genotoxicity test information for a chemical. 
    Summary data provides an overview of genotoxicity testing results across 
    different assay types.

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

    Returns:
        List of dictionaries containing genotoxicity summary data with fields such as:
            - dtxsid (str): Chemical identifier
            - testType (str): Type of genotoxicity test
            - result (str): Overall test result (positive/negative)
            - callSummary (str): Summary of test calls
            - numberOfPositive (int): Number of positive results
            - numberOfNegative (int): Number of negative results
            - numberOfTests (int): Total number of tests
            - source (str): Data source
            - Notes: Exact fields vary by test type

    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 ToxValDBGenetox
        >>> genetox = ToxValDBGenetox()
        >>> 
        >>> # Get genotoxicity summary for benzene
        >>> summary = genetox.get_summary_by_dtxsid("DTXSID0021125")
        >>> 
        >>> if summary:
        ...     print(f"Found {len(summary)} genotoxicity summary records")
        ...     
        ...     for record in summary:
        ...         test_type = record.get('testType', 'Unknown')
        ...         result = record.get('result', 'N/A')
        ...         print(f"\n{test_type}: {result}")
        ...         
        ...         if record.get('numberOfTests'):
        ...             pos = record.get('numberOfPositive', 0)
        ...             neg = record.get('numberOfNegative', 0)
        ...             total = record.get('numberOfTests', 0)
        ...             print(f"  Tests: {pos} positive, {neg} negative (out of {total} total)")
        >>> else:
        ...     print("No genotoxicity summary data available")

    Note:
        - Not all chemicals have genotoxicity test data
        - Summary provides overview across multiple tests
        - For detailed test results, use get_detail_by_dtxsid()
    """
    if not dtxsid or not isinstance(dtxsid, str):
        raise ValueError("dtxsid must be a non-empty string")

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

get_summary_by_dtxsid_batch(dtxsids, use_cache=None) 

    Get genotoxicity summary data for multiple chemicals in a single batch request.

    Batch retrieval of genotoxicity summary data for up to 200 chemicals.
    More efficient than making individual requests.

    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 genotoxicity summary data for all
        requested chemicals. Each entry includes similar fields as
        get_summary_by_dtxsid().

    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 ToxValDBGenetox
        >>> genetox = ToxValDBGenetox()
        >>> 
        >>> # Get summary for multiple chemicals
        >>> dtxsids = ["DTXSID0021125", "DTXSID7020182", "DTXSID0020032"]
        >>> batch_summary = genetox.get_summary_by_dtxsid_batch(dtxsids)
        >>> 
        >>> # Group by chemical
        >>> by_chemical = {}
        >>> for record in batch_summary:
        ...     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)} test type(s)") ...
... # Check for positive results ... positive = [r for r in records if 'positive' in str(r.get('result', '')).lower()] ... if positive: ... print(f" WARNING: {len(positive)} positive genotoxicity result(s)")

    Note:
        - Maximum 200 DTXSIDs per request
        - Batch requests are more efficient than individual queries
        - Useful for screening chemical libraries for genotoxicity
Source code in src/pycomptox/hazard/toxvaldbgenetox.py 
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
def get_summary_by_dtxsid_batch(self, dtxsids: List[str], 
                          use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
    """
    Get genotoxicity summary data for multiple chemicals in a single batch request.

    Batch retrieval of genotoxicity summary data for up to 200 chemicals.
    More efficient than making individual requests.

    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 genotoxicity summary data for all
        requested chemicals. Each entry includes similar fields as
        get_summary_by_dtxsid().

    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 ToxValDBGenetox
        >>> genetox = ToxValDBGenetox()
        >>> 
        >>> # Get summary for multiple chemicals
        >>> dtxsids = ["DTXSID0021125", "DTXSID7020182", "DTXSID0020032"]
        >>> batch_summary = genetox.get_summary_by_dtxsid_batch(dtxsids)
        >>> 
        >>> # Group by chemical
        >>> by_chemical = {}
        >>> for record in batch_summary:
        ...     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)} test type(s)")
        ...     
        ...     # Check for positive results
        ...     positive = [r for r in records if 'positive' in str(r.get('result', '')).lower()]
        ...     if positive:
        ...         print(f"  WARNING: {len(positive)} positive genotoxicity result(s)")

    Note:
        - Maximum 200 DTXSIDs per request
        - Batch requests are more efficient than individual queries
        - Useful for screening chemical libraries for genotoxicity
    """
    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/genetox/summary/search/by-dtxsid/"
    return self._make_cached_request(
        endpoint, 
        json=dtxsids, 
        method='POST', 
        use_cache=use_cache
    )