Skip to content

IRIS API Reference

pycomptox.hazard.iris.IRIS

Bases: CachedAPIClient

Client for accessing EPA IRIS (Integrated Risk Information System) data.

Integrated Risk Information System (IRIS): EPA's IRIS Program identifies and characterizes the health hazards of chemicals found in the environment. Each IRIS assessment can cover: - A single chemical - A group of related chemicals - A complex mixture

IRIS assessments provide: - Oral reference doses (RfD) for non-cancer effects - Inhalation reference concentrations (RfC) for non-cancer effects - Cancer slope factors and unit risks - Weight of evidence for carcinogenicity - Critical effect descriptions - Uncertainty and modifying factors

IRIS assessments are an important source of toxicity information used by: - EPA programs and regional offices - State and local health agencies - Other federal agencies - International health organizations - Risk assessors and researchers

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
use_cache bool

Whether to use caching by default. Default is True.

 required
Example

from pycomptox.hazard import IRIS iris = IRIS()

Get IRIS assessment data for a chemical

data = iris.get_data_by_dtxsid("DTXSID7020182") if data: ... print(f"Found {len(data)} IRIS assessment(s)")

Source code in src/pycomptox/hazard/iris.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
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
class IRIS(CachedAPIClient):
    """
    Client for accessing EPA IRIS (Integrated Risk Information System) data.

    Integrated Risk Information System (IRIS): EPA's IRIS Program identifies and 
    characterizes the health hazards of chemicals found in the environment. Each 
    IRIS assessment can cover:
    - A single chemical
    - A group of related chemicals
    - A complex mixture

    IRIS assessments provide:
    - Oral reference doses (RfD) for non-cancer effects
    - Inhalation reference concentrations (RfC) for non-cancer effects
    - Cancer slope factors and unit risks
    - Weight of evidence for carcinogenicity
    - Critical effect descriptions
    - Uncertainty and modifying factors

    IRIS assessments are an important source of toxicity information used by:
    - EPA programs and regional offices
    - State and local health agencies
    - Other federal agencies
    - International health organizations
    - Risk assessors and researchers

    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 IRIS
        >>> iris = IRIS()
        >>> 
        >>> # Get IRIS assessment data for a chemical
        >>> data = iris.get_data_by_dtxsid("DTXSID7020182")
        >>> if data:
        ...     print(f"Found {len(data)} IRIS assessment(s)")
    """

    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: Any
    ):
        """
        Initialize the IRIS 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_data_by_dtxsid(self, dtxsid: str, 
                           use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
        """
        Get all IRIS assessment data by DTXSID.

        Retrieves comprehensive IRIS assessment information for a chemical identified 
        by its DSSTox Substance Identifier. IRIS assessments include detailed health 
        hazard characterizations and toxicity reference values used in risk assessment.

        Args:
            dtxsid: DSSTox Substance Identifier (e.g., 'DTXSID7020182')
            use_cache: Whether to use cache for this request. If None, uses
                the instance default setting.

        Returns:
            List of dictionaries containing IRIS assessment data with fields such as:
                - dtxsid (str): Chemical identifier
                - casrn (str): CAS Registry Number
                - chemicalName (str): Chemical name
                - irisUrl (str): URL to full IRIS assessment
                - lastUpdated (str): Last assessment update date
                - assessmentStatus (str): Status of assessment

                Non-cancer hazard data:
                - oralRfD (float): Oral reference dose
                - oralRfDUnits (str): RfD units (typically mg/kg-day)
                - oralRfDCriticalEffect (str): Critical effect for RfD
                - oralRfDPOD (float): Point of departure
                - oralRfDUF (int): Uncertainty factor
                - inhalationRfC (float): Inhalation reference concentration
                - inhalationRfCUnits (str): RfC units (typically mg/m³)
                - inhalationRfCCriticalEffect (str): Critical effect for RfC
                - inhalationRfCPOD (float): Point of departure
                - inhalationRfCUF (int): Uncertainty factor

                Cancer hazard data:
                - cancerWeightOfEvidence (str): Weight of evidence classification
                - oralSlopeFactor (float): Oral cancer slope factor
                - oralSlopeFactorUnits (str): Slope factor units
                - inhalationUnitRisk (float): Inhalation unit risk
                - inhalationUnitRiskUnits (str): Unit risk units

                - Notes: Exact fields vary by assessment

        Raises:
            ValueError: If dtxsid is not a valid non-empty string
            PermissionError: If API key is invalid
            RuntimeError: For other API errors

        Example:
            >>> from pycomptox.hazard import IRIS
            >>> iris = IRIS()
            >>> 
            >>> # Get IRIS data for formaldehyde
            >>> data = iris.get_data_by_dtxsid("DTXSID7020182")
            >>> 
            >>> if data:
            ...     print(f"Found {len(data)} IRIS assessment(s)")
            ...     
            ...     for assessment in data:
            ...         print(f"\nChemical: {assessment.get('chemicalName', 'N/A')}")
            ...         print(f"CAS: {assessment.get('casrn', 'N/A')}")
            ...         print(f"Status: {assessment.get('assessmentStatus', 'N/A')}")
            ...         
            ...         # Non-cancer oral hazard
            ...         if assessment.get('oralRfD'):
            ...             print(f"\nOral RfD: {assessment['oralRfD']} {assessment.get('oralRfDUnits', '')}")
            ...             if assessment.get('oralRfDCriticalEffect'):
            ...                 print(f"  Critical Effect: {assessment['oralRfDCriticalEffect']}")
            ...             if assessment.get('oralRfDUF'):
            ...                 print(f"  Uncertainty Factor: {assessment['oralRfDUF']}")
            ...         
            ...         # Non-cancer inhalation hazard
            ...         if assessment.get('inhalationRfC'):
            ...             print(f"\nInhalation RfC: {assessment['inhalationRfC']} {assessment.get('inhalationRfCUnits', '')}")
            ...             if assessment.get('inhalationRfCCriticalEffect'):
            ...                 print(f"  Critical Effect: {assessment['inhalationRfCCriticalEffect']}")
            ...         
            ...         # Cancer hazard
            ...         if assessment.get('cancerWeightOfEvidence'):
            ...             print(f"\nCancer Weight of Evidence: {assessment['cancerWeightOfEvidence']}")
            ...         
            ...         if assessment.get('oralSlopeFactor'):
            ...             print(f"Oral Slope Factor: {assessment['oralSlopeFactor']} {assessment.get('oralSlopeFactorUnits', '')}")
            ...         
            ...         if assessment.get('inhalationUnitRisk'):
            ...             print(f"Inhalation Unit Risk: {assessment['inhalationUnitRisk']} {assessment.get('inhalationUnitRiskUnits', '')}")
            ...         
            ...         # Link to full assessment
            ...         if assessment.get('irisUrl'):
            ...             print(f"\nFull Assessment: {assessment['irisUrl']}")
            ...         
            ...         if assessment.get('lastUpdated'):
            ...             print(f"Last Updated: {assessment['lastUpdated']}")
            >>> else:
            ...     print("No IRIS assessment available for this chemical")
            >>> 
            >>> # Example: Check for cancer classification
            >>> if data:
            ...     for assessment in data:
            ...         woe = assessment.get('cancerWeightOfEvidence', '')
            ...         if 'carcinogenic' in woe.lower():
            ...             print(f"WARNING: {assessment.get('chemicalName')} classified as carcinogenic")

        Note:
            - Only chemicals with completed IRIS assessments have data
            - IRIS assessments undergo rigorous scientific review
            - Assessments are periodically updated as new data becomes available
            - Not all chemicals have both oral and inhalation values
            - Not all chemicals have cancer assessments
            - IRIS values are widely used in regulatory risk assessment
            - Full assessments with supporting documentation available at irisUrl
            - Assessment status indicates stage: draft, final, under review, etc.
        """
        if not dtxsid or not isinstance(dtxsid, str):
            raise ValueError("dtxsid must be a non-empty string")

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

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

Initialize the IRIS 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 Any

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/hazard/iris.py 
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
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: Any
):
    """
    Initialize the IRIS 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
    )

get_data_by_dtxsid(dtxsid, use_cache=None) 

    Get all IRIS assessment data by DTXSID.

    Retrieves comprehensive IRIS assessment information for a chemical identified 
    by its DSSTox Substance Identifier. IRIS assessments include detailed health 
    hazard characterizations and toxicity reference values used in risk assessment.

    Args:
        dtxsid: DSSTox Substance Identifier (e.g., 'DTXSID7020182')
        use_cache: Whether to use cache for this request. If None, uses
            the instance default setting.

    Returns:
        List of dictionaries containing IRIS assessment data with fields such as:
            - dtxsid (str): Chemical identifier
            - casrn (str): CAS Registry Number
            - chemicalName (str): Chemical name
            - irisUrl (str): URL to full IRIS assessment
            - lastUpdated (str): Last assessment update date
            - assessmentStatus (str): Status of assessment

            Non-cancer hazard data:
            - oralRfD (float): Oral reference dose
            - oralRfDUnits (str): RfD units (typically mg/kg-day)
            - oralRfDCriticalEffect (str): Critical effect for RfD
            - oralRfDPOD (float): Point of departure
            - oralRfDUF (int): Uncertainty factor
            - inhalationRfC (float): Inhalation reference concentration
            - inhalationRfCUnits (str): RfC units (typically mg/m³)
            - inhalationRfCCriticalEffect (str): Critical effect for RfC
            - inhalationRfCPOD (float): Point of departure
            - inhalationRfCUF (int): Uncertainty factor

            Cancer hazard data:
            - cancerWeightOfEvidence (str): Weight of evidence classification
            - oralSlopeFactor (float): Oral cancer slope factor
            - oralSlopeFactorUnits (str): Slope factor units
            - inhalationUnitRisk (float): Inhalation unit risk
            - inhalationUnitRiskUnits (str): Unit risk units

            - Notes: Exact fields vary by assessment

    Raises:
        ValueError: If dtxsid is not a valid non-empty string
        PermissionError: If API key is invalid
        RuntimeError: For other API errors

    Example:
        >>> from pycomptox.hazard import IRIS
        >>> iris = IRIS()
        >>> 
        >>> # Get IRIS data for formaldehyde
        >>> data = iris.get_data_by_dtxsid("DTXSID7020182")
        >>> 
        >>> if data:
        ...     print(f"Found {len(data)} IRIS assessment(s)")
        ...     
        ...     for assessment in data:
        ...         print(f"

Chemical: {assessment.get('chemicalName', 'N/A')}") ... print(f"CAS: {assessment.get('casrn', 'N/A')}") ... print(f"Status: {assessment.get('assessmentStatus', 'N/A')}") ...
... # Non-cancer oral hazard ... if assessment.get('oralRfD'): ... print(f" Oral RfD: {assessment['oralRfD']} {assessment.get('oralRfDUnits', '')}") ... if assessment.get('oralRfDCriticalEffect'): ... print(f" Critical Effect: {assessment['oralRfDCriticalEffect']}") ... if assessment.get('oralRfDUF'): ... print(f" Uncertainty Factor: {assessment['oralRfDUF']}") ...
... # Non-cancer inhalation hazard ... if assessment.get('inhalationRfC'): ... print(f" Inhalation RfC: {assessment['inhalationRfC']} {assessment.get('inhalationRfCUnits', '')}") ... if assessment.get('inhalationRfCCriticalEffect'): ... print(f" Critical Effect: {assessment['inhalationRfCCriticalEffect']}") ...
... # Cancer hazard ... if assessment.get('cancerWeightOfEvidence'): ... print(f" Cancer Weight of Evidence: {assessment['cancerWeightOfEvidence']}") ...
... if assessment.get('oralSlopeFactor'): ... print(f"Oral Slope Factor: {assessment['oralSlopeFactor']} {assessment.get('oralSlopeFactorUnits', '')}") ...
... if assessment.get('inhalationUnitRisk'): ... print(f"Inhalation Unit Risk: {assessment['inhalationUnitRisk']} {assessment.get('inhalationUnitRiskUnits', '')}") ...
... # Link to full assessment ... if assessment.get('irisUrl'): ... print(f" Full Assessment: {assessment['irisUrl']}") ...
... if assessment.get('lastUpdated'): ... print(f"Last Updated: {assessment['lastUpdated']}") >>> else: ... print("No IRIS assessment available for this chemical") >>> >>> # Example: Check for cancer classification >>> if data: ... for assessment in data: ... woe = assessment.get('cancerWeightOfEvidence', '') ... if 'carcinogenic' in woe.lower(): ... print(f"WARNING: {assessment.get('chemicalName')} classified as carcinogenic")

    Note:
        - Only chemicals with completed IRIS assessments have data
        - IRIS assessments undergo rigorous scientific review
        - Assessments are periodically updated as new data becomes available
        - Not all chemicals have both oral and inhalation values
        - Not all chemicals have cancer assessments
        - IRIS values are widely used in regulatory risk assessment
        - Full assessments with supporting documentation available at irisUrl
        - Assessment status indicates stage: draft, final, under review, etc.
Source code in src/pycomptox/hazard/iris.py 
 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
def get_data_by_dtxsid(self, dtxsid: str, 
                       use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
    """
    Get all IRIS assessment data by DTXSID.

    Retrieves comprehensive IRIS assessment information for a chemical identified 
    by its DSSTox Substance Identifier. IRIS assessments include detailed health 
    hazard characterizations and toxicity reference values used in risk assessment.

    Args:
        dtxsid: DSSTox Substance Identifier (e.g., 'DTXSID7020182')
        use_cache: Whether to use cache for this request. If None, uses
            the instance default setting.

    Returns:
        List of dictionaries containing IRIS assessment data with fields such as:
            - dtxsid (str): Chemical identifier
            - casrn (str): CAS Registry Number
            - chemicalName (str): Chemical name
            - irisUrl (str): URL to full IRIS assessment
            - lastUpdated (str): Last assessment update date
            - assessmentStatus (str): Status of assessment

            Non-cancer hazard data:
            - oralRfD (float): Oral reference dose
            - oralRfDUnits (str): RfD units (typically mg/kg-day)
            - oralRfDCriticalEffect (str): Critical effect for RfD
            - oralRfDPOD (float): Point of departure
            - oralRfDUF (int): Uncertainty factor
            - inhalationRfC (float): Inhalation reference concentration
            - inhalationRfCUnits (str): RfC units (typically mg/m³)
            - inhalationRfCCriticalEffect (str): Critical effect for RfC
            - inhalationRfCPOD (float): Point of departure
            - inhalationRfCUF (int): Uncertainty factor

            Cancer hazard data:
            - cancerWeightOfEvidence (str): Weight of evidence classification
            - oralSlopeFactor (float): Oral cancer slope factor
            - oralSlopeFactorUnits (str): Slope factor units
            - inhalationUnitRisk (float): Inhalation unit risk
            - inhalationUnitRiskUnits (str): Unit risk units

            - Notes: Exact fields vary by assessment

    Raises:
        ValueError: If dtxsid is not a valid non-empty string
        PermissionError: If API key is invalid
        RuntimeError: For other API errors

    Example:
        >>> from pycomptox.hazard import IRIS
        >>> iris = IRIS()
        >>> 
        >>> # Get IRIS data for formaldehyde
        >>> data = iris.get_data_by_dtxsid("DTXSID7020182")
        >>> 
        >>> if data:
        ...     print(f"Found {len(data)} IRIS assessment(s)")
        ...     
        ...     for assessment in data:
        ...         print(f"\nChemical: {assessment.get('chemicalName', 'N/A')}")
        ...         print(f"CAS: {assessment.get('casrn', 'N/A')}")
        ...         print(f"Status: {assessment.get('assessmentStatus', 'N/A')}")
        ...         
        ...         # Non-cancer oral hazard
        ...         if assessment.get('oralRfD'):
        ...             print(f"\nOral RfD: {assessment['oralRfD']} {assessment.get('oralRfDUnits', '')}")
        ...             if assessment.get('oralRfDCriticalEffect'):
        ...                 print(f"  Critical Effect: {assessment['oralRfDCriticalEffect']}")
        ...             if assessment.get('oralRfDUF'):
        ...                 print(f"  Uncertainty Factor: {assessment['oralRfDUF']}")
        ...         
        ...         # Non-cancer inhalation hazard
        ...         if assessment.get('inhalationRfC'):
        ...             print(f"\nInhalation RfC: {assessment['inhalationRfC']} {assessment.get('inhalationRfCUnits', '')}")
        ...             if assessment.get('inhalationRfCCriticalEffect'):
        ...                 print(f"  Critical Effect: {assessment['inhalationRfCCriticalEffect']}")
        ...         
        ...         # Cancer hazard
        ...         if assessment.get('cancerWeightOfEvidence'):
        ...             print(f"\nCancer Weight of Evidence: {assessment['cancerWeightOfEvidence']}")
        ...         
        ...         if assessment.get('oralSlopeFactor'):
        ...             print(f"Oral Slope Factor: {assessment['oralSlopeFactor']} {assessment.get('oralSlopeFactorUnits', '')}")
        ...         
        ...         if assessment.get('inhalationUnitRisk'):
        ...             print(f"Inhalation Unit Risk: {assessment['inhalationUnitRisk']} {assessment.get('inhalationUnitRiskUnits', '')}")
        ...         
        ...         # Link to full assessment
        ...         if assessment.get('irisUrl'):
        ...             print(f"\nFull Assessment: {assessment['irisUrl']}")
        ...         
        ...         if assessment.get('lastUpdated'):
        ...             print(f"Last Updated: {assessment['lastUpdated']}")
        >>> else:
        ...     print("No IRIS assessment available for this chemical")
        >>> 
        >>> # Example: Check for cancer classification
        >>> if data:
        ...     for assessment in data:
        ...         woe = assessment.get('cancerWeightOfEvidence', '')
        ...         if 'carcinogenic' in woe.lower():
        ...             print(f"WARNING: {assessment.get('chemicalName')} classified as carcinogenic")

    Note:
        - Only chemicals with completed IRIS assessments have data
        - IRIS assessments undergo rigorous scientific review
        - Assessments are periodically updated as new data becomes available
        - Not all chemicals have both oral and inhalation values
        - Not all chemicals have cancer assessments
        - IRIS values are widely used in regulatory risk assessment
        - Full assessments with supporting documentation available at irisUrl
        - Assessment status indicates stage: draft, final, under review, etc.
    """
    if not dtxsid or not isinstance(dtxsid, str):
        raise ValueError("dtxsid must be a non-empty string")

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