plato-learn 1.1__py3-none-any.whl

plato/samplers/distribution_noniid.py

@@ -0,0 +1,132 @@
+"""
+Samples data from a dataset, biased across labels according to the Dirichlet
+distribution and biased across data size according to Dirichlet distribution.
+
+This sampler can introduce the hardest non-IID data scenarios because it contains:
+
+    - Label skewness - equals to the sampler called dirichlet, i.e., dirichlet.py
+        The number of classes contained in clients follows the Dirichlet distribution
+        that is parameterized by the "label_concentration".
+    - Quantity skewness - equals to the sampler called "sample_quantity_noniid.py".
+            The local dataset sizes of clients follow the  Dirichlet distribution that is
+        parameterized by the "client_quantity_concentration".
+
+    For example,
+        1. Setting label_concentration = 0.1 will induce extreme label unbalance between clients.
+        When there are ten classes, each client only contains sufficient samples from one class.
+                classes 1       2       3 ...   8     9
+                client1 100     8       9       3     7
+                client2 4      108      7       9     6
+                ...
+                clientN 3       10      11      99    2
+        2. Setting client_quantity_concentration = 0.1 will induce extreme data scale
+         unbalance between clients.
+        The sample sizes of clients follow the Dirichlet distribution.
+                classes 1       2       3 ...   8     9
+                client1 5       6       7       5     8
+                client2 50      45      67      49    56
+                ...
+                clientN 6       7      11      10     7
+        3. Then, this sampler introduces the above two unbalance conditions simultaneously.
+                classes 1       2       3 ...   8     9
+                client1 60      66      380     45    38
+                client2 90      5       3       6     8
+                ...
+                clientN 1       50      1      1      1
+"""
+
+import numpy as np
+import torch
+
+from torch.utils.data import WeightedRandomSampler, SubsetRandomSampler
+
+from plato.config import Config
+from plato.samplers import base
+from plato.samplers import sampler_utils
+
+
+class Sampler(base.Sampler):
+    """Create a data sampler for each client to use a divided partition of the
+    dataset, biased across labels according to the Dirichlet distribution
+    and biased partition size."""
+
+    def __init__(self, datasource, client_id, testing):
+        super().__init__()
+        self.client_id = client_id
+
+        # set the random seed based on client id
+        np.random.seed(self.random_seed * int(client_id))
+
+        # obtain the dataset information
+        if testing:
+            target_list = datasource.get_test_set().targets
+        else:
+            # the list of labels (targets) for all the examples
+            target_list = datasource.get_train_set().targets
+
+        class_list = datasource.classes()
+        total_data_size = len(target_list)
+
+        # obtain the configuration
+        min_partition_size = (
+            Config().data.min_partition_size
+            if hasattr(Config().data, "min_partition_size")
+            else 100
+        )
+        total_clients = Config().clients.total_clients
+
+        client_quantity_concentration = (
+            Config().data.client_quantity_concentration
+            if hasattr(Config().data, "client_quantity_concentration")
+            else 1.0
+        )
+
+        label_concentration = (
+            Config().data.label_concentration
+            if hasattr(Config().data, "label_concentration")
+            else 1.0
+        )
+
+        self.client_partition = sampler_utils.create_dirichlet_skew(
+            total_size=total_data_size,
+            concentration=client_quantity_concentration,
+            min_partition_size=None,
+            number_partitions=total_clients,
+        )[client_id - 1]
+
+        self.client_partition_size = int(total_data_size * self.client_partition)
+        self.client_partition_size = max(self.client_partition_size, min_partition_size)
+
+        self.client_label_proportions = sampler_utils.create_dirichlet_skew(
+            total_size=len(class_list),
+            concentration=label_concentration,
+            min_partition_size=None,
+            number_partitions=len(class_list),
+        )
+
+        self.sample_weights = self.client_label_proportions[target_list]
+
+    def get(self):
+        """Obtains an instance of the sampler."""
+        gen = torch.Generator()
+        gen.manual_seed(self.random_seed)
+
+        # Samples without replacement using the sample weights
+        subset_indices = list(
+            WeightedRandomSampler(
+                weights=self.sample_weights,
+                num_samples=self.client_partition_size,
+                replacement=False,
+                generator=gen,
+            )
+        )
+
+        return SubsetRandomSampler(subset_indices, generator=gen)
+
+    def num_samples(self):
+        """Returns the length of the dataset after sampling."""
+        return self.client_partition_size
+
+    def get_sampler_condition(self):
+        """Obtain the label ratio and the sampler configuration"""
+        return self.client_partition, self.client_label_proportions

plato/samplers/iid.py

@@ -0,0 +1,53 @@
+"""
+Samples data from a dataset in an independent and identically distributed fashion.
+"""
+
+import numpy as np
+import torch
+from torch.utils.data import SubsetRandomSampler
+
+from plato.config import Config
+from plato.samplers import base
+
+
+class Sampler(base.Sampler):
+    """Create a data sampler for each client to use a randomly divided partition of the
+    dataset."""
+
+    def __init__(self, datasource, client_id, testing):
+        super().__init__()
+
+        if testing:
+            dataset = datasource.get_test_set()
+        else:
+            dataset = datasource.get_train_set()
+
+        self.dataset_size = len(dataset)
+        indices = list(range(self.dataset_size))
+        np.random.seed(self.random_seed)
+        np.random.shuffle(indices)
+
+        partition_size = Config().data.partition_size
+        total_clients = Config().clients.total_clients
+        total_size = partition_size * total_clients
+
+        # add extra samples to make it evenly divisible, if needed
+        if len(indices) < total_size:
+            while len(indices) < total_size:
+                indices += indices[: (total_size - len(indices))]
+        else:
+            indices = indices[:total_size]
+        assert len(indices) == total_size
+
+        # Compute the indices of data in the subset for this client
+        self.subset_indices = indices[(int(client_id) - 1) : total_size : total_clients]
+
+    def get(self):
+        """Obtains an instance of the sampler."""
+        gen = torch.Generator()
+        gen.manual_seed(self.random_seed)
+        return SubsetRandomSampler(self.subset_indices, generator=gen)
+
+    def num_samples(self):
+        """Returns the length of the dataset after sampling."""
+        return len(self.subset_indices)

plato/samplers/label_quantity_noniid.py

@@ -0,0 +1,119 @@
+"""
+Samples data from a dataset, biased across labels, and the number of labels
+(corresponding classes) in different clients is the same.
+
+This sampler implements one type of label distribution skew called:
+
+    Quantity-based label imbalance:
+        Each client contains a fixed number of classes parameterized by the
+         "per_client_classes_size", while the number of samples in each class
+         is almost the same. Besides, the classes assigned to each client are
+         randomly selected from all classes.
+
+        The samples of one class are equally divided and assigned to clients
+         who contain this class. Thus, the samples of different clients
+         are mutual-exclusive.
+
+    For Example:
+        Setting per_client_classes_size = 2 will induce the condition that each client
+         only contains two classes.
+                classes 1       2       3 ...       8     9
+                client1 100     0       100         0     0
+                client2 0      108      100         0     0
+                ...
+                clientN 0       0       0           100   100
+
+        We have N clients while K clients contain class c. As class c contains D_c samples,
+         each client in K will contain D_c / K samples of this class.
+"""
+
+import numpy as np
+import torch
+from torch.utils.data import SubsetRandomSampler
+
+from plato.config import Config
+from plato.samplers import base
+
+from plato.samplers import sampler_utils
+
+
+class Sampler(base.Sampler):
+    """Create a data sampler for each client to use a divided partition of the
+    dataset, biased across classes according to the parameter per_client_classes_size."""
+
+    def __init__(self, datasource, client_id, testing):
+        super().__init__()
+        self.client_id = client_id
+
+        # Different clients should share the randomness
+        #  as the assignment of classes is completed in each
+        #  sampling process.
+        # Thus, they share the clients_dataidx_map
+        np.random.seed(self.random_seed)
+
+        per_client_classes_size = Config().data.per_client_classes_size
+        total_clients = Config().clients.total_clients
+
+        # obtain the dataset information
+        if testing:
+            target_list = datasource.get_test_set().targets
+        else:
+            # the list of labels (targets) for all the examples
+            target_list = datasource.get_train_set().targets
+
+        self.targets_list = target_list
+        classes_text_list = datasource.classes()
+        classes_id_list = list(range(len(classes_text_list)))
+
+        self.clients_dataidx_map = {
+            client_id: np.ndarray(0, dtype=np.int64)
+            for client_id in range(total_clients)
+        }
+        # construct the quantity label skewness
+        self.quantity_label_skew(
+            dataset_labels=self.targets_list,
+            dataset_classes=classes_id_list,
+            num_clients=total_clients,
+            per_client_classes_size=per_client_classes_size,
+        )
+
+        self.subset_indices = self.clients_dataidx_map[client_id - 1]
+
+    def quantity_label_skew(
+        self, dataset_labels, dataset_classes, num_clients, per_client_classes_size
+    ):
+        """Achieve the quantity-based lable skewness"""
+        client_id = self.client_id
+        # each client contains the full classes
+        if per_client_classes_size == len(dataset_classes):
+            self.clients_dataidx_map = sampler_utils.assign_fully_classes(
+                dataset_labels, dataset_classes, num_clients, client_id
+            )
+        else:
+            self.clients_dataidx_map = sampler_utils.assign_sub_classes(
+                dataset_labels,
+                dataset_classes,
+                num_clients,
+                per_client_classes_size,
+                anchor_classes=None,
+                consistent_clients=None,
+                keep_anchor_classes_size=None,
+            )
+
+    def get(self):
+        """Obtains an instance of the sampler."""
+        gen = torch.Generator()
+        gen.manual_seed(self.random_seed)
+
+        return SubsetRandomSampler(self.subset_indices, generator=gen)
+
+    def num_samples(self):
+        """Returns the length of the dataset after sampling."""
+        return len(self.subset_indices)
+
+    def get_trainset_condition(self):
+        """Obtain the detailed information in the trainser"""
+        targets_array = np.array(self.targets_list)
+        client_sampled_subset_labels = targets_array[self.subset_indices]
+        unique, counts = np.unique(client_sampled_subset_labels, return_counts=True)
+        return np.asarray((unique, counts)).T

plato/samplers/mixed.py

@@ -0,0 +1,44 @@
+"""
+Samples data from a dataset as clients' local datasets.
+Some are biased across labels according to the Dirichlet distribution,
+while some are in an independent and identically distributed fashion.
+"""
+
+import numpy as np
+from plato.config import Config
+from plato.samplers import dirichlet
+
+
+class Sampler(dirichlet.Sampler):
+    """Create a data sampler for each client to use a divided partition of the dataset,
+    either biased across labels according to the Dirichlet distribution, or in an iid fashion."""
+
+    def __init__(self, datasource, client_id, testing):
+        super().__init__(datasource, client_id, testing)
+
+        assert hasattr(Config().data, "non_iid_clients")
+        non_iid_clients = Config().data.non_iid_clients
+
+        if isinstance(non_iid_clients, int):
+            # Gived the number of non-iid clients
+            self.non_iid_clients_list = [
+                x + 1 for x in range(int(non_iid_clients))
+            ]  # [int(non_iid_clients)]
+        else:
+            # Gived the list of non-iid clients
+            self.non_iid_clients_list = [
+                int(x.strip()) for x in non_iid_clients.split(",")
+            ]
+
+        if int(client_id) not in self.non_iid_clients_list:
+            if testing:
+                target_list = datasource.get_test_set().targets
+            else:
+                target_list = datasource.targets()
+            class_list = datasource.classes()
+            self.sample_weights = np.array(
+                [1 / len(class_list) for _ in range(len(class_list))]
+            )[target_list]
+
+            # Different iid clients should have a different random seed for Generator
+            self.random_seed = self.random_seed * int(client_id)

plato/samplers/mixed_label_quantity_noniid.py

@@ -0,0 +1,128 @@
+"""
+Samples data from a dataset, 1). biased across labels, and 2). the number of labels
+ (corresponding classes) in different clients is the same, and 3). part of clients
+ share same classes 4) the classes shared by these clients are partly used by other
+ clients.
+
+This sampler implements the basic label quantity noniid as that in "label_quantity_noniid.py".
+ However, part of clients "consistent_clients_size" contain same classes "anchor_classes". Then,
+ the "keep_anchor_classes_size" classes of "consistent_clients" are also used in classes pool
+ to complete the class assignment.
+
+    For Example:
+        Setting per_client_classes_size = 3, anchor_classes=[2, 3, 9], consistent_clients=[0,1,N],
+         keep_anchor_classes_size=1 will induce the condition:
+
+                classes 1       2       3 ...     7       8     9
+                client1 0      350      350       0       0     350
+                client2 0      350      350       0       0     350
+                client3 100     20      0         0      100    0
+                client4 100     0       0         100    100    0
+                ...
+                clientN 0       350     350     0       0      350
+
+        We have N clients while K clients contain class c. As class c contains D_c samples,
+         each client in K will contain D_c / K samples of this class.
+"""
+
+import numpy as np
+import torch
+from torch.utils.data import SubsetRandomSampler
+
+from plato.config import Config
+from plato.samplers import base
+
+from plato.samplers import sampler_utils
+
+
+class Sampler(base.Sampler):
+    """Create a data sampler for each client to use a divided partition of the
+    dataset, biased across classes according to the parameter per_client_classes_size."""
+
+    def __init__(self, datasource, client_id, testing):
+        super().__init__()
+        self.client_id = client_id
+
+        # Different clients should share the randomness
+        #  as the assignment of classes is completed in each
+        #  sampling process.
+        # Thus, they share the clients_dataidx_map
+        np.random.seed(self.random_seed)
+
+        per_client_classes_size = Config().data.per_client_classes_size
+        anchor_classes = Config().data.anchor_classes
+        consistent_clients_size = Config().data.consistent_clients_size
+        keep_anchor_classes_size = Config().data.keep_anchor_classes_size
+        total_clients = Config().clients.total_clients
+
+        assert per_client_classes_size == len(anchor_classes)
+
+        self.consistent_clients = np.random.choice(
+            list(range(total_clients)), size=consistent_clients_size, replace=False
+        )
+        self.anchor_classes = anchor_classes
+        self.keep_anchor_classes_size = keep_anchor_classes_size
+
+        # obtain the dataset information
+        if testing:
+            target_list = datasource.get_test_set().targets
+        else:
+            # the list of labels (targets) for all the examples
+            target_list = datasource.get_train_set().targets
+
+        self.targets_list = target_list
+        classes_text_list = datasource.classes()
+        classes_id_list = list(range(len(classes_text_list)))
+
+        self.clients_dataidx_map = {
+            client_id: np.ndarray(0, dtype=np.int64)
+            for client_id in range(total_clients)
+        }
+        # construct the quantity label skewness
+        self.quantity_label_skew(
+            dataset_labels=self.targets_list,
+            dataset_classes=classes_id_list,
+            num_clients=total_clients,
+            per_client_classes_size=per_client_classes_size,
+        )
+
+        self.subset_indices = self.clients_dataidx_map[client_id - 1]
+
+    def quantity_label_skew(
+        self, dataset_labels, dataset_classes, num_clients, per_client_classes_size
+    ):
+        """Achieve the quantity-based lable skewness"""
+        client_id = self.client_id
+        # each client contains the full classes
+        if per_client_classes_size == len(dataset_classes):
+            self.clients_dataidx_map = sampler_utils.assign_fully_classes(
+                dataset_labels, dataset_classes, num_clients, client_id
+            )
+        else:
+            self.clients_dataidx_map = sampler_utils.assign_sub_classes(
+                dataset_labels,
+                dataset_classes,
+                num_clients,
+                per_client_classes_size,
+                anchor_classes=self.anchor_classes,
+                consistent_clients=self.consistent_clients,
+                keep_anchor_classes_size=self.keep_anchor_classes_size,
+            )
+
+    def get(self):
+        """Obtains an instance of the sampler."""
+        gen = torch.Generator()
+        gen.manual_seed(self.random_seed)
+
+        return SubsetRandomSampler(self.subset_indices, generator=gen)
+
+    def num_samples(self):
+        """Returns the length of the dataset after sampling."""
+        return len(self.subset_indices)
+
+    def get_trainset_condition(self):
+        """Obtain the detailed information in the trainser"""
+        targets_array = np.array(self.targets_list)
+        client_sampled_subset_labels = targets_array[self.subset_indices]
+        unique, counts = np.unique(client_sampled_subset_labels, return_counts=True)
+        return np.asarray((unique, counts)).T

plato/samplers/modality_iid.py

@@ -0,0 +1,42 @@
+"""
+Samples data from a dataset, biased across modalities in an
+ independent and identically distributed (IID) fashion.
+
+    Thus, all modalities of one sample are utilized as the input.
+
+    There is no difference between the train sampler and test sampler.
+"""
+
+import numpy as np
+
+from plato.samplers import base
+
+
+class Sampler(base.Sampler):
+    """Create a data sampler for each client to use a randomly divided partition of the
+    dataset."""
+
+    def __init__(self, datasource, client_id):
+        super().__init__()
+
+        self.client_id = client_id
+        if hasattr(datasource, "get_modality_name"):
+            modalities_name = datasource.get_modality_name()
+        else:  # default: it only contains image data
+            modalities_name = ["rgb"]
+
+        np.random.seed(self.random_seed)
+
+        # obtain the modalities that hold for this data
+        self.subset_modalities = modalities_name
+
+    def get(self):
+        """Obtains the modality sampler.
+        Note: the sampler here is utilized as the mask to
+         remove modalities.
+        """
+        return self.subset_modalities
+
+    def modality_size(self):
+        """Obtain the utilized modality size"""
+        return len(self.subset_modalities)

plato/samplers/modality_quantity_noniid.py

@@ -0,0 +1,56 @@
+"""
+Samples data from a dataset, biased across modalities in an
+ quantity-based nonIID fashion.
+
+    Thus, the quantity-based modality non-IID can be achieved by just keeping
+     one subset of modalities in each sample.
+
+"""
+
+import numpy as np
+
+from plato.config import Config
+from plato.samplers import base
+
+
+class Sampler(base.Sampler):
+    """Create a data sampler for each client to use a randomly divided partition of the
+    dataset."""
+
+    def __init__(self, datasource, client_id):
+        super().__init__()
+        self.client_id = client_id
+        if hasattr(datasource, "get_modality_name"):
+            modalities_name = datasource.get_modality_name()
+        else:  # default: it only contains image data
+            modalities_name = ["rgb"]
+
+        # Different clients should have a different bias across modalities
+        np.random.seed(self.random_seed * int(client_id))
+
+        # default, one sample holds only one modality
+        per_client_modalties_size = (
+            Config().data.per_client_modalties_size
+            if hasattr(Config().data, "per_client_modalties_size")
+            else 1
+        )
+
+        assert per_client_modalties_size < len(modalities_name)
+
+        # obtain the modalities that hold for this data
+        self.subset_modalities = np.random.choice(
+            modalities_name,
+            per_client_modalties_size,
+            replace=False,
+        )
+
+    def get(self):
+        """Obtains the modality sampler.
+        Note: the sampler here is utilized as the mask to
+         remove modalities.
+        """
+        return self.subset_modalities
+
+    def modality_size(self):
+        """Obtain the utilized modality size"""
+        return len(self.subset_modalities)

plato/samplers/orthogonal.py

@@ -0,0 +1,99 @@
+"""
+A sampler for orthogonal cross-silo federated learning.
+Each insitution's clients have data of different classes.
+"""
+
+import numpy as np
+import torch
+from torch.utils.data import WeightedRandomSampler, SubsetRandomSampler
+from plato.config import Config
+
+from plato.samplers import base
+
+
+class Sampler(base.Sampler):
+    """Create a data sampler for each client to use a divided partition of the dataset.
+    A client only has data of certain classes."""
+
+    def __init__(self, datasource, client_id, testing):
+        super().__init__()
+
+        # Different clients should have a different bias across the labels
+        np.random.seed(self.random_seed * int(client_id))
+
+        self.partition_size = Config().data.partition_size
+
+        if testing:
+            target_list = datasource.get_test_set().targets
+        else:
+            # The list of labels (targets) for all the examples
+            target_list = datasource.targets()
+        class_list = datasource.classes()
+
+        max_client_id = int(Config().clients.total_clients)
+
+        if client_id > max_client_id:
+            # This client is an edge server
+            institution_id = client_id - 1 - max_client_id
+        else:
+            institution_id = (client_id - 1) % int(Config().algorithm.total_silos)
+
+        if hasattr(Config().data, "institution_class_ids"):
+            institution_class_ids = Config().data.institution_class_ids
+            class_ids = [x.strip() for x in institution_class_ids.split(";")][
+                institution_id
+            ]
+            class_id_list = [int(x.strip()) for x in class_ids.split(",")]
+        else:
+            class_ids = np.array_split(
+                [i for i in range(len(class_list))], Config().algorithm.total_silos
+            )[institution_id]
+            class_id_list = class_ids.tolist()
+
+        if (
+            hasattr(Config().data, "label_distribution")
+            and Config().data.label_distribution == "noniid"
+        ):
+            # Concentration parameter to be used in the Dirichlet distribution
+            concentration = (
+                Config().data.concentration
+                if hasattr(Config().data, "concentration")
+                else 1.0
+            )
+
+            class_proportions = np.random.dirichlet(
+                np.repeat(concentration, len(class_id_list))
+            )
+
+        else:
+            class_proportions = [
+                1.0 / len(class_id_list) for i in range(len(class_id_list))
+            ]
+
+        target_proportions = [0 for i in range(len(class_list))]
+        for index, class_id in enumerate(class_id_list):
+            target_proportions[class_id] = class_proportions[index]
+        target_proportions = np.asarray(target_proportions)
+
+        self.sample_weights = target_proportions[target_list]
+
+    def get(self):
+        """Obtains an instance of the sampler."""
+        gen = torch.Generator()
+        gen.manual_seed(self.random_seed)
+
+        # Samples without replacement using the sample weights
+        subset_indices = list(
+            WeightedRandomSampler(
+                weights=self.sample_weights,
+                num_samples=self.partition_size,
+                replacement=False,
+                generator=gen,
+            )
+        )
+
+        return SubsetRandomSampler(subset_indices, generator=gen)
+
+    def num_samples(self):
+        """Returns the length of the dataset after sampling."""
+        return self.partition_size