Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Main classes

DatasetInfo

class datasets.DatasetInfo

< >

( description: str = <factory> citation: str = <factory> homepage: str = <factory> license: str = <factory> features: typing.Optional[datasets.features.features.Features] = None post_processed: typing.Optional[datasets.info.PostProcessedInfo] = None supervised_keys: typing.Optional[datasets.info.SupervisedKeysData] = None task_templates: typing.Optional[typing.List[datasets.tasks.base.TaskTemplate]] = None builder_name: typing.Optional[str] = None config_name: typing.Optional[str] = None version: typing.Union[str, datasets.utils.version.Version, NoneType] = None splits: typing.Optional[dict] = None download_checksums: typing.Optional[dict] = None download_size: typing.Optional[int] = None post_processing_size: typing.Optional[int] = None dataset_size: typing.Optional[int] = None size_in_bytes: typing.Optional[int] = None )

Parameters

  • description (str) — A description of the dataset.
  • citation (str) — A BibTeX citation of the dataset.
  • homepage (str) — A URL to the official homepage for the dataset.
  • license (str) — The dataset’s license. It can be the name of the license or a paragraph containing the terms of the license.
  • features (Features, optional) — The features used to specify the dataset’s column types.
  • post_processed (PostProcessedInfo, optional) — Information regarding the resources of a possible post-processing of a dataset. For example, it can contain the information of an index.
  • supervised_keys (SupervisedKeysData, optional) — Specifies the input feature and the label for supervised learning if applicable for the dataset (legacy from TFDS).
  • builder_name (str, optional) — The name of the GeneratorBasedBuilder subclass used to create the dataset. Usually matched to the corresponding script name. It is also the snake_case version of the dataset builder class name.
  • config_name (str, optional) — The name of the configuration derived from BuilderConfig
  • version (str or Version, optional) — The version of the dataset.
  • splits (dict, optional) — The mapping between split name and metadata.
  • download_checksums (dict, optional) — The mapping between the URL to download the dataset’s checksums and corresponding metadata.
  • download_size (int, optional) — The size of the files to download to generate the dataset, in bytes.
  • post_processing_size (int, optional) — Size of the dataset in bytes after post-processing, if any.
  • dataset_size (int, optional) — The combined size in bytes of the Arrow tables for all splits.
  • size_in_bytes (int, optional) — The combined size in bytes of all files associated with the dataset (downloaded files + Arrow files).
  • task_templates (List[TaskTemplate], optional) — The task templates to prepare the dataset for during training and evaluation. Each template casts the dataset’s Features to standardized column names and types as detailed in :py:mod:datasets.tasks.
  • **config_kwargs (additional keyword arguments) — Keyword arguments to be passed to the BuilderConfig and used in the DatasetBuilder.

Information about a dataset.

DatasetInfo documents datasets, including its name, version, and features. See the constructor arguments and properties for a full list.

Note: Not all fields are known on construction and may be updated later.

from_directory

< >

( dataset_info_dir: str )

Parameters

  • dataset_info_dir (str) — The directory containing the metadata file. This should be the root directory of a specific dataset version.

Create DatasetInfo from the JSON file in dataset_info_dir.

This function updates all the dynamically generated fields (num_examples, hash, time of creation,…) of the DatasetInfo.

This will overwrite all previous metadata.

Example:

>>> from datasets import DatasetInfo
>>> ds_info = DatasetInfo.from_directory("/path/to/directory/")

write_to_directory

< >

( dataset_info_dir pretty_print = False )

Parameters

  • dataset_info_dir (str) — Destination directory.
  • pretty_print (bool, default False) — If True, the JSON will be pretty-printed with the indent level of 4.

Write DatasetInfo and license (if present) as JSON files to dataset_info_dir.

Example:

>>> from datasets import load_dataset
>>> ds = load_dataset("rotten_tomatoes", split="validation")
>>> ds.info.write_to_directory("/path/to/directory/")

Dataset

The base class Dataset implements a Dataset backed by an Apache Arrow table.

class datasets.Dataset

< >

( arrow_table: Table info: typing.Optional[datasets.info.DatasetInfo] = None split: typing.Optional[datasets.splits.NamedSplit] = None indices_table: typing.Optional[datasets.table.Table] = None fingerprint: typing.Optional[str] = None )

A Dataset backed by an Arrow table.

add_column

< >

( name: str column: typing.Union[list, <built-in function array>] new_fingerprint: str ) Dataset

Parameters

  • name (str) — Column name.
  • column (list or np.array) — Column data to be added.

Returns

Dataset

Add column to Dataset.

New in version 1.7.

Example:

>>> from datasets import load_dataset
>>> ds = load_dataset("rotten_tomatoes", split="validation")
>>> more_text = ds["text"]
>>> ds.add_column(name="text_2", column=more_text)
Dataset({
    features: ['text', 'label', 'text_2'],
    num_rows: 1066
})

add_item

< >

( item: dict new_fingerprint: str ) Dataset

Parameters

  • item (dict) — Item data to be added.

Returns

Dataset

Add item to Dataset.

New in version 1.7.

Example:

>>> from datasets import load_dataset
>>> ds = load_dataset("rotten_tomatoes", split="validation")
>>> new_review = {'label': 0, 'text': 'this movie is the absolute worst thing I have ever seen'}
>>> ds = ds.add_item(new_review)
>>> ds[-1]
{'label': 0, 'text': 'this movie is the absolute worst thing I have ever seen'}

from_file

< >

( filename: str info: typing.Optional[datasets.info.DatasetInfo] = None split: typing.Optional[datasets.splits.NamedSplit] = None indices_filename: typing.Optional[str] = None in_memory: bool = False ) Dataset

Parameters

  • filename (str) — File name of the dataset.
  • info (DatasetInfo, optional) — Dataset information, like description, citation, etc.
  • split (NamedSplit, optional) — Name of the dataset split.
  • indices_filename (str, optional) — File names of the indices.
  • in_memory (bool, default False) — Whether to copy the data in-memory.

Returns

Dataset

Instantiate a Dataset backed by an Arrow table at filename.

from_buffer

< >

( buffer: Buffer info: typing.Optional[datasets.info.DatasetInfo] = None split: typing.Optional[datasets.splits.NamedSplit] = None indices_buffer: typing.Optional[pyarrow.lib.Buffer] = None ) Dataset

Parameters

  • buffer (pyarrow.Buffer) — Arrow buffer.
  • info (DatasetInfo, optional) — Dataset information, like description, citation, etc.
  • split (NamedSplit, optional) — Name of the dataset split.
  • indices_buffer (pyarrow.Buffer, optional) — Indices Arrow buffer.

Returns

Dataset

Instantiate a Dataset backed by an Arrow buffer.

from_pandas

< >

( df: DataFrame features: typing.Optional[datasets.features.features.Features] = None info: typing.Optional[datasets.info.DatasetInfo] = None split: typing.Optional[datasets.splits.NamedSplit] = None preserve_index: typing.Optional[bool] = None ) Dataset

Parameters

  • df (pandas.DataFrame) — Dataframe that contains the dataset.
  • features (Features, optional) — Dataset features.
  • info (DatasetInfo, optional) — Dataset information, like description, citation, etc.
  • split (NamedSplit, optional) — Name of the dataset split.
  • preserve_index (bool, optional) — Whether to store the index as an additional column in the resulting Dataset. The default of None will store the index as a column, except for RangeIndex which is stored as metadata only. Use preserve_index=True to force it to be stored as a column.

Returns

Dataset

Convert pandas.DataFrame to a pyarrow.Table to create a Dataset.

The column types in the resulting Arrow Table are inferred from the dtypes of the pandas.Series in the DataFrame. In the case of non-object Series, the NumPy dtype is translated to its Arrow equivalent. In the case of object, we need to guess the datatype by looking at the Python objects in this Series.

Be aware that Series of the object dtype don’t carry enough information to always lead to a meaningful Arrow type. In the case that we cannot infer a type, e.g. because the DataFrame is of length 0 or the Series only contains None/nan objects, the type is set to null. This behavior can be avoided by constructing explicit features and passing it to this function.

Example:

>>> ds = Dataset.from_pandas(df)

from_dict

< >

( mapping: dict features: typing.Optional[datasets.features.features.Features] = None info: typing.Optional[datasets.info.DatasetInfo] = None split: typing.Optional[datasets.splits.NamedSplit] = None ) Dataset

Parameters

  • mapping (Mapping) — Mapping of strings to Arrays or Python lists.
  • features (Features, optional) — Dataset features.
  • info (DatasetInfo, optional) — Dataset information, like description, citation, etc.
  • split (NamedSplit, optional) — Name of the dataset split.

Returns

Dataset

Convert dict to a pyarrow.Table to create a Dataset.

data

< >

( )

The Apache Arrow table backing the dataset.

Example:

>>> from datasets import load_dataset
>>> ds = load_dataset("rotten_tomatoes", split="validation")
>>> ds.data
MemoryMappedTable
text: string
label: int64
----
text: [["compassionately explores the seemingly irreconcilable situation between conservative christian parents and their estranged gay and lesbian children .","the soundtrack alone is worth the price of admission .","rodriguez does a splendid job of racial profiling hollywood style--casting excellent latin actors of all ages--a trend long overdue .","beneath the film's obvious determination to shock at any cost lies considerable skill and determination , backed by sheer nerve .","bielinsky is a filmmaker of impressive talent .","so beautifully acted and directed , it's clear that washington most certainly has a new career ahead of him if he so chooses .","a visual spectacle full of stunning images and effects .","a gentle and engrossing character study .","it's enough to watch huppert scheming , with her small , intelligent eyes as steady as any noir villain , and to enjoy the perfectly pitched web of tension that chabrol spins .","an engrossing portrait of uncompromising artists trying to create something original against the backdrop of a corporate music industry that only seems to care about the bottom line .",...,"ultimately , jane learns her place as a girl , softens up and loses some of the intensity that made her an interesting character to begin with .","ah-nuld's action hero days might be over .","it's clear why deuces wild , which was shot two years ago , has been gathering dust on mgm's shelf .","feels like nothing quite so much as a middle-aged moviemaker's attempt to surround himself with beautiful , half-naked women .","when the precise nature of matthew's predicament finally comes into sharp focus , the revelation fails to justify the build-up .","this picture is murder by numbers , and as easy to be bored by as your abc's , despite a few whopping shootouts .","hilarious musical comedy though stymied by accents thick as mud .","if you are into splatter movies , then you will probably have a reasonably good time with the salton sea .","a dull , simple-minded and stereotypical tale of drugs , death and mind-numbing indifference on the inner-city streets .","the feature-length stretch . . . strains the show's concept ."]]
label: [[1,1,1,1,1,1,1,1,1,1,...,0,0,0,0,0,0,0,0,0,0]]

cache_files

< >

( )

The cache files containing the Apache Arrow table backing the dataset.

Example:

>>> from datasets import load_dataset
>>> ds = load_dataset("rotten_tomatoes", split="validation")
>>> ds.cache_files
[{'filename': '/root/.cache/huggingface/datasets/rotten_tomatoes_movie_review/default/1.0.0/40d411e45a6ce3484deed7cc15b82a53dad9a72aafd9f86f8f227134bec5ca46/rotten_tomatoes_movie_review-validation.arrow'}]

num_columns

< >

( )

Number of columns in the dataset.

Example:

>>> from datasets import load_dataset
>>> ds = load_dataset("rotten_tomatoes", split="validation")
>>> ds.num_columns
2

num_rows

< >

( )

Number of rows in the dataset (same as Dataset.len()).

Example:

>>> from datasets import load_dataset
>>> ds = load_dataset("rotten_tomatoes", split="validation")
>>> ds.num_rows
1066

column_names

< >

( )

Names of the columns in the dataset.

Example:

>>> from datasets import load_dataset
>>> ds = load_dataset("rotten_tomatoes", split="validation")
>>> ds.column_names
['text', 'label']

shape

< >

( )

Shape of the dataset (number of columns, number of rows).

Example:

>>> from datasets import load_dataset
>>> ds = load_dataset("rotten_tomatoes", split="validation")
>>> ds.shape
(1066, 2)

unique

< >

( column: str ) list

Parameters

Returns

list

List of unique elements in the given column.

Return a list of the unique elements in a column.

This is implemented in the low-level backend and as such, very fast.

Example:

>>> from datasets import load_dataset
>>> ds = load_dataset("rotten_tomatoes", split="validation")
>>> ds.unique('label')
[1, 0]

flatten

< >

( new_fingerprint: typing.Optional[str] = None max_depth = 16 ) Dataset

Parameters

  • new_fingerprint (str, optional) — The new fingerprint of the dataset after transform. If None, the new fingerprint is computed using a hash of the previous fingerprint, and the transform arguments.

Returns

Dataset

A copy of the dataset with flattened columns.

Flatten the table. Each column with a struct type is flattened into one column per struct field. Other columns are left unchanged.

Example:

>>> from datasets import load_dataset
>>> ds = load_dataset("squad", split="train")
>>> ds.features
{'answers': Sequence(feature={'text': Value(dtype='string', id=None), 'answer_start': Value(dtype='int32', id=None)}, length=-1, id=None),
 'context': Value(dtype='string', id=None),
 'id': Value(dtype='string', id=None),
 'question': Value(dtype='string', id=None),
 'title': Value(dtype='string', id=None)}
>>> ds.flatten()
Dataset({
    features: ['id', 'title', 'context', 'question', 'answers.text', 'answers.answer_start'],
    num_rows: 87599
})

cast

< >

( features: Features batch_size: typing.Optional[int] = 10000 keep_in_memory: bool = False load_from_cache_file: bool = True cache_file_name: typing.Optional[str] = None writer_batch_size: typing.Optional[int] = 10000 num_proc: typing.Optional[int] = None ) Dataset

Parameters

  • features (datasets.Features) — New features to cast the dataset to. The name of the fields in the features must match the current column names. The type of the data must also be convertible from one type to the other. For non-trivial conversion, e.g. string <-> ClassLabel you should use map to update the Dataset.
  • batch_size (int, defaults to 1000) — Number of examples per batch provided to cast. batch_size <= 0 or batch_size == None: Provide the full dataset as a single batch to cast.
  • keep_in_memory (bool, default False) — Whether to copy the data in-memory.
  • load_from_cache_file (bool, default True if caching is enabled) — If a cache file storing the current computation from function can be identified, use it instead of recomputing.
  • cache_file_name (str, optional, default None) — Provide the name of a path for the cache file. It is used to store the results of the computation instead of the automatically generated cache file name.
  • writer_batch_size (int, default 1000) — Number of rows per write operation for the cache file writer. This value is a good trade-off between memory usage during the processing, and processing speed. Higher value makes the processing do fewer lookups, lower value consume less temporary memory while running .map().
  • num_proc (int, optional, default None) — Number of processes for multiprocessing. By default it doesn’t use multiprocessing.

Returns

Dataset

A copy of the dataset with casted features.

Cast the dataset to a new set of features.

Example:

>>> from datasets import load_dataset, ClassLabel, Value
>>> ds = load_dataset("rotten_tomatoes", split="validation")
>>> ds.features
{'label': ClassLabel(num_classes=2, names=['neg', 'pos'], id=None),
 'text': Value(dtype='string', id=None)}
>>> new_features = ds.features.copy()
>>> new_features['label'] = ClassLabel(names=['bad', 'good'])
>>> new_features['text'] = Value('large_string')
>>> ds = ds.cast(new_features)
>>> ds.features
{'label': ClassLabel(num_classes=2, names=['bad', 'good'], id=None),
 'text': Value(dtype='large_string', id=None)}

cast_column

< >

( column: str feature: typing.Union[dict, list, tuple, datasets.features.features.Value, datasets.features.features.ClassLabel, datasets.features.translation.Translation, datasets.features.translation.TranslationVariableLanguages, datasets.features.features.Sequence, datasets.features.features.Array2D, datasets.features.features.Array3D, datasets.features.features.Array4D, datasets.features.features.Array5D, datasets.features.audio.Audio, datasets.features.image.Image] new_fingerprint: typing.Optional[str] = None ) Dataset

Parameters

  • column (str) — Column name.
  • feature (FeatureType) — Target feature.
  • new_fingerprint (str, optional) — The new fingerprint of the dataset after transform. If None, the new fingerprint is computed using a hash of the previous fingerprint, and the transform arguments.

Returns

Dataset

Cast column to feature for decoding.

Example:

>>> from datasets import load_dataset
>>> ds = load_dataset("rotten_tomatoes", split="validation")
>>> ds.features
{'label': ClassLabel(num_classes=2, names=['neg', 'pos'], id=None),
 'text': Value(dtype='string', id=None)}
>>> ds = ds.cast_column('label', ClassLabel(names=['bad', 'good']))
>>> ds.features
{'label': ClassLabel(num_classes=2, names=['bad', 'good'], id=None),
 'text': Value(dtype='string', id=None)}

remove_columns

< >

( column_names: typing.Union[str, typing.List[str]] new_fingerprint: typing.Optional[str] = None ) Dataset

Parameters

  • column_names (Union[str, List[str]]) — Name of the column(s) to remove.
  • new_fingerprint (str, optional) — The new fingerprint of the dataset after transform. If None, the new fingerprint is computed using a hash of the previous fingerprint, and the transform arguments.

Returns

Dataset

A copy of the dataset object without the columns to remove.

Remove one or several column(s) in the dataset and the features associated to them.

You can also remove a column using Dataset.map() with remove_columns but the present method is in-place (doesn’t copy the data to a new dataset) and is thus faster.

Example:

>>> from datasets import load_dataset
>>> ds = load_dataset("rotten_tomatoes", split="validation")
>>> ds.remove_columns('label')
Dataset({
    features: ['text'],
    num_rows: 1066
})

rename_column

< >

( original_column_name: str new_column_name: str new_fingerprint: typing.Optional[str] = None ) Dataset

Parameters

  • original_column_name (str) — Name of the column to rename.
  • new_column_name (str) — New name for the column.
  • new_fingerprint (str, optional) — The new fingerprint of the dataset after transform. If None, the new fingerprint is computed using a hash of the previous fingerprint, and the transform arguments.

Returns

Dataset

A copy of the dataset with a renamed column.

Rename a column in the dataset, and move the features associated to the original column under the new column name.

Example:

>>> from datasets import load_dataset
>>> ds = load_dataset("rotten_tomatoes", split="validation")
>>> ds.rename_column('label', 'label_new')
Dataset({
    features: ['text', 'label_new'],
    num_rows: 1066
})

rename_columns

< >

( column_mapping: typing.Dict[str, str] new_fingerprint: typing.Optional[str] = None ) Dataset

Parameters

  • column_mapping (Dict[str, str]) — A mapping of columns to rename to their new names
  • new_fingerprint (str, optional) — The new fingerprint of the dataset after transform. If None, the new fingerprint is computed using a hash of the previous fingerprint, and the transform arguments.

Returns

Dataset

A copy of the dataset with renamed columns

Rename several columns in the dataset, and move the features associated to the original columns under the new column names.

Example:

>>> from datasets import load_dataset
>>> ds = load_dataset("rotten_tomatoes", split="validation")
>>> ds.rename_columns({'text': 'text_new', 'label': 'label_new'})
Dataset({
    features: ['text_new', 'label_new'],
    num_rows: 1066
})

class_encode_column

< >

( column: str include_nulls: bool = False )

Parameters

  • column (str) — The name of the column to cast (list all the column names with datasets.Dataset.column_names)
  • include_nulls (bool, default False) — Whether to include null values in the class labels. If True, the null values will be encoded as the “None” class label.

    New in version 1.14.2

Casts the given column as :obj:datasets.features.ClassLabel and updates the table.

Example:

>>> from datasets import load_dataset
>>> ds = load_dataset("boolq", split="validation")
>>> ds.features
{'answer': Value(dtype='bool', id=None),
 'passage': Value(dtype='string', id=None),
 'question': Value(dtype='string', id=None)}
>>> ds = ds.class_encode_column('answer')
>>> ds.features
{'answer': ClassLabel(num_classes=2, names=['False', 'True'], id=None),
 'passage': Value(dtype='string', id=None),
 'question': Value(dtype='string', id=None)}

__len__

< >

( )

Number of rows in the dataset.

Example:

>>> from datasets import load_dataset
>>> ds = load_dataset("rotten_tomatoes", split="validation")
>>> ds.__len__
<bound method Dataset.__len__ of Dataset({
    features: ['text', 'label'],
    num_rows: 1066
})>

__iter__

< >

( )

Iterate through the examples.

If a formatting is set with Dataset.set_format() rows will be returned with the selected format.

formatted_as

< >

( type: typing.Optional[str] = None columns: typing.Optional[typing.List] = None output_all_columns: bool = False **format_kwargs )

Parameters

  • type (str, optional) — output type selected in [None, 'numpy', 'torch', 'tensorflow', 'pandas', 'arrow'] None means __getitem__ returns python objects (default)
  • columns (List[str], optional) — columns to format in the output None means __getitem__ returns all columns (default)
  • output_all_columns (bool, default to False) — keep un-formatted columns as well in the output (as python objects)
  • **format_kwargs (additional keyword arguments) — keywords arguments passed to the convert function like np.array, torch.tensor or tensorflow.ragged.constant.

To be used in a with statement. Set __getitem__ return format (type and columns).

set_format

< >

( type: typing.Optional[str] = None columns: typing.Optional[typing.List] = None output_all_columns: bool = False **format_kwargs )

Parameters

  • type (str, optional) — Either output type selected in [None, ‘numpy’, ‘torch’, ‘tensorflow’, ‘pandas’, ‘arrow’]. None means getitem returns python objects (default)
  • columns (List[str], optional) — columns to format in the output. None means getitem returns all columns (default).
  • output_all_columns (bool, default to False) — keep un-formatted columns as well in the output (as python objects)
  • **format_kwargs (additional keyword arguments) — keywords arguments passed to the convert function like np.array, torch.tensor or tensorflow.ragged.constant.

Set getitem return format (type and columns). The data formatting is applied on-the-fly. The format type (for example “numpy”) is used to format batches when using getitem. It’s also possible to use custom transforms for formatting using datasets.Dataset.set_transform().

It is possible to call map after calling set_format. Since map may add new columns, then the list of formatted columns gets updated. In this case, if you apply map on a dataset to add a new column, then this column will be formatted:

new formatted columns = (all columns - previously unformatted columns)

Example:

>>> from datasets import load_dataset
>>> from transformers import AutoTokenizer
>>> ds = load_dataset("rotten_tomatoes", split="validation")
>>> tokenizer = AutoTokenizer.from_pretrained("bert-base-cased")
>>> ds = ds.map(lambda x: tokenizer(x['text'], truncation=True, padding=True), batched=True)
>>> ds.set_format(type='numpy', columns=['text', 'label'])
>>> ds.format
{'columns': ['input_ids', 'token_type_ids', 'attention_mask', 'label'],
 'format_kwargs': {},
 'output_all_columns': False,
 'type': 'numpy'}

set_transform

< >

( transform: typing.Optional[typing.Callable] columns: typing.Optional[typing.List] = None output_all_columns: bool = False )

Parameters

  • transform (Callable, optional) — user-defined formatting transform, replaces the format defined by datasets.Dataset.set_format() A formatting function is a callable that takes a batch (as a dict) as input and returns a batch. This function is applied right before returning the objects in getitem.
  • columns (List[str], optional) — columns to format in the output If specified, then the input batch of the transform only contains those columns.
  • output_all_columns (bool, default to False) — keep un-formatted columns as well in the output (as python objects) If set to True, then the other un-formatted columns are kept with the output of the transform.

Set getitem return format using this transform. The transform is applied on-the-fly on batches when getitem is called. As datasets.Dataset.set_format(), this can be reset using datasets.Dataset.reset_format()

Example:

>>> from datasets import load_dataset
>>> from transformers import AutoTokenizer
>>> ds = load_dataset("rotten_tomatoes", split="validation")
>>> tokenizer = AutoTokenizer.from_pretrained('bert-base-uncased')
>>> def encode(batch):
...     return tokenizer(batch['text'], padding=True, truncation=True, return_tensors='pt')
>>> ds.set_transform(encode)
>>> ds[0]
{'attention_mask': tensor([1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
 1, 1]),
 'input_ids': tensor([  101, 29353,  2135, 15102,  1996,  9428, 20868,  2890,  8663,  6895,
         20470,  2571,  3663,  2090,  4603,  3017,  3008,  1998,  2037, 24211,
         5637,  1998, 11690,  2336,  1012,   102]),
 'token_type_ids': tensor([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
         0, 0])}

reset_format

< >

( )

Reset getitem return format to python objects and all columns.

Same as self.set_format()

Example:

>>> from datasets import load_dataset
>>> from transformers import AutoTokenizer
>>> ds = load_dataset("rotten_tomatoes", split="validation")
>>> tokenizer = AutoTokenizer.from_pretrained("bert-base-cased")
>>> ds = ds.map(lambda x: tokenizer(x['text'], truncation=True, padding=True), batched=True)
>>> ds.set_format(type='numpy', columns=['input_ids', 'token_type_ids', 'attention_mask', 'label'])
>>> ds.format
{'columns': ['input_ids', 'token_type_ids', 'attention_mask', 'label'],
 'format_kwargs': {},
 'output_all_columns': False,
 'type': 'numpy'}
>>> ds.reset_format()
>>> ds.format
{'columns': ['text', 'label', 'input_ids', 'token_type_ids', 'attention_mask'],
 'format_kwargs': {},
 'output_all_columns': False,
 'type': None}

with_format

< >

( type: typing.Optional[str] = None columns: typing.Optional[typing.List] = None output_all_columns: bool = False **format_kwargs )

Parameters

  • type (str, optional) — Either output type selected in [None, ‘numpy’, ‘torch’, ‘tensorflow’, ‘pandas’, ‘arrow’]. None means getitem returns python objects (default)
  • columns (List[str], optional) — columns to format in the output None means getitem returns all columns (default)
  • output_all_columns (bool, default to False) — keep un-formatted columns as well in the output (as python objects)
  • **format_kwargs (additional keyword arguments) — keywords arguments passed to the convert function like np.array, torch.tensor or tensorflow.ragged.constant.

Set getitem return format (type and columns). The data formatting is applied on-the-fly. The format type (for example “numpy”) is used to format batches when using getitem.

It’s also possible to use custom transforms for formatting using datasets.Dataset.with_transform().

Contrary to datasets.Dataset.set_format(), with_format returns a new Dataset object.

Example:

>>> from datasets import load_dataset
>>> from transformers import AutoTokenizer
>>> ds = load_dataset("rotten_tomatoes", split="validation")
>>> tokenizer = AutoTokenizer.from_pretrained("bert-base-cased")
>>> ds = ds.map(lambda x: tokenizer(x['text'], truncation=True, padding=True), batched=True)
>>> ds.format
{'columns': ['text', 'label', 'input_ids', 'token_type_ids', 'attention_mask'],
 'format_kwargs': {},
 'output_all_columns': False,
 'type': None}
>>> ds = ds.with_format(type='tensorflow', columns=['input_ids', 'token_type_ids', 'attention_mask', 'label'])
>>> ds.format
{'columns': ['input_ids', 'token_type_ids', 'attention_mask', 'label'],
 'format_kwargs': {},
 'output_all_columns': False,
 'type': 'tensorflow'}

with_transform

< >

( transform: typing.Optional[typing.Callable] columns: typing.Optional[typing.List] = None output_all_columns: bool = False )

Parameters

  • transform (Callable, optional) — user-defined formatting transform, replaces the format defined by datasets.Dataset.set_format() A formatting function is a callable that takes a batch (as a dict) as input and returns a batch. This function is applied right before returning the objects in getitem.
  • columns (List[str], optional) — columns to format in the output If specified, then the input batch of the transform only contains those columns.
  • output_all_columns (bool, default to False) — keep un-formatted columns as well in the output (as python objects) If set to True, then the other un-formatted columns are kept with the output of the transform.

Set getitem return format using this transform. The transform is applied on-the-fly on batches when getitem is called.

As datasets.Dataset.set_format(), this can be reset using datasets.Dataset.reset_format().

Contrary to datasets.Dataset.set_transform(), with_transform returns a new Dataset object.

Example:

>>> from datasets import load_dataset
>>> from transformers import AutoTokenizer
>>> ds = load_dataset("rotten_tomatoes", split="validation")
>>> tokenizer = AutoTokenizer.from_pretrained("bert-base-cased")
>>> def encode(example):
...     return tokenizer(example["text"], padding=True, truncation=True, return_tensors='pt')
>>> ds = ds.with_transform(encode)
>>> ds[0]
{'attention_mask': tensor([1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
 1, 1, 1, 1, 1]),
 'input_ids': tensor([  101, 18027, 16310, 16001,  1103,  9321,   178, 11604,  7235,  6617,
         1742,  2165,  2820,  1206,  6588, 22572, 12937,  1811,  2153,  1105,
         1147, 12890, 19587,  6463,  1105, 15026,  1482,   119,   102]),
 'token_type_ids': tensor([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
         0, 0, 0, 0, 0])}

__getitem__

< >

( key )

Can be used to index columns (by string names) or rows (by integer index or iterable of indices or bools).

cleanup_cache_files

< >

( ) int

Returns

int

Number of removed files.

Clean up all cache files in the dataset cache directory, excepted the currently used cache file if there is one.

Be careful when running this command that no other process is currently using other cache files.

Example:

>>> from datasets import load_dataset
>>> ds = load_dataset("rotten_tomatoes", split="validation")
>>> ds.cleanup_cache_files()
10

map

< >

( function: typing.Optional[typing.Callable] = None with_indices: bool = False with_rank: bool = False input_columns: typing.Union[str, typing.List[str], NoneType] = None batched: bool = False batch_size: typing.Optional[int] = 1000 drop_last_batch: bool = False remove_columns: typing.Union[str, typing.List[str], NoneType] = None keep_in_memory: bool = False load_from_cache_file: bool = None cache_file_name: typing.Optional[str] = None writer_batch_size: typing.Optional[int] = 1000 features: typing.Optional[datasets.features.features.Features] = None disable_nullable: bool = False fn_kwargs: typing.Optional[dict] = None num_proc: typing.Optional[int] = None suffix_template: str = '_{rank:05d}_of_{num_proc:05d}' new_fingerprint: typing.Optional[str] = None desc: typing.Optional[str] = None )

Parameters

  • function (Callable) — Function with one of the following signatures:

    • function(example: Dict[str, Any]) -> Dict[str, Any] if batched=False and with_indices=False and with_rank=False
    • function(example: Dict[str, Any], extra_args) -> Dict[str, Any] if batched=False and with_indices=True and/or with_rank=True* (one extra arg for each)
    • function(batch: Dict[str, List]) -> Dict[str, List] if batched=True and with_indices=False and with_rank=False
    • function(batch: Dict[str, List], extra_args) -> Dict[str, List] if batched=True and with_indices=True and/or with_rank=True* (one extra arg for each)

    For advanced usage, the function can also return a pyarrow.Table. Moreover if your function returns nothing (None), then map will run your function and return the dataset unchanged. If no function is provided, default to identity function: lambda x: x.

  • with_indices (bool, default False) — Provide example indices to function. Note that in this case the signature of function should be def function(example, idx[, rank]): ….
  • with_rank (bool, default False) — Provide process rank to function. Note that in this case the signature of function should be def function(example[, idx], rank): ….
  • input_columns (Optional[Union[str, List[str]]], default None) — The columns to be passed into function as positional arguments. If None, a dict mapping to all formatted columns is passed as one argument.
  • batched (bool, default False) — Provide batch of examples to function.
  • batch_size (int, optional, default 1000) — Number of examples per batch provided to function if batched=True batch_size <= 0 or batch_size == None: Provide the full dataset as a single batch to function.
  • drop_last_batch (bool, default False) — Whether a last batch smaller than the batch_size should be dropped instead of being processed by the function.
  • remove_columns (Optional[Union[str, List[str]]], default None) — Remove a selection of columns while doing the mapping. Columns will be removed before updating the examples with the output of function, i.e. if function is adding columns with names in remove_columns, these columns will be kept.
  • keep_in_memory (bool, default False) — Keep the dataset in memory instead of writing it to a cache file.
  • load_from_cache_file (bool, default True if caching is enabled) — If a cache file storing the current computation from function can be identified, use it instead of recomputing.
  • cache_file_name (str, optional, default None) — Provide the name of a path for the cache file. It is used to store the results of the computation instead of the automatically generated cache file name.
  • writer_batch_size (int, default 1000) — Number of rows per write operation for the cache file writer. This value is a good trade-off between memory usage during the processing, and processing speed. Higher value makes the processing do fewer lookups, lower value consume less temporary memory while running .map().
  • features (Optional[datasets.Features], default None) — Use a specific Features to store the cache file instead of the automatically generated one.
  • disable_nullable (bool, default False) — Disallow null values in the table.
  • fn_kwargs (Dict, optional, default None) — Keyword arguments to be passed to function.
  • num_proc (int, optional, default None) — Max number of processes when generating cache. Already cached shards are loaded sequentially
  • suffix_template (str) — If cachefile_name is specified, then this suffix will be added at the end of the base name of each: defaults to ”{rank:05d}of{num_proc:05d}“. For example, if cache_file_name is “processed.arrow”, then for rank=1 and num_proc=4, the resulting file would be “processed_00001_of_00004.arrow” for the default suffix.
  • new_fingerprint (str, optional, default None) — the new fingerprint of the dataset after transform. If None, the new fingerprint is computed using a hash of the previous fingerprint, and the transform arguments.
  • desc (str, optional, defaults to None) — Meaningful description to be displayed alongside with the progress bar while mapping examples.

Apply a function to all the examples in the table (individually or in batches) and update the table. If your function returns a column that already exists, then it overwrites it.

You can specify whether the function should be batched or not with the batched parameter:

  • If batched is False, then the function takes 1 example in and should return 1 example. An example is a dictionary, e.g. {“text”: “Hello there !“}
  • If batched is True and batch_size is 1, then the function takes a batch of 1 example as input and can return a batch with 1 or more examples. A batch is a dictionary, e.g. a batch of 1 example is {“text”: [“Hello there !”]}
  • If batched is True and batch_size is n > 1, then the function takes a batch of n examples as input and can return a batch with n examples, or with an arbitrary number of examples. Note that the last batch may have less than n examples. A batch is a dictionary, e.g. a batch of n examples is {“text”: [“Hello there !”] * n}

Example:

>>> from datasets import load_dataset
>>> ds = load_dataset("rotten_tomatoes", split="validation")
>>> def add_prefix(example):
...     example["text"] = "Review: " + example["text"]
...     return example
>>> ds = ds.map(add_prefix)
>>> ds[0:3]["text"]
['Review: compassionately explores the seemingly irreconcilable situation between conservative christian parents and their estranged gay and lesbian children .',
 'Review: the soundtrack alone is worth the price of admission .',
 'Review: rodriguez does a splendid job of racial profiling hollywood style--casting excellent latin actors of all ages--a trend long overdue .']

# process a batch of examples
>>> ds = ds.map(lambda example: tokenizer(example["text"]), batched=True)
# set number of processors
>>> ds = ds.map(add_prefix, num_proc=4)

filter

< >

( function: typing.Optional[typing.Callable] = None with_indices = False input_columns: typing.Union[str, typing.List[str], NoneType] = None batched: bool = False batch_size: typing.Optional[int] = 1000 keep_in_memory: bool = False load_from_cache_file: bool = True cache_file_name: typing.Optional[str] = None writer_batch_size: typing.Optional[int] = 1000 fn_kwargs: typing.Optional[dict] = None num_proc: typing.Optional[int] = None suffix_template: str = '_{rank:05d}_of_{num_proc:05d}' new_fingerprint: typing.Optional[str] = None desc: typing.Optional[str] = None )

Parameters

  • function (Callable) — Callable with one of the following signatures:

    • function(example: Dict[str, Any]) -> bool if with_indices=False, batched=False
    • function(example: Dict[str, Any], indices: int) -> bool if with_indices=True, batched=False
    • function(example: Dict[str, List]) -> List[bool] if with_indices=False, batched=True
    • function(example: Dict[str, List], indices: List[int]) -> List[bool] if with_indices=True, batched=True

    If no function is provided, defaults to an always True function: lambda x: True.

  • with_indices (bool, default False) — Provide example indices to function. Note that in this case the signature of function should be def function(example, idx): ….
  • input_columns (str or List[str], optional) — The columns to be passed into function as positional arguments. If None, a dict mapping to all formatted columns is passed as one argument.
  • batched (bool, defaults to False) — Provide batch of examples to function
  • batch_size (int, optional, default 1000) — Number of examples per batch provided to function if batched = True. If batched = False, one example per batch is passed to function. If batch_size <= 0 or batch_size == None: provide the full dataset as a single batch to function
  • keep_in_memory (bool, default False) — Keep the dataset in memory instead of writing it to a cache file.
  • load_from_cache_file (bool, default True) — If a cache file storing the current computation from function can be identified, use it instead of recomputing.
  • cache_file_name (str, optional) — Provide the name of a path for the cache file. It is used to store the results of the computation instead of the automatically generated cache file name.
  • writer_batch_size (int, default 1000) — Number of rows per write operation for the cache file writer. This value is a good trade-off between memory usage during the processing, and processing speed. Higher value makes the processing do fewer lookups, lower value consume less temporary memory while running .map().
  • fn_kwargs (dict, optional) — Keyword arguments to be passed to function
  • num_proc (int, optional) — Number of processes for multiprocessing. By default it doesn’t use multiprocessing.
  • suffix_template (str) — If cache_file_name is specified, then this suffix will be added at the end of the base name of each. For example, if cache_file_name is “processed.arrow”, then for rank = 1 and num_proc = 4, the resulting file would be “processed_00001_of_00004.arrow” for the default suffix (default {rank:05d}_of{num_proc:05d})
  • new_fingerprint (str, optional) — The new fingerprint of the dataset after transform. If None, the new fingerprint is computed using a hash of the previous fingerprint, and the transform arguments.
  • desc (str, optional, defaults to None) — Meaningful description to be displayed alongside with the progress bar while filtering examples.

Apply a filter function to all the elements in the table in batches and update the table so that the dataset only includes examples according to the filter function.

Example:

>>> from datasets import load_dataset
>>> ds = load_dataset("rotten_tomatoes", split="validation")
>>> ds.filter(lambda x: x["label"] == 1)
Dataset({
    features: ['text', 'label'],
    num_rows: 533
})

select

< >

( indices: typing.Iterable keep_in_memory: bool = False indices_cache_file_name: typing.Optional[str] = None writer_batch_size: typing.Optional[int] = 1000 new_fingerprint: typing.Optional[str] = None )

Parameters

  • indices (range, list, iterable, ndarray or Series) — Range, list or 1D-array of integer indices for indexing. If the indices correspond to a contiguous range, the Arrow table is simply sliced. However passing a list of indices that are not contiguous creates indices mapping, which is much less efficient, but still faster than recreating an Arrow table made of the requested rows.
  • keep_in_memory (bool, default False) — Keep the indices mapping in memory instead of writing it to a cache file.
  • indices_cache_file_name (str, optional, default None) — Provide the name of a path for the cache file. It is used to store the indices mapping instead of the automatically generated cache file name.
  • writer_batch_size (int, default 1000) — Number of rows per write operation for the cache file writer. This value is a good trade-off between memory usage during the processing, and processing speed. Higher value makes the processing do fewer lookups, lower value consume less temporary memory while running .map().
  • new_fingerprint (str, optional, default None) — the new fingerprint of the dataset after transform. If None, the new fingerprint is computed using a hash of the previous fingerprint, and the transform arguments

Create a new dataset with rows selected following the list/array of indices.

Example:

>>> from datasets import load_dataset
>>> ds = load_dataset("rotten_tomatoes", split="validation")
>>> ds.select(range(4))
Dataset({
    features: ['text', 'label'],
    num_rows: 4
})

sort

< >

( column: str reverse: bool = False kind: str = None null_placement: str = 'last' keep_in_memory: bool = False load_from_cache_file: bool = True indices_cache_file_name: typing.Optional[str] = None writer_batch_size: typing.Optional[int] = 1000 new_fingerprint: typing.Optional[str] = None )

Parameters

  • column (str) — column name to sort by.
  • reverse (bool, default False) — If True, sort by descending order rather then ascending.
  • kind (str, optional) — Pandas algorithm for sorting selected in {‘quicksort’, ‘mergesort’, ‘heapsort’, ‘stable’}, The default is ‘quicksort’. Note that both ‘stable’ and ‘mergesort’ use timsort under the covers and, in general, the actual implementation will vary with data type. The ‘mergesort’ option is retained for backwards compatibility.
  • null_placement (str, default last) — Put None values at the beginning if ‘first‘; ‘last‘ puts None values at the end.

    New in version 1.14.2

  • keep_in_memory (bool, default False) — Keep the sorted indices in memory instead of writing it to a cache file.
  • load_from_cache_file (bool, default True) — If a cache file storing the sorted indices can be identified, use it instead of recomputing.
  • indices_cache_file_name (str, optional, default None) — Provide the name of a path for the cache file. It is used to store the sorted indices instead of the automatically generated cache file name.
  • writer_batch_size (int, default 1000) — Number of rows per write operation for the cache file writer. Higher value gives smaller cache files, lower value consume less temporary memory.
  • new_fingerprint (str, optional, default None) — the new fingerprint of the dataset after transform. If None, the new fingerprint is computed using a hash of the previous fingerprint, and the transform arguments

Create a new dataset sorted according to a column.

Currently sorting according to a column name uses pandas sorting algorithm under the hood. The column should thus be a pandas compatible type (in particular not a nested type). This also means that the column used for sorting is fully loaded in memory (which should be fine in most cases).

Example:

>>> from datasets import load_dataset
>>> ds = load_dataset("rotten_tomatoes", split="validation")
>>> ds['label'][:10]
[1, 1, 1, 1, 1, 1, 1, 1, 1, 1]
>>> sorted_ds = ds.sort('label')
>>> sorted_ds['label'][:10]
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0]

shuffle

< >

( seed: typing.Optional[int] = None generator: typing.Optional[numpy.random._generator.Generator] = None keep_in_memory: bool = False load_from_cache_file: bool = True indices_cache_file_name: typing.Optional[str] = None writer_batch_size: typing.Optional[int] = 1000 new_fingerprint: typing.Optional[str] = None )

Parameters

  • seed (int, optional) — A seed to initialize the default BitGenerator if generator=None. If None, then fresh, unpredictable entropy will be pulled from the OS. If an int or array_like[ints] is passed, then it will be passed to SeedSequence to derive the initial BitGenerator state.
  • generator (numpy.random.Generator, optional) — Numpy random Generator to use to compute the permutation of the dataset rows. If generator=None (default), uses np.random.default_rng (the default BitGenerator (PCG64) of NumPy).
  • keep_in_memory (bool, default False) — Keep the shuffled indices in memory instead of writing it to a cache file.
  • load_from_cache_file (bool, default True) — If a cache file storing the shuffled indices can be identified, use it instead of recomputing.
  • indices_cache_file_name (str, optional) — Provide the name of a path for the cache file. It is used to store the shuffled indices instead of the automatically generated cache file name.
  • writer_batch_size (int, default 1000) — Number of rows per write operation for the cache file writer. This value is a good trade-off between memory usage during the processing, and processing speed. Higher value makes the processing do fewer lookups, lower value consume less temporary memory while running .map().
  • new_fingerprint (str, optional, default None) — the new fingerprint of the dataset after transform. If None, the new fingerprint is computed using a hash of the previous fingerprint, and the transform arguments

Create a new Dataset where the rows are shuffled.

Currently shuffling uses numpy random generators. You can either supply a NumPy BitGenerator to use, or a seed to initiate NumPy’s default random generator (PCG64).

Example:

>>> from datasets import load_dataset
>>> ds = load_dataset("rotten_tomatoes", split="validation")
>>> ds['label'][:10]
[1, 1, 1, 1, 1, 1, 1, 1, 1, 1]

# set a seed
>>> shuffled_ds = ds.shuffle(seed=42)
>>> shuffled_ds['label'][:10]
[1, 0, 1, 1, 0, 0, 0, 0, 0, 0]

train_test_split

< >

( test_size: typing.Union[float, int, NoneType] = None train_size: typing.Union[float, int, NoneType] = None shuffle: bool = True stratify_by_column: typing.Optional[str] = None seed: typing.Optional[int] = None generator: typing.Optional[numpy.random._generator.Generator] = None keep_in_memory: bool = False load_from_cache_file: bool = True train_indices_cache_file_name: typing.Optional[str] = None test_indices_cache_file_name: typing.Optional[str] = None writer_batch_size: typing.Optional[int] = 1000 train_new_fingerprint: typing.Optional[str] = None test_new_fingerprint: typing.Optional[str] = None )

Parameters

  • test_size (numpy.random.Generator, optional) — Size of the test split If float, should be between 0.0 and 1.0 and represent the proportion of the dataset to include in the test split. If int, represents the absolute number of test samples. If None, the value is set to the complement of the train size. If train_size is also None, it will be set to 0.25.
  • train_size (numpy.random.Generator, optional) — Size of the train split If float, should be between 0.0 and 1.0 and represent the proportion of the dataset to include in the train split. If int, represents the absolute number of train samples. If None, the value is automatically set to the complement of the test size.
  • shuffle (bool, optional, default True) — Whether or not to shuffle the data before splitting.
  • stratify_by_column (str, optional, default None) — The column name of labels to be used to perform stratified split of data.
  • seed (int, optional) — A seed to initialize the default BitGenerator if generator=None. If None, then fresh, unpredictable entropy will be pulled from the OS. If an int or array_like[ints] is passed, then it will be passed to SeedSequence to derive the initial BitGenerator state.
  • generator (numpy.random.Generator, optional) — Numpy random Generator to use to compute the permutation of the dataset rows. If generator=None (default), uses np.random.default_rng (the default BitGenerator (PCG64) of NumPy).
  • keep_in_memory (bool, default False) — Keep the splits indices in memory instead of writing it to a cache file.
  • load_from_cache_file (bool, default True) — If a cache file storing the splits indices can be identified, use it instead of recomputing.
  • train_cache_file_name (str, optional) — Provide the name of a path for the cache file. It is used to store the train split indices instead of the automatically generated cache file name.
  • test_cache_file_name (str, optional) — Provide the name of a path for the cache file. It is used to store the test split indices instead of the automatically generated cache file name.
  • writer_batch_size (int, default 1000) — Number of rows per write operation for the cache file writer. This value is a good trade-off between memory usage during the processing, and processing speed. Higher value makes the processing do fewer lookups, lower value consume less temporary memory while running .map().
  • train_new_fingerprint (str, optional, defaults to None) — the new fingerprint of the train set after transform. If None, the new fingerprint is computed using a hash of the previous fingerprint, and the transform arguments
  • test_new_fingerprint (str, optional, defaults to None) — the new fingerprint of the test set after transform. If None, the new fingerprint is computed using a hash of the previous fingerprint, and the transform arguments

Return a dictionary (datasets.DatasetDict) with two random train and test subsets (train and test Dataset splits). Splits are created from the dataset according to test_size, train_size and shuffle.

This method is similar to scikit-learn train_test_split with the omission of the stratified options.

Example:

>>> from datasets import load_dataset
>>> ds = load_dataset("rotten_tomatoes", split="validation")
>>> ds = ds.train_test_split(test_size=0.2, shuffle=True)
DatasetDict({
    train: Dataset({
        features: ['text', 'label'],
        num_rows: 852
    })
    test: Dataset({
        features: ['text', 'label'],
        num_rows: 214
    })
})

# set a seed
>>> ds = ds.train_test_split(test_size=0.2, seed=42)

# stratified split
>>> ds = load_dataset("imdb",split="train")
Dataset({
    features: ['text', 'label'],
    num_rows: 25000
})
>>> ds = ds.train_test_split(test_size=0.2, stratify_by_column="label")
DatasetDict({
    train: Dataset({
        features: ['text', 'label'],
        num_rows: 20000
    })
    test: Dataset({
        features: ['text', 'label'],
        num_rows: 5000
    })
})

shard

< >

( num_shards: int index: int contiguous: bool = False keep_in_memory: bool = False indices_cache_file_name: typing.Optional[str] = None writer_batch_size: typing.Optional[int] = 1000 )

Parameters

  • num_shards (int) — How many shards to split the dataset into.
  • index (int) — Which shard to select and return. contiguous — (bool, default False): Whether to select contiguous blocks of indices for shards.
  • keep_in_memory (bool, default False) — Keep the dataset in memory instead of writing it to a cache file.
  • load_from_cache_file (bool, default True) — If a cache file storing the current computation from function can be identified, use it instead of recomputing.
  • indices_cache_file_name (str, optional) — Provide the name of a path for the cache file. It is used to store the indices of each shard instead of the automatically generated cache file name.
  • writer_batch_size (int, default 1000) — Number of rows per write operation for the cache file writer. This value is a good trade-off between memory usage during the processing, and processing speed. Higher value makes the processing do fewer lookups, lower value consume less temporary memory while running .map().

Return the index-nth shard from dataset split into num_shards pieces.

This shards deterministically. dset.shard(n, i) will contain all elements of dset whose index mod n = i.

dset.shard(n, i, contiguous=True) will instead split dset into contiguous chunks, so it can be easily concatenated back together after processing. If n % i == l, then the first l shards will have length (n // i) + 1, and the remaining shards will have length (n // i). datasets.concatenate([dset.shard(n, i, contiguous=True) for i in range(n)]) will return a dataset with the same order as the original.

Be sure to shard before using any randomizing operator (such as shuffle). It is best if the shard operator is used early in the dataset pipeline.

Example:

>>> from datasets import load_dataset
>>> ds = load_dataset("rotten_tomatoes", split="validation")
>>> ds
Dataset({
    features: ['text', 'label'],
    num_rows: 1066
})
>>> ds.shard(num_shards=2, index=0)
Dataset({
    features: ['text', 'label'],
    num_rows: 533
})

to_tf_dataset

< >

( batch_size: int columns: typing.Union[str, typing.List[str], NoneType] = None shuffle: bool = False collate_fn: typing.Optional[typing.Callable] = None drop_remainder: bool = False collate_fn_args: typing.Union[typing.Dict[str, typing.Any], NoneType] = None label_cols: typing.Union[str, typing.List[str], NoneType] = None prefetch: bool = True )

Parameters

  • batch_size (int) — Size of batches to load from the dataset.
  • columns (List[str] or str, optional) — Dataset column(s) to load in the tf.data.Dataset. Column names that are created by the collate_fn and that do not exist in the original dataset can be used.
  • shuffle(bool, default to False) — Shuffle the dataset order when loading. Recommended True for training, False for validation/evaluation.
  • drop_remainder(bool, default False) — Drop the last incomplete batch when loading. Ensures that all batches yielded by the dataset will have the same length on the batch dimension.
  • collate_fn(Callable, optional) — A function or callable object (such as a DataCollator) that will collate lists of samples into a batch.
  • collate_fn_args (Dict, optional) — An optional dict of keyword arguments to be passed to the collate_fn.
  • label_cols (List[str] or str, default None) — Dataset column(s) to load as labels. Note that many models compute loss internally rather than letting Keras do it, in which case passing the labels here is optional, as long as they’re in the input columns.
  • prefetch (bool, default True) — Whether to run the dataloader in a separate thread and maintain a small buffer of batches for training. Improves performance by allowing data to be loaded in the background while the model is training.

Create a tf.data.Dataset from the underlying Dataset. This tf.data.Dataset will load and collate batches from the Dataset, and is suitable for passing to methods like model.fit() or model.predict(). The dataset will yield dicts for both inputs and labels unless the dict would contain only a single key, in which case a raw tf.Tensor is yielded instead.

Example:

>>> ds_train = ds["train"].to_tf_dataset(
...    columns=['input_ids', 'token_type_ids', 'attention_mask', 'label'],
...    shuffle=True,
...    batch_size=16,
...    collate_fn=data_collator,
... )

push_to_hub

< >

( repo_id: str split: typing.Optional[str] = None private: typing.Optional[bool] = False token: typing.Optional[str] = None branch: typing.Optional[str] = None max_shard_size: typing.Union[int, str] = '500MB' shard_size: typing.Optional[int] = 'deprecated' embed_external_files: bool = True )

Parameters

  • repo_id (str) — The ID of the repository to push to in the following format: / or /. Also accepts , which will default to the namespace of the logged-in user.
  • split (Optional, str) — The name of the split that will be given to that dataset. Defaults to self.split.
  • private (Optional bool, defaults to False) — Whether the dataset repository should be set to private or not. Only affects repository creation: a repository that already exists will not be affected by that parameter.
  • token (Optional str) — An optional authentication token for the Hugging Face Hub. If no token is passed, will default to the token saved locally when logging in with huggingface-cli login. Will raise an error if no token is passed and the user is not logged-in.
  • branch (Optional str) — The git branch on which to push the dataset. This defaults to the default branch as specified in your repository, which defaults to “main”.
  • max_shard_size (int or str, optional, defaults to “500MB”) — The maximum size of the dataset shards to be uploaded to the hub. If expressed as a string, needs to be digits followed by a unit (like “5MB”).
  • shard_size (Optional int) — Deprecated: ‘shard_size’ was renamed to ‘max_shard_size’ in version 2.1.1 and will be removed in 2.4.0.
  • embed_external_files (bool, default True) — Whether to embed file bytes in the shards. In particular, this will do the following before the push for the fields of type:

    • Audio and class:Image: remove local path information and embed file content in the Parquet files.

Pushes the dataset to the hub as a Parquet dataset. The dataset is pushed using HTTP requests and does not need to have neither git or git-lfs installed.

The resulting Parquet files are self-contained by default: if your dataset contains Image or Audio data, the Parquet files will store the bytes of your images or audio files. You can disable this by setting embed_external_files to False.

Example:

>>> dataset.push_to_hub("<organization>/<dataset_id>", split="evaluation")

save_to_disk

< >

( dataset_path: str fs = None )

Parameters

  • dataset_path (str) — Path (e.g. dataset/train) or remote URI (e.g. s3://my-bucket/dataset/train) of the dataset directory where the dataset will be saved to.
  • fs (S3FileSystem, fsspec.spec.AbstractFileSystem, optional, defaults None) — Instance of the remote filesystem used to download the files from.

Saves a dataset to a dataset directory, or in a filesystem using either S3FileSystem or any implementation of fsspec.spec.AbstractFileSystem.

For Image and Audio data:

If your images and audio files are local files, then the resulting arrow file will store paths to these files. If you want to include the bytes or your images or audio files instead, you must read() those files first.

This can be done by storing the “bytes” instead of the “path” of the images or audio files:

>>> def read_image_file(example):
...     with open(example["image"].filename, "rb") as f:
...         return {"image": {"bytes": f.read()}}
>>> ds = ds.map(read_image_file)
>>> ds.save_to_disk("path/to/dataset/dir")
>>> def read_audio_file(example):
...     with open(example["audio"]["path"], "rb") as f:
...         return {"audio": {"bytes": f.read()}}
>>> ds = ds.map(read_audio_file)
>>> ds.save_to_disk("path/to/dataset/dir")

Example:

>>> saved_ds = ds.save_to_disk("path/to/dataset/directory")

load_from_disk

< >

( dataset_path: str fs = None keep_in_memory: typing.Optional[bool] = None ) Dataset or DatasetDict

Parameters

  • dataset_path (str) — Path (e.g. “dataset/train”) or remote URI (e.g. “s3//my-bucket/dataset/train”) of the dataset directory where the dataset will be loaded from.
  • fs (S3FileSystem, fsspec.spec.AbstractFileSystem, optional, default None) — Instance of the remote filesystem used to download the files from.
  • keep_in_memory (bool, default None) — Whether to copy the dataset in-memory. If None, the dataset will not be copied in-memory unless explicitly enabled by setting datasets.config.IN_MEMORY_MAX_SIZE to nonzero. See more details in the load_dataset_enhancing_performance section.

Returns

Dataset or DatasetDict

  • If dataset_path is a path of a dataset directory: the dataset requested.
  • If dataset_path is a path of a dataset dict directory: a datasets.DatasetDict with each split.

Loads a dataset that was previously saved using save_to_disk from a dataset directory, or from a filesystem using either S3FileSystem or any implementation of fsspec.spec.AbstractFileSystem.

Example:

>>> ds = load_from_disk("path/to/dataset/directory")

flatten_indices

< >

( keep_in_memory: bool = False cache_file_name: typing.Optional[str] = None writer_batch_size: typing.Optional[int] = 1000 features: typing.Optional[datasets.features.features.Features] = None disable_nullable: bool = False new_fingerprint: typing.Optional[str] = None )

Parameters

  • keep_in_memory (bool, default False) — Keep the dataset in memory instead of writing it to a cache file.
  • cache_file_name (str, optional, default None) — Provide the name of a path for the cache file. It is used to store the results of the computation instead of the automatically generated cache file name.
  • writer_batch_size (int, default 1000) — Number of rows per write operation for the cache file writer. This value is a good trade-off between memory usage during the processing, and processing speed. Higher value makes the processing do fewer lookups, lower value consume less temporary memory while running .map().
  • features (Optional[datasets.Features], default None) — Use a specific Features to store the cache file instead of the automatically generated one.
  • disable_nullable (bool, default False) — Allow null values in the table.
  • new_fingerprint (str, optional, default None) — The new fingerprint of the dataset after transform. If None, the new fingerprint is computed using a hash of the previous fingerprint, and the transform arguments

Create and cache a new Dataset by flattening the indices mapping.

to_csv

< >

( path_or_buf: typing.Union[str, bytes, os.PathLike, typing.BinaryIO] batch_size: typing.Optional[int] = None num_proc: typing.Optional[int] = None **to_csv_kwargs ) int

Parameters

  • path_or_buf (PathLike or FileOrBuffer) — Either a path to a file or a BinaryIO.
  • batch_size (int, optional) — Size of the batch to load in memory and write at once. Defaults to datasets.config.DEFAULT_MAX_BATCH_SIZE.
  • num_proc (int, optional) — Number of processes for multiprocessing. By default it doesn’t use multiprocessing. batch_size in this case defaults to datasets.config.DEFAULT_MAX_BATCH_SIZE but feel free to make it 5x or 10x of the default value if you have sufficient compute power.
  • **to_csv_kwargs (additional keyword arguments) — Parameters to pass to pandas’s pandas.DataFrame.to_csv

Returns

int

The number of characters or bytes written

Exports the dataset to csv

Example:

>>> ds.to_csv("path/to/dataset/directory")

to_pandas

< >

( batch_size: typing.Optional[int] = None batched: bool = False )

Parameters

  • batched (bool) — Set to True to return a generator that yields the dataset as batches of batch_size rows. Defaults to False (returns the whole datasetas once)
  • batch_size (int, optional) — The size (number of rows) of the batches if batched is True. Defaults to datasets.config.DEFAULT_MAX_BATCH_SIZE.

Returns the dataset as a pandas.DataFrame. Can also return a generator for large datasets.

Example:

>>> ds.to_pandas()

to_dict

< >

( batch_size: typing.Optional[int] = None batched: bool = False )

Parameters

  • batched (bool) — Set to True to return a generator that yields the dataset as batches of batch_size rows. Defaults to False (returns the whole datasetas once)
  • batch_size (int, optional) — The size (number of rows) of the batches if batched is True. Defaults to datasets.config.DEFAULT_MAX_BATCH_SIZE.

Returns the dataset as a Python dict. Can also return a generator for large datasets.

Example:

>>> ds.to_dict()

to_json

< >

( path_or_buf: typing.Union[str, bytes, os.PathLike, typing.BinaryIO] batch_size: typing.Optional[int] = None num_proc: typing.Optional[int] = None **to_json_kwargs ) int

Parameters

  • path_or_buf (PathLike or FileOrBuffer) — Either a path to a file or a BinaryIO.
  • batch_size (int, optional) — Size of the batch to load in memory and write at once. Defaults to datasets.config.DEFAULT_MAX_BATCH_SIZE.
  • num_proc (int, optional) — Number of processes for multiprocessing. By default it doesn’t use multiprocessing. batch_size in this case defaults to datasets.config.DEFAULT_MAX_BATCH_SIZE but feel free to make it 5x or 10x of the default value if you have sufficient compute power.
  • lines (bool, default True) — Whether output JSON lines format. Only possible if `orient="records". It will throw ValueError with orient different from "records", since the others are not list-like. - orient (str, default "records") — Format of the JSON:

    • "records": list like [{column -> value}, … , {column -> value}]
    • "split": dict like {"index" -> [index], "columns" -> [columns], "data" -> [values]}
    • "index": dict like {index -> {column -> value}‌}
    • "columns": dict like {column -> {index -> value}‌}
    • "values": just the values array
    • "table": dict like {"schema": {schema}, "data": {data}‌}
  • **to_json_kwargs (additional keyword arguments) — Parameters to pass to pandas’s pandas.DataFrame.to_json.

Returns

int

The number of characters or bytes written.

Export the dataset to JSON Lines or JSON.

Example:

>>> ds.to_json("path/to/dataset/directory")

to_parquet

< >

( path_or_buf: typing.Union[str, bytes, os.PathLike, typing.BinaryIO] batch_size: typing.Optional[int] = None **parquet_writer_kwargs ) int

Parameters

  • path_or_buf (PathLike or FileOrBuffer) — Either a path to a file or a BinaryIO.
  • batch_size (int, optional) — Size of the batch to load in memory and write at once. Defaults to datasets.config.DEFAULT_MAX_BATCH_SIZE.
  • **parquet_writer_kwargs (additional keyword arguments) — Parameters to pass to PyArrow’s pyarrow.parquet.ParquetWriter

Returns

int

The number of characters or bytes written

Exports the dataset to parquet

Example:

>>> ds.to_parquet("path/to/dataset/directory")

add_faiss_index

< >

( column: str index_name: typing.Optional[str] = None device: typing.Optional[int] = None string_factory: typing.Optional[str] = None metric_type: typing.Optional[int] = None custom_index: typing.Optional[ForwardRef('faiss.Index')] = None batch_size: int = 1000 train_size: typing.Optional[int] = None faiss_verbose: bool = False dtype = <class 'numpy.float32'> )

Parameters

  • column (str) — The column of the vectors to add to the index.
  • index_name (Optional str) — The index_name/identifier of the index. This is the index_name that is used to call datasets.Dataset.get_nearest_examples() or datasets.Dataset.search(). By default it corresponds to column.
  • device (Optional Union[int, List[int]]) — If positive integer, this is the index of the GPU to use. If negative integer, use all GPUs. If a list of positive integers is passed in, run only on those GPUs. By default it uses the CPU.
  • string_factory (Optional str) — This is passed to the index factory of Faiss to create the index. Default index class is IndexFlat.
  • metric_type (Optional int) — Type of metric. Ex: faiss.faiss.METRIC_INNER_PRODUCT or faiss.METRIC_L2.
  • custom_index (Optional faiss.Index) — Custom Faiss index that you already have instantiated and configured for your needs.
  • batch_size (Optional int) — Size of the batch to use while adding vectors to the FaissIndex. Default value is 1000.
  • train_size (Optional int) — If the index needs a training step, specifies how many vectors will be used to train the index.
  • faiss_verbose (bool, defaults to False) — Enable the verbosity of the Faiss index.
  • dtype (data-type) — The dtype of the numpy arrays that are indexed. Default is np.float32.

Add a dense index using Faiss for fast retrieval. By default the index is done over the vectors of the specified column. You can specify device if you want to run it on GPU (device must be the GPU index). You can find more information about Faiss here:

Example:

>>> ds = datasets.load_dataset('crime_and_punish', split='train')
>>> ds_with_embeddings = ds.map(lambda example: {'embeddings': embed(example['line']}))
>>> ds_with_embeddings.add_faiss_index(column='embeddings')
>>> # query
>>> scores, retrieved_examples = ds_with_embeddings.get_nearest_examples('embeddings', embed('my new query'), k=10)
>>> # save index
>>> ds_with_embeddings.save_faiss_index('embeddings', 'my_index.faiss')

>>> ds = datasets.load_dataset('crime_and_punish', split='train')
>>> # load index
>>> ds.load_faiss_index('embeddings', 'my_index.faiss')
>>> # query
>>> scores, retrieved_examples = ds.get_nearest_examples('embeddings', embed('my new query'), k=10)

add_faiss_index_from_external_arrays

< >

( external_arrays: array index_name: str device: typing.Optional[int] = None string_factory: typing.Optional[str] = None metric_type: typing.Optional[int] = None custom_index: typing.Optional[ForwardRef('faiss.Index')] = None batch_size: int = 1000 train_size: typing.Optional[int] = None faiss_verbose: bool = False dtype = <class 'numpy.float32'> )

Parameters

  • external_arrays (np.array) — If you want to use arrays from outside the lib for the index, you can set external_arrays. It will use external_arrays to create the Faiss index instead of the arrays in the given column.
  • index_name (str) — The index_name/identifier of the index. This is the index_name that is used to call datasets.Dataset.get_nearest_examples() or datasets.Dataset.search().
  • device (Optional Union[int, List[int]]) — If positive integer, this is the index of the GPU to use. If negative integer, use all GPUs. If a list of positive integers is passed in, run only on those GPUs. By default it uses the CPU.
  • string_factory (Optional str) — This is passed to the index factory of Faiss to create the index. Default index class is IndexFlat.
  • metric_type (Optional int) — Type of metric. Ex: faiss.faiss.METRIC_INNER_PRODUCT or faiss.METRIC_L2.
  • custom_index (Optional faiss.Index) — Custom Faiss index that you already have instantiated and configured for your needs.
  • batch_size (Optional int) — Size of the batch to use while adding vectors to the FaissIndex. Default value is 1000.
  • train_size (Optional int) — If the index needs a training step, specifies how many vectors will be used to train the index.
  • faiss_verbose (bool, defaults to False) — Enable the verbosity of the Faiss index.
  • dtype (numpy.dtype) — The dtype of the numpy arrays that are indexed. Default is np.float32.

Add a dense index using Faiss for fast retrieval. The index is created using the vectors of external_arrays. You can specify device if you want to run it on GPU (device must be the GPU index). You can find more information about Faiss here:

save_faiss_index

< >

( index_name: str file: typing.Union[str, pathlib.PurePath] )

Parameters

  • index_name (str) — The index_name/identifier of the index. This is the index_name that is used to call .get_nearest or .search.
  • file (str) — The path to the serialized faiss index on disk.

Save a FaissIndex on disk.

load_faiss_index

< >

( index_name: str file: typing.Union[str, pathlib.PurePath] device: typing.Union[int, typing.List[int], NoneType] = None )

Parameters

  • index_name (str) — The index_name/identifier of the index. This is the index_name that is used to call .get_nearest or .search.
  • file (str) — The path to the serialized faiss index on disk.
  • device (Optional Union[int, List[int]]) — If positive integer, this is the index of the GPU to use. If negative integer, use all GPUs. If a list of positive integers is passed in, run only on those GPUs. By default it uses the CPU.

Load a FaissIndex from disk.

If you want to do additional configurations, you can have access to the faiss index object by doing .get_index(index_name).faiss_index to make it fit your needs.

add_elasticsearch_index

< >

( column: str index_name: typing.Optional[str] = None host: typing.Optional[str] = None port: typing.Optional[int] = None es_client: typing.Optional[ForwardRef('elasticsearch.Elasticsearch')] = None es_index_name: typing.Optional[str] = None es_index_config: typing.Optional[dict] = None )

Parameters

  • column (str) — The column of the documents to add to the index.
  • index_name (Optional str) — The index_name/identifier of the index. This is the index name that is used to call Dataset.get_nearest_examples() or Dataset.search(). By default it corresponds to column.
  • host (Optional str, defaults to localhost) — host of where ElasticSearch is running
  • port (Optional str, defaults to 9200) — port of where ElasticSearch is running
  • es_client (Optional elasticsearch.Elasticsearch) — The elasticsearch client used to create the index if host and port are None.
  • es_index_name (Optional str) — The elasticsearch index name used to create the index.
  • es_index_config (Optional dict) — The configuration of the elasticsearch index. Default config is:

Add a text index using ElasticSearch for fast retrieval. This is done in-place.

Example:

>>> es_client = elasticsearch.Elasticsearch()
>>> ds = datasets.load_dataset('crime_and_punish', split='train')
>>> ds.add_elasticsearch_index(column='line', es_client=es_client, es_index_name="my_es_index")
>>> scores, retrieved_examples = ds.get_nearest_examples('line', 'my new query', k=10)

load_elasticsearch_index

< >

( index_name: str es_index_name: str host: typing.Optional[str] = None port: typing.Optional[int] = None es_client: typing.Optional[ForwardRef('Elasticsearch')] = None es_index_config: typing.Optional[dict] = None )

Parameters

  • index_name (str) — The index_name/identifier of the index. This is the index name that is used to call .get_nearest or .search.
  • es_index_name (str) — The name of elasticsearch index to load.
  • host (Optional str, defaults to localhost) — host of where ElasticSearch is running
  • port (Optional str, defaults to 9200) — port of where ElasticSearch is running
  • es_client (Optional elasticsearch.Elasticsearch) — The elasticsearch client used to create the index if host and port are None.
  • es_index_config (Optional dict) — The configuration of the elasticsearch index.

Load an existing text index using ElasticSearch for fast retrieval.

Default config is:

{
"settings": {
"number_of_shards": 1,
"analysis": {"analyzer": {"stop_standard": {"type": "standard", " stopwords": "_english_"}}},
},
"mappings": {
"properties": {
"text": {
"type": "text",
"analyzer": "standard",
"similarity": "BM25"
},
}
},
}

list_indexes

< >

( )

List the colindex_nameumns/identifiers of all the attached indexes.

get_index

< >

( index_name: str ) BaseIndex

Parameters

  • index_name (str) — Index name.

Returns

BaseIndex

List the index_name/identifiers of all the attached indexes.

drop_index

< >

( index_name: str )

Parameters

  • index_name (str) — The index_name/identifier of the index.

Drop the index with the specified column.

search

< >

( index_name: str query: typing.Union[str, <built-in function array>] k: int = 10 ) scores (List[List[float])

Parameters

  • index_name (str) — The name/identifier of the index.
  • query (Union[str, np.ndarray]) — The query as a string if index_name is a text index or as a numpy array if index_name is a vector index.
  • k (int) — The number of examples to retrieve.

Returns

scores (List[List[float])

The retrieval scores of the retrieved examples. indices (List[List[int]]): The indices of the retrieved examples.

Find the nearest examples indices in the dataset to the query.

search_batch

< >

( index_name: str queries: typing.Union[typing.List[str], <built-in function array>] k: int = 10 ) total_scores (List[List[float])

Parameters

  • index_name (str) — The index_name/identifier of the index.
  • queries (Union[List[str], np.ndarray]) — The queries as a list of strings if index_name is a text index or as a numpy array if index_name is a vector index.
  • k (int) — The number of examples to retrieve per query.

Returns

total_scores (List[List[float])

The retrieval scores of the retrieved examples per query. total_indices (List[List[int]]): The indices of the retrieved examples per query.

Find the nearest examples indices in the dataset to the query.

get_nearest_examples

< >

( index_name: str query: typing.Union[str, <built-in function array>] k: int = 10 ) scores (List[float])

Parameters

  • index_name (str) — The index_name/identifier of the index.
  • query (Union[str, np.ndarray]) — The query as a string if index_name is a text index or as a numpy array if index_name is a vector index.
  • k (int) — The number of examples to retrieve.

Returns

scores (List[float])

The retrieval scores of the retrieved examples. examples (dict): The retrieved examples.

Find the nearest examples in the dataset to the query.

get_nearest_examples_batch

< >

( index_name: str queries: typing.Union[typing.List[str], <built-in function array>] k: int = 10 ) total_scores (List[List[float])

Parameters

  • index_name (str) — The index_name/identifier of the index.
  • queries (Union[List[str], np.ndarray]) — The queries as a list of strings if index_name is a text index or as a numpy array if index_name is a vector index.
  • k (int) — The number of examples to retrieve per query.

Returns

total_scores (List[List[float])

The retrieval scores of the retrieved examples per query. total_examples (List[dict]): The retrieved examples per query.

Find the nearest examples in the dataset to the query.

info

< >

( )

datasets.DatasetInfo object containing all the metadata in the dataset.

split

< >

( )

datasets.NamedSplit object corresponding to a named dataset split.

builder_name

< >

( )

citation

< >

( )

config_name

< >

( )

dataset_size

< >

( )

description

< >

( )

download_checksums

< >

( )

download_size

< >

( )

features

< >

( )

homepage

< >

( )

license

< >

( )

size_in_bytes

< >

( )

supervised_keys

< >

( )

version

< >

( )

from_csv

< >

( path_or_paths: typing.Union[str, bytes, os.PathLike, typing.List[typing.Union[str, bytes, os.PathLike]]] split: typing.Optional[datasets.splits.NamedSplit] = None features: typing.Optional[datasets.features.features.Features] = None cache_dir: str = None keep_in_memory: bool = False **kwargs ) Dataset

Parameters

  • path_or_paths (path-like or list of path-like) — Path(s) of the CSV file(s).
  • split (NamedSplit, optional) — Split name to be assigned to the dataset.
  • features (Features, optional) — Dataset features.
  • cache_dir (str, optional, default "~/.cache/huggingface/datasets") — Directory to cache data.
  • keep_in_memory (bool, default False) — Whether to copy the data in-memory.
  • **kwargs (additional keyword arguments) — Keyword arguments to be passed to pandas.read_csv.

Returns

Dataset

Create Dataset from CSV file(s).

Example:

>>> ds = Dataset.from_csv('path/to/dataset.csv')

from_json

< >

( path_or_paths: typing.Union[str, bytes, os.PathLike, typing.List[typing.Union[str, bytes, os.PathLike]]] split: typing.Optional[datasets.splits.NamedSplit] = None features: typing.Optional[datasets.features.features.Features] = None cache_dir: str = None keep_in_memory: bool = False field: typing.Optional[str] = None **kwargs ) Dataset

Parameters

  • path_or_paths (path-like or list of path-like) — Path(s) of the JSON or JSON Lines file(s).
  • split (NamedSplit, optional) — Split name to be assigned to the dataset.
  • features (Features, optional) — Dataset features.
  • cache_dir (str, optional, default "~/.cache/huggingface/datasets") — Directory to cache data.
  • keep_in_memory (bool, default False) — Whether to copy the data in-memory.
  • field (str, optional) — Field name of the JSON file where the dataset is contained in.
  • **kwargs (additional keyword arguments) — Keyword arguments to be passed to JsonConfig.

Returns

Dataset

Create Dataset from JSON or JSON Lines file(s).

Example:

>>> ds = Dataset.from_json('path/to/dataset.json')

from_parquet

< >

( path_or_paths: typing.Union[str, bytes, os.PathLike, typing.List[typing.Union[str, bytes, os.PathLike]]] split: typing.Optional[datasets.splits.NamedSplit] = None features: typing.Optional[datasets.features.features.Features] = None cache_dir: str = None keep_in_memory: bool = False columns: typing.Optional[typing.List[str]] = None **kwargs ) Dataset

Parameters

  • path_or_paths (path-like or list of path-like) — Path(s) of the Parquet file(s).
  • split (NamedSplit, optional) — Split name to be assigned to the dataset.
  • features (Features, optional) — Dataset features.
  • cache_dir (str, optional, default "~/.cache/huggingface/datasets") — Directory to cache data.
  • keep_in_memory (bool, default False) — Whether to copy the data in-memory.
  • columns (List[str], optional) — If not None, only these columns will be read from the file. A column name may be a prefix of a nested field, e.g. ‘a’ will select ‘a.b’, ‘a.c’, and ‘a.d.e’.
  • **kwargs (additional keyword arguments) — Keyword arguments to be passed to ParquetConfig.

Returns

Dataset

Create Dataset from Parquet file(s).

Example:

>>> ds = Dataset.from_parquet('path/to/dataset.parquet')

from_text

< >

( path_or_paths: typing.Union[str, bytes, os.PathLike, typing.List[typing.Union[str, bytes, os.PathLike]]] split: typing.Optional[datasets.splits.NamedSplit] = None features: typing.Optional[datasets.features.features.Features] = None cache_dir: str = None keep_in_memory: bool = False **kwargs ) Dataset

Parameters

  • path_or_paths (path-like or list of path-like) — Path(s) of the text file(s).
  • split (NamedSplit, optional) — Split name to be assigned to the dataset.
  • features (Features, optional) — Dataset features.
  • cache_dir (str, optional, default "~/.cache/huggingface/datasets") — Directory to cache data.
  • keep_in_memory (bool, default False) — Whether to copy the data in-memory.
  • **kwargs (additional keyword arguments) — Keyword arguments to be passed to TextConfig.

Returns

Dataset

Create Dataset from text file(s).

Example:

>>> ds = Dataset.from_text('path/to/dataset.txt')

prepare_for_task

< >

( task: typing.Union[str, datasets.tasks.base.TaskTemplate] id: int = 0 )

Parameters

  • task (Union[str, TaskTemplate]) — The task to prepare the dataset for during training and evaluation. If str, supported tasks include:

    • "text-classification"
    • "question-answering"

    If TaskTemplate, must be one of the task templates in datasets.tasks.

  • id (int, defaults to 0) — The id required to unambiguously identify the task template when multiple task templates of the same type are supported.

Prepare a dataset for the given task by casting the dataset’s Features to standardized column names and types as detailed in datasets.tasks.

Casts datasets.DatasetInfo.features according to a task-specific schema. Intended for single-use only, so all task templates are removed from datasets.DatasetInfo.task_templates after casting.

align_labels_with_mapping

< >

( label2id: typing.Dict label_column: str )

Parameters

  • label2id (dict) — The label name to ID mapping to align the dataset with.
  • label_column (str) — The column name of labels to align on.

Align the dataset’s label ID and label name mapping to match an input label2id mapping. This is useful when you want to ensure that a model’s predicted labels are aligned with the dataset. The alignment in done using the lowercase label names.

Example:

>>> # dataset with mapping {'entailment': 0, 'neutral': 1, 'contradiction': 2}
>>> ds = load_dataset("glue", "mnli", split="train")
>>> # mapping to align with
>>> label2id = {'CONTRADICTION': 0, 'NEUTRAL': 1, 'ENTAILMENT': 2}
>>> ds_aligned = ds.align_labels_with_mapping(label2id, "label")

datasets.concatenate_datasets

< >

( dsets: typing.List[datasets.arrow_dataset.Dataset] info: typing.Optional[datasets.info.DatasetInfo] = None split: typing.Optional[datasets.splits.NamedSplit] = None axis: int = 0 )

Parameters

  • dsets (List[datasets.Dataset]) — List of Datasets to concatenate.
  • info (DatasetInfo, optional) — Dataset information, like description, citation, etc.
  • split (NamedSplit, optional) — Name of the dataset split.
  • axis ({0, 1}, default 0, meaning over rows) — Axis to concatenate over, where 0 means over rows (vertically) and 1 means over columns (horizontally).

    New in version 1.6.0

Converts a list of Dataset with the same schema into a single Dataset.

Example:

>>> ds3 = concatenate_datasets([ds1, ds2])

datasets.interleave_datasets

< >

( datasets: typing.List[~DatasetType] probabilities: typing.Optional[typing.List[float]] = None seed: typing.Optional[int] = None info: typing.Optional[datasets.info.DatasetInfo] = None split: typing.Optional[datasets.splits.NamedSplit] = None ) Dataset or IterableDataset

Parameters

  • datasets (List[Dataset] or List[IterableDataset]) — list of datasets to interleave
  • probabilities (List[float], optional, default None) — If specified, the new dataset is constructued by sampling examples from one source at a time according to these probabilities.
  • seed (int, optional, default None) — The random seed used to choose a source for each example.

Return type depends on the input datasets parameter. Dataset if the input is a list of Dataset, IterableDataset if the input is a list of IterableDataset.

Interleave several datasets (sources) into a single dataset. The new dataset is constructed by alternating between the sources to get the examples.

You can use this function on a list of Dataset objects, or on a list of IterableDataset objects.

If probabilities is None (default) the new dataset is constructed by cycling between each source to get the examples. If probabilities is not None, the new dataset is constructed by getting examples from a random source at a time according to the provided probabilities.

The resulting dataset ends when one of the source datasets runs out of examples.

Example:

For regular datasets (map-style):

>>> from datasets import Dataset, interleave_datasets
>>> d1 = Dataset.from_dict({"a": [0, 1, 2]})
>>> d2 = Dataset.from_dict({"a": [10, 11, 12]})
>>> d3 = Dataset.from_dict({"a": [20, 21, 22]})
>>> dataset = interleave_datasets([d1, d2, d3])
>>> dataset["a"]
[0, 10, 20, 1, 11, 21, 2, 12, 22]
>>> dataset = interleave_datasets([d1, d2, d3], probabilities=[0.7, 0.2, 0.1], seed=42)
>>> dataset["a"]
[10, 0, 11, 1, 2, 20, 12]

For datasets in streaming mode (iterable):

>>> from datasets import load_dataset, interleave_datasets
>>> d1 = load_dataset("oscar", "unshuffled_deduplicated_en", split="train", streaming=True)
>>> d2 = load_dataset("oscar", "unshuffled_deduplicated_fr", split="train", streaming=True)
>>> dataset = interleave_datasets([d1, d2])
>>> iterator = iter(dataset)
>>> next(iterator)
{'text': 'Mtendere Village was inspired by the vision...
>>> next(iterator)
{'text': "Média de débat d'idées, de culture...

datasets.enable_caching

< >

( )

When applying transforms on a dataset, the data are stored in cache files. The caching mechanism allows to reload an existing cache file if it’s already been computed.

Reloading a dataset is possible since the cache files are named using the dataset fingerprint, which is updated after each transform.

If disabled, the library will no longer reload cached datasets files when applying transforms to the datasets. More precisely, if the caching is disabled:

  • cache files are always recreated
  • cache files are written to a temporary directory that is deleted when session closes
  • cache files are named using a random hash instead of the dataset fingerprint
  • use datasets.Dataset.save_to_disk() to save a transformed dataset or it will be deleted when session closes
  • caching doesn’t affect datasets.load_dataset(). If you want to regenerate a dataset from scratch you should use the download_mode parameter in datasets.load_dataset().

datasets.disable_caching

< >

( )

When applying transforms on a dataset, the data are stored in cache files. The caching mechanism allows to reload an existing cache file if it’s already been computed.

Reloading a dataset is possible since the cache files are named using the dataset fingerprint, which is updated after each transform.

If disabled, the library will no longer reload cached datasets files when applying transforms to the datasets. More precisely, if the caching is disabled:

  • cache files are always recreated
  • cache files are written to a temporary directory that is deleted when session closes
  • cache files are named using a random hash instead of the dataset fingerprint
  • use datasets.Dataset.save_to_disk() to save a transformed dataset or it will be deleted when session closes
  • caching doesn’t affect datasets.load_dataset(). If you want to regenerate a dataset from scratch you should use the download_mode parameter in datasets.load_dataset().

datasets.is_caching_enabled

< >

( )

When applying transforms on a dataset, the data are stored in cache files. The caching mechanism allows to reload an existing cache file if it’s already been computed.

Reloading a dataset is possible since the cache files are named using the dataset fingerprint, which is updated after each transform.

If disabled, the library will no longer reload cached datasets files when applying transforms to the datasets. More precisely, if the caching is disabled:

  • cache files are always recreated
  • cache files are written to a temporary directory that is deleted when session closes
  • cache files are named using a random hash instead of the dataset fingerprint
  • use datasets.Dataset.save_to_disk() to save a transformed dataset or it will be deleted when session closes
  • caching doesn’t affect datasets.load_dataset(). If you want to regenerate a dataset from scratch you should use the download_mode parameter in datasets.load_dataset().

DatasetDict

Dictionary with split names as keys (‘train’, ‘test’ for example), and Dataset objects as values. It also has dataset transform methods like map or filter, to process all the splits at once.

class datasets.DatasetDict

< >

( )

A dictionary (dict of str: datasets.Dataset) with dataset transforms methods (map, filter, etc.)