Skip to content

Bioactivity Data API Reference

pycomptox.bioactivity.bioactivitydata.BioactivityData

Bases: CachedAPIClient

Client for accessing bioactivity data from EPA CompTox Dashboard.

This class provides methods for retrieving: - Summary data by DTXSID, tissue, and AEID - Detailed bioactivity data records - AED (Activity-Exposure-Dose) data - Batch operations for multiple identifiers

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
Example

from pycomptox import BioactivityData client = BioactivityData()

Get summary data

summary = client.get_summary_by_dtxsid("DTXSID9026974")

Get data by AEID

data = client.get_data_by_aeid(3032)

Source code in src/pycomptox/bioactivity/bioactivitydata.py 
 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
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
class BioactivityData(CachedAPIClient):
    """
    Client for accessing bioactivity data from EPA CompTox Dashboard.

    This class provides methods for retrieving:
    - Summary data by DTXSID, tissue, and AEID
    - Detailed bioactivity data records
    - AED (Activity-Exposure-Dose) data
    - Batch operations for multiple identifiers

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

    Example:
        >>> from pycomptox import BioactivityData
        >>> client = BioactivityData()
        >>> 
        >>> # Get summary data
        >>> summary = client.get_summary_by_dtxsid("DTXSID9026974")
        >>> 
        >>> # Get data by AEID
        >>> data = client.get_data_by_aeid(3032)
    """

    def __init__(
        self,
        api_key: Optional[str] = None,
        base_url: str = "https://comptox.epa.gov/ctx-api/",
        time_delay_between_calls: float = 0.0,
        **kwargs
    ):
        """
        Initialize the BioactivityData 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_and_tissue(self, dtxsid: str, tissue: str, use_cache: Optional[bool] = None) -> dict:
        """
        Get bioactivity summary data for a chemical filtered by tissue type.

        Retrieves summary bioactivity data for a specific chemical (by DTXSID)
        filtered by tissue of origin.

        Args:
            dtxsid: DSSTox Substance Identifier (e.g., 'DTXSID7024241')
            tissue: Tissue of origin (e.g., 'liver', 'kidney')

        Returns:
            Dictionary containing summary bioactivity data including:
                - intendedTargetFamily: Target family
                - dtxsid: Chemical identifier
                - tissue: Tissue type
                - maxMedConc: Maximum median concentration
                - continuousHitCall: Continuous hit call value
                - chemicalName: Name of chemical
                - hitCall: Hit call classification
                - cutOff: Activity cutoff value
                - logAC50: Log of AC50 value
                - ac50: Half maximal activity concentration
                - acc: Activity concentration at cutoff

        Raises:
            ValueError: If dtxsid or tissue is not a valid string

        Example:
            >>> client = BioactivityData()
            >>> summary = client.get_summary_by_dtxsid_and_tissue('DTXSID7024241', 'liver')
            >>> print(summary['chemicalName'])
        """
        if not dtxsid or not isinstance(dtxsid, str):
            raise ValueError("dtxsid must be a non-empty string")
        if not tissue or not isinstance(tissue, str):
            raise ValueError("tissue must be a non-empty string")

        endpoint = "bioactivity/data/summary/search/by-tissue/"
        params = {"dtxsid": dtxsid, "tissue": tissue}
        return self._make_cached_request(endpoint, params=params, use_cache=use_cache)

    def get_summary_by_dtxsid(self, dtxsid: str, use_cache: Optional[bool] = None) -> dict:
        """
        Get bioactivity summary data for a chemical.

        Retrieves summary bioactivity data for a specific chemical identified
        by its DSSTox Substance Identifier (DTXSID).

        Args:
            dtxsid: DSSTox Substance Identifier (e.g., 'DTXSID9026974')

        Returns:
            Summary bioactivity data for the chemical

        Raises:
            ValueError: If dtxsid is not a valid string

        Example:
            >>> client = BioactivityData()
            >>> summary = client.get_summary_by_dtxsid('DTXSID9026974')
        """
        if not dtxsid or not isinstance(dtxsid, str):
            raise ValueError("dtxsid must be a non-empty string")

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

    def get_summary_by_aeid(self, aeid: str, use_cache: Optional[bool] = None) -> dict:
        """
        Get summary by aeid
        get /bioactivity/data/summary/search/by-aeid/{aeid}
        Return summary data for given aeid
        aeid int32 Numeric assay endpoint identifier
        Examples: 3032

        curl -X GET "https://comptox.epa.gov/ctx-api/bioactivity/data/summary/search/by-aeid/3032" \
        -H 'accept: application/json' 

        response
        200 OK
        US EPA's Toxicity Forecaster (ToxCast) program makes invitro medium- and high-throughput screening assay data publicly available for prioritization and hazard characterization.The summary endpoint returns the number of active hits and total multi- and single-concentration chemicals tested for specific ‘aeids’. For multi-concentration data, a continuous hit call value greater than or equal to 0.9 is considered active, whereas values less than 0.9 are considered inactive. For single concentration data, the hit call value is binary where 1 is active and 0 is inactive. Multiple samples of the same chemical may be tested for a given assay endpoint, and all samples per endpoint are reflected in these counts.
        {
        "aeid": 0,
        "activeMc": 0,
        "totalMc": 0,
        "activeSc": 0,
        "totalSc": 0
        }
        """
        if not isinstance(aeid, (int, str)):
            raise ValueError("aeid must be an integer or string")

        endpoint = f"bioactivity/data/summary/search/by-aeid/{aeid}"
        return self._make_cached_request(endpoint, use_cache=use_cache)

    def get_data_by_spid(self, spid: str, use_cache: Optional[bool] = None) -> dict:
        """
        Get bioactivity data by sample identifier.

        Retrieves bioactivity data for a specific sample identified by its SPID
        (Sample Identifier).

        Args:
            spid: Sample identifier (e.g., 'EPAPLT0232A03')

        Returns:
            Bioactivity data for the specified sample

        Raises:
            ValueError: If spid is not a valid non-empty string

        Example:
            >>> client = BioactivityData()
            >>> data = client.get_data_by_spid('EPAPLT0232A03')
        """
        if not spid or not isinstance(spid, str):
            raise ValueError("spid must be a non-empty string")

        endpoint = f"bioactivity/data/search/by-spid/{spid}"
        return self._make_cached_request(endpoint, use_cache=use_cache)

    def get_data_by_m4id(self, m4id: str, use_cache: Optional[bool] = None) -> dict:
        """
        Get bioactivity data by data identifier.

        Retrieves a single bioactivity data record for a specific M4ID
        (numeric data identifier).

        Args:
            m4id: Numeric data identifier (e.g., '1135145')

        Returns:
            Single bioactivity data record for the specified M4ID

        Raises:
            ValueError: If m4id is not an integer or string

        Example:
            >>> client = BioactivityData()
            >>> data = client.get_data_by_m4id('1135145')
        """
        if not isinstance(m4id, (int, str)):
            raise ValueError("m4id must be an integer or string")

        endpoint = f"bioactivity/data/search/by-m4id/{m4id}"
        return self._make_cached_request(endpoint, use_cache=use_cache)

    def get_data_by_dtxsid_and_projection(self, dtxsid: str, projection: str="", use_cache: Optional[bool] = None) -> dict:
        """
        Get bioactivity data for a chemical with optional projection.

        Retrieves bioactivity data for a specific chemical identified by DTXSID,
        with optional projection parameter to control the format of returned data.

        Args:
            dtxsid: DSSTox Substance Identifier (e.g., 'DTXSID7020182')
            projection: Optional projection type. Use 'toxcast-summary-plot' for
                summary plot data, or omit for default BioactivityDataAll format.

        Returns:
            Bioactivity data for the chemical in requested format

        Raises:
            ValueError: If dtxsid is not a valid non-empty string

        Example:
            >>> client = BioactivityData()
            >>> # Get default format
            >>> data = client.get_data_by_dtxsid_and_projection('DTXSID7020182')
            >>> # Get summary plot format
            >>> plot_data = client.get_data_by_dtxsid_and_projection(
            ...     'DTXSID7020182', projection='toxcast-summary-plot')
        """
        if not dtxsid or not isinstance(dtxsid, str):
            raise ValueError("dtxsid must be a non-empty string")

        endpoint = f"bioactivity/data/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_data_by_aeid(self, aeid: int, use_cache: Optional[bool] = None) -> dict:
        """
        Get detailed bioactivity data for an assay endpoint.

        Retrieves all bioactivity data records associated with a specific
        assay endpoint identifier (AEID).

        Args:
            aeid: Numeric assay endpoint identifier (e.g., 3032)

        Returns:
            All bioactivity data records for the specified assay endpoint

        Raises:
            ValueError: If aeid is not a positive integer

        Example:
            >>> client = BioactivityData()
            >>> data = client.get_data_by_aeid(3032)
        """
        if not isinstance(aeid, int) or aeid <= 0:
            raise ValueError("aeid must be a positive integer")

        endpoint = f"bioactivity/data/search/by-aeid/{aeid}"
        return self._make_cached_request(endpoint, use_cache=use_cache)

    def get_aed_data_by_dtxsid(self, dtxsid: str, use_cache: Optional[bool] = None) -> dict:
        """
        Get Activity-Exposure-Dose (AED) data for a chemical.

        Retrieves AED bioactivity data for a specific chemical identified
        by its DSSTox Substance Identifier (DTXSID).

        Args:
            dtxsid: DSSTox Substance Identifier (e.g., 'DTXSID5021209')

        Returns:
            AED bioactivity data for the chemical

        Raises:
            ValueError: If dtxsid is not a valid non-empty string

        Example:
            >>> client = BioactivityData()
            >>> aed_data = client.get_aed_data_by_dtxsid('DTXSID5021209')
        """
        if not dtxsid or not isinstance(dtxsid, str):
            raise ValueError("dtxsid must be a non-empty string")

        endpoint = f"bioactivity/data/aed/search/by-dtxsid/{dtxsid}"
        return self._make_cached_request(endpoint, use_cache=use_cache)

    def find_bioactivity_data_by_spid_batch(self, spids: list, use_cache: Optional[bool] = None) -> dict:
        """
        Batch retrieve bioactivity data by sample identifiers.

        Retrieves bioactivity data for multiple samples in a single request.

        Args:
            spids: List of sample identifiers (e.g., ['EPAPLT0232A03', 'EPAPLT0232A04'])

        Returns:
            Bioactivity data for all requested sample identifiers

        Raises:
            ValueError: If spids is not a non-empty list or contains non-string values

        Example:
            >>> client = BioactivityData()
            >>> data = client.find_bioactivity_data_by_spid_batch(
            ...     ['EPAPLT0232A03', 'EPAPLT0232A04'])
        """
        if not spids or not isinstance(spids, list):
            raise ValueError("spids must be a non-empty list")
        if not all(isinstance(spid, str) for spid in spids):
            raise ValueError("All spids must be strings")

        endpoint = "bioactivity/data/search/by-spid/"
        # Note: Batch POST requests bypass cache since they're not typically cacheable
        self._enforce_rate_limit()
        url = f"{self.base_url}{endpoint}"
        response = self.session.post(url, json=spids)
        response.raise_for_status()
        return response.json()

    def find_bioactivity_data_by_m4id_batch(self, m4ids: list, use_cache: Optional[bool] = None) -> dict:
        """
        Batch retrieve bioactivity data by data identifiers.

        Retrieves bioactivity data for multiple M4IDs (data identifiers) in a single request.

        Args:
            m4ids: List of numeric data identifiers (e.g., [1135145, 1135146])

        Returns:
            Bioactivity data for all requested data identifiers

        Raises:
            ValueError: If m4ids is not a non-empty list or contains invalid values

        Example:
            >>> client = BioactivityData()
            >>> data = client.find_bioactivity_data_by_m4id_batch([1135145, 1135146])
        """
        if not m4ids or not isinstance(m4ids, list):
            raise ValueError("m4ids must be a non-empty list")
        if not all(isinstance(m4id, (int, str)) for m4id in m4ids):
            raise ValueError("All m4ids must be integers or strings")

        endpoint = "bioactivity/data/search/by-m4id/"
        # Note: Batch POST requests bypass cache since they're not typically cacheable
        self._enforce_rate_limit()
        url = f"{self.base_url}{endpoint}"
        response = self.session.post(url, json=m4ids)
        response.raise_for_status()
        return response.json()

    def find_bioactivity_data_by_dtxsid_batch(self, dtxsids: list, use_cache: Optional[bool] = None) -> dict:
        """
        Batch retrieve bioactivity data by chemical identifiers.

        Retrieves bioactivity data for multiple chemicals identified by their
        DSSTox Substance Identifiers (DTXSIDs) in a single request.

        Args:
            dtxsids: List of DSSTox Substance Identifiers
                (e.g., ['DTXSID7020182', 'DTXSID9026974'])

        Returns:
            Bioactivity data for all requested chemicals

        Raises:
            ValueError: If dtxsids is not a non-empty list or contains non-string values

        Example:
            >>> client = BioactivityData()
            >>> data = client.find_bioactivity_data_by_dtxsid_batch(
            ...     ['DTXSID7020182', 'DTXSID9026974'])
        """
        if not dtxsids or not isinstance(dtxsids, list):
            raise ValueError("dtxsids must be a non-empty list")
        if not all(isinstance(dtxsid, str) for dtxsid in dtxsids):
            raise ValueError("All dtxsids must be strings")

        endpoint = "bioactivity/data/search/by-dtxsid/"
        # Note: Batch POST requests bypass cache since they're not typically cacheable
        self._enforce_rate_limit()
        url = f"{self.base_url}{endpoint}"
        response = self.session.post(url, json=dtxsids)
        response.raise_for_status()
        return response.json()

    def find_bioactivity_data_by_aeid_batch(self, aeids: list, use_cache: Optional[bool] = None) -> dict:
        """
        Batch retrieve bioactivity data by assay endpoint identifiers.

        Retrieves bioactivity data for multiple assay endpoints in a single request.

        Args:
            aeids: List of numeric assay endpoint identifiers (e.g., [3032, 3033])

        Returns:
            Bioactivity data for all requested assay endpoints

        Raises:
            ValueError: If aeids is not a non-empty list or contains non-positive integers

        Example:
            >>> client = BioactivityData()
            >>> data = client.find_bioactivity_data_by_aeid_batch([3032, 3033])
        """
        if not aeids or not isinstance(aeids, list):
            raise ValueError("aeids must be a non-empty list")
        if not all(isinstance(aeid, int) and aeid > 0 for aeid in aeids):
            raise ValueError("All aeids must be positive integers")

        endpoint = "bioactivity/data/search/by-aeid/"
        # Note: Batch POST requests bypass cache since they're not typically cacheable
        self._enforce_rate_limit()
        url = f"{self.base_url}{endpoint}"
        response = self.session.post(url, json=aeids)
        response.raise_for_status()
        return response.json()

    def find_aed_data_by_dtxsid_batch(self, dtxsids: list, use_cache: Optional[bool] = None) -> dict:
        """
        Batch retrieve Activity-Exposure-Dose (AED) data by chemical identifiers.

        Retrieves AED bioactivity data for multiple chemicals identified by their
        DSSTox Substance Identifiers (DTXSIDs) in a single request.

        Args:
            dtxsids: List of DSSTox Substance Identifiers
                (e.g., ['DTXSID5021209', 'DTXSID7020182'])

        Returns:
            AED bioactivity data for all requested chemicals

        Raises:
            ValueError: If dtxsids is not a non-empty list or contains non-string values

        Example:
            >>> client = BioactivityData()
            >>> aed_data = client.find_aed_data_by_dtxsid_batch(
            ...     ['DTXSID5021209', 'DTXSID7020182'])
        """
        if not dtxsids or not isinstance(dtxsids, list):
            raise ValueError("dtxsids must be a non-empty list")
        if not all(isinstance(dtxsid, str) for dtxsid in dtxsids):
            raise ValueError("All dtxsids must be strings")

        endpoint = "bioactivity/data/aed/search/by-dtxsid"
        # Note: Batch POST requests bypass cache since they're not typically cacheable
        self._enforce_rate_limit()
        url = f"{self.base_url}{endpoint}"
        response = self.session.post(url, json=dtxsids)
        response.raise_for_status()
        return response.json()

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

Initialize the BioactivityData 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

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/bioactivity/bioactivitydata.py 
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
def __init__(
    self,
    api_key: Optional[str] = None,
    base_url: str = "https://comptox.epa.gov/ctx-api/",
    time_delay_between_calls: float = 0.0,
    **kwargs
):
    """
    Initialize the BioactivityData 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
    )

find_aed_data_by_dtxsid_batch(dtxsids, use_cache=None)

Batch retrieve Activity-Exposure-Dose (AED) data by chemical identifiers.

Retrieves AED bioactivity data for multiple chemicals identified by their DSSTox Substance Identifiers (DTXSIDs) in a single request.

Parameters:

Name Type Description Default
dtxsids list

List of DSSTox Substance Identifiers (e.g., ['DTXSID5021209', 'DTXSID7020182'])

 required

Returns:

Type Description
dict

AED bioactivity data for all requested chemicals

Raises:

Type Description
ValueError

If dtxsids is not a non-empty list or contains non-string values
Example

client = BioactivityData() aed_data = client.find_aed_data_by_dtxsid_batch( ... ['DTXSID5021209', 'DTXSID7020182'])

Source code in src/pycomptox/bioactivity/bioactivitydata.py 
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
def find_aed_data_by_dtxsid_batch(self, dtxsids: list, use_cache: Optional[bool] = None) -> dict:
    """
    Batch retrieve Activity-Exposure-Dose (AED) data by chemical identifiers.

    Retrieves AED bioactivity data for multiple chemicals identified by their
    DSSTox Substance Identifiers (DTXSIDs) in a single request.

    Args:
        dtxsids: List of DSSTox Substance Identifiers
            (e.g., ['DTXSID5021209', 'DTXSID7020182'])

    Returns:
        AED bioactivity data for all requested chemicals

    Raises:
        ValueError: If dtxsids is not a non-empty list or contains non-string values

    Example:
        >>> client = BioactivityData()
        >>> aed_data = client.find_aed_data_by_dtxsid_batch(
        ...     ['DTXSID5021209', 'DTXSID7020182'])
    """
    if not dtxsids or not isinstance(dtxsids, list):
        raise ValueError("dtxsids must be a non-empty list")
    if not all(isinstance(dtxsid, str) for dtxsid in dtxsids):
        raise ValueError("All dtxsids must be strings")

    endpoint = "bioactivity/data/aed/search/by-dtxsid"
    # Note: Batch POST requests bypass cache since they're not typically cacheable
    self._enforce_rate_limit()
    url = f"{self.base_url}{endpoint}"
    response = self.session.post(url, json=dtxsids)
    response.raise_for_status()
    return response.json()

find_bioactivity_data_by_aeid_batch(aeids, use_cache=None)

Batch retrieve bioactivity data by assay endpoint identifiers.

Retrieves bioactivity data for multiple assay endpoints in a single request.

Parameters:

Name Type Description Default
aeids list

List of numeric assay endpoint identifiers (e.g., [3032, 3033])

 required

Returns:

Type Description
dict

Bioactivity data for all requested assay endpoints

Raises:

Type Description
ValueError

If aeids is not a non-empty list or contains non-positive integers
Example

client = BioactivityData() data = client.find_bioactivity_data_by_aeid_batch([3032, 3033])

Source code in src/pycomptox/bioactivity/bioactivitydata.py 
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
def find_bioactivity_data_by_aeid_batch(self, aeids: list, use_cache: Optional[bool] = None) -> dict:
    """
    Batch retrieve bioactivity data by assay endpoint identifiers.

    Retrieves bioactivity data for multiple assay endpoints in a single request.

    Args:
        aeids: List of numeric assay endpoint identifiers (e.g., [3032, 3033])

    Returns:
        Bioactivity data for all requested assay endpoints

    Raises:
        ValueError: If aeids is not a non-empty list or contains non-positive integers

    Example:
        >>> client = BioactivityData()
        >>> data = client.find_bioactivity_data_by_aeid_batch([3032, 3033])
    """
    if not aeids or not isinstance(aeids, list):
        raise ValueError("aeids must be a non-empty list")
    if not all(isinstance(aeid, int) and aeid > 0 for aeid in aeids):
        raise ValueError("All aeids must be positive integers")

    endpoint = "bioactivity/data/search/by-aeid/"
    # Note: Batch POST requests bypass cache since they're not typically cacheable
    self._enforce_rate_limit()
    url = f"{self.base_url}{endpoint}"
    response = self.session.post(url, json=aeids)
    response.raise_for_status()
    return response.json()

find_bioactivity_data_by_dtxsid_batch(dtxsids, use_cache=None)

Batch retrieve bioactivity data by chemical identifiers.

Retrieves bioactivity data for multiple chemicals identified by their DSSTox Substance Identifiers (DTXSIDs) in a single request.

Parameters:

Name Type Description Default
dtxsids list

List of DSSTox Substance Identifiers (e.g., ['DTXSID7020182', 'DTXSID9026974'])

 required

Returns:

Type Description
dict

Bioactivity data for all requested chemicals

Raises:

Type Description
ValueError

If dtxsids is not a non-empty list or contains non-string values
Example

client = BioactivityData() data = client.find_bioactivity_data_by_dtxsid_batch( ... ['DTXSID7020182', 'DTXSID9026974'])

Source code in src/pycomptox/bioactivity/bioactivitydata.py 
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
def find_bioactivity_data_by_dtxsid_batch(self, dtxsids: list, use_cache: Optional[bool] = None) -> dict:
    """
    Batch retrieve bioactivity data by chemical identifiers.

    Retrieves bioactivity data for multiple chemicals identified by their
    DSSTox Substance Identifiers (DTXSIDs) in a single request.

    Args:
        dtxsids: List of DSSTox Substance Identifiers
            (e.g., ['DTXSID7020182', 'DTXSID9026974'])

    Returns:
        Bioactivity data for all requested chemicals

    Raises:
        ValueError: If dtxsids is not a non-empty list or contains non-string values

    Example:
        >>> client = BioactivityData()
        >>> data = client.find_bioactivity_data_by_dtxsid_batch(
        ...     ['DTXSID7020182', 'DTXSID9026974'])
    """
    if not dtxsids or not isinstance(dtxsids, list):
        raise ValueError("dtxsids must be a non-empty list")
    if not all(isinstance(dtxsid, str) for dtxsid in dtxsids):
        raise ValueError("All dtxsids must be strings")

    endpoint = "bioactivity/data/search/by-dtxsid/"
    # Note: Batch POST requests bypass cache since they're not typically cacheable
    self._enforce_rate_limit()
    url = f"{self.base_url}{endpoint}"
    response = self.session.post(url, json=dtxsids)
    response.raise_for_status()
    return response.json()

find_bioactivity_data_by_m4id_batch(m4ids, use_cache=None)

Batch retrieve bioactivity data by data identifiers.

Retrieves bioactivity data for multiple M4IDs (data identifiers) in a single request.

Parameters:

Name Type Description Default
m4ids list

List of numeric data identifiers (e.g., [1135145, 1135146])

 required

Returns:

Type Description
dict

Bioactivity data for all requested data identifiers

Raises:

Type Description
ValueError

If m4ids is not a non-empty list or contains invalid values
Example

client = BioactivityData() data = client.find_bioactivity_data_by_m4id_batch([1135145, 1135146])

Source code in src/pycomptox/bioactivity/bioactivitydata.py 
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
def find_bioactivity_data_by_m4id_batch(self, m4ids: list, use_cache: Optional[bool] = None) -> dict:
    """
    Batch retrieve bioactivity data by data identifiers.

    Retrieves bioactivity data for multiple M4IDs (data identifiers) in a single request.

    Args:
        m4ids: List of numeric data identifiers (e.g., [1135145, 1135146])

    Returns:
        Bioactivity data for all requested data identifiers

    Raises:
        ValueError: If m4ids is not a non-empty list or contains invalid values

    Example:
        >>> client = BioactivityData()
        >>> data = client.find_bioactivity_data_by_m4id_batch([1135145, 1135146])
    """
    if not m4ids or not isinstance(m4ids, list):
        raise ValueError("m4ids must be a non-empty list")
    if not all(isinstance(m4id, (int, str)) for m4id in m4ids):
        raise ValueError("All m4ids must be integers or strings")

    endpoint = "bioactivity/data/search/by-m4id/"
    # Note: Batch POST requests bypass cache since they're not typically cacheable
    self._enforce_rate_limit()
    url = f"{self.base_url}{endpoint}"
    response = self.session.post(url, json=m4ids)
    response.raise_for_status()
    return response.json()

find_bioactivity_data_by_spid_batch(spids, use_cache=None)

Batch retrieve bioactivity data by sample identifiers.

Retrieves bioactivity data for multiple samples in a single request.

Parameters:

Name Type Description Default
spids list

List of sample identifiers (e.g., ['EPAPLT0232A03', 'EPAPLT0232A04'])

 required

Returns:

Type Description
dict

Bioactivity data for all requested sample identifiers

Raises:

Type Description
ValueError

If spids is not a non-empty list or contains non-string values
Example

client = BioactivityData() data = client.find_bioactivity_data_by_spid_batch( ... ['EPAPLT0232A03', 'EPAPLT0232A04'])

Source code in src/pycomptox/bioactivity/bioactivitydata.py 
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
def find_bioactivity_data_by_spid_batch(self, spids: list, use_cache: Optional[bool] = None) -> dict:
    """
    Batch retrieve bioactivity data by sample identifiers.

    Retrieves bioactivity data for multiple samples in a single request.

    Args:
        spids: List of sample identifiers (e.g., ['EPAPLT0232A03', 'EPAPLT0232A04'])

    Returns:
        Bioactivity data for all requested sample identifiers

    Raises:
        ValueError: If spids is not a non-empty list or contains non-string values

    Example:
        >>> client = BioactivityData()
        >>> data = client.find_bioactivity_data_by_spid_batch(
        ...     ['EPAPLT0232A03', 'EPAPLT0232A04'])
    """
    if not spids or not isinstance(spids, list):
        raise ValueError("spids must be a non-empty list")
    if not all(isinstance(spid, str) for spid in spids):
        raise ValueError("All spids must be strings")

    endpoint = "bioactivity/data/search/by-spid/"
    # Note: Batch POST requests bypass cache since they're not typically cacheable
    self._enforce_rate_limit()
    url = f"{self.base_url}{endpoint}"
    response = self.session.post(url, json=spids)
    response.raise_for_status()
    return response.json()

get_aed_data_by_dtxsid(dtxsid, use_cache=None)

Get Activity-Exposure-Dose (AED) data for a chemical.

Retrieves AED bioactivity data for a specific chemical identified by its DSSTox Substance Identifier (DTXSID).

Parameters:

Name Type Description Default
dtxsid str

DSSTox Substance Identifier (e.g., 'DTXSID5021209')

 required

Returns:

Type Description
dict

AED bioactivity data for the chemical

Raises:

Type Description
ValueError

If dtxsid is not a valid non-empty string
Example

client = BioactivityData() aed_data = client.get_aed_data_by_dtxsid('DTXSID5021209')

Source code in src/pycomptox/bioactivity/bioactivitydata.py 
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
def get_aed_data_by_dtxsid(self, dtxsid: str, use_cache: Optional[bool] = None) -> dict:
    """
    Get Activity-Exposure-Dose (AED) data for a chemical.

    Retrieves AED bioactivity data for a specific chemical identified
    by its DSSTox Substance Identifier (DTXSID).

    Args:
        dtxsid: DSSTox Substance Identifier (e.g., 'DTXSID5021209')

    Returns:
        AED bioactivity data for the chemical

    Raises:
        ValueError: If dtxsid is not a valid non-empty string

    Example:
        >>> client = BioactivityData()
        >>> aed_data = client.get_aed_data_by_dtxsid('DTXSID5021209')
    """
    if not dtxsid or not isinstance(dtxsid, str):
        raise ValueError("dtxsid must be a non-empty string")

    endpoint = f"bioactivity/data/aed/search/by-dtxsid/{dtxsid}"
    return self._make_cached_request(endpoint, use_cache=use_cache)

get_data_by_aeid(aeid, use_cache=None)

Get detailed bioactivity data for an assay endpoint.

Retrieves all bioactivity data records associated with a specific assay endpoint identifier (AEID).

Parameters:

Name Type Description Default
aeid int

Numeric assay endpoint identifier (e.g., 3032)

 required

Returns:

Type Description
dict

All bioactivity data records for the specified assay endpoint

Raises:

Type Description
ValueError

If aeid is not a positive integer
Example

client = BioactivityData() data = client.get_data_by_aeid(3032)

Source code in src/pycomptox/bioactivity/bioactivitydata.py 
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
def get_data_by_aeid(self, aeid: int, use_cache: Optional[bool] = None) -> dict:
    """
    Get detailed bioactivity data for an assay endpoint.

    Retrieves all bioactivity data records associated with a specific
    assay endpoint identifier (AEID).

    Args:
        aeid: Numeric assay endpoint identifier (e.g., 3032)

    Returns:
        All bioactivity data records for the specified assay endpoint

    Raises:
        ValueError: If aeid is not a positive integer

    Example:
        >>> client = BioactivityData()
        >>> data = client.get_data_by_aeid(3032)
    """
    if not isinstance(aeid, int) or aeid <= 0:
        raise ValueError("aeid must be a positive integer")

    endpoint = f"bioactivity/data/search/by-aeid/{aeid}"
    return self._make_cached_request(endpoint, use_cache=use_cache)

get_data_by_dtxsid_and_projection(dtxsid, projection='', use_cache=None)

Get bioactivity data for a chemical with optional projection.

Retrieves bioactivity data for a specific chemical identified by DTXSID, with optional projection parameter to control the format of returned data.

Parameters:

Name Type Description Default
dtxsid str

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

 required
projection str

Optional projection type. Use 'toxcast-summary-plot' for summary plot data, or omit for default BioactivityDataAll format.

 ''

Returns:

Type Description
dict

Bioactivity data for the chemical in requested format

Raises:

Type Description
ValueError

If dtxsid is not a valid non-empty string
Example

client = BioactivityData()

Get default format

data = client.get_data_by_dtxsid_and_projection('DTXSID7020182')

Get summary plot format

plot_data = client.get_data_by_dtxsid_and_projection( ... 'DTXSID7020182', projection='toxcast-summary-plot')

Source code in src/pycomptox/bioactivity/bioactivitydata.py 
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
def get_data_by_dtxsid_and_projection(self, dtxsid: str, projection: str="", use_cache: Optional[bool] = None) -> dict:
    """
    Get bioactivity data for a chemical with optional projection.

    Retrieves bioactivity data for a specific chemical identified by DTXSID,
    with optional projection parameter to control the format of returned data.

    Args:
        dtxsid: DSSTox Substance Identifier (e.g., 'DTXSID7020182')
        projection: Optional projection type. Use 'toxcast-summary-plot' for
            summary plot data, or omit for default BioactivityDataAll format.

    Returns:
        Bioactivity data for the chemical in requested format

    Raises:
        ValueError: If dtxsid is not a valid non-empty string

    Example:
        >>> client = BioactivityData()
        >>> # Get default format
        >>> data = client.get_data_by_dtxsid_and_projection('DTXSID7020182')
        >>> # Get summary plot format
        >>> plot_data = client.get_data_by_dtxsid_and_projection(
        ...     'DTXSID7020182', projection='toxcast-summary-plot')
    """
    if not dtxsid or not isinstance(dtxsid, str):
        raise ValueError("dtxsid must be a non-empty string")

    endpoint = f"bioactivity/data/search/by-dtxsid/{dtxsid}"
    params = {"projection": projection} if projection else None
    return self._make_cached_request(endpoint, params=params, use_cache=use_cache)

get_data_by_m4id(m4id, use_cache=None)

Get bioactivity data by data identifier.

Retrieves a single bioactivity data record for a specific M4ID (numeric data identifier).

Parameters:

Name Type Description Default
m4id str

Numeric data identifier (e.g., '1135145')

 required

Returns:

Type Description
dict

Single bioactivity data record for the specified M4ID

Raises:

Type Description
ValueError

If m4id is not an integer or string
Example

client = BioactivityData() data = client.get_data_by_m4id('1135145')

Source code in src/pycomptox/bioactivity/bioactivitydata.py 
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
def get_data_by_m4id(self, m4id: str, use_cache: Optional[bool] = None) -> dict:
    """
    Get bioactivity data by data identifier.

    Retrieves a single bioactivity data record for a specific M4ID
    (numeric data identifier).

    Args:
        m4id: Numeric data identifier (e.g., '1135145')

    Returns:
        Single bioactivity data record for the specified M4ID

    Raises:
        ValueError: If m4id is not an integer or string

    Example:
        >>> client = BioactivityData()
        >>> data = client.get_data_by_m4id('1135145')
    """
    if not isinstance(m4id, (int, str)):
        raise ValueError("m4id must be an integer or string")

    endpoint = f"bioactivity/data/search/by-m4id/{m4id}"
    return self._make_cached_request(endpoint, use_cache=use_cache)

get_data_by_spid(spid, use_cache=None)

Get bioactivity data by sample identifier.

Retrieves bioactivity data for a specific sample identified by its SPID (Sample Identifier).

Parameters:

Name Type Description Default
spid str

Sample identifier (e.g., 'EPAPLT0232A03')

 required

Returns:

Type Description
dict

Bioactivity data for the specified sample

Raises:

Type Description
ValueError

If spid is not a valid non-empty string
Example

client = BioactivityData() data = client.get_data_by_spid('EPAPLT0232A03')

Source code in src/pycomptox/bioactivity/bioactivitydata.py 
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
def get_data_by_spid(self, spid: str, use_cache: Optional[bool] = None) -> dict:
    """
    Get bioactivity data by sample identifier.

    Retrieves bioactivity data for a specific sample identified by its SPID
    (Sample Identifier).

    Args:
        spid: Sample identifier (e.g., 'EPAPLT0232A03')

    Returns:
        Bioactivity data for the specified sample

    Raises:
        ValueError: If spid is not a valid non-empty string

    Example:
        >>> client = BioactivityData()
        >>> data = client.get_data_by_spid('EPAPLT0232A03')
    """
    if not spid or not isinstance(spid, str):
        raise ValueError("spid must be a non-empty string")

    endpoint = f"bioactivity/data/search/by-spid/{spid}"
    return self._make_cached_request(endpoint, use_cache=use_cache)

get_summary_by_aeid(aeid, use_cache=None)

Get summary by aeid get /bioactivity/data/summary/search/by-aeid/{aeid} Return summary data for given aeid aeid int32 Numeric assay endpoint identifier Examples: 3032

curl -X GET "https://comptox.epa.gov/ctx-api/bioactivity/data/summary/search/by-aeid/3032" -H 'accept: application/json'

response 200 OK US EPA's Toxicity Forecaster (ToxCast) program makes invitro medium- and high-throughput screening assay data publicly available for prioritization and hazard characterization.The summary endpoint returns the number of active hits and total multi- and single-concentration chemicals tested for specific ‘aeids’. For multi-concentration data, a continuous hit call value greater than or equal to 0.9 is considered active, whereas values less than 0.9 are considered inactive. For single concentration data, the hit call value is binary where 1 is active and 0 is inactive. Multiple samples of the same chemical may be tested for a given assay endpoint, and all samples per endpoint are reflected in these counts. { "aeid": 0, "activeMc": 0, "totalMc": 0, "activeSc": 0, "totalSc": 0 }

Source code in src/pycomptox/bioactivity/bioactivitydata.py 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
def get_summary_by_aeid(self, aeid: str, use_cache: Optional[bool] = None) -> dict:
    """
    Get summary by aeid
    get /bioactivity/data/summary/search/by-aeid/{aeid}
    Return summary data for given aeid
    aeid int32 Numeric assay endpoint identifier
    Examples: 3032

    curl -X GET "https://comptox.epa.gov/ctx-api/bioactivity/data/summary/search/by-aeid/3032" \
    -H 'accept: application/json' 

    response
    200 OK
    US EPA's Toxicity Forecaster (ToxCast) program makes invitro medium- and high-throughput screening assay data publicly available for prioritization and hazard characterization.The summary endpoint returns the number of active hits and total multi- and single-concentration chemicals tested for specific ‘aeids’. For multi-concentration data, a continuous hit call value greater than or equal to 0.9 is considered active, whereas values less than 0.9 are considered inactive. For single concentration data, the hit call value is binary where 1 is active and 0 is inactive. Multiple samples of the same chemical may be tested for a given assay endpoint, and all samples per endpoint are reflected in these counts.
    {
    "aeid": 0,
    "activeMc": 0,
    "totalMc": 0,
    "activeSc": 0,
    "totalSc": 0
    }
    """
    if not isinstance(aeid, (int, str)):
        raise ValueError("aeid must be an integer or string")

    endpoint = f"bioactivity/data/summary/search/by-aeid/{aeid}"
    return self._make_cached_request(endpoint, use_cache=use_cache)

get_summary_by_dtxsid(dtxsid, use_cache=None)

Get bioactivity summary data for a chemical.

Retrieves summary bioactivity data for a specific chemical identified by its DSSTox Substance Identifier (DTXSID).

Parameters:

Name Type Description Default
dtxsid str

DSSTox Substance Identifier (e.g., 'DTXSID9026974')

 required

Returns:

Type Description
dict

Summary bioactivity data for the chemical

Raises:

Type Description
ValueError

If dtxsid is not a valid string
Example

client = BioactivityData() summary = client.get_summary_by_dtxsid('DTXSID9026974')

Source code in src/pycomptox/bioactivity/bioactivitydata.py 
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
def get_summary_by_dtxsid(self, dtxsid: str, use_cache: Optional[bool] = None) -> dict:
    """
    Get bioactivity summary data for a chemical.

    Retrieves summary bioactivity data for a specific chemical identified
    by its DSSTox Substance Identifier (DTXSID).

    Args:
        dtxsid: DSSTox Substance Identifier (e.g., 'DTXSID9026974')

    Returns:
        Summary bioactivity data for the chemical

    Raises:
        ValueError: If dtxsid is not a valid string

    Example:
        >>> client = BioactivityData()
        >>> summary = client.get_summary_by_dtxsid('DTXSID9026974')
    """
    if not dtxsid or not isinstance(dtxsid, str):
        raise ValueError("dtxsid must be a non-empty string")

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

get_summary_by_dtxsid_and_tissue(dtxsid, tissue, use_cache=None)

Get bioactivity summary data for a chemical filtered by tissue type.

Retrieves summary bioactivity data for a specific chemical (by DTXSID) filtered by tissue of origin.

Parameters:

Name Type Description Default
dtxsid str

DSSTox Substance Identifier (e.g., 'DTXSID7024241')

 required
tissue str

Tissue of origin (e.g., 'liver', 'kidney')

 required

Returns:

Type Description
dict

Dictionary containing summary bioactivity data including: - intendedTargetFamily: Target family - dtxsid: Chemical identifier - tissue: Tissue type - maxMedConc: Maximum median concentration - continuousHitCall: Continuous hit call value - chemicalName: Name of chemical - hitCall: Hit call classification - cutOff: Activity cutoff value - logAC50: Log of AC50 value - ac50: Half maximal activity concentration - acc: Activity concentration at cutoff

Raises:

Type Description
ValueError

If dtxsid or tissue is not a valid string
Example

client = BioactivityData() summary = client.get_summary_by_dtxsid_and_tissue('DTXSID7024241', 'liver') print(summary['chemicalName'])

Source code in src/pycomptox/bioactivity/bioactivitydata.py 
 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
def get_summary_by_dtxsid_and_tissue(self, dtxsid: str, tissue: str, use_cache: Optional[bool] = None) -> dict:
    """
    Get bioactivity summary data for a chemical filtered by tissue type.

    Retrieves summary bioactivity data for a specific chemical (by DTXSID)
    filtered by tissue of origin.

    Args:
        dtxsid: DSSTox Substance Identifier (e.g., 'DTXSID7024241')
        tissue: Tissue of origin (e.g., 'liver', 'kidney')

    Returns:
        Dictionary containing summary bioactivity data including:
            - intendedTargetFamily: Target family
            - dtxsid: Chemical identifier
            - tissue: Tissue type
            - maxMedConc: Maximum median concentration
            - continuousHitCall: Continuous hit call value
            - chemicalName: Name of chemical
            - hitCall: Hit call classification
            - cutOff: Activity cutoff value
            - logAC50: Log of AC50 value
            - ac50: Half maximal activity concentration
            - acc: Activity concentration at cutoff

    Raises:
        ValueError: If dtxsid or tissue is not a valid string

    Example:
        >>> client = BioactivityData()
        >>> summary = client.get_summary_by_dtxsid_and_tissue('DTXSID7024241', 'liver')
        >>> print(summary['chemicalName'])
    """
    if not dtxsid or not isinstance(dtxsid, str):
        raise ValueError("dtxsid must be a non-empty string")
    if not tissue or not isinstance(tissue, str):
        raise ValueError("tissue must be a non-empty string")

    endpoint = "bioactivity/data/summary/search/by-tissue/"
    params = {"dtxsid": dtxsid, "tissue": tissue}
    return self._make_cached_request(endpoint, params=params, use_cache=use_cache)