Skip to content

HAWC API Reference

pycomptox.hazard.hawc.HAWC

Bases: CachedAPIClient

Client for accessing EPA HAWC (Health Assessment Workspace Collaborative) data.

EPA Health Assessment Workspace Collaborative (HAWC) is an interactive, expert-driven, content management system for EPA health and environmental risk assessment programs that is intended to promote: - Transparency in assessment processes - Data usability and accessibility - Understanding of data and decisions supporting assessments

EPA HAWC is an application that allows the data and decisions supporting an assessment to be evaluated and managed in modules (e.g., study evaluation, summary study data) that can then be publicly accessed online.

This class provides methods for retrieving links between chemicals in the CompTox Chemicals Dashboard and their corresponding HAWC assessments.

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 HAWC hawc = HAWC()

Get HAWC assessment links for a chemical

links = hawc.get_ccd_hawc_link_mapper_by_dtxsid("DTXSID7020182") if links: ... print(f"Found {len(links)} HAWC assessment(s)")

Source code in src/pycomptox/hazard/hawc.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
148
149
150
151
152
153
154
155
156
157
158
159
160
class HAWC(CachedAPIClient):
    """
    Client for accessing EPA HAWC (Health Assessment Workspace Collaborative) data.

    EPA Health Assessment Workspace Collaborative (HAWC) is an interactive, 
    expert-driven, content management system for EPA health and environmental risk 
    assessment programs that is intended to promote:
    - Transparency in assessment processes
    - Data usability and accessibility
    - Understanding of data and decisions supporting assessments

    EPA HAWC is an application that allows the data and decisions supporting an 
    assessment to be evaluated and managed in modules (e.g., study evaluation, 
    summary study data) that can then be publicly accessed online.

    This class provides methods for retrieving links between chemicals in the 
    CompTox Chemicals Dashboard and their corresponding HAWC assessments.

    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 HAWC
        >>> hawc = HAWC()
        >>> 
        >>> # Get HAWC assessment links for a chemical
        >>> links = hawc.get_ccd_hawc_link_mapper_by_dtxsid("DTXSID7020182")
        >>> if links:
        ...     print(f"Found {len(links)} HAWC 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 HAWC 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_ccd_hawc_link_mapper_by_dtxsid(self, dtxsid: str, 
                                   use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
        """
        Get CompTox Dashboard - EPA HAWC link mapper by DTXSID.

        Retrieves links between a chemical in the CompTox Chemicals Dashboard (CCD) 
        and its corresponding assessments in the EPA Health Assessment Workspace 
        Collaborative (HAWC) platform. This provides access to detailed health and 
        environmental risk assessment information for the chemical.

        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 HAWC link information with fields such as:
                - dtxsid (str): Chemical identifier
                - hawcUrl (str): URL to the HAWC assessment
                - hawcAssessmentId (int): HAWC assessment identifier
                - assessmentName (str): Name of the assessment
                - assessmentType (str): Type of assessment
                - program (str): EPA program conducting the assessment
                - status (str): Assessment status
                - lastUpdated (str): Last update date
                - description (str): Assessment description
                - Notes: Exact fields may vary

        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 HAWC
            >>> hawc = HAWC()
            >>> 
            >>> # Get HAWC links for formaldehyde
            >>> links = hawc.get_ccd_hawc_link_mapper_by_dtxsid("DTXSID7020182")
            >>> 
            >>> if links:
            ...     print(f"Found {len(links)} HAWC assessment(s) for this chemical")
            ...     
            ...     for link in links:
            ...         print(f"\nAssessment: {link.get('assessmentName', 'N/A')}")
            ...         print(f"Type: {link.get('assessmentType', 'N/A')}")
            ...         print(f"Program: {link.get('program', 'N/A')}")
            ...         print(f"Status: {link.get('status', 'N/A')}")
            ...         
            ...         if link.get('hawcUrl'):
            ...             print(f"HAWC URL: {link['hawcUrl']}")
            ...         
            ...         if link.get('description'):
            ...             print(f"Description: {link['description'][:100]}...")
            ...         
            ...         # Access the HAWC assessment
            ...         if link.get('hawcAssessmentId'):
            ...             print(f"Assessment ID: {link['hawcAssessmentId']}")
            >>> else:
            ...     print("No HAWC assessments found for this chemical")
            >>> 
            >>> # Example: Filter by assessment type
            >>> if links:
            ...     iris_assessments = [l for l in links 
            ...                        if 'IRIS' in l.get('program', '')]
            ...     if iris_assessments:
            ...         print(f"\nIRIS assessments: {len(iris_assessments)}")

        Note:
            - Not all chemicals have HAWC assessments
            - HAWC assessments are created for chemicals undergoing EPA review
            - Links provide direct access to detailed assessment data
            - HAWC platform allows viewing study evaluation and summary data
            - Assessments may be in various stages (in progress, completed, etc.)
            - Multiple assessments may exist for the same chemical from different programs
        """
        if not dtxsid or not isinstance(dtxsid, str):
            raise ValueError("dtxsid must be a non-empty string")

        endpoint = f"hazard/hawc/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 HAWC 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/hawc.py 
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
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 HAWC 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 CompTox Dashboard - EPA HAWC link mapper by DTXSID.

    Retrieves links between a chemical in the CompTox Chemicals Dashboard (CCD) 
    and its corresponding assessments in the EPA Health Assessment Workspace 
    Collaborative (HAWC) platform. This provides access to detailed health and 
    environmental risk assessment information for the chemical.

    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 HAWC link information with fields such as:
            - dtxsid (str): Chemical identifier
            - hawcUrl (str): URL to the HAWC assessment
            - hawcAssessmentId (int): HAWC assessment identifier
            - assessmentName (str): Name of the assessment
            - assessmentType (str): Type of assessment
            - program (str): EPA program conducting the assessment
            - status (str): Assessment status
            - lastUpdated (str): Last update date
            - description (str): Assessment description
            - Notes: Exact fields may vary

    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 HAWC
        >>> hawc = HAWC()
        >>> 
        >>> # Get HAWC links for formaldehyde
        >>> links = hawc.get_ccd_hawc_link_mapper_by_dtxsid("DTXSID7020182")
        >>> 
        >>> if links:
        ...     print(f"Found {len(links)} HAWC assessment(s) for this chemical")
        ...     
        ...     for link in links:
        ...         print(f"

Assessment: {link.get('assessmentName', 'N/A')}") ... print(f"Type: {link.get('assessmentType', 'N/A')}") ... print(f"Program: {link.get('program', 'N/A')}") ... print(f"Status: {link.get('status', 'N/A')}") ...
... if link.get('hawcUrl'): ... print(f"HAWC URL: {link['hawcUrl']}") ...
... if link.get('description'): ... print(f"Description: {link['description'][:100]}...") ...
... # Access the HAWC assessment ... if link.get('hawcAssessmentId'): ... print(f"Assessment ID: {link['hawcAssessmentId']}") >>> else: ... print("No HAWC assessments found for this chemical") >>> >>> # Example: Filter by assessment type >>> if links: ... iris_assessments = [l for l in links ... if 'IRIS' in l.get('program', '')] ... if iris_assessments: ... print(f" IRIS assessments: {len(iris_assessments)}")

    Note:
        - Not all chemicals have HAWC assessments
        - HAWC assessments are created for chemicals undergoing EPA review
        - Links provide direct access to detailed assessment data
        - HAWC platform allows viewing study evaluation and summary data
        - Assessments may be in various stages (in progress, completed, etc.)
        - Multiple assessments may exist for the same chemical from different programs
Source code in src/pycomptox/hazard/hawc.py 
 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
def get_ccd_hawc_link_mapper_by_dtxsid(self, dtxsid: str, 
                               use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
    """
    Get CompTox Dashboard - EPA HAWC link mapper by DTXSID.

    Retrieves links between a chemical in the CompTox Chemicals Dashboard (CCD) 
    and its corresponding assessments in the EPA Health Assessment Workspace 
    Collaborative (HAWC) platform. This provides access to detailed health and 
    environmental risk assessment information for the chemical.

    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 HAWC link information with fields such as:
            - dtxsid (str): Chemical identifier
            - hawcUrl (str): URL to the HAWC assessment
            - hawcAssessmentId (int): HAWC assessment identifier
            - assessmentName (str): Name of the assessment
            - assessmentType (str): Type of assessment
            - program (str): EPA program conducting the assessment
            - status (str): Assessment status
            - lastUpdated (str): Last update date
            - description (str): Assessment description
            - Notes: Exact fields may vary

    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 HAWC
        >>> hawc = HAWC()
        >>> 
        >>> # Get HAWC links for formaldehyde
        >>> links = hawc.get_ccd_hawc_link_mapper_by_dtxsid("DTXSID7020182")
        >>> 
        >>> if links:
        ...     print(f"Found {len(links)} HAWC assessment(s) for this chemical")
        ...     
        ...     for link in links:
        ...         print(f"\nAssessment: {link.get('assessmentName', 'N/A')}")
        ...         print(f"Type: {link.get('assessmentType', 'N/A')}")
        ...         print(f"Program: {link.get('program', 'N/A')}")
        ...         print(f"Status: {link.get('status', 'N/A')}")
        ...         
        ...         if link.get('hawcUrl'):
        ...             print(f"HAWC URL: {link['hawcUrl']}")
        ...         
        ...         if link.get('description'):
        ...             print(f"Description: {link['description'][:100]}...")
        ...         
        ...         # Access the HAWC assessment
        ...         if link.get('hawcAssessmentId'):
        ...             print(f"Assessment ID: {link['hawcAssessmentId']}")
        >>> else:
        ...     print("No HAWC assessments found for this chemical")
        >>> 
        >>> # Example: Filter by assessment type
        >>> if links:
        ...     iris_assessments = [l for l in links 
        ...                        if 'IRIS' in l.get('program', '')]
        ...     if iris_assessments:
        ...         print(f"\nIRIS assessments: {len(iris_assessments)}")

    Note:
        - Not all chemicals have HAWC assessments
        - HAWC assessments are created for chemicals undergoing EPA review
        - Links provide direct access to detailed assessment data
        - HAWC platform allows viewing study evaluation and summary data
        - Assessments may be in various stages (in progress, completed, etc.)
        - Multiple assessments may exist for the same chemical from different programs
    """
    if not dtxsid or not isinstance(dtxsid, str):
        raise ValueError("dtxsid must be a non-empty string")

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