Skip to content

Bioactivity AOP API Reference

pycomptox.bioactivity.bioactivityaop.BioactivityAOP

Bases: CachedAPIClient

Client for accessing AOP (Adverse Outcome Pathway) data from EPA CompTox Dashboard.

This class provides methods for retrieving AOP data by: - ToxCast assay endpoint ID (AEID) - Event number - Entrez gene ID

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
Example

from pycomptox import BioactivityAOP client = BioactivityAOP()

Get AOP data by ToxCast AEID

aop_data = client.get_aop_data_by_toxcast_aeid(63)

Get AOP data by event number

events = client.get_aop_data_by_event_number(18)

Source code in src/pycomptox/bioactivity/bioactivityaop.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
155
156
157
158
159
160
class BioactivityAOP(CachedAPIClient):
    """
    Client for accessing AOP (Adverse Outcome Pathway) data from EPA CompTox Dashboard.

    This class provides methods for retrieving AOP data by:
    - ToxCast assay endpoint ID (AEID)
    - Event number
    - Entrez gene ID

    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).

    Example:
        >>> from pycomptox import BioactivityAOP
        >>> client = BioactivityAOP()
        >>> 
        >>> # Get AOP data by ToxCast AEID
        >>> aop_data = client.get_aop_data_by_toxcast_aeid(63)
        >>> 
        >>> # Get AOP data by event number
        >>> events = client.get_aop_data_by_event_number(18)
    """

    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 BioactivityAOP 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_aop_data_by_toxcast_aeid(self, toxcast_aeid: int, use_cache: Optional[bool] = None) -> Optional[List[Dict[str, Any]]]:
        """
        Get AOP data by ToxCast assay endpoint ID.

        Retrieves Adverse Outcome Pathway data associated with a specific
        ToxCast assay endpoint identifier (AEID).

        Args:
            toxcast_aeid: ToxCast assay endpoint identifier (integer)

        Returns:
            List of AOP records, each containing:
                - id: Record identifier
                - toxcastAeid: ToxCast AEID
                - entrezGeneId: Associated Entrez Gene ID
                - eventNumber: AOP event number
                - eventLink: Link to event details
                - aopNumber: AOP pathway number
                - aopLink: Link to AOP pathway

        Raises:
            ValueError: If toxcast_aeid is not a positive integer

        Example:
            >>> client = BioactivityAOP()
            >>> aop_data = client.get_aop_data_by_toxcast_aeid(63)
            >>> print(f"Found {len(aop_data)} AOP records")
        """
        if not isinstance(toxcast_aeid, int) or toxcast_aeid <= 0:
            raise ValueError("toxcast_aeid must be a positive integer")

        endpoint = f"bioactivity/aop/search/by-toxcast-aeid/{toxcast_aeid}"
        return self._make_cached_request(endpoint, use_cache=use_cache)

    def get_aop_data_by_event_number(self, event_number: int, use_cache: Optional[bool] = None) -> Optional[List[Dict[str, Any]]]:
        """
        Get AOP data by event number.

        Retrieves Adverse Outcome Pathway data for a specific event number,
        including all associated ToxCast assays and gene information.

        Args:
            event_number: AOP event number (integer)

        Returns:
            List of AOP records containing event, assay, and pathway information

        Raises:
            ValueError: If event_number is not a positive integer

        Example:
            >>> client = BioactivityAOP()
            >>> events = client.get_aop_data_by_event_number(18)
            >>> print(f"Event 18 has {len(events)} associated records")
        """
        if not isinstance(event_number, int) or event_number <= 0:
            raise ValueError("event_number must be a positive integer")

        endpoint = f"bioactivity/aop/search/by-event-number/{event_number}"
        return self._make_cached_request(endpoint, use_cache=use_cache)

    def get_aop_data_by_entrez_gene_id(self, entrez_gene_id: int, use_cache: Optional[bool] = None) -> Optional[List[Dict[str, Any]]]:
        """
        Get AOP data by Entrez Gene ID.

        Retrieves Adverse Outcome Pathway data for a specific Entrez Gene ID,
        showing all AOP events and pathways associated with the gene.

        Args:
            entrez_gene_id: NCBI Entrez Gene identifier (integer)

        Returns:
            List of AOP records linking the gene to events and pathways

        Raises:
            ValueError: If entrez_gene_id is not a positive integer

        Example:
            >>> client = BioactivityAOP()
            >>> gene_aops = client.get_aop_data_by_entrez_gene_id(196)
            >>> print(f"Gene 196 is involved in {len(gene_aops)} AOP records")
        """
        if not isinstance(entrez_gene_id, int) or entrez_gene_id <= 0:
            raise ValueError("entrez_gene_id must be a positive integer")

        endpoint = f"bioactivity/aop/search/by-entrez-gene-id/{entrez_gene_id}"
        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 BioactivityAOP 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

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/bioactivity/bioactivityaop.py 
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
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 BioactivityAOP 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_aop_data_by_entrez_gene_id(entrez_gene_id, use_cache=None)

Get AOP data by Entrez Gene ID.

Retrieves Adverse Outcome Pathway data for a specific Entrez Gene ID, showing all AOP events and pathways associated with the gene.

Parameters:

Name Type Description Default
entrez_gene_id int

NCBI Entrez Gene identifier (integer)

 required

Returns:

Type Description
Optional[List[Dict[str, Any]]]

List of AOP records linking the gene to events and pathways

Raises:

Type Description
ValueError

If entrez_gene_id is not a positive integer
Example

client = BioactivityAOP() gene_aops = client.get_aop_data_by_entrez_gene_id(196) print(f"Gene 196 is involved in {len(gene_aops)} AOP records")

Source code in src/pycomptox/bioactivity/bioactivityaop.py 
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_aop_data_by_entrez_gene_id(self, entrez_gene_id: int, use_cache: Optional[bool] = None) -> Optional[List[Dict[str, Any]]]:
    """
    Get AOP data by Entrez Gene ID.

    Retrieves Adverse Outcome Pathway data for a specific Entrez Gene ID,
    showing all AOP events and pathways associated with the gene.

    Args:
        entrez_gene_id: NCBI Entrez Gene identifier (integer)

    Returns:
        List of AOP records linking the gene to events and pathways

    Raises:
        ValueError: If entrez_gene_id is not a positive integer

    Example:
        >>> client = BioactivityAOP()
        >>> gene_aops = client.get_aop_data_by_entrez_gene_id(196)
        >>> print(f"Gene 196 is involved in {len(gene_aops)} AOP records")
    """
    if not isinstance(entrez_gene_id, int) or entrez_gene_id <= 0:
        raise ValueError("entrez_gene_id must be a positive integer")

    endpoint = f"bioactivity/aop/search/by-entrez-gene-id/{entrez_gene_id}"
    return self._make_cached_request(endpoint, use_cache=use_cache)

get_aop_data_by_event_number(event_number, use_cache=None)

Get AOP data by event number.

Retrieves Adverse Outcome Pathway data for a specific event number, including all associated ToxCast assays and gene information.

Parameters:

Name Type Description Default
event_number int

AOP event number (integer)

 required

Returns:

Type Description
Optional[List[Dict[str, Any]]]

List of AOP records containing event, assay, and pathway information

Raises:

Type Description
ValueError

If event_number is not a positive integer
Example

client = BioactivityAOP() events = client.get_aop_data_by_event_number(18) print(f"Event 18 has {len(events)} associated records")

Source code in src/pycomptox/bioactivity/bioactivityaop.py 
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
def get_aop_data_by_event_number(self, event_number: int, use_cache: Optional[bool] = None) -> Optional[List[Dict[str, Any]]]:
    """
    Get AOP data by event number.

    Retrieves Adverse Outcome Pathway data for a specific event number,
    including all associated ToxCast assays and gene information.

    Args:
        event_number: AOP event number (integer)

    Returns:
        List of AOP records containing event, assay, and pathway information

    Raises:
        ValueError: If event_number is not a positive integer

    Example:
        >>> client = BioactivityAOP()
        >>> events = client.get_aop_data_by_event_number(18)
        >>> print(f"Event 18 has {len(events)} associated records")
    """
    if not isinstance(event_number, int) or event_number <= 0:
        raise ValueError("event_number must be a positive integer")

    endpoint = f"bioactivity/aop/search/by-event-number/{event_number}"
    return self._make_cached_request(endpoint, use_cache=use_cache)

get_aop_data_by_toxcast_aeid(toxcast_aeid, use_cache=None)

Get AOP data by ToxCast assay endpoint ID.

Retrieves Adverse Outcome Pathway data associated with a specific ToxCast assay endpoint identifier (AEID).

Parameters:

Name Type Description Default
toxcast_aeid int

ToxCast assay endpoint identifier (integer)

 required

Returns:

Type Description
Optional[List[Dict[str, Any]]]

List of AOP records, each containing: - id: Record identifier - toxcastAeid: ToxCast AEID - entrezGeneId: Associated Entrez Gene ID - eventNumber: AOP event number - eventLink: Link to event details - aopNumber: AOP pathway number - aopLink: Link to AOP pathway

Raises:

Type Description
ValueError

If toxcast_aeid is not a positive integer
Example

client = BioactivityAOP() aop_data = client.get_aop_data_by_toxcast_aeid(63) print(f"Found {len(aop_data)} AOP records")

Source code in src/pycomptox/bioactivity/bioactivityaop.py 
 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
def get_aop_data_by_toxcast_aeid(self, toxcast_aeid: int, use_cache: Optional[bool] = None) -> Optional[List[Dict[str, Any]]]:
    """
    Get AOP data by ToxCast assay endpoint ID.

    Retrieves Adverse Outcome Pathway data associated with a specific
    ToxCast assay endpoint identifier (AEID).

    Args:
        toxcast_aeid: ToxCast assay endpoint identifier (integer)

    Returns:
        List of AOP records, each containing:
            - id: Record identifier
            - toxcastAeid: ToxCast AEID
            - entrezGeneId: Associated Entrez Gene ID
            - eventNumber: AOP event number
            - eventLink: Link to event details
            - aopNumber: AOP pathway number
            - aopLink: Link to AOP pathway

    Raises:
        ValueError: If toxcast_aeid is not a positive integer

    Example:
        >>> client = BioactivityAOP()
        >>> aop_data = client.get_aop_data_by_toxcast_aeid(63)
        >>> print(f"Found {len(aop_data)} AOP records")
    """
    if not isinstance(toxcast_aeid, int) or toxcast_aeid <= 0:
        raise ValueError("toxcast_aeid must be a positive integer")

    endpoint = f"bioactivity/aop/search/by-toxcast-aeid/{toxcast_aeid}"
    return self._make_cached_request(endpoint, use_cache=use_cache)