Skip to content

ADMEIVIVE API Reference

pycomptox.hazard.admeivive.ADMEIVIVE

Bases: CachedAPIClient

Client for accessing ADME-IVIVE (Absorption, Distribution, Metabolism, Excretion - In Vitro to In Vivo Extrapolation) toxicokinetics data from EPA CompTox Dashboard.

This class provides access to toxicokinetics data describing how chemicals behave in the human body. Data values are:

  1. Measured - either in vitro or in vivo
  2. Predicted - from chemical properties using in silico tools
  3. Computed - with mathematical models simulating toxicokinetics

Key Parameters: - Intrinsic hepatic clearance - Fraction unbound in plasma - Volume of distribution - PK half-life - Steady-state plasma concentration

Data Sources: - httk R package: In vitro measured values (https://CRAN.R-project.org/package=httk) - CvTdb: In vivo concentration vs. time data (https://doi.org/10.1038/s41597-020-0455-1) - invivoPKfit: In vivo estimates (https://github.com/USEPA/CompTox-ExpoCast-invivoPKfit)

Note: Some measured values may be assumed from surrogate species data. The Data Source Species column identifies the species source for measured data. These assumed measured values are used in calculations to estimate other outcomes.

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.

 DEFAULT_BASE_URL
time_delay_between_calls float

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

 None
use_cache bool

Whether to use caching by default. Default is True.

 False
Example

from pycomptox.hazard import ADMEIVIVE adme = ADMEIVIVE()

Get ADME-IVIVE data for bisphenol A

data = adme.get_all_data_by_dtxsid_ccd_projection("DTXSID7020182")

if data: ... for record in data: ... param = record.get('parameter', 'Unknown') ... value = record.get('value', 'N/A') ... units = record.get('units', '') ... print(f"{param}: {value} {units}")

Source code in src/pycomptox/hazard/admeivive.py 
 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
class ADMEIVIVE(CachedAPIClient):
    """
    Client for accessing ADME-IVIVE (Absorption, Distribution, Metabolism, Excretion - 
    In Vitro to In Vivo Extrapolation) toxicokinetics data from EPA CompTox Dashboard.

    This class provides access to toxicokinetics data describing how chemicals behave 
    in the human body. Data values are:

    1. **Measured** - either in vitro or in vivo
    2. **Predicted** - from chemical properties using in silico tools
    3. **Computed** - with mathematical models simulating toxicokinetics

    Key Parameters:
    - Intrinsic hepatic clearance
    - Fraction unbound in plasma
    - Volume of distribution
    - PK half-life
    - Steady-state plasma concentration

    Data Sources:
    - **httk R package**: In vitro measured values (https://CRAN.R-project.org/package=httk)
    - **CvTdb**: In vivo concentration vs. time data (https://doi.org/10.1038/s41597-020-0455-1)
    - **invivoPKfit**: In vivo estimates (https://github.com/USEPA/CompTox-ExpoCast-invivoPKfit)

    Note: Some measured values may be assumed from surrogate species data. The Data 
    Source Species column identifies the species source for measured data. These 
    assumed measured values are used in calculations to estimate other outcomes.

    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 ADMEIVIVE
        >>> adme = ADMEIVIVE()
        >>> 
        >>> # Get ADME-IVIVE data for bisphenol A
        >>> data = adme.get_all_data_by_dtxsid_ccd_projection("DTXSID7020182")
        >>> 
        >>> if data:
        ...     for record in data:
        ...         param = record.get('parameter', 'Unknown')
        ...         value = record.get('value', 'N/A')
        ...         units = record.get('units', '')
        ...         print(f"{param}: {value} {units}")
    """

    def get_all_data_by_dtxsid_ccd_projection(
        self, 
        dtxsid: str, 
        projection: Optional[str] = None,
        use_cache: Optional[bool] = None
    ) -> List[Dict[str, Any]]:
        """
        Get ADME-IVIVE toxicokinetics data by DTXSID.

        Retrieves all ADME-IVIVE (Absorption, Distribution, Metabolism, Excretion - 
        In Vitro to In Vivo Extrapolation) data for a chemical. Optionally use 
        projection for CompTox Dashboard-specific formatting.

        The data includes toxicokinetic parameters such as:
        - Intrinsic hepatic clearance (CLint)
        - Fraction unbound in plasma (Fup)
        - Volume of distribution (Vd)
        - Pharmacokinetic half-life (t½)
        - Steady-state plasma concentration (Css)
        - Oral bioavailability
        - Renal clearance
        - Blood:plasma ratio

        Data types include:
        - **In vitro measured**: Direct measurements from in vitro assays
        - **In vivo measured**: Derived from concentration-time data (CvTdb)
        - **In silico predicted**: Predictions from chemical properties
        - **Computed**: Calculated using httk or invivoPKfit models

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

        Returns:
            List of dictionaries containing ADME-IVIVE data with fields such as:
                - dtxsid (str): Chemical identifier
                - parameter (str): ADME parameter name
                - value (float): Parameter value
                - units (str): Units of measurement
                - dataType (str): Type of data (measured/predicted/computed)
                - source (str): Data source (httk, CvTdb, in silico tool)
                - species (str): Species for measured data
                - method (str): Measurement or prediction method
                - reference (str): Literature reference
                - confidence (str): Confidence level or quality indicator
                - Notes: Exact fields vary by projection

        Raises:
            ValueError: If dtxsid is not a valid non-empty string
            AuthenticationError: If the API key is missing, invalid, or lacks access.
            NotFoundError: If the requested identifier does not exist.
            RateLimitError: If the API rate limit is exceeded.
            APIError: For any other unsuccessful API response.

        Example:
            >>> from pycomptox.hazard import ADMEIVIVE
            >>> adme = ADMEIVIVE()
            >>> 
            >>> # Get ADME-IVIVE data for bisphenol A
            >>> data = adme.get_all_data_by_dtxsid_ccd_projection("DTXSID7020182")
            >>> 
            >>> if data:
            ...     print(f"Found {len(data)} ADME-IVIVE parameters")
            ...     
            ...     # Group by data type
            ...     by_type = {}
            ...     for record in data:
            ...         dtype = record.get('dataType', 'Unknown')
            ...         if dtype not in by_type:
            ...             by_type[dtype] = []
            ...         by_type[dtype].append(record)
            ...     
            ...     print(f"\nData types available:")
            ...     for dtype, records in sorted(by_type.items()):
            ...         print(f"  {dtype}: {len(records)} parameter(s)")
            ...     
            ...     # Show key parameters
            ...     print(f"\nKey toxicokinetic parameters:")
            ...     key_params = ['Clint', 'Fup', 'Vd', 't1/2', 'Css']
            ...     for record in data:
            ...         param = record.get('parameter', '')
            ...         if any(kp in param for kp in key_params):
            ...             value = record.get('value', 'N/A')
            ...             units = record.get('units', '')
            ...             source = record.get('source', 'Unknown')
            ...             print(f"  {param}: {value} {units} ({source})")
            >>> 
            >>> # Get with CompTox Dashboard projection
            >>> ccd_data = adme.get_all_data_by_dtxsid_ccd_projection(
            ...     "DTXSID7020182", 
            ...     projection="ccd-adme-data"
            ... )
            >>> 
            >>> # Compare in vitro vs in vivo data
            >>> if data:
            ...     in_vitro = [r for r in data if 'in vitro' in str(r.get('dataType', '')).lower()]
            ...     in_vivo = [r for r in data if 'in vivo' in str(r.get('dataType', '')).lower()]
            ...     print(f"\nIn vitro parameters: {len(in_vitro)}")
            ...     print(f"In vivo parameters: {len(in_vivo)}")

        Note:
            - Data may include measured, predicted, and computed values
            - Some measured values may be from surrogate species
            - Check 'species' field to identify data source species
            - Computed values are derived using httk or invivoPKfit R packages
            - Use projection='ccd-adme-data' for dashboard-formatted data
        """
        if not dtxsid or not isinstance(dtxsid, str):
            raise ValueError("dtxsid must be a non-empty string")

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

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

get_all_data_by_dtxsid_ccd_projection(dtxsid, projection=None, use_cache=None) 

    Get ADME-IVIVE toxicokinetics data by DTXSID.

    Retrieves all ADME-IVIVE (Absorption, Distribution, Metabolism, Excretion - 
    In Vitro to In Vivo Extrapolation) data for a chemical. Optionally use 
    projection for CompTox Dashboard-specific formatting.

    The data includes toxicokinetic parameters such as:
    - Intrinsic hepatic clearance (CLint)
    - Fraction unbound in plasma (Fup)
    - Volume of distribution (Vd)
    - Pharmacokinetic half-life (t½)
    - Steady-state plasma concentration (Css)
    - Oral bioavailability
    - Renal clearance
    - Blood:plasma ratio

    Data types include:
    - **In vitro measured**: Direct measurements from in vitro assays
    - **In vivo measured**: Derived from concentration-time data (CvTdb)
    - **In silico predicted**: Predictions from chemical properties
    - **Computed**: Calculated using httk or invivoPKfit models

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

    Returns:
        List of dictionaries containing ADME-IVIVE data with fields such as:
            - dtxsid (str): Chemical identifier
            - parameter (str): ADME parameter name
            - value (float): Parameter value
            - units (str): Units of measurement
            - dataType (str): Type of data (measured/predicted/computed)
            - source (str): Data source (httk, CvTdb, in silico tool)
            - species (str): Species for measured data
            - method (str): Measurement or prediction method
            - reference (str): Literature reference
            - confidence (str): Confidence level or quality indicator
            - Notes: Exact fields vary by projection

    Raises:
        ValueError: If dtxsid is not a valid non-empty string
        AuthenticationError: If the API key is missing, invalid, or lacks access.
        NotFoundError: If the requested identifier does not exist.
        RateLimitError: If the API rate limit is exceeded.
        APIError: For any other unsuccessful API response.

    Example:
        >>> from pycomptox.hazard import ADMEIVIVE
        >>> adme = ADMEIVIVE()
        >>> 
        >>> # Get ADME-IVIVE data for bisphenol A
        >>> data = adme.get_all_data_by_dtxsid_ccd_projection("DTXSID7020182")
        >>> 
        >>> if data:
        ...     print(f"Found {len(data)} ADME-IVIVE parameters")
        ...     
        ...     # Group by data type
        ...     by_type = {}
        ...     for record in data:
        ...         dtype = record.get('dataType', 'Unknown')
        ...         if dtype not in by_type:
        ...             by_type[dtype] = []
        ...         by_type[dtype].append(record)
        ...     
        ...     print(f"

Data types available:") ... for dtype, records in sorted(by_type.items()): ... print(f" {dtype}: {len(records)} parameter(s)") ...
... # Show key parameters ... print(f" Key toxicokinetic parameters:") ... key_params = ['Clint', 'Fup', 'Vd', 't1/2', 'Css'] ... for record in data: ... param = record.get('parameter', '') ... if any(kp in param for kp in key_params): ... value = record.get('value', 'N/A') ... units = record.get('units', '') ... source = record.get('source', 'Unknown') ... print(f" {param}: {value} {units} ({source})") >>> >>> # Get with CompTox Dashboard projection >>> ccd_data = adme.get_all_data_by_dtxsid_ccd_projection( ... "DTXSID7020182", ... projection="ccd-adme-data" ... ) >>> >>> # Compare in vitro vs in vivo data >>> if data: ... in_vitro = [r for r in data if 'in vitro' in str(r.get('dataType', '')).lower()] ... in_vivo = [r for r in data if 'in vivo' in str(r.get('dataType', '')).lower()] ... print(f" In vitro parameters: {len(in_vitro)}") ... print(f"In vivo parameters: {len(in_vivo)}")

    Note:
        - Data may include measured, predicted, and computed values
        - Some measured values may be from surrogate species
        - Check 'species' field to identify data source species
        - Computed values are derived using httk or invivoPKfit R packages
        - Use projection='ccd-adme-data' for dashboard-formatted data
Source code in src/pycomptox/hazard/admeivive.py 
 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
def get_all_data_by_dtxsid_ccd_projection(
    self, 
    dtxsid: str, 
    projection: Optional[str] = None,
    use_cache: Optional[bool] = None
) -> List[Dict[str, Any]]:
    """
    Get ADME-IVIVE toxicokinetics data by DTXSID.

    Retrieves all ADME-IVIVE (Absorption, Distribution, Metabolism, Excretion - 
    In Vitro to In Vivo Extrapolation) data for a chemical. Optionally use 
    projection for CompTox Dashboard-specific formatting.

    The data includes toxicokinetic parameters such as:
    - Intrinsic hepatic clearance (CLint)
    - Fraction unbound in plasma (Fup)
    - Volume of distribution (Vd)
    - Pharmacokinetic half-life (t½)
    - Steady-state plasma concentration (Css)
    - Oral bioavailability
    - Renal clearance
    - Blood:plasma ratio

    Data types include:
    - **In vitro measured**: Direct measurements from in vitro assays
    - **In vivo measured**: Derived from concentration-time data (CvTdb)
    - **In silico predicted**: Predictions from chemical properties
    - **Computed**: Calculated using httk or invivoPKfit models

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

    Returns:
        List of dictionaries containing ADME-IVIVE data with fields such as:
            - dtxsid (str): Chemical identifier
            - parameter (str): ADME parameter name
            - value (float): Parameter value
            - units (str): Units of measurement
            - dataType (str): Type of data (measured/predicted/computed)
            - source (str): Data source (httk, CvTdb, in silico tool)
            - species (str): Species for measured data
            - method (str): Measurement or prediction method
            - reference (str): Literature reference
            - confidence (str): Confidence level or quality indicator
            - Notes: Exact fields vary by projection

    Raises:
        ValueError: If dtxsid is not a valid non-empty string
        AuthenticationError: If the API key is missing, invalid, or lacks access.
        NotFoundError: If the requested identifier does not exist.
        RateLimitError: If the API rate limit is exceeded.
        APIError: For any other unsuccessful API response.

    Example:
        >>> from pycomptox.hazard import ADMEIVIVE
        >>> adme = ADMEIVIVE()
        >>> 
        >>> # Get ADME-IVIVE data for bisphenol A
        >>> data = adme.get_all_data_by_dtxsid_ccd_projection("DTXSID7020182")
        >>> 
        >>> if data:
        ...     print(f"Found {len(data)} ADME-IVIVE parameters")
        ...     
        ...     # Group by data type
        ...     by_type = {}
        ...     for record in data:
        ...         dtype = record.get('dataType', 'Unknown')
        ...         if dtype not in by_type:
        ...             by_type[dtype] = []
        ...         by_type[dtype].append(record)
        ...     
        ...     print(f"\nData types available:")
        ...     for dtype, records in sorted(by_type.items()):
        ...         print(f"  {dtype}: {len(records)} parameter(s)")
        ...     
        ...     # Show key parameters
        ...     print(f"\nKey toxicokinetic parameters:")
        ...     key_params = ['Clint', 'Fup', 'Vd', 't1/2', 'Css']
        ...     for record in data:
        ...         param = record.get('parameter', '')
        ...         if any(kp in param for kp in key_params):
        ...             value = record.get('value', 'N/A')
        ...             units = record.get('units', '')
        ...             source = record.get('source', 'Unknown')
        ...             print(f"  {param}: {value} {units} ({source})")
        >>> 
        >>> # Get with CompTox Dashboard projection
        >>> ccd_data = adme.get_all_data_by_dtxsid_ccd_projection(
        ...     "DTXSID7020182", 
        ...     projection="ccd-adme-data"
        ... )
        >>> 
        >>> # Compare in vitro vs in vivo data
        >>> if data:
        ...     in_vitro = [r for r in data if 'in vitro' in str(r.get('dataType', '')).lower()]
        ...     in_vivo = [r for r in data if 'in vivo' in str(r.get('dataType', '')).lower()]
        ...     print(f"\nIn vitro parameters: {len(in_vitro)}")
        ...     print(f"In vivo parameters: {len(in_vivo)}")

    Note:
        - Data may include measured, predicted, and computed values
        - Some measured values may be from surrogate species
        - Check 'species' field to identify data source species
        - Computed values are derived using httk or invivoPKfit R packages
        - Use projection='ccd-adme-data' for dashboard-formatted data
    """
    if not dtxsid or not isinstance(dtxsid, str):
        raise ValueError("dtxsid must be a non-empty string")

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

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