dataset

openml._api.resources.dataset

DatasetV1API

DatasetV1API(http: HTTPClient, minio: MinIOClient)

Bases: ResourceV1API, DatasetAPI

Version 1 API implementation for dataset resources.

Source code in openml/_api/resources/base/base.py

def __init__(self, http: HTTPClient, minio: MinIOClient):
    self._http = http
    self._minio = minio

add_topic

add_topic(dataset_id: int, topic: str) -> int

Adds a topic to a dataset. This API is not available for all OpenML users and is accessible only by admins.

PARAMETER	DESCRIPTION
dataset_id	id of the dataset to be forked TYPE: int
topic	Topic to be added TYPE: str

RETURNS	DESCRIPTION
Dataset id

Source code in openml/_api/resources/dataset.py

def add_topic(self, dataset_id: int, topic: str) -> int:
    """
    Adds a topic to a dataset.
    This API is not available for all OpenML users and is accessible only by admins.

    Parameters
    ----------
    dataset_id : int
        id of the dataset to be forked
    topic : str
        Topic to be added

    Returns
    -------
    Dataset id
    """
    form_data = {"data_id": dataset_id, "topic": topic}  # type: dict[str, str | int]
    result_xml = self._http.post("data/topicadd", data=form_data).text
    result = xmltodict.parse(result_xml)
    dataset_id = result["oml:data_topic"]["oml:id"]
    return int(dataset_id)

delete

delete(resource_id: int) -> bool

Delete a resource using the V1 API.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to delete. TYPE: int

RETURNS	DESCRIPTION
bool	True if the server confirms successful deletion.

RAISES	DESCRIPTION
ValueError	If the resource type is not supported for deletion.
OpenMLNotAuthorizedError	If the user is not permitted to delete the resource.
OpenMLServerError	If deletion fails for an unknown reason.
OpenMLServerException	For other server-side errors.

Source code in openml/_api/resources/base/versions.py

def delete(self, resource_id: int) -> bool:
    """
    Delete a resource using the V1 API.

    Parameters
    ----------
    resource_id : int
        Identifier of the resource to delete.

    Returns
    -------
    bool
        ``True`` if the server confirms successful deletion.

    Raises
    ------
    ValueError
        If the resource type is not supported for deletion.
    OpenMLNotAuthorizedError
        If the user is not permitted to delete the resource.
    OpenMLServerError
        If deletion fails for an unknown reason.
    OpenMLServerException
        For other server-side errors.
    """
    if self.resource_type not in _LEGAL_RESOURCES_DELETE:
        raise ValueError(f"Can't delete a {self.resource_type.value}")

    endpoint_name = self._get_endpoint_name()
    path = f"{endpoint_name}/{resource_id}"
    try:
        response = self._http.delete(path)
        try:
            parsed_response = xmltodict.parse(response.content)
        except xml.parsers.expat.ExpatError as e:
            msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
            raise OpenMLServerError(msg) from e
        return f"oml:{endpoint_name}_delete" in parsed_response
    except OpenMLServerException as e:
        self._handle_delete_exception(endpoint_name, e)
        raise

delete_topic

delete_topic(dataset_id: int, topic: str) -> int

Removes a topic from a dataset. This API is not available for all OpenML users and is accessible only by admins.

PARAMETER	DESCRIPTION
dataset_id	id of the dataset to be forked TYPE: int
topic	Topic to be deleted TYPE: str

RETURNS	DESCRIPTION
Dataset id

Source code in openml/_api/resources/dataset.py

def delete_topic(self, dataset_id: int, topic: str) -> int:
    """
    Removes a topic from a dataset.
    This API is not available for all OpenML users and is accessible only by admins.

    Parameters
    ----------
    dataset_id : int
        id of the dataset to be forked
    topic : str
        Topic to be deleted

    Returns
    -------
    Dataset id
    """
    form_data = {"data_id": dataset_id, "topic": topic}  # type: dict[str, str | int]
    result_xml = self._http.post("data/topicdelete", data=form_data).text
    result = xmltodict.parse(result_xml)
    dataset_id = result["oml:data_topic"]["oml:id"]
    return int(dataset_id)

download_dataset_arff

download_dataset_arff(description: dict | OpenMLDataset) -> Path

Download dataset arff file.

PARAMETER	DESCRIPTION
description	Either a dataset description as dict or OpenMLDataset. TYPE: dictionary or OpenMLDataset

RETURNS	DESCRIPTION
output_filename	Location of ARFF file. TYPE: Path

Source code in openml/_api/resources/dataset.py

def download_dataset_arff(
    self,
    description: dict | OpenMLDataset,
) -> Path:
    """Download dataset arff file.

    Parameters
    ----------
    description : dictionary or OpenMLDataset
        Either a dataset description as dict or OpenMLDataset.

    Returns
    -------
    output_filename : Path
        Location of ARFF file.
    """
    if isinstance(description, dict):
        md5_checksum_fixture = description.get("oml:md5_checksum")
        url = str(description["oml:url"])
        did = int(description.get("oml:id"))  # type: ignore
    elif isinstance(description, OpenMLDataset):
        md5_checksum_fixture = description.md5_checksum
        assert description.url is not None
        assert description.dataset_id is not None

        url = description.url
        did = int(description.dataset_id)
    else:
        raise TypeError("`description` should be either OpenMLDataset or Dict.")

    try:
        # save the file in cache and get it's path
        self._http.get(url, enable_cache=True, md5_checksum=md5_checksum_fixture)
        output_file_path = self._http.cache_path_from_url(url)
    except OpenMLHashException as e:
        additional_info = f" Raised when downloading dataset {did}."
        e.args = (e.args[0] + additional_info,)
        raise e

    return output_file_path

download_dataset_parquet

download_dataset_parquet(description: dict | OpenMLDataset, download_all_files: bool = False) -> Path | None

Download dataset parquet file.

PARAMETER	DESCRIPTION
description	Either a dataset description as dict or OpenMLDataset. TYPE: dictionary or OpenMLDataset
download_all_files	If True, download all data found in the bucket to which the description's parquet_url points, only download the parquet file otherwise. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
Path | None

Source code in openml/_api/resources/dataset.py

def download_dataset_parquet(
    self,
    description: dict | OpenMLDataset,
    download_all_files: bool = False,  # noqa: FBT002
) -> Path | None:
    """Download dataset parquet file.

    Parameters
    ----------
    description : dictionary or OpenMLDataset
        Either a dataset description as dict or OpenMLDataset.
    download_all_files: bool, optional (default=False)
        If `True`, download all data found in the bucket to which the description's
        ``parquet_url`` points, only download the parquet file otherwise.

    Returns
    -------
    Path | None
    """
    if isinstance(description, dict):
        url = str(description.get("oml:parquet_url"))
    elif isinstance(description, OpenMLDataset):
        url = str(description._parquet_url)
        assert description.dataset_id is not None
    else:
        raise TypeError("`description` should be either OpenMLDataset or Dict.")

    output_file_path = Path(openml.config.get_minio_download_path(url))
    if download_all_files:
        self._minio.download_minio_bucket(source=url)

    if not output_file_path.is_file():
        try:
            output_file_path = self._minio.download_minio_file(
                source=url,
            )
        except (
            FileNotFoundError,
            urllib3.exceptions.MaxRetryError,
            minio.error.ServerError,
        ) as e:
            logger.warning(f"Could not download file from {url}: {e}")
            return None
    return output_file_path

download_features_file

download_features_file(dataset_id: int) -> Path

Download features file.

PARAMETER	DESCRIPTION
dataset_id	ID of the dataset. TYPE: int

RETURNS	DESCRIPTION
Path

Source code in openml/_api/resources/dataset.py

def download_features_file(self, dataset_id: int) -> Path:
    """Download features file.

    Parameters
    ----------
    dataset_id : int
        ID of the dataset.

    Returns
    -------
    Path
    """
    path = f"data/features/{dataset_id}"
    file = self._download_file(path)
    self.parse_features_file(file)
    return file

download_qualities_file

download_qualities_file(dataset_id: int) -> Path | None

Download qualities file.

PARAMETER	DESCRIPTION
dataset_id	ID of the dataset. TYPE: int

RETURNS	DESCRIPTION
Path

Source code in openml/_api/resources/dataset.py

def download_qualities_file(self, dataset_id: int) -> Path | None:
    """Download qualities file.

    Parameters
    ----------
    dataset_id : int
        ID of the dataset.

    Returns
    -------
    Path
    """
    path = f"data/qualities/{dataset_id}"
    try:
        file = self._download_file(path)
    except OpenMLServerException as e:
        if e.code == 362 and str(e) == "No qualities found - None":
            # quality file stays as None
            logger.warning(f"No qualities found for dataset {dataset_id}")
            return None
        raise e

    self.parse_qualities_file(file)
    return file

edit

edit(dataset_id: int, *, description: str | None = None, creator: str | None = None, contributor: str | None = None, collection_date: str | None = None, language: str | None = None, default_target_attribute: str | None = None, ignore_attribute: str | list[str] | None = None, citation: str | None = None, row_id_attribute: str | None = None, original_data_url: str | None = None, paper_url: str | None = None) -> int

Edits an OpenMLDataset.

PARAMETER	DESCRIPTION
dataset_id	ID of the dataset. TYPE: int
description	Description of the dataset. TYPE: str DEFAULT: None
creator	The person who created the dataset. TYPE: str DEFAULT: None
contributor	People who contributed to the current version of the dataset. TYPE: str DEFAULT: None
collection_date	The date the data was originally collected, given by the uploader. TYPE: str DEFAULT: None
language	Language in which the data is represented. Starts with 1 upper case letter, rest lower case, e.g. 'English'. TYPE: str DEFAULT: None
default_target_attribute	The default target attribute, if it exists. Can have multiple values, comma separated. TYPE: str DEFAULT: None
ignore_attribute	Attributes that should be excluded in modelling, such as identifiers and indexes. TYPE: str | list DEFAULT: None
citation	Reference(s) that should be cited when building on this data. TYPE: str DEFAULT: None
row_id_attribute	The attribute that represents the row-id column, if present in the dataset. If data is a dataframe and row_id_attribute is not specified, the index of the dataframe will be used as the row_id_attribute. If the name of the index is None, it will be discarded. .. versionadded: 0.8 Inference of row_id_attribute from a dataframe. TYPE: str DEFAULT: None
original_data_url	For derived data, the url to the original dataset. TYPE: str DEFAULT: None
paper_url	Link to a paper describing the dataset. TYPE: str DEFAULT: None

RETURNS	DESCRIPTION
Dataset id

Source code in openml/_api/resources/dataset.py

def edit(
    self,
    dataset_id: int,
    *,
    description: str | None = None,
    creator: str | None = None,
    contributor: str | None = None,
    collection_date: str | None = None,
    language: str | None = None,
    default_target_attribute: str | None = None,
    ignore_attribute: str | builtins.list[str] | None = None,
    citation: str | None = None,
    row_id_attribute: str | None = None,
    original_data_url: str | None = None,
    paper_url: str | None = None,
) -> int:
    """Edits an OpenMLDataset.

    Parameters
    ----------
    dataset_id : int
        ID of the dataset.
    description : str, optional
        Description of the dataset.
    creator : str, optional
        The person who created the dataset.
    contributor : str, optional
        People who contributed to the current version of the dataset.
    collection_date : str, optional
        The date the data was originally collected, given by the uploader.
    language : str, optional
        Language in which the data is represented.
        Starts with 1 upper case letter, rest lower case, e.g. 'English'.
    default_target_attribute : str, optional
        The default target attribute, if it exists.
        Can have multiple values, comma separated.
    ignore_attribute : str | list, optional
        Attributes that should be excluded in modelling,
        such as identifiers and indexes.
    citation : str, optional
        Reference(s) that should be cited when building on this data.
    row_id_attribute : str, optional
        The attribute that represents the row-id column, if present in the
        dataset. If ``data`` is a dataframe and ``row_id_attribute`` is not
        specified, the index of the dataframe will be used as the
        ``row_id_attribute``. If the name of the index is ``None``, it will
        be discarded.

        .. versionadded: 0.8
            Inference of ``row_id_attribute`` from a dataframe.
    original_data_url : str, optional
        For derived data, the url to the original dataset.
    paper_url : str, optional
        Link to a paper describing the dataset.

    Returns
    -------
    Dataset id
    """
    # compose data edit parameters as xml
    form_data = {"data_id": dataset_id}  # type: dict[str, str | int]
    xml = OrderedDict()  # type: 'OrderedDict[str, OrderedDict]'
    xml["oml:data_edit_parameters"] = OrderedDict()
    xml["oml:data_edit_parameters"]["@xmlns:oml"] = "http://openml.org/openml"
    xml["oml:data_edit_parameters"]["oml:description"] = description
    xml["oml:data_edit_parameters"]["oml:creator"] = creator
    xml["oml:data_edit_parameters"]["oml:contributor"] = contributor
    xml["oml:data_edit_parameters"]["oml:collection_date"] = collection_date
    xml["oml:data_edit_parameters"]["oml:language"] = language
    xml["oml:data_edit_parameters"]["oml:default_target_attribute"] = default_target_attribute
    xml["oml:data_edit_parameters"]["oml:row_id_attribute"] = row_id_attribute
    xml["oml:data_edit_parameters"]["oml:ignore_attribute"] = ignore_attribute
    xml["oml:data_edit_parameters"]["oml:citation"] = citation
    xml["oml:data_edit_parameters"]["oml:original_data_url"] = original_data_url
    xml["oml:data_edit_parameters"]["oml:paper_url"] = paper_url

    # delete None inputs
    for k in list(xml["oml:data_edit_parameters"]):
        if not xml["oml:data_edit_parameters"][k]:
            del xml["oml:data_edit_parameters"][k]

    file_elements = {
        "edit_parameters": ("description.xml", xmltodict.unparse(xml)),
    }  # type: dict[str, str | tuple[str, str]]
    result_xml = self._http.post("data/edit", data=form_data, files=file_elements).text
    result = xmltodict.parse(result_xml)
    dataset_id = result["oml:data_edit"]["oml:id"]
    return int(dataset_id)

feature_add_ontology

feature_add_ontology(dataset_id: int, index: int, ontology: str) -> bool

An ontology describes the concept that are described in a feature. An ontology is defined by an URL where the information is provided. Adds an ontology (URL) to a given dataset feature (defined by a dataset id and index). The dataset has to exists on OpenML and needs to have been processed by the evaluation engine.

PARAMETER	DESCRIPTION
dataset_id	id of the dataset to which the feature belongs TYPE: int
index	index of the feature in dataset (0-based) TYPE: int
ontology	URL to ontology (max. 256 characters) TYPE: str

RETURNS	DESCRIPTION
True or throws an OpenML server exception

Source code in openml/_api/resources/dataset.py

def feature_add_ontology(self, dataset_id: int, index: int, ontology: str) -> bool:
    """
    An ontology describes the concept that are described in a feature. An
    ontology is defined by an URL where the information is provided. Adds
    an ontology (URL) to a given dataset feature (defined by a dataset id
    and index). The dataset has to exists on OpenML and needs to have been
    processed by the evaluation engine.

    Parameters
    ----------
    dataset_id : int
        id of the dataset to which the feature belongs
    index : int
        index of the feature in dataset (0-based)
    ontology : str
        URL to ontology (max. 256 characters)

    Returns
    -------
    True or throws an OpenML server exception
    """
    upload_data: dict[str, int | str] = {
        "data_id": dataset_id,
        "index": index,
        "ontology": ontology,
    }
    self._http.post("data/feature/ontology/add", data=upload_data)
    # an error will be thrown in case the request was unsuccessful
    return True

feature_remove_ontology

feature_remove_ontology(dataset_id: int, index: int, ontology: str) -> bool

Removes an existing ontology (URL) from a given dataset feature (defined by a dataset id and index). The dataset has to exists on OpenML and needs to have been processed by the evaluation engine. Ontology needs to be attached to the specific fearure.

PARAMETER	DESCRIPTION
dataset_id	id of the dataset to which the feature belongs TYPE: int
index	index of the feature in dataset (0-based) TYPE: int
ontology	URL to ontology (max. 256 characters) TYPE: str

RETURNS	DESCRIPTION
True or throws an OpenML server exception

Source code in openml/_api/resources/dataset.py

def feature_remove_ontology(self, dataset_id: int, index: int, ontology: str) -> bool:
    """
    Removes an existing ontology (URL) from a given dataset feature (defined
    by a dataset id and index). The dataset has to exists on OpenML and needs
    to have been processed by the evaluation engine. Ontology needs to be
    attached to the specific fearure.

    Parameters
    ----------
    dataset_id : int
        id of the dataset to which the feature belongs
    index : int
        index of the feature in dataset (0-based)
    ontology : str
        URL to ontology (max. 256 characters)

    Returns
    -------
    True or throws an OpenML server exception
    """
    upload_data: dict[str, int | str] = {
        "data_id": dataset_id,
        "index": index,
        "ontology": ontology,
    }
    self._http.post("data/feature/ontology/remove", data=upload_data)
    # an error will be thrown in case the request was unsuccessful
    return True

fork

fork(dataset_id: int) -> int

Creates a new dataset version, with the authenticated user as the new owner. The forked dataset can have distinct dataset meta-data, but the actual data itself is shared with the original version.

PARAMETER	DESCRIPTION
dataset_id	id of the dataset to be forked TYPE: int

RETURNS	DESCRIPTION
Dataset id of the forked dataset

Source code in openml/_api/resources/dataset.py

def fork(self, dataset_id: int) -> int:
    """
    Creates a new dataset version, with the authenticated user as the new owner.
    The forked dataset can have distinct dataset meta-data,
    but the actual data itself is shared with the original version.

    Parameters
    ----------
    dataset_id : int
        id of the dataset to be forked

    Returns
    -------
    Dataset id of the forked dataset

    """
    # compose data fork parameters
    form_data = {"data_id": dataset_id}
    result_xml = self._http.post("data/fork", data=form_data).text
    result = xmltodict.parse(result_xml)
    dataset_id = result["oml:data_fork"]["oml:id"]
    return int(dataset_id)

get

get(dataset_id: int, *, download_data: bool = False, cache_format: Literal['pickle', 'feather'] = 'pickle', download_qualities: bool = False, download_features_meta_data: bool = False, download_all_files: bool = False, force_refresh_cache: bool = False) -> OpenMLDataset

Download the OpenML dataset representation, optionally also download actual data file.

PARAMETER	DESCRIPTION
dataset_id	Dataset ID (integer) or dataset name (string) of the dataset to download. TYPE: int or str
download_data	If True, download the data file. TYPE: bool(default=False) DEFAULT: False
cache_format	Format for caching the dataset - may be feather or pickle Note that the default 'pickle' option may load slower than feather when no.of.rows is very high. TYPE: str(default='pickle') in {'pickle', 'feather'} DEFAULT: 'pickle'
download_qualities	Option to download 'qualities' meta-data with the minimal dataset description. TYPE: bool(default=False) DEFAULT: False
download_features_meta_data	Option to download 'features' meta-data with the minimal dataset description. TYPE: bool(default=False) DEFAULT: False
download_all_files	EXPERIMENTAL. Download all files related to the dataset that reside on the server. TYPE: bool DEFAULT: False
force_refresh_cache	Force the cache to delete the cache directory and re-download the data. TYPE: bool(default=False) DEFAULT: False

RETURNS	DESCRIPTION
dataset	The downloaded dataset. TYPE: :class:`openml.OpenMLDataset`

Source code in openml/_api/resources/dataset.py

def get(
    self,
    dataset_id: int,
    *,
    download_data: bool = False,
    cache_format: Literal["pickle", "feather"] = "pickle",
    download_qualities: bool = False,
    download_features_meta_data: bool = False,
    download_all_files: bool = False,
    force_refresh_cache: bool = False,
) -> OpenMLDataset:
    """Download the OpenML dataset representation, optionally also download actual data file.

    Parameters
    ----------
    dataset_id : int or str
        Dataset ID (integer) or dataset name (string) of the dataset to download.
    download_data : bool (default=False)
        If True, download the data file.
    cache_format : str (default='pickle') in {'pickle', 'feather'}
        Format for caching the dataset - may be feather or pickle
        Note that the default 'pickle' option may load slower than feather when
        no.of.rows is very high.
    download_qualities : bool (default=False)
        Option to download 'qualities' meta-data with the minimal dataset description.
    download_features_meta_data : bool (default=False)
        Option to download 'features' meta-data with the minimal dataset description.
    download_all_files: bool (default=False)
        EXPERIMENTAL. Download all files related to the dataset that reside on the server.
    force_refresh_cache : bool (default=False)
        Force the cache to delete the cache directory and re-download the data.

    Returns
    -------
    dataset : :class:`openml.OpenMLDataset`
        The downloaded dataset.
    """
    path = f"data/{dataset_id}"
    try:
        response = self._http.get(path, enable_cache=True, refresh_cache=force_refresh_cache)
        xml_content = response.text
        description = xmltodict.parse(xml_content)["oml:data_set_description"]

        features_file = None
        qualities_file = None

        if download_features_meta_data:
            features_file = self.download_features_file(dataset_id)
        if download_qualities:
            qualities_file = self.download_qualities_file(dataset_id)

        parquet_file = None
        skip_parquet = (
            os.environ.get(openml.config.OPENML_SKIP_PARQUET_ENV_VAR, "false").casefold()
            == "true"
        )
        download_parquet = "oml:parquet_url" in description and not skip_parquet
        if download_parquet and (download_data or download_all_files):
            try:
                parquet_file = self.download_dataset_parquet(
                    description,
                    download_all_files=download_all_files,
                )
            except urllib3.exceptions.MaxRetryError:
                parquet_file = None

        arff_file = None
        if parquet_file is None and download_data:
            if download_parquet:
                logger.warning("Failed to download parquet, fallback on ARFF.")
            arff_file = self.download_dataset_arff(description)
    except OpenMLServerException as e:
        # if there was an exception
        # check if the user had access to the dataset
        if e.code == NO_ACCESS_GRANTED_ERRCODE:
            raise OpenMLPrivateDatasetError(e.message) from None

        raise e

    return self._create_dataset_from_xml(
        description,
        features_file=features_file,
        qualities_file=qualities_file,
        arff_file=arff_file,
        parquet_file=parquet_file,
        cache_format=cache_format,
    )

get_features

get_features(dataset_id: int, force_refresh_cache: bool = False) -> dict[int, OpenMLDataFeature]

Get features of a dataset from server.

PARAMETER	DESCRIPTION
dataset_id	ID of the dataset. TYPE: int
force_refresh_cache	Refresh the cache and re-download the features file. TYPE: bool(default=False) DEFAULT: False

RETURNS	DESCRIPTION
dict[int, OpenMLDataFeature]

Source code in openml/_api/resources/dataset.py

def get_features(
    self,
    dataset_id: int,
    force_refresh_cache: bool = False,  # noqa: FBT002
) -> dict[int, OpenMLDataFeature]:
    """Get features of a dataset from server.

    Parameters
    ----------
    dataset_id : int
        ID of the dataset.
    force_refresh_cache : bool (default=False)
        Refresh the cache and re-download the features file.

    Returns
    -------
    dict[int, OpenMLDataFeature]
    """
    path = f"data/features/{dataset_id}"
    xml = self._http.get(path, enable_cache=True, refresh_cache=force_refresh_cache).text
    return self._parse_features_xml(xml)

get_online_dataset_format

get_online_dataset_format(dataset_id: int) -> str

Get the dataset format for a given dataset id from the OpenML website.

PARAMETER	DESCRIPTION
dataset_id	A dataset id. TYPE: int

RETURNS	DESCRIPTION
str	Dataset format.

Source code in openml/_api/resources/dataset.py

def get_online_dataset_format(self, dataset_id: int) -> str:
    """Get the dataset format for a given dataset id from the OpenML website.

    Parameters
    ----------
    dataset_id : int
        A dataset id.

    Returns
    -------
    str
        Dataset format.
    """
    dataset_xml = self._http.get(f"data/{dataset_id}").text
    # build a dict from the xml and get the format from the dataset description
    return xmltodict.parse(dataset_xml)["oml:data_set_description"]["oml:format"].lower()  # type: ignore

get_qualities

get_qualities(dataset_id: int, force_refresh_cache: bool = False) -> dict[str, float] | None

Get qualities of a dataset from server.

PARAMETER	DESCRIPTION
dataset_id	ID of the dataset. TYPE: int
force_refresh_cache	Refresh the cache and re-download the qualities file. TYPE: bool(default=False) DEFAULT: False

RETURNS	DESCRIPTION
dict[str, float] | None

Source code in openml/_api/resources/dataset.py

def get_qualities(
    self,
    dataset_id: int,
    force_refresh_cache: bool = False,  # noqa: FBT002
) -> dict[str, float] | None:
    """Get qualities of a dataset from server.

    Parameters
    ----------
    dataset_id : int
        ID of the dataset.
    force_refresh_cache : bool (default=False)
        Refresh the cache and re-download the qualities file.

    Returns
    -------
    dict[str, float] | None
    """
    path = f"data/qualities/{dataset_id!s}"
    try:
        xml = self._http.get(path, enable_cache=True, refresh_cache=force_refresh_cache).text
    except OpenMLServerException as e:
        if e.code == 362 and str(e) == "No qualities found - None":
            # quality file stays as None
            logger.warning(f"No qualities found for dataset {dataset_id}")
            return None

        raise e
    return self._parse_qualities_xml(xml)

list

list(limit: int, offset: int, *, data_id: list[int] | None = None, **kwargs: Any) -> DataFrame

Perform api call to return a list of all datasets.

PARAMETER	DESCRIPTION
The
ones
display_errors
default
limit	The maximum number of datasets to show. TYPE: int
offset	The number of datasets to skip, starting from the first. TYPE: int
data_id	TYPE: list DEFAULT: None
kwargs	Legal filter operators (keys in the dict): tag, status, limit, offset, data_name, data_version, number_instances, number_features, number_classes, number_missing_values. TYPE: dict DEFAULT: {}

RETURNS	DESCRIPTION
datasets	TYPE: dataframe

Source code in openml/_api/resources/dataset.py

def list(
    self,
    limit: int,
    offset: int,
    *,
    data_id: builtins.list[int] | None = None,
    **kwargs: Any,
) -> pd.DataFrame:
    """
    Perform api call to return a list of all datasets.

    Parameters
    ----------
    The arguments that are lists are separated from the single value
    ones which are put into the kwargs.
    display_errors is also separated from the kwargs since it has a
    default value.

    limit : int
        The maximum number of datasets to show.
    offset : int
        The number of datasets to skip, starting from the first.
    data_id : list, optional

    kwargs : dict, optional
        Legal filter operators (keys in the dict):
        tag, status, limit, offset, data_name, data_version, number_instances,
        number_features, number_classes, number_missing_values.

    Returns
    -------
    datasets : dataframe
    """
    api_call = "data/list"

    if limit is not None:
        api_call += f"/limit/{limit}"
    if offset is not None:
        api_call += f"/offset/{offset}"

    if kwargs is not None:
        for operator, value in kwargs.items():
            if value is not None:
                api_call += f"/{operator}/{value}"
    if data_id is not None:
        api_call += f"/data_id/{','.join([str(int(i)) for i in data_id])}"
    xml_string = self._http.get(api_call).text
    return self._parse_list_xml(xml_string)

list_qualities

list_qualities() -> list[str]

Return list of data qualities available.

The function performs an API call to retrieve the entire list of data qualities that are computed on the datasets uploaded.

RETURNS	DESCRIPTION
list

Source code in openml/_api/resources/dataset.py

def list_qualities(self) -> builtins.list[str]:
    """Return list of data qualities available.

    The function performs an API call to retrieve the entire list of
    data qualities that are computed on the datasets uploaded.

    Returns
    -------
    list
    """
    api_call = "data/qualities/list"
    xml_string = self._http.get(api_call).text
    qualities = xmltodict.parse(xml_string, force_list=("oml:quality"))
    # Minimalistic check if the XML is useful
    if "oml:data_qualities_list" not in qualities:
        raise ValueError('Error in return XML, does not contain "oml:data_qualities_list"')

    if not isinstance(qualities["oml:data_qualities_list"]["oml:quality"], list):
        raise TypeError('Error in return XML, does not contain "oml:quality" as a list')

    return qualities["oml:data_qualities_list"]["oml:quality"]

parse_features_file

parse_features_file(features_file: Path, features_pickle_file: Path | None = None) -> dict[int, OpenMLDataFeature]

Parse features file (xml) and store it as a pickle file.

PARAMETER	DESCRIPTION
features_file	Path to features file. TYPE: Path
features_pickle_file	Path to pickle file for features. TYPE: Path DEFAULT: None

RETURNS	DESCRIPTION
features	TYPE: dict[int, OpenMLDataFeature]

Source code in openml/_api/resources/dataset.py

def parse_features_file(
    self, features_file: Path, features_pickle_file: Path | None = None
) -> dict[int, OpenMLDataFeature]:
    """
    Parse features file (xml) and store it as a pickle file.

    Parameters
    ----------
    features_file : Path
        Path to features file.
    features_pickle_file : Path, optional
        Path to pickle file for features.

    Returns
    -------
    features : dict[int, OpenMLDataFeature]
    """
    if features_pickle_file is None:
        features_pickle_file = features_file.with_suffix(features_file.suffix + ".pkl")
    assert features_file.suffix == ".xml"

    with Path(features_file).open("r", encoding="utf8") as fh:
        features_xml = fh.read()

    features = self._parse_features_xml(features_xml)

    with features_pickle_file.open("wb") as fh_binary:
        pickle.dump(features, fh_binary)

    return features

parse_qualities_file

parse_qualities_file(qualities_file: Path, qualities_pickle_file: Path | None = None) -> dict[str, float]

Parse qualities file (xml) and store it as a pickle file.

PARAMETER	DESCRIPTION
qualities_file	Path to qualities file. TYPE: Path
qualities_pickle_file	Path to pickle file for qualities. TYPE: Path DEFAULT: None

RETURNS	DESCRIPTION
qualities	TYPE: dict[str, float]

Source code in openml/_api/resources/dataset.py

def parse_qualities_file(
    self, qualities_file: Path, qualities_pickle_file: Path | None = None
) -> dict[str, float]:
    """Parse qualities file (xml) and store it as a pickle file.

    Parameters
    ----------
    qualities_file : Path
        Path to qualities file.
    qualities_pickle_file : Path, optional
        Path to pickle file for qualities.

    Returns
    -------
    qualities : dict[str, float]
    """
    if qualities_pickle_file is None:
        qualities_pickle_file = qualities_file.with_suffix(qualities_file.suffix + ".pkl")
    assert qualities_file.suffix == ".xml"

    with Path(qualities_file).open("r", encoding="utf8") as fh:
        qualities_xml = fh.read()

    qualities = self._parse_qualities_xml(qualities_xml)

    with qualities_pickle_file.open("wb") as fh_binary:
        pickle.dump(qualities, fh_binary)

    return qualities

publish

publish(path: str, files: Mapping[str, Any] | None) -> int

Publish a new resource using the V1 API.

PARAMETER	DESCRIPTION
path	API endpoint path for the upload. TYPE: str
files	Files to upload as part of the request payload. TYPE: Mapping of str to Any or None

RETURNS	DESCRIPTION
int	Identifier of the newly created resource.

RAISES	DESCRIPTION
ValueError	If the server response does not contain a valid resource ID.
OpenMLServerException	If the server returns an error during upload.

Source code in openml/_api/resources/base/versions.py

def publish(self, path: str, files: Mapping[str, Any] | None) -> int:
    """
    Publish a new resource using the V1 API.

    Parameters
    ----------
    path : str
        API endpoint path for the upload.
    files : Mapping of str to Any or None
        Files to upload as part of the request payload.

    Returns
    -------
    int
        Identifier of the newly created resource.

    Raises
    ------
    ValueError
        If the server response does not contain a valid resource ID.
    OpenMLServerException
        If the server returns an error during upload.
    """
    response = self._http.post(path, files=files)
    try:
        parsed_response = xmltodict.parse(response.content)
    except xml.parsers.expat.ExpatError as e:
        msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
        raise OpenMLServerError(msg) from e
    return self._extract_id_from_upload(parsed_response)

status_update

status_update(dataset_id: int, status: Literal['active', 'deactivated']) -> None

Updates the status of a dataset to either 'active' or 'deactivated'. Please see the OpenML API documentation for a description of the status and all legal status transitions: docs.openml.org/concepts/data/#dataset-status

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

Source code in openml/_api/resources/dataset.py

def status_update(self, dataset_id: int, status: Literal["active", "deactivated"]) -> None:
    """
    Updates the status of a dataset to either 'active' or 'deactivated'.
    Please see the OpenML API documentation for a description of the status
    and all legal status transitions:
    https://docs.openml.org/concepts/data/#dataset-status

    Parameters
    ----------
    dataset_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: dict[str, str | int] = {"data_id": dataset_id, "status": status}
    result_xml = self._http.post("data/status/update", data=data).text
    result = xmltodict.parse(result_xml)
    server_data_id = result["oml:data_status_update"]["oml:id"]
    server_status = result["oml:data_status_update"]["oml:status"]
    if status != server_status or int(dataset_id) != int(server_data_id):
        # This should never happen
        raise ValueError("Data id/status does not match")

tag

tag(resource_id: int, tag: str) -> list[str]

Add a tag to a resource using the V1 API.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to tag. TYPE: int
tag	Tag to associate with the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

RAISES	DESCRIPTION
ValueError	If the resource type does not support tagging.
OpenMLServerException	If the server returns an error.

Source code in openml/_api/resources/base/versions.py

def tag(self, resource_id: int, tag: str) -> list[str]:
    """
    Add a tag to a resource using the V1 API.

    Parameters
    ----------
    resource_id : int
        Identifier of the resource to tag.
    tag : str
        Tag to associate with the resource.

    Returns
    -------
    list of str
        Updated list of tags assigned to the resource.

    Raises
    ------
    ValueError
        If the resource type does not support tagging.
    OpenMLServerException
        If the server returns an error.
    """
    if self.resource_type not in _LEGAL_RESOURCES_TAG:
        raise ValueError(f"Can't tag a {self.resource_type.value}")

    endpoint_name = self._get_endpoint_name()
    path = f"{endpoint_name}/tag"
    data = {f"{endpoint_name}_id": resource_id, "tag": tag}
    response = self._http.post(path, data=data)

    try:
        parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    except xml.parsers.expat.ExpatError as e:
        msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
        raise OpenMLServerError(msg) from e
    result = parsed_response[f"oml:{endpoint_name}_tag"]
    tags: list[str] = result.get("oml:tag", [])

    return tags

untag

untag(resource_id: int, tag: str) -> list[str]

Remove a tag from a resource using the V1 API.

PARAMETER	DESCRIPTION
resource_id	Identifier of the resource to untag. TYPE: int
tag	Tag to remove from the resource. TYPE: str

RETURNS	DESCRIPTION
list of str	Updated list of tags assigned to the resource.

RAISES	DESCRIPTION
ValueError	If the resource type does not support tagging.
OpenMLServerException	If the server returns an error.

Source code in openml/_api/resources/base/versions.py

def untag(self, resource_id: int, tag: str) -> list[str]:
    """
    Remove a tag from a resource using the V1 API.

    Parameters
    ----------
    resource_id : int
        Identifier of the resource to untag.
    tag : str
        Tag to remove from the resource.

    Returns
    -------
    list of str
        Updated list of tags assigned to the resource.

    Raises
    ------
    ValueError
        If the resource type does not support tagging.
    OpenMLServerException
        If the server returns an error.
    """
    if self.resource_type not in _LEGAL_RESOURCES_TAG:
        raise ValueError(f"Can't untag a {self.resource_type.value}")

    endpoint_name = self._get_endpoint_name()
    path = f"{endpoint_name}/untag"
    data = {f"{endpoint_name}_id": resource_id, "tag": tag}
    response = self._http.post(path, data=data)

    try:
        parsed_response = xmltodict.parse(response.content, force_list={"oml:tag"})
    except xml.parsers.expat.ExpatError as e:
        msg = f"Unexpected response to {path}Could not parse: {response.content!r}"
        raise OpenMLServerError(msg) from e
    result = parsed_response[f"oml:{endpoint_name}_untag"]
    tags: list[str] = result.get("oml:tag", [])

    return tags

DatasetV2API

DatasetV2API(http: HTTPClient, minio: MinIOClient)

Bases: ResourceV2API, DatasetAPI

Version 2 API implementation for dataset resources.

Source code in openml/_api/resources/base/base.py

def __init__(self, http: HTTPClient, minio: MinIOClient):
    self._http = http
    self._minio = minio

download_dataset_arff

download_dataset_arff(description: dict | OpenMLDataset) -> Path

Download dataset arff file.

PARAMETER	DESCRIPTION
description	Either a dataset description as dict or OpenMLDataset. TYPE: dictionary or OpenMLDataset

RETURNS	DESCRIPTION
output_filename	Location of ARFF file. TYPE: Path

Source code in openml/_api/resources/dataset.py

def download_dataset_arff(
    self,
    description: dict | OpenMLDataset,
) -> Path:
    """Download dataset arff file.

    Parameters
    ----------
    description : dictionary or OpenMLDataset
        Either a dataset description as dict or OpenMLDataset.

    Returns
    -------
    output_filename : Path
        Location of ARFF file.
    """
    if isinstance(description, dict):
        url = str(description["url"])
        did = int(description.get("id"))  # type: ignore
        md5_checksum_fixture = description.get("md5_checksum")
    elif isinstance(description, OpenMLDataset):
        assert description.url is not None
        assert description.dataset_id is not None
        md5_checksum_fixture = description.md5_checksum

        url = description.url
        did = int(description.dataset_id)
    else:
        raise TypeError("`description` should be either OpenMLDataset or Dict.")

    try:
        # save the file in cache and get it's path
        self._http.get(url, enable_cache=True, md5_checksum=md5_checksum_fixture)
        output_file_path = self._http.cache_path_from_url(url)
    except OpenMLHashException as e:
        additional_info = f" Raised when downloading dataset {did}."
        e.args = (e.args[0] + additional_info,)
        raise e

    return output_file_path

download_dataset_parquet

download_dataset_parquet(description: dict | OpenMLDataset, download_all_files: bool = False) -> Path | None

Download dataset parquet file.

PARAMETER	DESCRIPTION
description	Either a dataset description as dict or OpenMLDataset. TYPE: dictionary or OpenMLDataset
download_all_files	If True, download all data found in the bucket to which the description's parquet_url points, only download the parquet file otherwise. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
Path | None

Source code in openml/_api/resources/dataset.py

def download_dataset_parquet(
    self,
    description: dict | OpenMLDataset,
    download_all_files: bool = False,  # noqa: FBT002
) -> Path | None:
    """Download dataset parquet file.

    Parameters
    ----------
    description : dictionary or OpenMLDataset
        Either a dataset description as dict or OpenMLDataset.
    download_all_files: bool, optional (default=False)
        If `True`, download all data found in the bucket to which the description's
        ``parquet_url`` points, only download the parquet file otherwise.

    Returns
    -------
    Path | None
    """
    if isinstance(description, dict):
        url = str(description.get("parquet_url"))
    elif isinstance(description, OpenMLDataset):
        url = str(description._parquet_url)
        assert description.dataset_id is not None
    else:
        raise TypeError("`description` should be either OpenMLDataset or Dict.")

    output_file_path = Path(openml.config.get_minio_download_path(url))
    if download_all_files:
        self._minio.download_minio_bucket(source=url)

    if not output_file_path.is_file():
        try:
            output_file_path = self._minio.download_minio_file(source=url)
        except (
            FileNotFoundError,
            urllib3.exceptions.MaxRetryError,
            minio.error.ServerError,
        ) as e:
            logger.warning(f"Could not download file from {url}: {e}")
            return None
    return output_file_path

download_features_file

download_features_file(dataset_id: int) -> Path

Download features file.

PARAMETER	DESCRIPTION
dataset_id	ID of the dataset. TYPE: int

RETURNS	DESCRIPTION
Path

Source code in openml/_api/resources/dataset.py

def download_features_file(self, dataset_id: int) -> Path:
    """Download features file.

    Parameters
    ----------
    dataset_id : int
        ID of the dataset.

    Returns
    -------
    Path
    """
    path = f"datasets/features/{dataset_id}"
    file = self._download_file(path)
    self.parse_features_file(file)
    return file

download_qualities_file

download_qualities_file(dataset_id: int) -> Path | None

Download qualities file.

PARAMETER	DESCRIPTION
dataset_id	ID of the dataset. TYPE: int

RETURNS	DESCRIPTION
Path

Source code in openml/_api/resources/dataset.py

def download_qualities_file(self, dataset_id: int) -> Path | None:
    """Download qualities file.

    Parameters
    ----------
    dataset_id : int
        ID of the dataset.

    Returns
    -------
    Path
    """
    path = f"datasets/qualities/{dataset_id}"
    try:
        file = self._download_file(path)
    except OpenMLServerException as e:
        if e.code == 362 and str(e) == "No qualities found - None":
            # quality file stays as None
            logger.warning(f"No qualities found for dataset {dataset_id}")
            return None
        raise e

    if not self.parse_qualities_file(file):
        logger.warning(f"No qualities found for dataset {dataset_id}")
        return None
    return file

get

get(dataset_id: int, *, download_data: bool = False, cache_format: Literal['pickle', 'feather'] = 'pickle', download_qualities: bool = False, download_features_meta_data: bool = False, download_all_files: bool = False, force_refresh_cache: bool = False) -> OpenMLDataset

Download the OpenML dataset representation, optionally also download actual data file.

PARAMETER	DESCRIPTION
dataset_id	Dataset ID (integer) or dataset name (string) of the dataset to download. TYPE: int or str
download_data	If True, download the data file. TYPE: bool(default=False) DEFAULT: False
cache_format	Format for caching the dataset - may be feather or pickle Note that the default 'pickle' option may load slower than feather when no.of.rows is very high. TYPE: str(default='pickle') in {'pickle', 'feather'} DEFAULT: 'pickle'
download_qualities	Option to download 'qualities' meta-data with the minimal dataset description. TYPE: bool(default=False) DEFAULT: False
download_features_meta_data	Option to download 'features' meta-data with the minimal dataset description. TYPE: bool(default=False) DEFAULT: False
download_all_files	EXPERIMENTAL. Download all files related to the dataset that reside on the server. TYPE: bool DEFAULT: False
force_refresh_cache	Force the cache to delete the cache directory and re-download the data. TYPE: bool(default=False) DEFAULT: False

RETURNS	DESCRIPTION
dataset	The downloaded dataset. TYPE: :class:`openml.OpenMLDataset`

Source code in openml/_api/resources/dataset.py

def get(
    self,
    dataset_id: int,
    *,
    download_data: bool = False,
    cache_format: Literal["pickle", "feather"] = "pickle",
    download_qualities: bool = False,
    download_features_meta_data: bool = False,
    download_all_files: bool = False,
    force_refresh_cache: bool = False,
) -> OpenMLDataset:
    """Download the OpenML dataset representation, optionally also download actual data file.

    Parameters
    ----------
    dataset_id : int or str
        Dataset ID (integer) or dataset name (string) of the dataset to download.
    download_data : bool (default=False)
        If True, download the data file.
    cache_format : str (default='pickle') in {'pickle', 'feather'}
        Format for caching the dataset - may be feather or pickle
        Note that the default 'pickle' option may load slower than feather when
        no.of.rows is very high.
    download_qualities : bool (default=False)
        Option to download 'qualities' meta-data with the minimal dataset description.
    download_features_meta_data : bool (default=False)
        Option to download 'features' meta-data with the minimal dataset description.
    download_all_files: bool (default=False)
        EXPERIMENTAL. Download all files related to the dataset that reside on the server.
    force_refresh_cache : bool (default=False)
        Force the cache to delete the cache directory and re-download the data.

    Returns
    -------
    dataset : :class:`openml.OpenMLDataset`
        The downloaded dataset.
    """
    path = f"datasets/{dataset_id}"
    try:
        response = self._http.get(path, enable_cache=True, refresh_cache=force_refresh_cache)
        json_content = response.json()
        features_file = None
        qualities_file = None

        if download_features_meta_data:
            features_file = self.download_features_file(dataset_id)
        if download_qualities:
            qualities_file = self.download_qualities_file(dataset_id)

        parquet_file = None
        skip_parquet = (
            os.environ.get(openml.config.OPENML_SKIP_PARQUET_ENV_VAR, "false").casefold()
            == "true"
        )
        download_parquet = "parquet_url" in json_content and not skip_parquet
        if download_parquet and (download_data or download_all_files):
            try:
                parquet_file = self.download_dataset_parquet(
                    json_content,
                    download_all_files=download_all_files,
                )
            except urllib3.exceptions.MaxRetryError:
                parquet_file = None

        arff_file = None
        if parquet_file is None and download_data:
            if download_parquet:
                logger.warning("Failed to download parquet, fallback on ARFF.")
            arff_file = self.download_dataset_arff(json_content)
    except OpenMLServerException as e:
        # if there was an exception
        # check if the user had access to the dataset
        if e.code == NO_ACCESS_GRANTED_ERRCODE:
            raise OpenMLPrivateDatasetError(e.message) from None

        raise e

    return self._create_dataset_from_json(
        json_content,
        features_file=features_file,
        qualities_file=qualities_file,
        arff_file=arff_file,
        parquet_file=parquet_file,
        cache_format=cache_format,
    )

get_features

get_features(dataset_id: int, force_refresh_cache: bool = False) -> dict[int, OpenMLDataFeature]

Get features of a dataset from server.

PARAMETER	DESCRIPTION
dataset_id	ID of the dataset. TYPE: int
force_refresh_cache	Refresh the cache and re-download the features file. TYPE: bool(default=False) DEFAULT: False

RETURNS	DESCRIPTION
dict[int, OpenMLDataFeature]
Dictionary mapping feature index to OpenMLDataFeature.

Source code in openml/_api/resources/dataset.py

def get_features(
    self,
    dataset_id: int,
    force_refresh_cache: bool = False,  # noqa: FBT002
) -> dict[int, OpenMLDataFeature]:
    """Get features of a dataset from server.

    Parameters
    ----------
    dataset_id : int
        ID of the dataset.
    force_refresh_cache : bool (default=False)
        Refresh the cache and re-download the features file.

    Returns
    -------
    dict[int, OpenMLDataFeature]
    Dictionary mapping feature index to OpenMLDataFeature.
    """
    path = f"datasets/features/{dataset_id}"
    json = self._http.get(path, enable_cache=True, refresh_cache=force_refresh_cache).json()

    return self._parse_features_json(json)

get_online_dataset_format

get_online_dataset_format(dataset_id: int) -> str

Get the dataset format for a given dataset id from the OpenML website.

PARAMETER	DESCRIPTION
dataset_id	A dataset id. TYPE: int

RETURNS	DESCRIPTION
str	Dataset format.

Source code in openml/_api/resources/dataset.py

def get_online_dataset_format(self, dataset_id: int) -> str:
    """Get the dataset format for a given dataset id from the OpenML website.

    Parameters
    ----------
    dataset_id : int
        A dataset id.

    Returns
    -------
    str
        Dataset format.
    """
    dataset_json = self._http.get(f"datasets/{dataset_id}").json()
    # build a dict from the json and get the format from the dataset description
    return dataset_json["format"].lower()  # type: ignore

get_qualities

get_qualities(dataset_id: int, force_refresh_cache: bool = False) -> dict[str, float] | None

Get qualities of a dataset from server.

PARAMETER	DESCRIPTION
dataset_id	ID of the dataset. TYPE: int
force_refresh_cache	Refresh the cache and re-download the qualities file. TYPE: bool(default=False) DEFAULT: False

RETURNS	DESCRIPTION
dict[str, float] | None
Dictionary mapping quality name to quality value.

Source code in openml/_api/resources/dataset.py

def get_qualities(
    self,
    dataset_id: int,
    force_refresh_cache: bool = False,  # noqa: FBT002
) -> dict[str, float] | None:
    """Get qualities of a dataset from server.

    Parameters
    ----------
    dataset_id : int
        ID of the dataset.
    force_refresh_cache : bool (default=False)
        Refresh the cache and re-download the qualities file.

    Returns
    -------
    dict[str, float] | None
    Dictionary mapping quality name to quality value.
    """
    path = f"datasets/qualities/{dataset_id!s}"
    try:
        qualities_json = self._http.get(
            path, enable_cache=True, refresh_cache=force_refresh_cache
        ).json()
    except OpenMLServerException as e:
        if e.code == 362 and str(e) == "No qualities found - None":
            logger.warning(f"No qualities found for dataset {dataset_id}")
            return None

        raise e

    qualities = self._parse_qualities_json(qualities_json)
    if not qualities:
        logger.warning(f"No qualities found for dataset {dataset_id}")
        return None
    return qualities

list

list(limit: int, offset: int, *, data_id: list[int] | None = None, **kwargs: Any) -> DataFrame

Perform api call to return a list of all datasets.

PARAMETER	DESCRIPTION
The
ones
display_errors
default
limit	The maximum number of datasets to show. TYPE: int
offset	The number of datasets to skip, starting from the first. TYPE: int
data_id	TYPE: list[int] | None DEFAULT: None
kwargs	Legal filter operators (keys in the dict): tag, status, limit, offset, data_name, data_version, number_instances, number_features, number_classes, number_missing_values. TYPE: dict DEFAULT: {}

RETURNS	DESCRIPTION
datasets	TYPE: dataframe

Source code in openml/_api/resources/dataset.py

def list(
    self,
    limit: int,
    offset: int,
    *,
    data_id: builtins.list[int] | None = None,
    **kwargs: Any,
) -> pd.DataFrame:
    """
    Perform api call to return a list of all datasets.

    Parameters
    ----------
    The arguments that are lists are separated from the single value
    ones which are put into the kwargs.
    display_errors is also separated from the kwargs since it has a
    default value.

    limit : int
        The maximum number of datasets to show.
    offset : int
        The number of datasets to skip, starting from the first.
    data_id: list[int], optional

    kwargs : dict, optional
        Legal filter operators (keys in the dict):
        tag, status, limit, offset, data_name, data_version, number_instances,
        number_features, number_classes, number_missing_values.

    Returns
    -------
    datasets : dataframe
    """
    json: dict[str, Any] = {"pagination": {}}

    if limit is not None:
        json["pagination"]["limit"] = limit
    if offset is not None:
        json["pagination"]["offset"] = offset
    if data_id is not None:
        json["data_id"] = data_id
    if kwargs is not None:
        for operator, value in kwargs.items():
            if value is not None:
                json[operator] = value

    api_call = "datasets/list"
    datasets_list = self._http.post(path=api_call, json=json, use_api_key=False).json()
    # Minimalistic check if the JSON is useful
    assert isinstance(datasets_list, list), type(datasets_list)

    return self._parse_list_json(datasets_list)

list_qualities

list_qualities() -> list[str]

Return list of data qualities available.

The function performs an API call to retrieve the entire list of data qualities that are computed on the datasets uploaded.

RETURNS	DESCRIPTION
list

Source code in openml/_api/resources/dataset.py

def list_qualities(self) -> builtins.list[str]:
    """Return list of data qualities available.

    The function performs an API call to retrieve the entire list of
    data qualities that are computed on the datasets uploaded.

    Returns
    -------
    list
    """
    api_call = "datasets/qualities/list"
    qualities = self._http.get(api_call).json()
    # Minimalistic check if the JSON is useful
    if "data_qualities_list" not in qualities:
        raise ValueError('Error in return JSON, does not contain "data_qualities_list"')

    if not isinstance(qualities["data_qualities_list"]["quality"], list):
        raise TypeError('Error in return JSON, does not contain "quality" as a list')

    return qualities["data_qualities_list"]["quality"]

parse_features_file

parse_features_file(features_file: Path, features_pickle_file: Path | None = None) -> dict[int, OpenMLDataFeature]

Parse features file (json) and store it as a pickle file.

PARAMETER	DESCRIPTION
features_file	Path to features file. TYPE: Path
features_pickle_file	Path to pickle file for features. TYPE: Path DEFAULT: None

RETURNS	DESCRIPTION
dict[int, OpenMLDataFeature]

Source code in openml/_api/resources/dataset.py

def parse_features_file(
    self, features_file: Path, features_pickle_file: Path | None = None
) -> dict[int, OpenMLDataFeature]:
    """
    Parse features file (json) and store it as a pickle file.

    Parameters
    ----------
    features_file : Path
        Path to features file.
    features_pickle_file : Path, optional
        Path to pickle file for features.

    Returns
    -------
    dict[int, OpenMLDataFeature]
    """
    if features_pickle_file is None:
        features_pickle_file = features_file.with_suffix(features_file.suffix + ".pkl")
    if features_file.suffix == ".xml":
        # can fallback to v1 if the file is .xml
        raise NotImplementedError("Unable to Parse .xml from v1")

    with Path(features_file).open("r", encoding="utf8") as fh:
        features_json = json.load(fh)

    features = self._parse_features_json(features_json)

    with features_pickle_file.open("wb") as fh_binary:
        pickle.dump(features, fh_binary)

    return features

parse_qualities_file

parse_qualities_file(qualities_file: Path, qualities_pickle_file: Path | None = None) -> dict[str, float]

Parse qualities file (json) and store it as a pickle file.

PARAMETER	DESCRIPTION
qualities_file	Path to qualities file. TYPE: Path
qualities_pickle_file	Path to pickle file for qualities. TYPE: Path DEFAULT: None

RETURNS	DESCRIPTION
qualities	TYPE: dict[str, float]

Source code in openml/_api/resources/dataset.py

def parse_qualities_file(
    self, qualities_file: Path, qualities_pickle_file: Path | None = None
) -> dict[str, float]:
    """Parse qualities file (json) and store it as a pickle file.

    Parameters
    ----------
    qualities_file : Path
        Path to qualities file.
    qualities_pickle_file : Path, optional
        Path to pickle file for qualities.

    Returns
    -------
    qualities : dict[str, float]
    """
    if qualities_pickle_file is None:
        qualities_pickle_file = qualities_file.with_suffix(qualities_file.suffix + ".pkl")
    if qualities_file.suffix == ".xml":
        # can fallback to v1 if the file is .xml
        raise NotImplementedError("Unable to Parse .xml from v1")

    with Path(qualities_file).open("r", encoding="utf8") as fh:
        qualities_json = json.load(fh)

    qualities = self._parse_qualities_json(qualities_json)

    with qualities_pickle_file.open("wb") as fh_binary:
        pickle.dump(qualities, fh_binary)

    return qualities

status_update

status_update(dataset_id: int, status: Literal['active', 'deactivated']) -> None

Updates the status of a dataset to either 'active' or 'deactivated'. Please see the OpenML API documentation for a description of the status and all legal status transitions: docs.openml.org/concepts/data/#dataset-status

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

Source code in openml/_api/resources/dataset.py

def status_update(self, dataset_id: int, status: Literal["active", "deactivated"]) -> None:
    """
    Updates the status of a dataset to either 'active' or 'deactivated'.
    Please see the OpenML API documentation for a description of the status
    and all legal status transitions:
    https://docs.openml.org/concepts/data/#dataset-status

    Parameters
    ----------
    dataset_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: dict[str, str | int] = {"dataset_id": dataset_id, "status": status}
    result = self._http.post(
        f"datasets/status/update/?api_key={self._http.api_key}", json=data, use_api_key=False
    ).json()
    server_data_id = result["dataset_id"]
    server_status = result["status"]
    if status != server_status or int(dataset_id) != int(server_data_id):
        # This should never happen
        raise ValueError("Data id/status does not match")