Skip to content

ToxValDBSkinEye API Reference

pycomptox.hazard.toxvaldbskineye.ToxValDBSkinEye

Bases: CachedAPIClient

Client for accessing skin and eye irritation data from EPA CompTox Dashboard.

Skin and eye irritation tests are used to assess the safety of products and chemicals that may come into contact with the skin or eyes. These tests are important for: - Product safety labeling - Chemical registration requirements - Agrochemical safety assessment - Drug development and safety evaluation

Types of skin and eye irritation tests include: - Draize test: Traditional rabbit eye/skin irritation test - EpiOcular Eye Irritation Test (EIT): In vitro alternative - Red blood cells test: Hemolysis-based assessment - Patch test: Human skin sensitization test

This class provides methods for retrieving irritation and corrosivity data for chemicals, including severity scores, study details, and test outcomes.

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 ToxValDBSkinEye skineye = ToxValDBSkinEye()

Get skin/eye irritation data for a chemical

data = skineye.get_data_by_dtxsid("DTXSID0021125") if data: ... print(f"Found {len(data)} irritation test records")

Source code in src/pycomptox/hazard/toxvaldbskineye.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
209
class ToxValDBSkinEye(CachedAPIClient):
    """
    Client for accessing skin and eye irritation data from EPA CompTox Dashboard.

    Skin and eye irritation tests are used to assess the safety of products and 
    chemicals that may come into contact with the skin or eyes. These tests are 
    important for:
    - Product safety labeling
    - Chemical registration requirements
    - Agrochemical safety assessment
    - Drug development and safety evaluation

    Types of skin and eye irritation tests include:
    - Draize test: Traditional rabbit eye/skin irritation test
    - EpiOcular Eye Irritation Test (EIT): In vitro alternative
    - Red blood cells test: Hemolysis-based assessment
    - Patch test: Human skin sensitization test

    This class provides methods for retrieving irritation and corrosivity data
    for chemicals, including severity scores, study details, and test outcomes.

    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 ToxValDBSkinEye
        >>> skineye = ToxValDBSkinEye()
        >>> 
        >>> # Get skin/eye irritation data for a chemical
        >>> data = skineye.get_data_by_dtxsid("DTXSID0021125")
        >>> if data:
        ...     print(f"Found {len(data)} irritation test records")
    """

    def get_data_by_dtxsid(self, dtxsid: str, 
                           use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
        """
        Get skin and eye irritation data by DTXSID.

        Retrieves skin and eye irritation test data for a specific chemical identified 
        by its DSSTox Substance Identifier. Includes results from various irritation 
        and corrosivity tests used for hazard assessment and product labeling.

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

        Returns:
            List of dictionaries containing skin/eye irritation data with fields such as:
                - dtxsid (str): Chemical identifier
                - testType (str): Type of irritation test
                - endpoint (str): Measured endpoint
                - result (str): Test result or classification
                - score (float): Irritation score (when applicable)
                - severity (str): Severity classification
                - species (str): Test species or system
                - exposureDuration (str): Duration of exposure
                - source (str): Data source
                - study (str): Study reference
                - Notes: Exact fields vary by test type

        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 ToxValDBSkinEye
            >>> skineye = ToxValDBSkinEye()
            >>> 
            >>> # Get skin/eye irritation data for benzene
            >>> data = skineye.get_data_by_dtxsid("DTXSID0021125")
            >>> 
            >>> if data:
            ...     print(f"Found {len(data)} irritation test records")
            ...     
            ...     # Group by test type
            ...     by_test = {}
            ...     for record in data:
            ...         test_type = record.get('testType', 'Unknown')
            ...         if test_type not in by_test:
            ...             by_test[test_type] = []
            ...         by_test[test_type].append(record)
            ...     
            ...     # Display results by test type
            ...     for test_type, records in by_test.items():
            ...         print(f"\n{test_type}:")
            ...         for rec in records:
            ...             result = rec.get('result', 'N/A')
            ...             severity = rec.get('severity', '')
            ...             print(f"  - {result} {severity}")
            ...             if rec.get('score'):
            ...                 print(f"    Score: {rec['score']}")
            >>> else:
            ...     print("No skin/eye irritation data available")

        Note:
            - Not all chemicals have irritation test data
            - Multiple test types may be available for the same chemical
            - Severity classifications vary by test method
            - Draize scores range from 0 (no irritation) to 4 (severe)
            - Data supports GHS hazard classification
        """
        if not dtxsid or not isinstance(dtxsid, str):
            raise ValueError("dtxsid must be a non-empty string")

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

    def get_data_by_dtxsid_batch(self, dtxsids: List[str], 
                                 use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
        """
        Get skin and eye irritation data for multiple chemicals in a single request.

        Batch retrieval of skin and eye irritation test data for up to 200 chemicals.
        More efficient than making individual requests when querying multiple chemicals.

        Args:
            dtxsids: List of DSSTox Substance Identifiers (max 200)
            use_cache: Whether to use cache for this request. If None, uses
                the instance default setting.

        Returns:
            List of dictionaries containing skin/eye irritation data for all
            requested chemicals. Each entry includes similar fields as
            get_data_by_dtxsid().

        Raises:
            ValueError: If dtxsids list is empty or contains more than 200 entries
            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 ToxValDBSkinEye
            >>> skineye = ToxValDBSkinEye()
            >>> 
            >>> # Get skin/eye data for multiple chemicals
            >>> dtxsids = ["DTXSID0021125", "DTXSID7020182", "DTXSID0020032"]
            >>> batch_data = skineye.get_data_by_dtxsid_batch(dtxsids)
            >>> 
            >>> # Group by chemical
            >>> by_chemical = {}
            >>> for record in batch_data:
            ...     dtxsid = record['dtxsid']
            ...     if dtxsid not in by_chemical:
            ...         by_chemical[dtxsid] = []
            ...     by_chemical[dtxsid].append(record)
            >>> 
            >>> # Display summary
            >>> for dtxsid, records in by_chemical.items():
            ...     print(f"{dtxsid}: {len(records)} test record(s)")
            ...     
            ...     # Check for severe irritation
            ...     severe = [r for r in records if 'severe' in str(r.get('severity', '')).lower()]
            ...     if severe:
            ...         print(f"  WARNING: {len(severe)} severe irritation result(s)")
            ...     
            ...     # List test types
            ...     tests = set(r.get('testType', 'Unknown') for r in records)
            ...     print(f"  Test types: {', '.join(tests)}")

        Note:
            - Maximum 200 DTXSIDs per request
            - Results may include multiple test records per chemical
            - Batch requests are more efficient than individual queries
            - Useful for screening chemical libraries for irritation potential
        """
        if not dtxsids:
            raise ValueError("dtxsids list cannot be empty")

        if len(dtxsids) > 200:
            raise ValueError(f"Maximum 200 DTXSIDs allowed, got {len(dtxsids)}")

        endpoint = "hazard/skin-eye/search/by-dtxsid/"
        return self._make_cached_request(
            endpoint, 
            json=dtxsids, 
            method='POST', 
            use_cache=use_cache
        )

get_data_by_dtxsid(dtxsid, use_cache=None) 

    Get skin and eye irritation data by DTXSID.

    Retrieves skin and eye irritation test data for a specific chemical identified 
    by its DSSTox Substance Identifier. Includes results from various irritation 
    and corrosivity tests used for hazard assessment and product labeling.

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

    Returns:
        List of dictionaries containing skin/eye irritation data with fields such as:
            - dtxsid (str): Chemical identifier
            - testType (str): Type of irritation test
            - endpoint (str): Measured endpoint
            - result (str): Test result or classification
            - score (float): Irritation score (when applicable)
            - severity (str): Severity classification
            - species (str): Test species or system
            - exposureDuration (str): Duration of exposure
            - source (str): Data source
            - study (str): Study reference
            - Notes: Exact fields vary by test type

    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 ToxValDBSkinEye
        >>> skineye = ToxValDBSkinEye()
        >>> 
        >>> # Get skin/eye irritation data for benzene
        >>> data = skineye.get_data_by_dtxsid("DTXSID0021125")
        >>> 
        >>> if data:
        ...     print(f"Found {len(data)} irritation test records")
        ...     
        ...     # Group by test type
        ...     by_test = {}
        ...     for record in data:
        ...         test_type = record.get('testType', 'Unknown')
        ...         if test_type not in by_test:
        ...             by_test[test_type] = []
        ...         by_test[test_type].append(record)
        ...     
        ...     # Display results by test type
        ...     for test_type, records in by_test.items():
        ...         print(f"

{test_type}:") ... for rec in records: ... result = rec.get('result', 'N/A') ... severity = rec.get('severity', '') ... print(f" - {result} {severity}") ... if rec.get('score'): ... print(f" Score: {rec['score']}") >>> else: ... print("No skin/eye irritation data available")

    Note:
        - Not all chemicals have irritation test data
        - Multiple test types may be available for the same chemical
        - Severity classifications vary by test method
        - Draize scores range from 0 (no irritation) to 4 (severe)
        - Data supports GHS hazard classification
Source code in src/pycomptox/hazard/toxvaldbskineye.py 
 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
def get_data_by_dtxsid(self, dtxsid: str, 
                       use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
    """
    Get skin and eye irritation data by DTXSID.

    Retrieves skin and eye irritation test data for a specific chemical identified 
    by its DSSTox Substance Identifier. Includes results from various irritation 
    and corrosivity tests used for hazard assessment and product labeling.

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

    Returns:
        List of dictionaries containing skin/eye irritation data with fields such as:
            - dtxsid (str): Chemical identifier
            - testType (str): Type of irritation test
            - endpoint (str): Measured endpoint
            - result (str): Test result or classification
            - score (float): Irritation score (when applicable)
            - severity (str): Severity classification
            - species (str): Test species or system
            - exposureDuration (str): Duration of exposure
            - source (str): Data source
            - study (str): Study reference
            - Notes: Exact fields vary by test type

    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 ToxValDBSkinEye
        >>> skineye = ToxValDBSkinEye()
        >>> 
        >>> # Get skin/eye irritation data for benzene
        >>> data = skineye.get_data_by_dtxsid("DTXSID0021125")
        >>> 
        >>> if data:
        ...     print(f"Found {len(data)} irritation test records")
        ...     
        ...     # Group by test type
        ...     by_test = {}
        ...     for record in data:
        ...         test_type = record.get('testType', 'Unknown')
        ...         if test_type not in by_test:
        ...             by_test[test_type] = []
        ...         by_test[test_type].append(record)
        ...     
        ...     # Display results by test type
        ...     for test_type, records in by_test.items():
        ...         print(f"\n{test_type}:")
        ...         for rec in records:
        ...             result = rec.get('result', 'N/A')
        ...             severity = rec.get('severity', '')
        ...             print(f"  - {result} {severity}")
        ...             if rec.get('score'):
        ...                 print(f"    Score: {rec['score']}")
        >>> else:
        ...     print("No skin/eye irritation data available")

    Note:
        - Not all chemicals have irritation test data
        - Multiple test types may be available for the same chemical
        - Severity classifications vary by test method
        - Draize scores range from 0 (no irritation) to 4 (severe)
        - Data supports GHS hazard classification
    """
    if not dtxsid or not isinstance(dtxsid, str):
        raise ValueError("dtxsid must be a non-empty string")

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

get_data_by_dtxsid_batch(dtxsids, use_cache=None)

Get skin and eye irritation data for multiple chemicals in a single request.

Batch retrieval of skin and eye irritation test data for up to 200 chemicals. More efficient than making individual requests when querying multiple chemicals.

Parameters:

Name Type Description Default
dtxsids List[str]

List of DSSTox Substance Identifiers (max 200)

 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 skin/eye irritation data for all
List[Dict[str, Any]]

requested chemicals. Each entry includes similar fields as
List[Dict[str, Any]]

get_data_by_dtxsid().

Raises:

Type Description
ValueError

If dtxsids list is empty or contains more than 200 entries
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 ToxValDBSkinEye skineye = ToxValDBSkinEye()

Get skin/eye data for multiple chemicals

dtxsids = ["DTXSID0021125", "DTXSID7020182", "DTXSID0020032"] batch_data = skineye.get_data_by_dtxsid_batch(dtxsids)

Group by chemical

by_chemical = {} for record in batch_data: ... dtxsid = record['dtxsid'] ... if dtxsid not in by_chemical: ... by_chemical[dtxsid] = [] ... by_chemical[dtxsid].append(record)

Display summary

for dtxsid, records in by_chemical.items(): ... print(f"{dtxsid}: {len(records)} test record(s)") ...
... # Check for severe irritation ... severe = [r for r in records if 'severe' in str(r.get('severity', '')).lower()] ... if severe: ... print(f" WARNING: {len(severe)} severe irritation result(s)") ...
... # List test types ... tests = set(r.get('testType', 'Unknown') for r in records) ... print(f" Test types: {', '.join(tests)}")

Note
  • Maximum 200 DTXSIDs per request
  • Results may include multiple test records per chemical
  • Batch requests are more efficient than individual queries
  • Useful for screening chemical libraries for irritation potential
Source code in src/pycomptox/hazard/toxvaldbskineye.py 
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
209
def get_data_by_dtxsid_batch(self, dtxsids: List[str], 
                             use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
    """
    Get skin and eye irritation data for multiple chemicals in a single request.

    Batch retrieval of skin and eye irritation test data for up to 200 chemicals.
    More efficient than making individual requests when querying multiple chemicals.

    Args:
        dtxsids: List of DSSTox Substance Identifiers (max 200)
        use_cache: Whether to use cache for this request. If None, uses
            the instance default setting.

    Returns:
        List of dictionaries containing skin/eye irritation data for all
        requested chemicals. Each entry includes similar fields as
        get_data_by_dtxsid().

    Raises:
        ValueError: If dtxsids list is empty or contains more than 200 entries
        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 ToxValDBSkinEye
        >>> skineye = ToxValDBSkinEye()
        >>> 
        >>> # Get skin/eye data for multiple chemicals
        >>> dtxsids = ["DTXSID0021125", "DTXSID7020182", "DTXSID0020032"]
        >>> batch_data = skineye.get_data_by_dtxsid_batch(dtxsids)
        >>> 
        >>> # Group by chemical
        >>> by_chemical = {}
        >>> for record in batch_data:
        ...     dtxsid = record['dtxsid']
        ...     if dtxsid not in by_chemical:
        ...         by_chemical[dtxsid] = []
        ...     by_chemical[dtxsid].append(record)
        >>> 
        >>> # Display summary
        >>> for dtxsid, records in by_chemical.items():
        ...     print(f"{dtxsid}: {len(records)} test record(s)")
        ...     
        ...     # Check for severe irritation
        ...     severe = [r for r in records if 'severe' in str(r.get('severity', '')).lower()]
        ...     if severe:
        ...         print(f"  WARNING: {len(severe)} severe irritation result(s)")
        ...     
        ...     # List test types
        ...     tests = set(r.get('testType', 'Unknown') for r in records)
        ...     print(f"  Test types: {', '.join(tests)}")

    Note:
        - Maximum 200 DTXSIDs per request
        - Results may include multiple test records per chemical
        - Batch requests are more efficient than individual queries
        - Useful for screening chemical libraries for irritation potential
    """
    if not dtxsids:
        raise ValueError("dtxsids list cannot be empty")

    if len(dtxsids) > 200:
        raise ValueError(f"Maximum 200 DTXSIDs allowed, got {len(dtxsids)}")

    endpoint = "hazard/skin-eye/search/by-dtxsid/"
    return self._make_cached_request(
        endpoint, 
        json=dtxsids, 
        method='POST', 
        use_cache=use_cache
    )