Skip to content

ExposurePrediction API Reference

pycomptox.exposure.exposureprediction.ExposurePrediction

Bases: CachedAPIClient

Client for accessing exposure prediction data from EPA CompTox Dashboard.

This class provides methods for retrieving estimated exposure rates (mg/kg bodyweight/day) for the U.S. population. Predictions include: - Median estimates (50% confidence) - Upper 95th percentile estimates (95% confidence)

Total population predictions are based on consensus exposure model predictions and the similarity of compounds to chemicals monitored by NHANES. The method was described in the 2018 publication: "Consensus Modeling of Median Chemical Intake for the U.S. Population Based on Predictions of Exposure Pathways".

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 ExposurePrediction exp_pred = ExposurePrediction()

Get exposure predictions for a chemical

data = exp_pred.general_prediction_SEEMs_by_dtxsid("DTXSID0020232")

Source code in src/pycomptox/exposure/exposureprediction.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
class ExposurePrediction(CachedAPIClient):
    """
    Client for accessing exposure prediction data from EPA CompTox Dashboard.

    This class provides methods for retrieving estimated exposure rates (mg/kg bodyweight/day)
    for the U.S. population. Predictions include:
    - Median estimates (50% confidence)
    - Upper 95th percentile estimates (95% confidence)

    Total population predictions are based on consensus exposure model predictions and
    the similarity of compounds to chemicals monitored by NHANES. The method was described
    in the 2018 publication: "Consensus Modeling of Median Chemical Intake for the U.S.
    Population Based on Predictions of Exposure Pathways".

    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 ExposurePrediction
        >>> exp_pred = ExposurePrediction()
        >>> 
        >>> # Get exposure predictions for a chemical
        >>> data = exp_pred.general_prediction_SEEMs_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 ExposurePrediction 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 general_prediction_SEEMs_by_dtxsid(
            self, dtxsid: str, 
            projection: str = "ccd-general"
            , use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
        """
        Get general SEEM exposure predictions for a chemical.

        Retrieves Systematic Empirical Evaluation of Models (SEEM) exposure predictions
        for a specific chemical identified by its DSSTox Substance Identifier (DTXSID).
        Returns estimates of average (geometric mean) exposure rate (mg/kg bodyweight/day)
        for the U.S. population.

        Predictions include:
        - Median estimate (50% confidence)
        - Upper 95th percentile estimate (95% confidence)

        Args:
            dtxsid: DSSTox Substance Identifier (e.g., 'DTXSID0020232')
            projection: Optional projection specification. Default is 'ccd-general'.

        Returns:
            List of dictionaries containing SEEM prediction data including:
            - Median exposure estimates
            - Upper 95th percentile estimates
            - Exposure pathways
            - Model predictions and confidence intervals

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

        Example:
            >>> exp_pred = ExposurePrediction()
            >>> data = exp_pred.general_prediction_SEEMs_by_dtxsid("DTXSID0020232")
            >>> for pred in data:
            ...     print(f"Median: {pred.get('medianEstimate')} mg/kg/day")
        """
        if not dtxsid or not isinstance(dtxsid, str):
            raise ValueError("dtxsid must be a non-empty string")

        endpoint = f"exposure/seem/general/search/by-dtxsid/{dtxsid}"
        params = {}
        if projection:
            params["projection"] = projection

        return self._make_cached_request(endpoint, params=params if params else None, use_cache=use_cache)

    def general_prediction_SEEMs_by_dtxsid_batch(
            self, dtxsid_list: List[str], use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
        """
        Get general SEEM exposure predictions for multiple chemicals in a single request.

        Retrieves SEEM exposure predictions 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 SEEM prediction data for all requested
            chemicals. Each entry includes the DTXSID and associated exposure
            predictions (median and 95th percentile estimates).

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

        Example:
            >>> exp_pred = ExposurePrediction()
            >>> dtxsids = ["DTXSID0020232", "DTXSID0020245"]
            >>> batch_data = exp_pred.general_prediction_SEEMs_by_dtxsid_batch(dtxsids)
            >>> for result in batch_data:
            ...     print(f"{result.get('dtxsid')}: {result.get('medianEstimate')} mg/kg/day")
        """
        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/seem/general/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 ExposurePrediction 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/exposureprediction.py 
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
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 ExposurePrediction 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
    )

general_prediction_SEEMs_by_dtxsid(dtxsid, projection='ccd-general', use_cache=None)

Get general SEEM exposure predictions for a chemical.

Retrieves Systematic Empirical Evaluation of Models (SEEM) exposure predictions for a specific chemical identified by its DSSTox Substance Identifier (DTXSID). Returns estimates of average (geometric mean) exposure rate (mg/kg bodyweight/day) for the U.S. population.

Predictions include: - Median estimate (50% confidence) - Upper 95th percentile estimate (95% confidence)

Parameters:

Name Type Description Default
dtxsid str

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

 required
projection str

Optional projection specification. Default is 'ccd-general'.

 'ccd-general'

Returns:

Type Description
List[Dict[str, Any]]

List of dictionaries containing SEEM prediction data including:
List[Dict[str, Any]]
  • Median exposure estimates
List[Dict[str, Any]]
  • Upper 95th percentile estimates
List[Dict[str, Any]]
  • Exposure pathways
List[Dict[str, Any]]
  • Model predictions and confidence intervals

Raises:

Type Description
ValueError

If dtxsid is not a valid non-empty string
Example

exp_pred = ExposurePrediction() data = exp_pred.general_prediction_SEEMs_by_dtxsid("DTXSID0020232") for pred in data: ... print(f"Median: {pred.get('medianEstimate')} mg/kg/day")

Source code in src/pycomptox/exposure/exposureprediction.py 
 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
def general_prediction_SEEMs_by_dtxsid(
        self, dtxsid: str, 
        projection: str = "ccd-general"
        , use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
    """
    Get general SEEM exposure predictions for a chemical.

    Retrieves Systematic Empirical Evaluation of Models (SEEM) exposure predictions
    for a specific chemical identified by its DSSTox Substance Identifier (DTXSID).
    Returns estimates of average (geometric mean) exposure rate (mg/kg bodyweight/day)
    for the U.S. population.

    Predictions include:
    - Median estimate (50% confidence)
    - Upper 95th percentile estimate (95% confidence)

    Args:
        dtxsid: DSSTox Substance Identifier (e.g., 'DTXSID0020232')
        projection: Optional projection specification. Default is 'ccd-general'.

    Returns:
        List of dictionaries containing SEEM prediction data including:
        - Median exposure estimates
        - Upper 95th percentile estimates
        - Exposure pathways
        - Model predictions and confidence intervals

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

    Example:
        >>> exp_pred = ExposurePrediction()
        >>> data = exp_pred.general_prediction_SEEMs_by_dtxsid("DTXSID0020232")
        >>> for pred in data:
        ...     print(f"Median: {pred.get('medianEstimate')} mg/kg/day")
    """
    if not dtxsid or not isinstance(dtxsid, str):
        raise ValueError("dtxsid must be a non-empty string")

    endpoint = f"exposure/seem/general/search/by-dtxsid/{dtxsid}"
    params = {}
    if projection:
        params["projection"] = projection

    return self._make_cached_request(endpoint, params=params if params else None, use_cache=use_cache)

general_prediction_SEEMs_by_dtxsid_batch(dtxsid_list, use_cache=None)

Get general SEEM exposure predictions for multiple chemicals in a single request.

Retrieves SEEM exposure predictions 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 SEEM prediction data for all requested
List[Dict[str, Any]]

chemicals. Each entry includes the DTXSID and associated exposure
List[Dict[str, Any]]

predictions (median and 95th percentile estimates).

Raises:

Type Description
ValueError

If dtxsid_list is not a valid non-empty list
Example

exp_pred = ExposurePrediction() dtxsids = ["DTXSID0020232", "DTXSID0020245"] batch_data = exp_pred.general_prediction_SEEMs_by_dtxsid_batch(dtxsids) for result in batch_data: ... print(f"{result.get('dtxsid')}: {result.get('medianEstimate')} mg/kg/day")

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

    Retrieves SEEM exposure predictions 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 SEEM prediction data for all requested
        chemicals. Each entry includes the DTXSID and associated exposure
        predictions (median and 95th percentile estimates).

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

    Example:
        >>> exp_pred = ExposurePrediction()
        >>> dtxsids = ["DTXSID0020232", "DTXSID0020245"]
        >>> batch_data = exp_pred.general_prediction_SEEMs_by_dtxsid_batch(dtxsids)
        >>> for result in batch_data:
        ...     print(f"{result.get('dtxsid')}: {result.get('medianEstimate')} mg/kg/day")
    """
    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/seem/general/search/by-dtxsid/"
    return self._make_request("POST", endpoint, json_data=dtxsid_list)