Skip to content

ListPresence API Reference

pycomptox.exposure.listpresence.ListPresence

Bases: CachedAPIClient

Client for accessing list presence data from EPA CompTox Dashboard.

This class provides methods for retrieving information about chemical presence on various regulatory, screening, and informational lists. This includes EPA lists, state lists, international lists, and other chemical inventories.

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 ListPresence list_pres = ListPresence()

Get list presence data for a chemical

data = list_pres.list_presence_data_by_dtxsid("DTXSID0020232")

Source code in src/pycomptox/exposure/listpresence.py 
 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
class ListPresence(CachedAPIClient):
    """
    Client for accessing list presence data from EPA CompTox Dashboard.

    This class provides methods for retrieving information about chemical presence
    on various regulatory, screening, and informational lists. This includes EPA lists,
    state lists, international lists, and other chemical inventories.

    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 ListPresence
        >>> list_pres = ListPresence()
        >>> 
        >>> # Get list presence data for a chemical
        >>> data = list_pres.list_presence_data_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 ListPresence 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 list_presence_tags(self, use_cache: Optional[bool] = None) -> List[Dict[str, str]]:
        """
        Get all available list presence tags.

        Retrieves a complete list of available list presence tags, which categorize
        the different types of chemical lists tracked in the CompTox Dashboard.
        These tags help identify regulatory lists, screening lists, and other
        chemical inventories.

        Returns:
            List of dictionaries containing list presence tags with their names,
            descriptions, and category information.

        Example:
            >>> list_pres = ListPresence()
            >>> tags = list_pres.list_presence_tags()
            >>> for tag in tags:
            ...     print(f"{tag.get('tag', 'N/A')}: {tag.get('description', '')}")
        """
        endpoint = "exposure/list-presence/tags"
        return self._make_cached_request(endpoint, use_cache=use_cache)

    def list_presence_data_by_dtxsid(self, dtxsid: str, use_cache: Optional[bool] = None) -> List[Dict[str, str]]:
        """
        Get list presence data for a chemical.

        Retrieves information about which regulatory, screening, and informational
        lists contain a specific chemical identified by its DSSTox Substance
        Identifier (DTXSID). This includes EPA lists, state lists, international
        lists, and other chemical inventories.

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

        Returns:
            List of dictionaries containing list presence information. Each entry
            includes the list name, source, category, and presence status.

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

        Example:
            >>> list_pres = ListPresence()
            >>> data = list_pres.list_presence_data_by_dtxsid("DTXSID0020232")
            >>> for item in data:
            ...     print(f"{item.get('listName', 'N/A')}: {item.get('presenceStatus', 'N/A')}")
        """
        if not dtxsid or not isinstance(dtxsid, str):
            raise ValueError("dtxsid must be a non-empty string")

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

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

        Retrieves list presence information for multiple chemicals at once using a
        batch API call. This is more efficient than making individual requests for
        each chemical when working with multiple DTXSIDs.

        Args:
            dtxsids: List of DSSTox Substance Identifiers

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

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

        Example:
            >>> list_pres = ListPresence()
            >>> dtxsids = ["DTXSID0020232", "DTXSID0020245"]
            >>> batch_data = list_pres.list_presence_data_by_dtxsid_batch(dtxsids)
            >>> for result in batch_data:
            ...     print(f"{result.get('dtxsid')}: {result.get('listName')}")
        """
        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/list-presence/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 ListPresence 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/listpresence.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 ListPresence 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
    )

list_presence_data_by_dtxsid(dtxsid, use_cache=None)

Get list presence data for a chemical.

Retrieves information about which regulatory, screening, and informational lists contain a specific chemical identified by its DSSTox Substance Identifier (DTXSID). This includes EPA lists, state lists, international lists, and other chemical inventories.

Parameters:

Name Type Description Default
dtxsid str

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

 required

Returns:

Type Description
List[Dict[str, str]]

List of dictionaries containing list presence information. Each entry
List[Dict[str, str]]

includes the list name, source, category, and presence status.

Raises:

Type Description
ValueError

If dtxsid is not a valid non-empty string
Example

list_pres = ListPresence() data = list_pres.list_presence_data_by_dtxsid("DTXSID0020232") for item in data: ... print(f"{item.get('listName', 'N/A')}: {item.get('presenceStatus', 'N/A')}")

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

    Retrieves information about which regulatory, screening, and informational
    lists contain a specific chemical identified by its DSSTox Substance
    Identifier (DTXSID). This includes EPA lists, state lists, international
    lists, and other chemical inventories.

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

    Returns:
        List of dictionaries containing list presence information. Each entry
        includes the list name, source, category, and presence status.

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

    Example:
        >>> list_pres = ListPresence()
        >>> data = list_pres.list_presence_data_by_dtxsid("DTXSID0020232")
        >>> for item in data:
        ...     print(f"{item.get('listName', 'N/A')}: {item.get('presenceStatus', 'N/A')}")
    """
    if not dtxsid or not isinstance(dtxsid, str):
        raise ValueError("dtxsid must be a non-empty string")

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

list_presence_data_by_dtxsid_batch(dtxsids, use_cache=None)

Get list presence data for multiple chemicals in a single request.

Retrieves list presence information for multiple chemicals at once using a batch API call. This is more efficient than making individual requests for each chemical when working with multiple DTXSIDs.

Parameters:

Name Type Description Default
dtxsids List[str]

List of DSSTox Substance Identifiers

 required

Returns:

Type Description
List[Dict[str, str]]

List of dictionaries containing list presence data for all requested
List[Dict[str, str]]

chemicals. Results include the DTXSID and associated list presence
List[Dict[str, str]]

information for each chemical.

Raises:

Type Description
ValueError

If dtxsids is not a valid non-empty list
Example

list_pres = ListPresence() dtxsids = ["DTXSID0020232", "DTXSID0020245"] batch_data = list_pres.list_presence_data_by_dtxsid_batch(dtxsids) for result in batch_data: ... print(f"{result.get('dtxsid')}: {result.get('listName')}")

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

    Retrieves list presence information for multiple chemicals at once using a
    batch API call. This is more efficient than making individual requests for
    each chemical when working with multiple DTXSIDs.

    Args:
        dtxsids: List of DSSTox Substance Identifiers

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

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

    Example:
        >>> list_pres = ListPresence()
        >>> dtxsids = ["DTXSID0020232", "DTXSID0020245"]
        >>> batch_data = list_pres.list_presence_data_by_dtxsid_batch(dtxsids)
        >>> for result in batch_data:
        ...     print(f"{result.get('dtxsid')}: {result.get('listName')}")
    """
    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/list-presence/search/by-dtxsid/"
    return self._make_request("POST", endpoint, json_data=dtxsids)

list_presence_tags(use_cache=None)

Get all available list presence tags.

Retrieves a complete list of available list presence tags, which categorize the different types of chemical lists tracked in the CompTox Dashboard. These tags help identify regulatory lists, screening lists, and other chemical inventories.

Returns:

Type Description
List[Dict[str, str]]

List of dictionaries containing list presence tags with their names,
List[Dict[str, str]]

descriptions, and category information.
Example

list_pres = ListPresence() tags = list_pres.list_presence_tags() for tag in tags: ... print(f"{tag.get('tag', 'N/A')}: {tag.get('description', '')}")

Source code in src/pycomptox/exposure/listpresence.py 
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
def list_presence_tags(self, use_cache: Optional[bool] = None) -> List[Dict[str, str]]:
    """
    Get all available list presence tags.

    Retrieves a complete list of available list presence tags, which categorize
    the different types of chemical lists tracked in the CompTox Dashboard.
    These tags help identify regulatory lists, screening lists, and other
    chemical inventories.

    Returns:
        List of dictionaries containing list presence tags with their names,
        descriptions, and category information.

    Example:
        >>> list_pres = ListPresence()
        >>> tags = list_pres.list_presence_tags()
        >>> for tag in tags:
        ...     print(f"{tag.get('tag', 'N/A')}: {tag.get('description', '')}")
    """
    endpoint = "exposure/list-presence/tags"
    return self._make_cached_request(endpoint, use_cache=use_cache)