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.

 '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 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
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
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 __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 PPRTV 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_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
            PermissionError: If API key is invalid
            RuntimeError: For other API errors

        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)

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

Initialize the PPRTV 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/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
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 PPRTV 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_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
PermissionError

If API key is invalid
RuntimeError

For other API errors
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 
 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
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
        PermissionError: If API key is invalid
        RuntimeError: For other API errors

    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)