Skip to content

HTTKData API Reference

pycomptox.exposure.httkdata.HTTKData

Bases: CachedAPIClient

Client for accessing High-Throughput Toxicokinetics (HTTK) data from EPA CompTox Dashboard.

This class provides methods for retrieving human toxicokinetic parameters including: - Intrinsic hepatic clearance - Fraction unbound in plasma - Volume of distribution - PK half-life - Steady-state plasma concentration

Values are measured (in vitro or in vivo), predicted from chemical properties using in silico tools, or computed with mathematical models simulating toxicokinetics.

The in vitro measured values reflect data curated for the open source R package "httk" (https://CRAN.R-project.org/package=httk). The computed values are generated with httk using reported in vitro values. In vivo measured values are estimated from toxicokinetic concentration vs. time data in CvTdb (https://doi.org/10.1038/s41597-020-0455-1) using R package "invivoPKfit" (https://github.com/USEPA/CompTox-ExpoCast-invivoPKfit).

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, **kwargs

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

 0.0
Example

from pycomptox import HTTKData httk = HTTKData()

Get HTTK data for a chemical

data = httk.httk_data_by_dtxsid("DTXSID0020232")

Source code in src/pycomptox/exposure/httkdata.py 
 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
class HTTKData(CachedAPIClient):
    """
    Client for accessing High-Throughput Toxicokinetics (HTTK) data from EPA CompTox Dashboard.

    This class provides methods for retrieving human toxicokinetic parameters including:
    - Intrinsic hepatic clearance
    - Fraction unbound in plasma
    - Volume of distribution
    - PK half-life
    - Steady-state plasma concentration

    Values are measured (in vitro or in vivo), predicted from chemical properties using
    in silico tools, or computed with mathematical models simulating toxicokinetics.

    The in vitro measured values reflect data curated for the open source R package "httk"
    (https://CRAN.R-project.org/package=httk). The computed values are generated with httk
    using reported in vitro values. In vivo measured values are estimated from
    toxicokinetic concentration vs. time data in CvTdb (https://doi.org/10.1038/s41597-020-0455-1)
    using R package "invivoPKfit" (https://github.com/USEPA/CompTox-ExpoCast-invivoPKfit).

    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, **kwargs): Delay in seconds between API calls for
            rate limiting. Default is 0.0 (no delay).

    Example:
        >>> from pycomptox import HTTKData
        >>> httk = HTTKData()
        >>> 
        >>> # Get HTTK data for a chemical
        >>> data = httk.httk_data_by_dtxsid("DTXSID0020232")
    """

    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 HTTKData 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

        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 httk_data_by_dtxsid(self, dtxsid: str, use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
        """
        Get high-throughput toxicokinetics (HTTK) data for a chemical.

        Retrieves toxicokinetic parameters for a specific chemical identified by its
        DSSTox Substance Identifier (DTXSID). Returns measured, predicted, and computed
        toxicokinetic values including clearance, volume of distribution, half-life,
        and steady-state plasma concentration.

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

        Returns:
            List of dictionaries containing HTTK data. Each entry includes:
            - Intrinsic hepatic clearance
            - Fraction unbound in plasma
            - Volume of distribution
            - PK half-life
            - Steady-state plasma concentration
            - Data source (in vitro, in vivo, predicted, computed)
            - Species information

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

        Example:
            >>> httk = HTTKData()
            >>> data = httk.httk_data_by_dtxsid("DTXSID0020232")
            >>> for param in data:
            ...     print(f"{param.get('parameter')}: {param.get('value')} {param.get('units')}")
        """
        if not dtxsid or not isinstance(dtxsid, str):
            raise ValueError("dtxsid must be a non-empty string")

        endpoint = f"exposure/httk/search/by-dtxsid/{dtxsid}"
        return self._make_cached_request(endpoint, use_cache=use_cache)

    def httk_data_by_dtxsid_batch(self, dtxsid_list: List[str], use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
        """
        Get HTTK data for multiple chemicals in a single request.

        Retrieves toxicokinetic parameters for multiple chemicals at once using a batch
        API call. This is more efficient than making individual requests for each chemical
        when working with multiple DTXSIDs.

        Args:
            dtxsid_list: List of DSSTox Substance Identifiers

        Returns:
            List of dictionaries containing HTTK data for all requested chemicals.
            Each entry includes the DTXSID and associated toxicokinetic parameters.

        Raises:
            ValueError: If dtxsid_list is not a valid non-empty list

        Example:
            >>> httk = HTTKData()
            >>> dtxsids = ["DTXSID0020232", "DTXSID7020182"]
            >>> batch_data = httk.httk_data_by_dtxsid_batch(dtxsids)
            >>> for result in batch_data:
            ...     print(f"{result.get('dtxsid')}: {result.get('parameter')} = {result.get('value')}")
        """
        if not dtxsid_list or not isinstance(dtxsid_list, list) or len(dtxsid_list) == 0:
            raise ValueError("dtxsid_list must be a non-empty list of strings")

        if not all(isinstance(dtxsid, str) for dtxsid in dtxsid_list):
            raise ValueError("All elements in dtxsid_list must be strings")

        endpoint = "exposure/httk/search/by-dtxsid/"
        return self._make_request("POST", endpoint, json_data=dtxsid_list)

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

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

Raises:

Type Description
ValueError

If no API key is provided or found in configuration
Source code in src/pycomptox/exposure/httkdata.py 
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
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 HTTKData 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

    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
    )

httk_data_by_dtxsid(dtxsid, use_cache=None)

Get high-throughput toxicokinetics (HTTK) data for a chemical.

Retrieves toxicokinetic parameters for a specific chemical identified by its DSSTox Substance Identifier (DTXSID). Returns measured, predicted, and computed toxicokinetic values including clearance, volume of distribution, half-life, and steady-state plasma concentration.

Parameters:

Name Type Description Default
dtxsid str

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

 required

Returns:

Type Description
List[Dict[str, Any]]

List of dictionaries containing HTTK data. Each entry includes:
List[Dict[str, Any]]
  • Intrinsic hepatic clearance
List[Dict[str, Any]]
  • Fraction unbound in plasma
List[Dict[str, Any]]
  • Volume of distribution
List[Dict[str, Any]]
  • PK half-life
List[Dict[str, Any]]
  • Steady-state plasma concentration
List[Dict[str, Any]]
  • Data source (in vitro, in vivo, predicted, computed)
List[Dict[str, Any]]
  • Species information

Raises:

Type Description
ValueError

If dtxsid is not a valid non-empty string
Example

httk = HTTKData() data = httk.httk_data_by_dtxsid("DTXSID0020232") for param in data: ... print(f"{param.get('parameter')}: {param.get('value')} {param.get('units')}")

Source code in src/pycomptox/exposure/httkdata.py 
 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
def httk_data_by_dtxsid(self, dtxsid: str, use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
    """
    Get high-throughput toxicokinetics (HTTK) data for a chemical.

    Retrieves toxicokinetic parameters for a specific chemical identified by its
    DSSTox Substance Identifier (DTXSID). Returns measured, predicted, and computed
    toxicokinetic values including clearance, volume of distribution, half-life,
    and steady-state plasma concentration.

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

    Returns:
        List of dictionaries containing HTTK data. Each entry includes:
        - Intrinsic hepatic clearance
        - Fraction unbound in plasma
        - Volume of distribution
        - PK half-life
        - Steady-state plasma concentration
        - Data source (in vitro, in vivo, predicted, computed)
        - Species information

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

    Example:
        >>> httk = HTTKData()
        >>> data = httk.httk_data_by_dtxsid("DTXSID0020232")
        >>> for param in data:
        ...     print(f"{param.get('parameter')}: {param.get('value')} {param.get('units')}")
    """
    if not dtxsid or not isinstance(dtxsid, str):
        raise ValueError("dtxsid must be a non-empty string")

    endpoint = f"exposure/httk/search/by-dtxsid/{dtxsid}"
    return self._make_cached_request(endpoint, use_cache=use_cache)

httk_data_by_dtxsid_batch(dtxsid_list, use_cache=None)

Get HTTK data for multiple chemicals in a single request.

Retrieves toxicokinetic parameters for multiple chemicals at once using a batch API call. This is more efficient than making individual requests for each chemical when working with multiple DTXSIDs.

Parameters:

Name Type Description Default
dtxsid_list List[str]

List of DSSTox Substance Identifiers

 required

Returns:

Type Description
List[Dict[str, Any]]

List of dictionaries containing HTTK data for all requested chemicals.
List[Dict[str, Any]]

Each entry includes the DTXSID and associated toxicokinetic parameters.

Raises:

Type Description
ValueError

If dtxsid_list is not a valid non-empty list
Example

httk = HTTKData() dtxsids = ["DTXSID0020232", "DTXSID7020182"] batch_data = httk.httk_data_by_dtxsid_batch(dtxsids) for result in batch_data: ... print(f"{result.get('dtxsid')}: {result.get('parameter')} = {result.get('value')}")

Source code in src/pycomptox/exposure/httkdata.py 
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
def httk_data_by_dtxsid_batch(self, dtxsid_list: List[str], use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
    """
    Get HTTK data for multiple chemicals in a single request.

    Retrieves toxicokinetic parameters for multiple chemicals at once using a batch
    API call. This is more efficient than making individual requests for each chemical
    when working with multiple DTXSIDs.

    Args:
        dtxsid_list: List of DSSTox Substance Identifiers

    Returns:
        List of dictionaries containing HTTK data for all requested chemicals.
        Each entry includes the DTXSID and associated toxicokinetic parameters.

    Raises:
        ValueError: If dtxsid_list is not a valid non-empty list

    Example:
        >>> httk = HTTKData()
        >>> dtxsids = ["DTXSID0020232", "DTXSID7020182"]
        >>> batch_data = httk.httk_data_by_dtxsid_batch(dtxsids)
        >>> for result in batch_data:
        ...     print(f"{result.get('dtxsid')}: {result.get('parameter')} = {result.get('value')}")
    """
    if not dtxsid_list or not isinstance(dtxsid_list, list) or len(dtxsid_list) == 0:
        raise ValueError("dtxsid_list must be a non-empty list of strings")

    if not all(isinstance(dtxsid, str) for dtxsid in dtxsid_list):
        raise ValueError("All elements in dtxsid_list must be strings")

    endpoint = "exposure/httk/search/by-dtxsid/"
    return self._make_request("POST", endpoint, json_data=dtxsid_list)