functions

openml.study.functions

__list_studies

__list_studies(api_call: str) -> DataFrame

Retrieves the list of OpenML studies and returns it in a dictionary or a Pandas DataFrame.

PARAMETER	DESCRIPTION
api_call	The API call for retrieving the list of OpenML studies. TYPE: str

RETURNS	DESCRIPTION
DataFrame	A Pandas DataFrame of OpenML studies

Source code in openml/study/functions.py

def __list_studies(api_call: str) -> pd.DataFrame:
    """Retrieves the list of OpenML studies and
    returns it in a dictionary or a Pandas DataFrame.

    Parameters
    ----------
    api_call : str
        The API call for retrieving the list of OpenML studies.

    Returns
    -------
    pd.DataFrame
        A Pandas DataFrame of OpenML studies
    """
    xml_string = openml._api_calls._perform_api_call(api_call, "get")
    study_dict = xmltodict.parse(xml_string, force_list=("oml:study",))

    # Minimalistic check if the XML is useful
    assert isinstance(study_dict["oml:study_list"]["oml:study"], list), type(
        study_dict["oml:study_list"],
    )
    assert study_dict["oml:study_list"]["@xmlns:oml"] == "http://openml.org/openml", study_dict[
        "oml:study_list"
    ]["@xmlns:oml"]

    studies = {}
    for study_ in study_dict["oml:study_list"]["oml:study"]:
        # maps from xml name to a tuple of (dict name, casting fn)
        expected_fields = {
            "oml:id": ("id", int),
            "oml:alias": ("alias", str),
            "oml:main_entity_type": ("main_entity_type", str),
            "oml:benchmark_suite": ("benchmark_suite", int),
            "oml:name": ("name", str),
            "oml:status": ("status", str),
            "oml:creation_date": ("creation_date", str),
            "oml:creator": ("creator", int),
        }
        study_id = int(study_["oml:id"])
        current_study = {}
        for oml_field_name, (real_field_name, cast_fn) in expected_fields.items():
            if oml_field_name in study_:
                current_study[real_field_name] = cast_fn(study_[oml_field_name])
        current_study["id"] = int(current_study["id"])
        studies[study_id] = current_study

    return pd.DataFrame.from_dict(studies, orient="index")

attach_to_study

attach_to_study(study_id: int, run_ids: list[int]) -> int

Attaches a set of runs to a study.

PARAMETER	DESCRIPTION
study_id	OpenML id of the study TYPE: int
run_ids	List of entities to link to the collection TYPE: list(int)

RETURNS	DESCRIPTION
int	new size of the study (in terms of explicitly linked entities)

Source code in openml/study/functions.py

def attach_to_study(study_id: int, run_ids: list[int]) -> int:
    """Attaches a set of runs to a study.

    Parameters
    ----------
    study_id : int
        OpenML id of the study

    run_ids : list (int)
        List of entities to link to the collection

    Returns
    -------
    int
        new size of the study (in terms of explicitly linked entities)
    """
    # Interestingly, there's no need to tell the server about the entity type, it knows by itself
    result_xml = openml._api_calls._perform_api_call(
        call=f"study/{study_id}/attach",
        request_method="post",
        data={"ids": ",".join(str(x) for x in run_ids)},
    )
    result = xmltodict.parse(result_xml)["oml:study_attach"]
    return int(result["oml:linked_entities"])

attach_to_suite

attach_to_suite(suite_id: int, task_ids: list[int]) -> int

Attaches a set of tasks to a benchmarking suite.

PARAMETER	DESCRIPTION
suite_id	OpenML id of the study TYPE: int
task_ids	List of entities to link to the collection TYPE: list(int)

RETURNS	DESCRIPTION
int	new size of the suite (in terms of explicitly linked entities)

Source code in openml/study/functions.py

def attach_to_suite(suite_id: int, task_ids: list[int]) -> int:
    """Attaches a set of tasks to a benchmarking suite.

    Parameters
    ----------
    suite_id : int
        OpenML id of the study

    task_ids : list (int)
        List of entities to link to the collection

    Returns
    -------
    int
        new size of the suite (in terms of explicitly linked entities)
    """
    return attach_to_study(suite_id, task_ids)

create_benchmark_suite

create_benchmark_suite(name: str, description: str, task_ids: list[int], alias: str | None = None) -> OpenMLBenchmarkSuite

Creates an OpenML benchmark suite (collection of entity types, where the tasks are the linked entity)

PARAMETER	DESCRIPTION
name	the name of the study (meta-info) TYPE: str
description	brief description (meta-info) TYPE: str
task_ids	a list of task ids associated with this study more can be added later with attach_to_suite. TYPE: list
alias	a string ID, unique on server (url-friendly) TYPE: str(optional) DEFAULT: None

RETURNS	DESCRIPTION
OpenMLStudy	A local OpenML study object (call publish method to upload to server)

Source code in openml/study/functions.py

def create_benchmark_suite(
    name: str,
    description: str,
    task_ids: list[int],
    alias: str | None = None,
) -> OpenMLBenchmarkSuite:
    """
    Creates an OpenML benchmark suite (collection of entity types, where
    the tasks are the linked entity)

    Parameters
    ----------
    name : str
        the name of the study (meta-info)
    description : str
        brief description (meta-info)
    task_ids : list
        a list of task ids associated with this study
        more can be added later with ``attach_to_suite``.
    alias : str (optional)
        a string ID, unique on server (url-friendly)

    Returns
    -------
    OpenMLStudy
        A local OpenML study object (call publish method to upload to server)
    """
    return OpenMLBenchmarkSuite(
        suite_id=None,
        alias=alias,
        name=name,
        description=description,
        status=None,
        creation_date=None,
        creator=None,
        tags=None,
        data=None,
        tasks=task_ids,
    )

create_study

create_study(name: str, description: str, run_ids: list[int] | None = None, alias: str | None = None, benchmark_suite: int | None = None) -> OpenMLStudy

Creates an OpenML study (collection of data, tasks, flows, setups and run), where the runs are the main entity (collection consists of runs and all entities (flows, tasks, etc) that are related to these runs)

PARAMETER	DESCRIPTION
benchmark_suite	the benchmark suite (another study) upon which this study is ran. TYPE: int(optional) DEFAULT: None
name	the name of the study (meta-info) TYPE: str
description	brief description (meta-info) TYPE: str
run_ids	a list of run ids associated with this study, these can also be added later with attach_to_study. TYPE: list DEFAULT: None
alias	a string ID, unique on server (url-friendly) TYPE: str(optional) DEFAULT: None
benchmark_suite	the ID of the suite for which this study contains run results TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
OpenMLStudy	A local OpenML study object (call publish method to upload to server)

Source code in openml/study/functions.py

def create_study(
    name: str,
    description: str,
    run_ids: list[int] | None = None,
    alias: str | None = None,
    benchmark_suite: int | None = None,
) -> OpenMLStudy:
    """
    Creates an OpenML study (collection of data, tasks, flows, setups and run),
    where the runs are the main entity (collection consists of runs and all
    entities (flows, tasks, etc) that are related to these runs)

    Parameters
    ----------
    benchmark_suite : int (optional)
        the benchmark suite (another study) upon which this study is ran.
    name : str
        the name of the study (meta-info)
    description : str
        brief description (meta-info)
    run_ids : list, optional
        a list of run ids associated with this study,
        these can also be added later with ``attach_to_study``.
    alias : str (optional)
        a string ID, unique on server (url-friendly)
    benchmark_suite: int (optional)
        the ID of the suite for which this study contains run results

    Returns
    -------
    OpenMLStudy
        A local OpenML study object (call publish method to upload to server)
    """
    return OpenMLStudy(
        study_id=None,
        alias=alias,
        benchmark_suite=benchmark_suite,
        name=name,
        description=description,
        status=None,
        creation_date=None,
        creator=None,
        tags=None,
        data=None,
        tasks=None,
        flows=None,
        runs=run_ids if run_ids != [] else None,
        setups=None,
    )

delete_study

delete_study(study_id: int) -> bool

Deletes a study from the OpenML server.

PARAMETER	DESCRIPTION
study_id	OpenML id of the study TYPE: int

RETURNS	DESCRIPTION
bool	True iff the deletion was successful. False otherwise

Source code in openml/study/functions.py

def delete_study(study_id: int) -> bool:
    """Deletes a study from the OpenML server.

    Parameters
    ----------
    study_id : int
        OpenML id of the study

    Returns
    -------
    bool
        True iff the deletion was successful. False otherwise
    """
    return openml.utils._delete_entity("study", study_id)

delete_suite

delete_suite(suite_id: int) -> bool

Deletes a study from the OpenML server.

PARAMETER	DESCRIPTION
suite_id	OpenML id of the study TYPE: int

RETURNS	DESCRIPTION
bool	True iff the deletion was successful. False otherwise

Source code in openml/study/functions.py

def delete_suite(suite_id: int) -> bool:
    """Deletes a study from the OpenML server.

    Parameters
    ----------
    suite_id : int
        OpenML id of the study

    Returns
    -------
    bool
        True iff the deletion was successful. False otherwise
    """
    return delete_study(suite_id)

detach_from_study

detach_from_study(study_id: int, run_ids: list[int]) -> int

Detaches a set of run ids from a study.

PARAMETER	DESCRIPTION
study_id	OpenML id of the study TYPE: int
run_ids	List of entities to unlink from the collection TYPE: list(int)

RETURNS	DESCRIPTION
int	new size of the study (in terms of explicitly linked entities)

Source code in openml/study/functions.py

def detach_from_study(study_id: int, run_ids: list[int]) -> int:
    """Detaches a set of run ids from a study.

    Parameters
    ----------
    study_id : int
        OpenML id of the study

    run_ids : list (int)
        List of entities to unlink from the collection

    Returns
    -------
    int
        new size of the study (in terms of explicitly linked entities)
    """
    # Interestingly, there's no need to tell the server about the entity type, it knows by itself
    uri = f"study/{study_id}/detach"
    post_variables = {"ids": ",".join(str(x) for x in run_ids)}  # type: openml._api_calls.DATA_TYPE
    result_xml = openml._api_calls._perform_api_call(
        call=uri,
        request_method="post",
        data=post_variables,
    )
    result = xmltodict.parse(result_xml)["oml:study_detach"]
    return int(result["oml:linked_entities"])

detach_from_suite

detach_from_suite(suite_id: int, task_ids: list[int]) -> int

Detaches a set of task ids from a suite.

PARAMETER	DESCRIPTION
suite_id	OpenML id of the study TYPE: int
task_ids	List of entities to unlink from the collection TYPE: list(int)

RETURNS	DESCRIPTION
int
new size of the study (in terms of explicitly linked entities)

Source code in openml/study/functions.py

def detach_from_suite(suite_id: int, task_ids: list[int]) -> int:
    """Detaches a set of task ids from a suite.

    Parameters
    ----------
    suite_id : int
        OpenML id of the study

    task_ids : list (int)
        List of entities to unlink from the collection

    Returns
    -------
    int
    new size of the study (in terms of explicitly linked entities)
    """
    return detach_from_study(suite_id, task_ids)

get_study

get_study(study_id: int | str, arg_for_backwards_compat: str | None = None) -> OpenMLStudy

Retrieves all relevant information of an OpenML study from the server.

PARAMETER	DESCRIPTION
study	study id (numeric or alias)
arg_for_backwards_compat	The example given in arxiv.org/pdf/1708.03731.pdf uses an older version of the API which required specifying the type of study, i.e. tasks. We changed the implementation of studies since then and split them up into suites (collections of tasks) and studies (collections of runs) so this argument is no longer needed. TYPE: str DEFAULT: None

RETURNS	DESCRIPTION
OpenMLStudy	The OpenML study object

Source code in openml/study/functions.py

def get_study(
    study_id: int | str,
    arg_for_backwards_compat: str | None = None,  # noqa: ARG001
) -> OpenMLStudy:  # F401
    """
    Retrieves all relevant information of an OpenML study from the server.

    Parameters
    ----------
    study id : int, str
        study id (numeric or alias)

    arg_for_backwards_compat : str, optional
        The example given in https://arxiv.org/pdf/1708.03731.pdf uses an older version of the
        API which required specifying the type of study, i.e. tasks. We changed the
        implementation of studies since then and split them up into suites (collections of tasks)
        and studies (collections of runs) so this argument is no longer needed.

    Returns
    -------
    OpenMLStudy
        The OpenML study object
    """
    if study_id == "OpenML100":
        message = (
            "It looks like you are running code from the OpenML100 paper. It still works, but lots "
            "of things have changed since then. Please use `get_suite('OpenML100')` instead."
        )
        warnings.warn(message, DeprecationWarning, stacklevel=2)
        openml.config.logger.warning(message)
        study = _get_study(study_id, entity_type="task")
        assert isinstance(study, OpenMLBenchmarkSuite)

        return study  # type: ignore

    study = _get_study(study_id, entity_type="run")
    assert isinstance(study, OpenMLStudy)
    return study

get_suite

get_suite(suite_id: int | str) -> OpenMLBenchmarkSuite

Retrieves all relevant information of an OpenML benchmarking suite from the server.

PARAMETER	DESCRIPTION
study	study id (numeric or alias)

RETURNS	DESCRIPTION
OpenMLSuite	The OpenML suite object

Source code in openml/study/functions.py

def get_suite(suite_id: int | str) -> OpenMLBenchmarkSuite:
    """
    Retrieves all relevant information of an OpenML benchmarking suite from the server.

    Parameters
    ----------
    study id : int, str
        study id (numeric or alias)

    Returns
    -------
    OpenMLSuite
        The OpenML suite object
    """
    study = _get_study(suite_id, entity_type="task")
    assert isinstance(study, OpenMLBenchmarkSuite)

    return study

list_studies

list_studies(offset: int | None = None, size: int | None = None, status: str | None = None, uploader: list[str] | None = None, benchmark_suite: int | None = None) -> DataFrame

Return a list of all studies which are on OpenML.

PARAMETER	DESCRIPTION
offset	The number of studies to skip, starting from the first. TYPE: int DEFAULT: None
size	The maximum number of studies to show. TYPE: int DEFAULT: None
status	Should be {active, in_preparation, deactivated, all}. By default active studies are returned. TYPE: str DEFAULT: None
uploader	Result filter. Will only return studies created by these users. TYPE: list(int) DEFAULT: None
benchmark_suite	TYPE: int DEFAULT: None

RETURNS	DESCRIPTION
datasets	Every dataset is represented by a dictionary containing the following information: - id - alias (optional) - name - benchmark_suite (optional) - status - creator - creation_date If qualities are calculated for the dataset, some of these are also returned. TYPE: dataframe

Source code in openml/study/functions.py

def list_studies(
    offset: int | None = None,
    size: int | None = None,
    status: str | None = None,
    uploader: list[str] | None = None,
    benchmark_suite: int | None = None,
) -> pd.DataFrame:
    """
    Return a list of all studies which are on OpenML.

    Parameters
    ----------
    offset : int, optional
        The number of studies to skip, starting from the first.
    size : int, optional
        The maximum number of studies to show.
    status : str, optional
        Should be {active, in_preparation, deactivated, all}. By default active
        studies are returned.
    uploader : list (int), optional
        Result filter. Will only return studies created by these users.
    benchmark_suite : int, optional

    Returns
    -------
    datasets : dataframe
        Every dataset is represented by a dictionary containing
        the following information:
        - id
        - alias (optional)
        - name
        - benchmark_suite (optional)
        - status
        - creator
        - creation_date
        If qualities are calculated for the dataset, some of
        these are also returned.
    """
    listing_call = partial(
        _list_studies,
        main_entity_type="run",
        status=status,
        uploader=uploader,
        benchmark_suite=benchmark_suite,
    )
    batches = openml.utils._list_all(listing_call, offset=offset, limit=size)
    if len(batches) == 0:
        return pd.DataFrame()

    return pd.concat(batches)

list_suites

list_suites(offset: int | None = None, size: int | None = None, status: str | None = None, uploader: list[int] | None = None) -> DataFrame

Return a list of all suites which are on OpenML.

PARAMETER	DESCRIPTION
offset	The number of suites to skip, starting from the first. TYPE: int DEFAULT: None
size	The maximum number of suites to show. TYPE: int DEFAULT: None
status	Should be {active, in_preparation, deactivated, all}. By default active suites are returned. TYPE: str DEFAULT: None
uploader	Result filter. Will only return suites created by these users. TYPE: list(int) DEFAULT: None

RETURNS	DESCRIPTION
datasets	Every row is represented by a dictionary containing the following information: - id - alias (optional) - name - main_entity_type - status - creator - creation_date TYPE: dataframe

Source code in openml/study/functions.py

def list_suites(
    offset: int | None = None,
    size: int | None = None,
    status: str | None = None,
    uploader: list[int] | None = None,
) -> pd.DataFrame:
    """
    Return a list of all suites which are on OpenML.

    Parameters
    ----------
    offset : int, optional
        The number of suites to skip, starting from the first.
    size : int, optional
        The maximum number of suites to show.
    status : str, optional
        Should be {active, in_preparation, deactivated, all}. By default active
        suites are returned.
    uploader : list (int), optional
        Result filter. Will only return suites created by these users.

    Returns
    -------
    datasets : dataframe
        Every row is represented by a dictionary containing the following information:
        - id
        - alias (optional)
        - name
        - main_entity_type
        - status
        - creator
        - creation_date
    """
    listing_call = partial(
        _list_studies,
        main_entity_type="task",
        status=status,
        uploader=uploader,
    )
    batches = openml.utils._list_all(listing_call, limit=size, offset=offset)
    if len(batches) == 0:
        return pd.DataFrame()

    return pd.concat(batches)

update_study_status

update_study_status(study_id: int, status: str) -> None

Updates the status of a study to either 'active' or 'deactivated'.

PARAMETER	DESCRIPTION
study_id	The data id of the dataset TYPE: int
status	'active' or 'deactivated' TYPE: (str,)

Source code in openml/study/functions.py

def update_study_status(study_id: int, status: str) -> None:
    """
    Updates the status of a study to either 'active' or 'deactivated'.

    Parameters
    ----------
    study_id : int
        The data id of the dataset
    status : str,
        'active' or 'deactivated'
    """
    legal_status = {"active", "deactivated"}
    if status not in legal_status:
        raise ValueError(f"Illegal status value. Legal values: {legal_status}")
    data = {"study_id": study_id, "status": status}  # type: openml._api_calls.DATA_TYPE
    result_xml = openml._api_calls._perform_api_call("study/status/update", "post", data=data)
    result = xmltodict.parse(result_xml)
    server_study_id = result["oml:study_status_update"]["oml:id"]
    server_status = result["oml:study_status_update"]["oml:status"]
    if status != server_status or int(study_id) != int(server_study_id):
        # This should never happen
        raise ValueError("Study id/status does not collide")

update_suite_status

update_suite_status(suite_id: int, status: str) -> None

Updates the status of a study to either 'active' or 'deactivated'.

PARAMETER	DESCRIPTION
suite_id	The data id of the dataset TYPE: int
status	'active' or 'deactivated' TYPE: (str,)

Source code in openml/study/functions.py

def update_suite_status(suite_id: int, status: str) -> None:
    """
    Updates the status of a study to either 'active' or 'deactivated'.

    Parameters
    ----------
    suite_id : int
        The data id of the dataset
    status : str,
        'active' or 'deactivated'
    """
    return update_study_status(suite_id, status)