Skip to content

DemographicExposure API Reference

pycomptox.exposure.demographicexposure.DemographicExposure

Bases: CachedAPIClient

Client for accessing demographic-specific exposure prediction data from EPA CompTox Dashboard.

This class provides methods for retrieving demographic-specific estimates of average (geometric mean) exposure rate (mg/kg bodyweight/day) for U.S. population subgroups.

Predictions include: - Median estimates (50% confidence) - Upper 95th percentile estimates (95% confidence) - Demographic-specific predictions (age groups, etc.)

Total population predictions are based on consensus exposure model predictions and the similarity of compounds to chemicals monitored by NHANES. The demographic-specific predictions use a heuristic model described in the 2014 publication "High Throughput Heuristics for Prioritizing Human Exposure to Environmental Chemicals".

Parameters:

Name Type Description Default
api_key str

CompTox API key. If not provided, will attempt to load from saved configuration or COMPTOX_API_KEY environment variable.

 None
base_url str

Base URL for the CompTox API. Defaults to EPA's endpoint.

 'https://comptox.epa.gov/ctx-api/'
time_delay_between_calls float, **kwargs

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

 0.0
Example

from pycomptox import DemographicExposure demo_exp = DemographicExposure()

Get demographic exposure predictions for a chemical

data = demo_exp.prediction_SEEMs_data_by_dtxsid("DTXSID0020232")

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

    This class provides methods for retrieving demographic-specific estimates of average
    (geometric mean) exposure rate (mg/kg bodyweight/day) for U.S. population subgroups.

    Predictions include:
    - Median estimates (50% confidence)
    - Upper 95th percentile estimates (95% confidence)
    - Demographic-specific predictions (age groups, etc.)

    Total population predictions are based on consensus exposure model predictions and
    the similarity of compounds to chemicals monitored by NHANES. The demographic-specific
    predictions use a heuristic model described in the 2014 publication "High Throughput
    Heuristics for Prioritizing Human Exposure to Environmental Chemicals".

    Args:
        api_key (str, optional): CompTox API key. If not provided, will attempt
            to load from saved configuration or COMPTOX_API_KEY environment variable.
        base_url (str): Base URL for the CompTox API. Defaults to EPA's endpoint.
        time_delay_between_calls (float, **kwargs): Delay in seconds between API calls for
            rate limiting. Default is 0.0 (no delay).

    Example:
        >>> from pycomptox import DemographicExposure
        >>> demo_exp = DemographicExposure()
        >>> 
        >>> # Get demographic exposure predictions for a chemical
        >>> data = demo_exp.prediction_SEEMs_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 DemographicExposure 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 prediction_SEEMs_data_by_dtxsid(self, dtxsid: str, projection: str = "ccd-demographic", use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
        """
        Get demographic-specific SEEM exposure predictions for a chemical.

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

        The demographic-specific predictions use a heuristic model described in the 2014
        publication "High Throughput Heuristics for Prioritizing Human Exposure to
        Environmental Chemicals".

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

        Returns:
            List of dictionaries containing demographic SEEM prediction data including:
            - Median exposure estimates by demographic group
            - Upper 95th percentile estimates by demographic group
            - Age-specific predictions
            - Population subgroup breakdowns

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

        Example:
            >>> demo_exp = DemographicExposure()
            >>> data = demo_exp.prediction_SEEMs_data_by_dtxsid("DTXSID0020232")
            >>> for pred in data:
            ...     print(f"{pred.get('demographic')}: {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/demographic/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 prediction_SEEMs_data_by_dtxsid_batch(self, dtxsid_list: List[str], use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
        """
        Get demographic SEEM exposure predictions for multiple chemicals in a single request.

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

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

        Example:
            >>> demo_exp = DemographicExposure()
            >>> dtxsids = ["DTXSID0020232", "DTXSID0020267"]
            >>> batch_data = demo_exp.prediction_SEEMs_data_by_dtxsid_batch(dtxsids)
            >>> for result in batch_data:
            ...     print(f"{result.get('dtxsid')}: {result.get('demographic')} - {result.get('medianEstimate')}")
        """
        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/demographic/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 DemographicExposure 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/demographicexposure.py 
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
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 DemographicExposure 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
    )

prediction_SEEMs_data_by_dtxsid(dtxsid, projection='ccd-demographic', use_cache=None)

Get demographic-specific SEEM exposure predictions for a chemical.

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

The demographic-specific predictions use a heuristic model described in the 2014 publication "High Throughput Heuristics for Prioritizing Human Exposure to Environmental Chemicals".

Parameters:

Name Type Description Default
dtxsid str

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

 required
projection str

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

 'ccd-demographic'

Returns:

Type Description
List[Dict[str, Any]]

List of dictionaries containing demographic SEEM prediction data including:
List[Dict[str, Any]]
  • Median exposure estimates by demographic group
List[Dict[str, Any]]
  • Upper 95th percentile estimates by demographic group
List[Dict[str, Any]]
  • Age-specific predictions
List[Dict[str, Any]]
  • Population subgroup breakdowns

Raises:

Type Description
ValueError

If dtxsid is not a valid non-empty string
Example

demo_exp = DemographicExposure() data = demo_exp.prediction_SEEMs_data_by_dtxsid("DTXSID0020232") for pred in data: ... print(f"{pred.get('demographic')}: {pred.get('medianEstimate')} mg/kg/day")

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

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

    The demographic-specific predictions use a heuristic model described in the 2014
    publication "High Throughput Heuristics for Prioritizing Human Exposure to
    Environmental Chemicals".

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

    Returns:
        List of dictionaries containing demographic SEEM prediction data including:
        - Median exposure estimates by demographic group
        - Upper 95th percentile estimates by demographic group
        - Age-specific predictions
        - Population subgroup breakdowns

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

    Example:
        >>> demo_exp = DemographicExposure()
        >>> data = demo_exp.prediction_SEEMs_data_by_dtxsid("DTXSID0020232")
        >>> for pred in data:
        ...     print(f"{pred.get('demographic')}: {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/demographic/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)

prediction_SEEMs_data_by_dtxsid_batch(dtxsid_list, use_cache=None)

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

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

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

demographic-specific exposure predictions (median and 95th percentile
List[Dict[str, Any]]

estimates by population subgroup).

Raises:

Type Description
ValueError

If dtxsid_list is not a valid non-empty list
Example

demo_exp = DemographicExposure() dtxsids = ["DTXSID0020232", "DTXSID0020267"] batch_data = demo_exp.prediction_SEEMs_data_by_dtxsid_batch(dtxsids) for result in batch_data: ... print(f"{result.get('dtxsid')}: {result.get('demographic')} - {result.get('medianEstimate')}")

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

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

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

    Example:
        >>> demo_exp = DemographicExposure()
        >>> dtxsids = ["DTXSID0020232", "DTXSID0020267"]
        >>> batch_data = demo_exp.prediction_SEEMs_data_by_dtxsid_batch(dtxsids)
        >>> for result in batch_data:
        ...     print(f"{result.get('dtxsid')}: {result.get('demographic')} - {result.get('medianEstimate')}")
    """
    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/demographic/search/by-dtxsid/"
    return self._make_request("POST", endpoint, json_data=dtxsid_list)