Skip to content

FunctionalUse API Reference

pycomptox.exposure.functionaluse.FunctionalUse

Bases: CachedAPIClient

Client for accessing functional use data from EPA CompTox Dashboard.

This class provides methods for retrieving functional use information, which describes how chemicals are used in products and applications.

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, **kwargs

Delay in seconds between API calls for rate limiting. Default is 0.0 (no delay).

 0.0
Example

from pycomptox import FunctionalUse func_use = FunctionalUse()

Get functional use data for a chemical

data = func_use.functiona_use_by_dtxsid("DTXSID0020232")

Source code in src/pycomptox/exposure/functionaluse.py 
 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
class FunctionalUse(CachedAPIClient):
    """
    Client for accessing functional use data from EPA CompTox Dashboard.

    This class provides methods for retrieving functional use information,
    which describes how chemicals are used in products and applications.

    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, **kwargs): Delay in seconds between API calls for
            rate limiting. Default is 0.0 (no delay).

    Example:
        >>> from pycomptox import FunctionalUse
        >>> func_use = FunctionalUse()
        >>> 
        >>> # Get functional use data for a chemical
        >>> data = func_use.functiona_use_by_dtxsid("DTXSID0020232")
    """

    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):
        """
        Initialize the FunctionalUse 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

        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 functiona_use_by_dtxsid(self, dtxsid: str, use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
        """
        Get functional use data for a chemical.

        Retrieves functional use information for a specific chemical identified by
        its DSSTox Substance Identifier (DTXSID). Functional use describes how a
        chemical is used in products and industrial applications.

        Args:
            dtxsid: DSSTox Substance Identifier (e.g., 'DTXSID0020232')

        Returns:
            List of dictionaries containing functional use data for the chemical.
            Each entry includes use category, harmonized function, and other metadata.

        Raises:
            ValueError: If dtxsid is not a valid non-empty string

        Example:
            >>> func_use = FunctionalUse()
            >>> data = func_use.functiona_use_by_dtxsid("DTXSID0020232")
            >>> for use in data:
            ...     print(f"{use.get('harmonizedFunctionalUse', 'N/A')}")
        """
        if not dtxsid or not isinstance(dtxsid, str):
            raise ValueError("dtxsid must be a non-empty string")

        endpoint = f"exposure/functional-use/search/by-dtxsid/{dtxsid}"
        return self._make_cached_request(endpoint, use_cache=use_cache)

    def functional_use_probability_by_dtxsid(self, dtxsid: str, use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
        """
        Get predicted functional use probabilities for a chemical.

        Retrieves predicted functional use probabilities for a specific chemical.
        These predictions estimate the likelihood that a chemical is used for
        various functional purposes based on modeling.

        Args:
            dtxsid: DSSTox Substance Identifier (e.g., 'DTXSID0020232')

        Returns:
            List of dictionaries containing functional use predictions with
            probability scores for different use categories.

        Raises:
            ValueError: If dtxsid is not a valid non-empty string

        Example:
            >>> func_use = FunctionalUse()
            >>> probs = func_use.functional_use_probability_by_dtxsid("DTXSID0020232")
            >>> for pred in probs:
            ...     print(f"{pred.get('functionalUse')}: {pred.get('probability')}")
        """
        if not dtxsid or not isinstance(dtxsid, str):
            raise ValueError("dtxsid must be a non-empty string")

        endpoint = f"exposure/functional-use/probability/search/by-dtxsid/{dtxsid}"
        return self._make_cached_request(endpoint, use_cache=use_cache)

    def functiona_use_categories(self, use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
        """
        Get all functional use categories.

        Retrieves a complete list of functional use categories available in the
        database. This is useful for understanding the available classification
        system for chemical functional uses.

        Returns:
            List of dictionaries containing functional use categories with their
            names, descriptions, and hierarchical information.

        Example:
            >>> func_use = FunctionalUse()
            >>> categories = func_use.functiona_use_categories()
            >>> for cat in categories:
            ...     print(f"{cat.get('category', 'N/A')}: {cat.get('description', '')}")
        """
        endpoint = "exposure/functional-use/category"
        return self._make_cached_request(endpoint, use_cache=use_cache)

    def functional_use_by_dtxsid_batch(self, dtxsids: List[str], use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
        """
        Get functional use data for multiple chemicals in a single request.

        Retrieves functional use information for multiple chemicals at once using
        a batch API call. This is more efficient than making individual requests
        for each chemical.

        Args:
            dtxsids: List of DSSTox Substance Identifiers

        Returns:
            List of dictionaries containing functional use data for all requested
            chemicals. Results include the DTXSID and associated functional use
            information for each chemical.

        Raises:
            ValueError: If dtxsids is not a valid non-empty list

        Example:
            >>> func_use = FunctionalUse()
            >>> dtxsids = ["DTXSID0020232", "DTXSID7020182"]
            >>> batch_data = func_use.functional_use_by_dtxsid_batch(dtxsids)
            >>> for result in batch_data:
            ...     print(f"{result.get('dtxsid')}: {result.get('harmonizedFunctionalUse')}")
        """
        if not dtxsids or not isinstance(dtxsids, list) or len(dtxsids) == 0:
            raise ValueError("dtxsids must be a non-empty list of strings")

        if not all(isinstance(dtxsid, str) for dtxsid in dtxsids):
            raise ValueError("All elements in dtxsids must be strings")

        endpoint = "exposure/functional-use/search/by-dtxsid/"
        return self._make_request("POST", endpoint, json_data=dtxsids)

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

Initialize the FunctionalUse 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

Raises:

Type Description
ValueError

If no API key is provided or found in configuration
Source code in src/pycomptox/exposure/functionaluse.py 
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
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):
    """
    Initialize the FunctionalUse 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

    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
    )

functiona_use_by_dtxsid(dtxsid, use_cache=None)

Get functional use data for a chemical.

Retrieves functional use information for a specific chemical identified by its DSSTox Substance Identifier (DTXSID). Functional use describes how a chemical is used in products and industrial applications.

Parameters:

Name Type Description Default
dtxsid str

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

 required

Returns:

Type Description
List[Dict[str, Any]]

List of dictionaries containing functional use data for the chemical.
List[Dict[str, Any]]

Each entry includes use category, harmonized function, and other metadata.

Raises:

Type Description
ValueError

If dtxsid is not a valid non-empty string
Example

func_use = FunctionalUse() data = func_use.functiona_use_by_dtxsid("DTXSID0020232") for use in data: ... print(f"{use.get('harmonizedFunctionalUse', 'N/A')}")

Source code in src/pycomptox/exposure/functionaluse.py 
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
def functiona_use_by_dtxsid(self, dtxsid: str, use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
    """
    Get functional use data for a chemical.

    Retrieves functional use information for a specific chemical identified by
    its DSSTox Substance Identifier (DTXSID). Functional use describes how a
    chemical is used in products and industrial applications.

    Args:
        dtxsid: DSSTox Substance Identifier (e.g., 'DTXSID0020232')

    Returns:
        List of dictionaries containing functional use data for the chemical.
        Each entry includes use category, harmonized function, and other metadata.

    Raises:
        ValueError: If dtxsid is not a valid non-empty string

    Example:
        >>> func_use = FunctionalUse()
        >>> data = func_use.functiona_use_by_dtxsid("DTXSID0020232")
        >>> for use in data:
        ...     print(f"{use.get('harmonizedFunctionalUse', 'N/A')}")
    """
    if not dtxsid or not isinstance(dtxsid, str):
        raise ValueError("dtxsid must be a non-empty string")

    endpoint = f"exposure/functional-use/search/by-dtxsid/{dtxsid}"
    return self._make_cached_request(endpoint, use_cache=use_cache)

functiona_use_categories(use_cache=None)

Get all functional use categories.

Retrieves a complete list of functional use categories available in the database. This is useful for understanding the available classification system for chemical functional uses.

Returns:

Type Description
List[Dict[str, Any]]

List of dictionaries containing functional use categories with their
List[Dict[str, Any]]

names, descriptions, and hierarchical information.
Example

func_use = FunctionalUse() categories = func_use.functiona_use_categories() for cat in categories: ... print(f"{cat.get('category', 'N/A')}: {cat.get('description', '')}")

Source code in src/pycomptox/exposure/functionaluse.py 
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
def functiona_use_categories(self, use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
    """
    Get all functional use categories.

    Retrieves a complete list of functional use categories available in the
    database. This is useful for understanding the available classification
    system for chemical functional uses.

    Returns:
        List of dictionaries containing functional use categories with their
        names, descriptions, and hierarchical information.

    Example:
        >>> func_use = FunctionalUse()
        >>> categories = func_use.functiona_use_categories()
        >>> for cat in categories:
        ...     print(f"{cat.get('category', 'N/A')}: {cat.get('description', '')}")
    """
    endpoint = "exposure/functional-use/category"
    return self._make_cached_request(endpoint, use_cache=use_cache)

functional_use_by_dtxsid_batch(dtxsids, use_cache=None)

Get functional use data for multiple chemicals in a single request.

Retrieves functional use information for multiple chemicals at once using a batch API call. This is more efficient than making individual requests for each chemical.

Parameters:

Name Type Description Default
dtxsids List[str]

List of DSSTox Substance Identifiers

 required

Returns:

Type Description
List[Dict[str, Any]]

List of dictionaries containing functional use data for all requested
List[Dict[str, Any]]

chemicals. Results include the DTXSID and associated functional use
List[Dict[str, Any]]

information for each chemical.

Raises:

Type Description
ValueError

If dtxsids is not a valid non-empty list
Example

func_use = FunctionalUse() dtxsids = ["DTXSID0020232", "DTXSID7020182"] batch_data = func_use.functional_use_by_dtxsid_batch(dtxsids) for result in batch_data: ... print(f"{result.get('dtxsid')}: {result.get('harmonizedFunctionalUse')}")

Source code in src/pycomptox/exposure/functionaluse.py 
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
def functional_use_by_dtxsid_batch(self, dtxsids: List[str], use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
    """
    Get functional use data for multiple chemicals in a single request.

    Retrieves functional use information for multiple chemicals at once using
    a batch API call. This is more efficient than making individual requests
    for each chemical.

    Args:
        dtxsids: List of DSSTox Substance Identifiers

    Returns:
        List of dictionaries containing functional use data for all requested
        chemicals. Results include the DTXSID and associated functional use
        information for each chemical.

    Raises:
        ValueError: If dtxsids is not a valid non-empty list

    Example:
        >>> func_use = FunctionalUse()
        >>> dtxsids = ["DTXSID0020232", "DTXSID7020182"]
        >>> batch_data = func_use.functional_use_by_dtxsid_batch(dtxsids)
        >>> for result in batch_data:
        ...     print(f"{result.get('dtxsid')}: {result.get('harmonizedFunctionalUse')}")
    """
    if not dtxsids or not isinstance(dtxsids, list) or len(dtxsids) == 0:
        raise ValueError("dtxsids must be a non-empty list of strings")

    if not all(isinstance(dtxsid, str) for dtxsid in dtxsids):
        raise ValueError("All elements in dtxsids must be strings")

    endpoint = "exposure/functional-use/search/by-dtxsid/"
    return self._make_request("POST", endpoint, json_data=dtxsids)

functional_use_probability_by_dtxsid(dtxsid, use_cache=None)

Get predicted functional use probabilities for a chemical.

Retrieves predicted functional use probabilities for a specific chemical. These predictions estimate the likelihood that a chemical is used for various functional purposes based on modeling.

Parameters:

Name Type Description Default
dtxsid str

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

 required

Returns:

Type Description
List[Dict[str, Any]]

List of dictionaries containing functional use predictions with
List[Dict[str, Any]]

probability scores for different use categories.

Raises:

Type Description
ValueError

If dtxsid is not a valid non-empty string
Example

func_use = FunctionalUse() probs = func_use.functional_use_probability_by_dtxsid("DTXSID0020232") for pred in probs: ... print(f"{pred.get('functionalUse')}: {pred.get('probability')}")

Source code in src/pycomptox/exposure/functionaluse.py 
 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
def functional_use_probability_by_dtxsid(self, dtxsid: str, use_cache: Optional[bool] = None) -> List[Dict[str, Any]]:
    """
    Get predicted functional use probabilities for a chemical.

    Retrieves predicted functional use probabilities for a specific chemical.
    These predictions estimate the likelihood that a chemical is used for
    various functional purposes based on modeling.

    Args:
        dtxsid: DSSTox Substance Identifier (e.g., 'DTXSID0020232')

    Returns:
        List of dictionaries containing functional use predictions with
        probability scores for different use categories.

    Raises:
        ValueError: If dtxsid is not a valid non-empty string

    Example:
        >>> func_use = FunctionalUse()
        >>> probs = func_use.functional_use_probability_by_dtxsid("DTXSID0020232")
        >>> for pred in probs:
        ...     print(f"{pred.get('functionalUse')}: {pred.get('probability')}")
    """
    if not dtxsid or not isinstance(dtxsid, str):
        raise ValueError("dtxsid must be a non-empty string")

    endpoint = f"exposure/functional-use/probability/search/by-dtxsid/{dtxsid}"
    return self._make_cached_request(endpoint, use_cache=use_cache)