<!-- # hard line break macro for HTML -->

# fiftyone.utils.fiw

Utilities for working with the
[Families in the Wild dataset](https://web.northeastern.edu/smilelab/fiw/).

Copyright 2017-2026, Voxel51, Inc.
<br/>
[voxel51.com](https://voxel51.com/)
<br/>
<br/>

**Classes:**

| [`FIWDatasetImporter`](#fiftyone.utils.fiw.FIWDatasetImporter)([dataset_dir, shuffle, ...])   | Importer for Faces in the Wild-formatted datasets stored on disk.   |
|-----------------------------------------------------------------------------------------------|---------------------------------------------------------------------|

**Functions:**

| [`get_pairwise_labels`](#fiftyone.utils.fiw.get_pairwise_labels)(samples[, label_type])       | Gets a list of all pairs of people that are related and the label of their relation, either through the "kinships" or "relationships" field.   |
|-----------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------|
| [`get_identifier_filepaths_map`](#fiftyone.utils.fiw.get_identifier_filepaths_map)(samples)   | Creates a mapping of `family_id/member_id` identifier to a list of filepaths for each person.                                                  |
| [`download_fiw_dataset`](#fiftyone.utils.fiw.download_fiw_dataset)(dataset_dir, split[, ...]) | Downloads and extracts the Families in the Wild dataset.                                                                                       |

### *class* fiftyone.utils.fiw.FIWDatasetImporter(dataset_dir=None, shuffle=False, seed=None, max_samples=None)

Bases: [`BatchDatasetImporter`](fiftyone.utils.data.importers.md#fiftyone.utils.data.importers.BatchDatasetImporter)

Importer for Faces in the Wild-formatted datasets stored on disk.

See
[this page](https://github.com/visionjo/pykinship#db-contents-and-structure)
for format details.

**Methods:**

| [`import_samples`](#fiftyone.utils.fiw.FIWDatasetImporter.import_samples)(dataset[, tags])   | Imports samples and labels stored on disk following the format of the Families in the Wild dataset.   |
|----------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------|
| [`close`](#fiftyone.utils.fiw.FIWDatasetImporter.close)(\*args)                              | Performs any necessary actions after the last sample has been imported.                               |
| [`get_dataset_info`](#fiftyone.utils.fiw.FIWDatasetImporter.get_dataset_info)()              | Returns the dataset info for the dataset.                                                             |
| [`get_media_sources`](#fiftyone.utils.fiw.FIWDatasetImporter.get_media_sources)()            | Returns the media-source entries the importing dataset records before any sample is added, or None.   |
| [`setup`](#fiftyone.utils.fiw.FIWDatasetImporter.setup)()                                    | Performs any necessary setup before importing the first sample in the dataset.                        |

**Attributes:**

| [`has_dataset_info`](#fiftyone.utils.fiw.FIWDatasetImporter.has_dataset_info)   | Whether this importer produces a dataset info dictionary.   |
|---------------------------------------------------------------------------------|-------------------------------------------------------------|

#### import_samples(dataset, tags=None)

Imports samples and labels stored on disk following the format of
the Families in the Wild dataset.

* **Parameters:**
  * **dataset** – a [`fiftyone.core.dataset.Dataset`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset)
  * **tags** (*None*) – an optional list of tags to attach to each sample
* **Returns:**
  a list of IDs of the samples that were added to the dataset

#### close(\*args)

Performs any necessary actions after the last sample has been
imported.

This method is called when the importer’s context manager interface is
exited, `DatasetImporter.__exit__()`.

* **Parameters:**
  **\*args** – the arguments to `DatasetImporter.__exit__()`

#### get_dataset_info()

Returns the dataset info for the dataset.

By convention, this method should be called after all samples in the
dataset have been imported.

* **Returns:**
  a dict of dataset info

#### get_media_sources()

Returns the media-source entries the importing dataset records
before any sample is added, or None.

Only importers of media-reference-backed samples provide these; see
[`fiftyone.utils.lerobot.LeRobotDatasetImporter`](fiftyone.utils.lerobot.md#fiftyone.utils.lerobot.LeRobotDatasetImporter).

#### *property* has_dataset_info

Whether this importer produces a dataset info dictionary.

#### setup()

Performs any necessary setup before importing the first sample in
the dataset.

This method is called when the importer’s context manager interface is
entered, `DatasetImporter.__enter__()`.

### fiftyone.utils.fiw.get_pairwise_labels(samples, label_type='kinships')

Gets a list of all pairs of people that are related and the label of
their relation, either through the “kinships” or “relationships” field.

Example:

```default
[
   ["F0009/MID2", "F0009/MID4", "sibling"],
   ...
]
```

* **Parameters:**
  * **samples** – a
    [`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
  * **label_type** ( *"kinships"*) – the type of label of which to return pairwise
    listings options are `("kinships", "relationships")`
* **Returns:**
  a list of triplets containing the identifier of person 1, identifier of
  person 2, and their kinship or relationship

### fiftyone.utils.fiw.get_identifier_filepaths_map(samples)

Creates a mapping of `family_id/member_id` identifier to a list of
filepaths for each person.

Example:

```default
{
    "F0325/MID4": [
        "/path/to/fiftyone/fiw/train/data/F0325/MID4/P03451_face4.jpg",
        ...
    ],
    ...
}
```

* **Parameters:**
  **samples** – a
  [`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
* **Returns:**
  a dict mapping `family_id/member_id` identifiers to a list of
  filepaths containing images of the corresponding person

### fiftyone.utils.fiw.download_fiw_dataset(dataset_dir, split, scratch_dir=None, cleanup=False)

Downloads and extracts the Families in the Wild dataset.

Any existing files are not re-downloaded.

* **Parameters:**
  * **dataset_dir** – the directory to output the final dataset
  * **split** – the split being loaded
  * **scratch_dir** (*None*) – a scratch directory to use to store temporary files
  * **cleanup** (*True*) – whether to cleanup the scratch directory after
    extraction