{"id":21341605,"url":"https://github.com/marksgraham/flip-sample-application","last_synced_at":"2026-03-19T20:00:53.989Z","repository":{"id":65386727,"uuid":"570259047","full_name":"marksgraham/flip-sample-application","owner":"marksgraham","description":"Example training application to run on FLIP","archived":false,"fork":false,"pushed_at":"2023-02-23T20:23:25.000Z","size":166196,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"develop","last_synced_at":"2025-01-22T15:36:25.496Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"answerdigital/flip-sample-application","license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marksgraham.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-11-24T18:06:00.000Z","updated_at":"2023-05-17T13:53:10.000Z","dependencies_parsed_at":"2025-01-22T15:42:02.109Z","dependency_job_id":null,"html_url":"https://github.com/marksgraham/flip-sample-application","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marksgraham%2Fflip-sample-application","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marksgraham%2Fflip-sample-application/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marksgraham%2Fflip-sample-application/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marksgraham%2Fflip-sample-application/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marksgraham","download_url":"https://codeload.github.com/marksgraham/flip-sample-application/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243817896,"owners_count":20352626,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-22T00:57:39.755Z","updated_at":"2026-01-03T05:05:34.394Z","avatar_url":"https://github.com/marksgraham.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\n\n# Sample FLIP Application\n\n![example workflow](https://github.com/answerconsulting/flip-sample-application/actions/workflows/nvflare-test.yml/badge.svg)\n\n\nThe purpose of this repository is to provide a sample application that can be developed and tested locally before being uploaded onto FLIP.\n## **How to use this repository**\n\nThis repository contains a simplified sample application that replicates a running application on FLIP. This application runs on [NVIDIA Flare](https://github.com/NVIDIA/NVFlare).\nDownload or clone this repository and use the `./flip-app` directory as a sample application to run in NVIDIA Flare.\n\n# *Workspace Setup*\n## **Setup NVFlare workspace with Docker 🐳** \n\nA dockerfile has been provided that will create a container with a NVFlare Server with two clients and start them.\nCopy any NVFlare Applications you wish to use to the ``/apps`` directory, the dockerfile will copy applications in this folder\nto the transfer section of the NVFlare Admin application.\n\n### 1. Build Image \u0026 Run Container\n\nUse the docker build commands and run the container\n\n```shell \ndocker build . -t nvflare-in-one``\ndocker run nvflare-in-one``\n```\n\n### 2. Execute \u0026 Monitor NVFlare\n\nIf you exec into the container\n\n``docker exec -it \u003cname\u003e bash``\n\nYou will be able to run ``fl-admin.sh``\nThe username and password for this container are ``admin``\nThis will grant you access to all the NVFlare Admin commands.\n\nThe logs for the model execution are written to STDOUT and can be accessible\n_by viewing the logs of the container_\n\n``docker logs \u003cname\u003e``\n\n### 3. Inserting Files into the container\n\nIf you wish to test the utillization of resources in your model E.g. DICOMS \nI recommend using the copy commnd to copy the files to the container\n\n```\ndocker cp \u003cpath_to_your_resource\u003e \u003ccontainer_name\u003e:/dir\n```\n\nYou can then edit the flip.py module and change the response to the parent directory of where your files were copied to\ne.g. ``/dir``\n\nWithin FLIP the files are identifiable by the accession number, as returned within the dataframe\n\n``/dir/\u003caccession_number\u003e``\n\n## Setup NVFlare Workspace without Docker 💻 \n\nFollow the [Installation](https://nvflare.readthedocs.io/en/2.0/installation.html) instructions.\n\n\u003e ⚠️ Please ensure you install version `2.0.16`\n\n\u003e Requires specific protobuf version [NVFlare GitHub Issue](https://github.com/NVIDIA/NVFlare/issues/608)\n\nInstall requirements:\n\nAll the requirements of NVFlare as well as additional packages used by FLIP have been provided in a requirements.txt file.\n\n```bash\npip install -r .\\requirements.txt\n```\n\n### 2. Setup your FL workspace\n\nFollow the [Quickstart](https://nvflare.readthedocs.io/en/2.0/quickstart.html) instructions to set up your POC (\"proof of concept\") workspace.\n\nEnsure you also copy this (`./flip-app`) directory into the NVFlare examples folder.\n\n```bash\nmkdir poc/admin/transfer/\u003cAPPLICATION_NAME\u003e\ncp -rf flip-app/* poc/admin/transfer/\u003cAPPLICATION_NAME\u003e\n```\n\n# Running the Sample Application flip-app\n\nThe `./apps/flip-app` directory contains a replica of an application that can be run on FLIP. Some modules are stubbed with only a return type set. There are two main files that FLIP requires before running any training - `trainer.py` and `validator.py`. Both of these files you will find within `flip-app/custom` and contain a working example application that can be used as a starting point.\nThis example uses [NVIDIA FLARE](https://nvidia.github.io/NVFlare) to train an image classifier using federated averaging ([FedAvg]([FedAvg](https://arxiv.org/abs/1602.05629))) and [PyTorch](https://pytorch.org/) as the deep learning training framework.\n\n\u003e **_NOTE:_** This example uses the [CIFAR-10](https://www.cs.toronto.edu/~kriz/cifar.html) dataset and will load its data within the trainer code.\n\nThese two files are where you should add your own application code. The `./samples` directory contains empty templates of both `trainer.py` and `validator.py`.\n\n\n### 3. Administration Console\n\nLog into the Admin client by entering `admin` for both the username and password.\nThen, use these Admin commands to run the experiment:\n\n```bash\nupload_app \u003cAPPLICATION_NAME\u003e\nset_run_number 1\ndeploy_app \u003cAPPLICATION_NAME\u003e all\nstart_app all\n```\n\n### 4. Shut down the server/clients\n\nTo shut down the clients and server, run the following Admin commands:\n```\nshutdown client\nshutdown server\n```\n\n\u003e **_NOTE:_** For more information about the Admin client, see [here](https://nvflare.readthedocs.io/en/2.0/user_guide/admin_commands.html).\n\n## **FLIP methods**\nThe following methods are available to be used in training, located in `flip.py`:\n\n- `get_dataframe(self, project_id: str, query: str) -\u003e DataFrame`\n  This retrieves data in the form of a Dataframe containing, at the minimum, accession IDs.\n  The method takes in the project ID and the project query as parameters. These values are\n  already passed in as parameters to the trainer to be used.\n\n- `get_by_accession_number(self, project_id: str, accession_id: str) -\u003e Path`\n  This downloads scans and places them in a directory made available for NVFlare to utilise.\n  The method takes in the project ID as a parameter as well as an accession ID, which can be \n  obtained from `get_dataframe`. It returns the path to where the scans are stored.\n\n- `add_resource(self, project_id: str, accession_id: str, scan_id: str, resource_id: str, files: List[str])`\n  This allows uploading scans to XNAT under the project that the model to. Scans are to be placed \n  in the `uploads` directory.\n  The method does not have a return type. It supports the following required parameters: \n    - project ID\n    - accession ID \n    - scan ID (ID/label of the directory at the scan level)\n    - resource ID (ID/label of the directory at the resource level) \n    - a list of files corresponding to the names of the files that reside within the `uploads` \n    directory that you wish to upload, e.g. [`scan-1.dcm`, `scan-2.dcm`, ...].\n\n  The list of files could also point to locations in subfolders relative to the uploads directory, \n  e.g. [`subfolder/scans/scan-1.dcm`, `scan-2.dcm`],\n  where `scan-1` has the path `uploads/subfolder/scans/scan-1.dcm` and `scan-2` has the path `uploads/scan-2.dcm`.\n\n- `update_status(self, model_id: str, new_model_status: ModelStatus)`\n  This method is for internal use only and is not to be called by the trainer.\n\n- `send_metrics_value(self, label: str, value: float, fl_ctx: FLContext)`\n  This method raises an event which allows the sending of metrics data back to the central hub.\n  The FL Server workflow component listens for these events and populates the data with the current global round and\n  model id before storing.\n  The method has no return type. It supports the following required parameters:\n  - label (Any string is valid. The value will be stored against this label)\n  - value\n  Some constant values are provided under `FlipMetricsLabel` in `utils/flip_constants` but is not required to use these\n\n- `handle_metrics_event(self, event_data: Shareable, global_round: int, model_id: str)`\n  This method is for internal use only and is not to be called by the trainer.\n\n### Import FLIP and call methods\n- Import the module: `from flip import FLIP`\n- Make an instance of the class: `flip = FLIP()`\n- Use the instance to call one of the methods: `dataframe = flip.get_dataframe(project_id, query)`\n\nThis will allow successful calls to any the methods in `flip.py`.\n\n## **Load config into trainer**\nThe `config.json` file allows variables to be defined and utilised within the trainer files.\n\nAn example of a config file:\n```\n{\n\t\"GLOBAL_ROUNDS\": 1,\n\t\"LOCAL_ROUNDS\": 1,\n\t\"ROUND_HALF_UP\": true,\n\t\"LOSS_FUNCTION_START_VALUE\": 1.0,\n\t\"DAYS_OF_WEEK\": [\n\t\t\"mon\",\n\t\t\"tue\",\n\t\t\"wed\",\n\t\t\"thu\",\n\t\t\"fri\",\n\t\t\"sat\",\n\t\t\"sun\"\n\t]\n}\n```\n\nTo use the config file within the trainer:\n\n```\nimport json\n\n\nself.config = {}\n\ncurrent_dir = os.path.dirname(__file__)\nconfig_file = os.path.join(current_dir, \"config.json\")\n\nwith open(config_file) as file:\n   self.config = json.load(file)\n```\n\nNOTE: As the sample application is a proof of concept, updating the global and local rounds in \nthe config file will not dynamically update the global and local round values.\n\n## Note for server config\nIn the file `config_fed_client.json` under the Cross Site Validation workflow, a parameter named\n`participating_clients` is passed in with the values `site-1` and `site-2` in a list. This may need\nmodifying depending on what clients you perform the training at locally. For example, if you only run\nthe training at `site-1`, then the list should should reflect that. Failure to do so could end up in a\nloop where the server is waiting for `site-2`'s response.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarksgraham%2Fflip-sample-application","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarksgraham%2Fflip-sample-application","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarksgraham%2Fflip-sample-application/lists"}