request.deserialize_zipfile

Request copies of relational datasets.

deserialize_zipfile(data_location, name, *, fold=1)

Deserialize a zipfile, returning train and test sets.

Warning

This method is presented here to illustrate how data are unpacked from zip archives. The user is responsible for the structure of custom archives.

The srlearn/datasets repository defines the assumptions for how datasets are stored.

Structure generally falls into two categories, where {{ name }} represents the dataset (e.g. cora, toy_cancer):

{{ name }}
├── README.md
└── {{ name }}
    ├─── background.txt
    ├─── train ─── train_pos.txt, train_neg.txt, train_facts.txt
    └─── test ──── test_pos.txt, test_neg.txt, test_facts.txt

... or:

{{ name }}
├── README.md
└── {{ name }}
    ├─── background.txt
    ├─── fold1
    │      ├─── train ─── train_pos.txt, train_neg.txt, train_facts.txt
    │      └─── test ──── test_pos.txt, test_neg.txt, test_facts.txt
    ├─── fold2
    .
    .

Parameters:

Name	Type	Description	Default
data_location	str	Location of a zipfile.	required
name	str	Name of the dataset.	required
fold	int	In datasets with multiple folds, return this fold. This value is ignored if the data is not split into multiple folds.	1

Returns:

Type	Description
Tuple[RelationalDataset, RelationalDataset]	Tuple of training and test sets.

Examples:

This loads fold-2 of cora-v0.0.3 using an absolute path to the dataset, assuming that it is already downloaded:

from relational_datasets.request import deserialize_zipfile

train, test = deserialize_zipfile(
    '/home/user/relational_datasets/cora_v0.0.3.zip',
    'cora',
    fold=2,
)

This can also load from the current directory:

from relational_datasets.request import deserialize_zipfile

train, test = deserialize_zipfile(
    './cora_v0.0.3.zip',
    'cora',
)

Source code in relational_datasets/request.py

def deserialize_zipfile(
    data_location: str, name: str, *, fold: int = 1
) -> Tuple[RelationalDataset, RelationalDataset]:
    """Deserialize a zipfile, returning train and test sets.

    !!! warning end
        This method is presented here to illustrate how data are unpacked from
        zip archives. The user is responsible for the structure of custom archives.

        The [`srlearn/datasets`](https://github.com/srlearn/datasets/tree/main/srlearn)
        repository defines the assumptions for how datasets are stored.

        Structure generally falls into two categories, where `{{ name }}`
        represents the dataset (e.g. `cora`, `toy_cancer`):

        ```
        {{ name }}
        ├── README.md
        └── {{ name }}
            ├─── background.txt
            ├─── train ─── train_pos.txt, train_neg.txt, train_facts.txt
            └─── test ──── test_pos.txt, test_neg.txt, test_facts.txt
        ```

        ... or:

        ```
        {{ name }}
        ├── README.md
        └── {{ name }}
            ├─── background.txt
            ├─── fold1
            │      ├─── train ─── train_pos.txt, train_neg.txt, train_facts.txt
            │      └─── test ──── test_pos.txt, test_neg.txt, test_facts.txt
            ├─── fold2
            .
            .
        ```

    Arguments:
        data_location: Location of a zipfile.
        name: Name of the dataset.
        fold: In datasets with multiple folds, return this fold. This value is
            ignored if the data is not split into multiple folds.

    Returns:
        Tuple of training and test sets.

    Examples:

    This loads fold-2 of cora-v0.0.3 using an absolute path to the dataset,
    assuming that it is already downloaded:

    ```python
    from relational_datasets.request import deserialize_zipfile

    train, test = deserialize_zipfile(
        '/home/user/relational_datasets/cora_v0.0.3.zip',
        'cora',
        fold=2,
    )
    ```

    This can also load from the current directory:

    ```python
    from relational_datasets.request import deserialize_zipfile

    train, test = deserialize_zipfile(
        './cora_v0.0.3.zip',
        'cora',
    )
    ```
    """

    with ZipFile(data_location) as myzip:

        folds = _n_folds(myzip)

        if folds == 0:
            # This dataset contains no folds.

            with myzip.open(f"{name}/train/train_pos.txt", "r") as _fh:
                train_pos = TextIOWrapper(_fh).read().splitlines()
            with myzip.open(f"{name}/train/train_neg.txt", "r") as _fh:
                train_neg = TextIOWrapper(_fh).read().splitlines()
            with myzip.open(f"{name}/train/train_facts.txt", "r") as _fh:
                train_facts = TextIOWrapper(_fh).read().splitlines()

            with myzip.open(f"{name}/test/test_pos.txt", "r") as _fh:
                test_pos = TextIOWrapper(_fh).read().splitlines()
            with myzip.open(f"{name}/test/test_neg.txt", "r") as _fh:
                test_neg = TextIOWrapper(_fh).read().splitlines()
            with myzip.open(f"{name}/test/test_facts.txt", "r") as _fh:
                test_facts = TextIOWrapper(_fh).read().splitlines()

        elif fold > folds:
            print(fold, folds)
            raise ValueError("Fold does not exist.")

        else:
            with myzip.open(f"{name}/fold{fold}/train/train_pos.txt", "r") as _fh:
                train_pos = TextIOWrapper(_fh).read().splitlines()
            with myzip.open(f"{name}/fold{fold}/train/train_neg.txt", "r") as _fh:
                train_neg = TextIOWrapper(_fh).read().splitlines()
            with myzip.open(f"{name}/fold{fold}/train/train_facts.txt", "r") as _fh:
                train_facts = TextIOWrapper(_fh).read().splitlines()

            with myzip.open(f"{name}/fold{fold}/test/test_pos.txt", "r") as _fh:
                test_pos = TextIOWrapper(_fh).read().splitlines()
            with myzip.open(f"{name}/fold{fold}/test/test_neg.txt", "r") as _fh:
                test_neg = TextIOWrapper(_fh).read().splitlines()
            with myzip.open(f"{name}/fold{fold}/test/test_facts.txt", "r") as _fh:
                test_facts = TextIOWrapper(_fh).read().splitlines()

    return (
        RelationalDataset._make([train_pos, train_neg, train_facts]),
        RelationalDataset._make([test_pos, test_neg, test_facts]),
    )

---

Last update: June 20, 2022