Skip to content

PPRTV API Reference

pycomptox.hazard.pprtv.PPRTV

Bases: CachedAPIClient

Client for accessing Provisional Peer-Reviewed Toxicity Values (PPRTV) data from EPA CompTox Dashboard.

This class provides methods for retrieving PPRTV hazard characterization data, including reference concentrations (RfC), reference doses (RfD), and weight of evidence assessments.

PPRTV provides toxicity values for chemicals that do not have EPA IRIS assessments. These values support human health risk assessments and are developed following peer review.

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 PPRTV pprtv = PPRTV()

Get PPRTV data for a chemical

data = pprtv.get_all_pprtv_chemical_by_dtxsid("DTXSID7020182") if data: ... print(f"RfC: {data[0].get('rfcValue')}") ... print(f"RfD: {data[0].get('rfdValue')}")

Source code in src/pycomptox/hazard/pprtv.py 
 18
 19
 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
class PPRTV(CachedAPIClient):
    """
    Client for accessing Provisional Peer-Reviewed Toxicity Values (PPRTV) data from EPA CompTox Dashboard.

    This class provides methods for retrieving PPRTV hazard characterization data, including
    reference concentrations (RfC), reference doses (RfD), and weight of evidence assessments.

    PPRTV provides toxicity values for chemicals that do not have EPA IRIS assessments.
    These values support human health risk assessments and are developed following peer review.

    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 PPRTV
        >>> pprtv = PPRTV()
        >>> 
        >>> # Get PPRTV data for a chemical
        >>> data = pprtv.get_all_pprtv_chemical_by_dtxsid("DTXSID7020182")
        >>> if data:
        ...     print(f"RfC: {data[0].get('rfcValue')}")
        ...     print(f"RfD: {data[0].get('rfdValue')}")
    """

    def get_all_pprtv_chemical_by_dtxsid(
        self,
        dtxsid: str,
        use_cache: Optional[bool] = None
    ) -> List[Dict[str, Any]]:
        """
        Get all PPRTV chemical data by DTXSID.

        Retrieves Provisional Peer-Reviewed Toxicity Values (PPRTV) hazard data for
        a specific chemical identified by its DSSTox Substance Identifier (DTXSID).

        PPRTV data includes reference concentrations (RfC) for inhalation exposure,
        reference doses (RfD) for oral exposure, weight of evidence classifications,
        and links to full assessments.

        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 PPRTV data with fields:
                - id (int): Record identifier
                - dtxsid (str): DSSTox Substance Identifier
                - pprtvSubstanceId (int): PPRTV substance identifier
                - name (str): Chemical name
                - casrn (str): CAS Registry Number
                - lastRevision (int): Last revision date/number
                - pprtvAssessment (str): Link to PPRTV assessment
                - irisLink (str): Link to IRIS assessment (if available)
                - rfcValue (str): Reference Concentration for inhalation (mg/m³)
                - rfdValue (str): Reference Dose for oral exposure (mg/kg-day)
                - woe (str): Weight of Evidence classification

        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 PPRTV
            >>> pprtv = PPRTV()
            >>> 
            >>> # Get PPRTV data for benzene
            >>> data = pprtv.get_all_pprtv_chemical_by_dtxsid("DTXSID7020182")
            >>> 
            >>> if data:
            ...     for record in data:
            ...         print(f"Chemical: {record['name']}")
            ...         print(f"CAS: {record['casrn']}")
            ...         if record.get('rfcValue'):
            ...             print(f"RfC (inhalation): {record['rfcValue']} mg/m³")
            ...         if record.get('rfdValue'):
            ...             print(f"RfD (oral): {record['rfdValue']} mg/kg-day")
            ...         if record.get('woe'):
            ...             print(f"Weight of Evidence: {record['woe']}")
            ...         if record.get('pprtvAssessment'):
            ...             print(f"Assessment: {record['pprtvAssessment']}")
            >>> else:
            ...     print("No PPRTV data available for this chemical")

        Note:
            - Not all chemicals have PPRTV assessments
            - RfC values are for inhalation exposure (mg/m³)
            - RfD values are for oral exposure (mg/kg-day)
            - Weight of Evidence (WoE) classifications indicate the strength
              of evidence for carcinogenicity or other health effects
            - PPRTV assessments are provisional and may be superseded by
              IRIS assessments
        """
        if not dtxsid or not isinstance(dtxsid, str):
            raise ValueError("dtxsid must be a non-empty string")

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

get_all_pprtv_chemical_by_dtxsid(dtxsid, use_cache=None)

Get all PPRTV chemical data by DTXSID.

Retrieves Provisional Peer-Reviewed Toxicity Values (PPRTV) hazard data for a specific chemical identified by its DSSTox Substance Identifier (DTXSID).

PPRTV data includes reference concentrations (RfC) for inhalation exposure, reference doses (RfD) for oral exposure, weight of evidence classifications, and links to full assessments.

Parameters:

Name Type Description Default
dtxsid str

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

 required
use_cache Optional[bool]

Whether to use cache for this request. If None, uses the instance default setting.

 None

Returns:

Type Description
List[Dict[str, Any]]

List of dictionaries containing PPRTV data with fields: - id (int): Record identifier - dtxsid (str): DSSTox Substance Identifier - pprtvSubstanceId (int): PPRTV substance identifier - name (str): Chemical name - casrn (str): CAS Registry Number - lastRevision (int): Last revision date/number - pprtvAssessment (str): Link to PPRTV assessment - irisLink (str): Link to IRIS assessment (if available) - rfcValue (str): Reference Concentration for inhalation (mg/m³) - rfdValue (str): Reference Dose for oral exposure (mg/kg-day) - woe (str): Weight of Evidence classification

Raises:

Type Description
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 PPRTV pprtv = PPRTV()

Get PPRTV data for benzene

data = pprtv.get_all_pprtv_chemical_by_dtxsid("DTXSID7020182")

if data: ... for record in data: ... print(f"Chemical: {record['name']}") ... print(f"CAS: {record['casrn']}") ... if record.get('rfcValue'): ... print(f"RfC (inhalation): {record['rfcValue']} mg/m³") ... if record.get('rfdValue'): ... print(f"RfD (oral): {record['rfdValue']} mg/kg-day") ... if record.get('woe'): ... print(f"Weight of Evidence: {record['woe']}") ... if record.get('pprtvAssessment'): ... print(f"Assessment: {record['pprtvAssessment']}") else: ... print("No PPRTV data available for this chemical")

Note
  • Not all chemicals have PPRTV assessments
  • RfC values are for inhalation exposure (mg/m³)
  • RfD values are for oral exposure (mg/kg-day)
  • Weight of Evidence (WoE) classifications indicate the strength of evidence for carcinogenicity or other health effects
  • PPRTV assessments are provisional and may be superseded by IRIS assessments
Source code in src/pycomptox/hazard/pprtv.py 
 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
def get_all_pprtv_chemical_by_dtxsid(
    self,
    dtxsid: str,
    use_cache: Optional[bool] = None
) -> List[Dict[str, Any]]:
    """
    Get all PPRTV chemical data by DTXSID.

    Retrieves Provisional Peer-Reviewed Toxicity Values (PPRTV) hazard data for
    a specific chemical identified by its DSSTox Substance Identifier (DTXSID).

    PPRTV data includes reference concentrations (RfC) for inhalation exposure,
    reference doses (RfD) for oral exposure, weight of evidence classifications,
    and links to full assessments.

    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 PPRTV data with fields:
            - id (int): Record identifier
            - dtxsid (str): DSSTox Substance Identifier
            - pprtvSubstanceId (int): PPRTV substance identifier
            - name (str): Chemical name
            - casrn (str): CAS Registry Number
            - lastRevision (int): Last revision date/number
            - pprtvAssessment (str): Link to PPRTV assessment
            - irisLink (str): Link to IRIS assessment (if available)
            - rfcValue (str): Reference Concentration for inhalation (mg/m³)
            - rfdValue (str): Reference Dose for oral exposure (mg/kg-day)
            - woe (str): Weight of Evidence classification

    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 PPRTV
        >>> pprtv = PPRTV()
        >>> 
        >>> # Get PPRTV data for benzene
        >>> data = pprtv.get_all_pprtv_chemical_by_dtxsid("DTXSID7020182")
        >>> 
        >>> if data:
        ...     for record in data:
        ...         print(f"Chemical: {record['name']}")
        ...         print(f"CAS: {record['casrn']}")
        ...         if record.get('rfcValue'):
        ...             print(f"RfC (inhalation): {record['rfcValue']} mg/m³")
        ...         if record.get('rfdValue'):
        ...             print(f"RfD (oral): {record['rfdValue']} mg/kg-day")
        ...         if record.get('woe'):
        ...             print(f"Weight of Evidence: {record['woe']}")
        ...         if record.get('pprtvAssessment'):
        ...             print(f"Assessment: {record['pprtvAssessment']}")
        >>> else:
        ...     print("No PPRTV data available for this chemical")

    Note:
        - Not all chemicals have PPRTV assessments
        - RfC values are for inhalation exposure (mg/m³)
        - RfD values are for oral exposure (mg/kg-day)
        - Weight of Evidence (WoE) classifications indicate the strength
          of evidence for carcinogenicity or other health effects
        - PPRTV assessments are provisional and may be superseded by
          IRIS assessments
    """
    if not dtxsid or not isinstance(dtxsid, str):
        raise ValueError("dtxsid must be a non-empty string")

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