Add hierarchical statistics support

[apatole]

This change adds hierarchical federated statistics support.

The existing StatisticsController outputs global statistics in a flat hierarchy. There are usecases where global statistics are required to be generated as per the given hierarchy configuration where NVFlare clients can be specified to belong to a particular hierarchy.

The new class HierarchicalStatisticsController is added to support hierarchical statistics. It is derived from StatisticsController and takes additional argument hierarchy_config for hierarchy specification file providing details about all the clients and their hierarchy.

Example hierarchy config file contents:

{
    "Manufacturers": [
        {
            "Name": "Manufacturer-1",
            "Orgs": [
                 {
                     "Name": "Org-1",
                     "Sites": ["Site-1"]
                 },
                 {
                     "Name": "Org-2",
                     "Sites": ["Site-2"]
                 }
            ],
        },
        {
            "Name": "Manufacturer-2",
            "Orgs": [
                {
                    "Name": "Org-3",
                    "Sites": ["Site-3", "Site-4"]
                }
            ]
        },
    ]
}

The above hierarchy config specifies three level hierarchy for four NVFlare clients named 'Site-1', 'Site-2', 'Site-3' and 'Site-4'. And the generate global statistics output will in hierarchical format like below. At each hierarchical level, global statistics are caulculated whereas local statistics are reported at the last hierarchical level.

{
    "Global": {
        <Global stats>
    },
    "Manufacturers": [
        {
            "Name": "Manufacturer-1",
            "Global": {
                <Manufacturer level stats>
            },
            "Orgs": [
                {
                    "Name": "Org-1",
                    "Global": {
                        <Org level stats>
                    },
                    "Sites": [
                        {
                            "Name": "Site-1",
                            "Local": {
                                <Local stats>
                            },
                        },
                        {
                            "Name": "Site-2",
                            "Local": {
                                <Local stats>
                            },
                        }
                    ],
                },
            ]
        },
    ],
}

The number of hierarchical levels and the hierarchical level names are automatically calculated from the given hierarchy config. Any number of hierarchical levels are supported.

This change also adds unit test to test hierarchical global statistics up to four hierarchical levels.

Types of changes

• Non-breaking change (fix or new feature that would not break existing functionality).
• New tests added to cover the changes.
• Quick tests passed locally by running ./runtest.sh.
• In-line docstrings updated.

[yanchengnv]

Nice work! I added some comments and requested changes to be more consistent with FLARE code style.

[apatole]

Thanks @chesterxgchen and @yanchengnv for the review, I have incorporated all the review comments. Also removed few redundant source lines in the latest change, thanks

[yanchengnv]

Looks better. There seems to be a logical gap about hierarchy_config_json handling (see my comments). Also added some minor style suggestions.

[apatole]

Thanks @yanchengnv again for the review. I have incorporated review comments, hoping I addressed comments properly, let me know otherwise, thanks.

[yanchengnv]

Looks good!

[apatole]

Hi @yanchengnv @chesterxgchen, Looks like someone needs to also approve workflow runs to be able to pass workflow checks and merge PR once all checks passed.

[chesterxgchen]

Hi @yanchengnv @chesterxgchen, Looks like someone needs to also approve workflow runs to be able to pass workflow checks and merge PR once all checks passed.

I am at conference, will take another look after that,

[yanchengnv]

Hi @yanchengnv @chesterxgchen, Looks like someone needs to also approve workflow runs to be able to pass workflow checks and merge PR once all checks passed.

I am at conference, will take another look after that,

I already did it.

There are some format issues.
@apatole, please run "python -m isort" and "python -m black" against your code to fix these issues.

[apatole]

@yanchengnv no worries, thanks. Fixed one typo in copyright section in latest patch, it was introduced in earlier patch, thanks.

[yanchengnv]

LGTM

[apatole]

Looks like blossom-ci is still waiting to be triggered.

[apatole]

Hi @yanchengnv, please help getting the workflows triggered once and in merging the PR. Had to rebase the PR and it seems blossom-ci also is not getting triggered. Thanks.