This demo shows how three organizations can work together to jointly offer
a cohort of data from three independent hospitals.  The data must remain
private, but they wish to offer detailed aggregate reporting which can
virtually combine all their patient data.

The demo involves three organizations:
A) Blue Sky Memorial Hospital
   This organization uses Microsoft Azure to hold their native data.  They are
   only a Data Provider in this federation.
B) General Prophecy Hospital
   This organization uses Oracle databases for their patient data.  They are
   only a Data Provider in this federation.
C) Harmony Research Hospital
   This organization uses Postgres to hold their data.  They are acting
   as both Data Provider and the Aggregator for this federation.

All three organizations will install a TripleBlind Access Point to facilitate
this collaboration.

=================================================
STANDARD VIEWS
=================================================

The hospitals agree upon these standard table views to enable their
collaboration:

    "Patient" table
        - PatientID
        - PatientDOB        (in Date format)
        - City
        - State
        - PostalCode
        - Sex               (either "Male" or "Female")

    "Billed Visit" table
        - PatientID
        - AdmitDate         (in Date format)
        - DischargeDate     (in Date format)
        - VisitType         (either 'Inpatient' or 'Outpatient')
        - BillingCode       (e.g. ICD-9 or ICD-10 codes)
        - ProcedureCode     (e.g. a CPT code)
        - NetCharges

    where Date is defined as YYYY-MM-DD


Each hospital will run their own script to define these two tables, found
in the script files:
  1a_position_views_mssql.py
  1b_position_views_oracle.py
  1c_position_views_psql.py
Within each of these scripts, the specifics of their databases are addressed
and differences in their internal data definitions are addressed.

Note that none of the organizations needs to understand anything about the
database type or the internal definitions of the others. All that is required
is creating the standard view and sharing the name (or Asset ID) of their
created tables.


=================================================
CREATING THE FEDERATED GROUP
=================================================
Now that each Data Provider has generated assets to provider a standard view
of their portion of the data, the Aggregator can build the Federated Group
using the script:
  2_create_fed_group.py

Note that this script can be rerun later to easily expand the list of data
providers in the Federation Group to provide larger cohorts.


=================================================
CREATING A FEDERATED REPORT TEMPLATE
=================================================
Reports can now be defined to work against the standard views.  The report
creator only needs to think about the standard view definition, they don't
need to be concerned with any data provider's internal representation or
mappings -- those happen automatically.

Report definitions consist of four basic pieces:
  * User selectable parameters
    Any number of parameters can be offered to the user of the report.
    Parameters can include numbers, string values, code system lookups
    (such as ICD9 codes) and dates.  Parameters include prompts, list of values
    and/or bounds and formats.
  * Query template against the standard view
    This is an SQL query to be performed against the standard tables and fields.
    The template can reference the user selected parameters.
  * Aggregation
    Query results from all of the data providers are aggregated in priv
  * Final reporting
    The report can automatically return the simple aggregated results,
    or the report writer can write perform nearly any kind of post-processing on
    the results to generate a custom report.

The Aggregator will define the report using the script:
  3_create_fed_report.py

This single asset defines all of the steps in the reporting process and once it
has been defined it cannot be altered in any way.

=================================================
FINAL AGREEMENTS
=================================================
All participants in the federation retain complete control over how their own
data is used.  In order for a federated report to be operational, each
Data Provider needs to agree to allow their data to be utilized.  Since the
report is immutable, they can be absolutely certain that their data is used
only in ways they agree with.

For convenience, all of the agreements are created in the script:
  4_create_agreements.py


=================================================
RUNNING A REPORT
=================================================
At the time of usage, the consumer of the report has the ability to select the
parameters for the report from the options defined when the report was created.
Additionally, they can optionally select which data providers to included when
generating the report.

Reports can be launched from the web interface's Report Library, or they can
be invoked using a Python script such as:
  5_run_fed_report.py

Whenever a report is run, the query is executed by each of the Data Providers
and aggregation and post-processing automatically happens before the final
report is returned to the consumer.
