Skip to content

Data Specifications

Jump to bottom
Spencer Childress edited this page Sep 18, 2024 · 24 revisions

Metric Results

This dataset contains the output of the metric analysis. For each group (typically site) the dataset provides the metric metric, its score, and the flagging of the score given the defined thresholds. This dataset applies to these modules:

  • scatter plot
  • bar chart

Data must be filtered on a single workflow ID prior to initializing a chart. For example:

const results = results_summary
    .filter(result => result.workflowid === 'kri0001');

Structure

  • array with one item/record per:
    • workflow ID
    • group ID

Specification

Property Type Description
studyid string Unique study identifier
workflowid string Unique workflow identifier
groupid string Unique group identifier
numerator number Numerator in metric calculation
denominator number Denominator in metric calculation
metric number Metric value
score number Group score given metric value
flag number Flag assigned to group given score and defined thresholds

Example data

Metric Metadata

This dataset contains the metadata associated with each metric. This dataset applies to these modules:

  • scatter plot
  • bar chart
  • time series
  • sparkline of score/metric
  • sparkline of flag counts by metric

Data must be filtered on a single workflow ID prior to initializing a chart. For example:

const metadata = results_summary
    .filter(workflow => workflow.workflowid === 'kri0001');

Structure

  • object representing a single workflow ID

Specification

Property Type Description
workflowid string Unique workflow identifier
gsm_version string {gsm} version
group string Analysis stratification (site, country, etc.)
metric string metric definition
numerator string Numerator in metric calculation
denominator string Denominator in metric calculation
outcome string metric type (rate, percent, etc.)
model string Statistical method
score string Analysis output measure with which to score metric value
data_inputs string Input data domains required to evaluate metric
data_filters string metric-specific subset applied to input data

Example data

Metric Bounds

This dataset contains the calculated bounds associated with the score returned by the metric analysis. This dataset applies to these modules:

  • scatter plot

Data must be filtered on a single workflow ID prior to initializing a chart. For example:

const bounds = results_bounds
    .filter(bound => bound.workflowid === 'kri0001');

Structure

  • array with one item/record per:
    • workflow ID
    • threshold
    • x-value

Specification

Property Type Description
studyid string Unique study identifier
workflowid string Unique workflow identifier
threshold number metric score threshold
denominator number X-value
numerator number Y-value

Example data

Metric Parameters

This dataset contains the parameters of the metric analysis, including thresholds. This dataset applies to these modules:

  • bar chart of score
  • time series of score
  • sparkline of score

Data must be filtered on a single workflow ID prior to initializing a chart and custom parameters take precedence over default parameters. For example:

const parameters_default = meta_param
    .filter(parameter_default => (
        parameter_default.workflowid === 'kri0001'
    ));

const parameters_custom = status_param
    .filter(parameter_custom => (
        parameter_custom.workflowid === 'kri0001'
    ));

// TODO: use a join here
const parameters = parameters_default.map(parameter_default => {
    const parameter_custom = parameters_custom
        .find(parameter_custom => (
            parameter_custom.param === parameter_default.param &&
            parameter_custom.index === parameter_default.index
        ));

    return parameter_custom === undefined
        ? parameter_default
        : parameter_custom;
});

Structure

  • array with one item/record per:
    • workflow ID
    • parameter
    • parameter index

Specification

Property Type Description
workflowid string Unique workflow identifier
gsm_version string version of {gsm} used to generate output
param string metric parameter
index number index of metric parameter
default string default metric parameter value
configurable boolean configurable by user?

Example data

Metric Parameters Over Time

This dataset contains the parameters of the metric analysis, including thresholds, across snapshots. This dataset applies to these modules:

  • time series of score

Data must be filtered on a single workflow ID prior to initializing a chart and custom parameters take precedence over default parameters. For example:

const parametersDefault = meta_param
    .filter(parameter_default => (
        parameter_default.workflowid === 'kri0001'
    ));

const parametersCustom = status_param_over_time
    .filter(parameterCustom => (
        parameterCustom.workflowid === 'kri0001'
    ));

const snapshotDates = [
    ...new Set(parametersCustom.map(parameter => parameter.snapshot_date)).values()
];

// TODO: use a join here
const parameters = parameters_default.map(parameter_default => {
    const parameter_custom = parameters_custom
        .find(parameter_custom => (
            parameter_custom.param === parameter_default.param &&
            parameter_custom.index === parameter_default.index
        ));

    return parameter_custom === undefined ? parameter_default : parameter_custom;
});

Structure

  • array with one item/record per:
    • snapshot date
    • workflow ID
    • parameter
    • parameter index

Specification

Property Type Description
workflowid string Unique workflow identifier
gsm_version string version of {gsm} used to generate output
param string metric parameter
index number index of metric parameter
value string default metric parameter value
gsm_analysis_date string Date {gsm} was run (yyyy-mm-dd)

Example data

Metric Results Over Time

This dataset contains metric results for each snapshot. The only difference is an additional variable, snapshot_date, that identifies the date of the analysis. This dataset applies to these modules:

  • time series of score/metric
  • sparkline of score/metric

Data must be filtered on a single workflow ID prior to initializing a chart. For example:

const resultsSummaryOverTime = results_summary_over_time.filter(
    d => d.workflowid === 'kri0001'
);

Structure

  • array with one item/record per:
    • snapshot date
    • workflow ID
    • group ID

Specification

Property Type Description
studyid string Unique study identifier
workflowid string Unique workflow identifier
groupid string Unique group identifier
numerator number Numerator in metric calculation
denominator number Denominator in metric calculation
metric number metric value
score number Group score given metric value
flag number Flag assigned to group given score and defined thresholds
snapshot_date string date of analysis (yyyy-mm-dd)

Example data

Flag Counts by metric

This dataset contains the number of at risk and flagged groups at each snapshot by metric. This dataset applies to these modules:

  • sparkline of flag counts by metric

Longitudinal data must be aggregated by workflowid and snapshot_date prior to initializing the sparkline. For example:

const n = new Set(
    results_summary_over_time.map(d => d.groupid)
).size;

const flag_counts_by_kri = d3.flatRollup(
    results_summary_over_time,
    workflowid => {
        const n_at_risk = workflowid
            .filter(d => Math.abs(+d.flag) === 1)
            .length;
        const n_flagged = workflowid
            .filter(d => Math.abs(+d.flag) === 2)
            .length;
        const n_at_risk_or_flagged = n_at_risk + n_flagged;

        return {
            n,
            n_at_risk,
            n_flagged
            n_at_risk_or_flagged,
        };
    },
    d => d.snapshot_date,
    d => d.workflowid
);

Structure

  • array with one item/record per:
    • snapshot date
    • workflow ID

Flags

Property Type Description
studyid string Unique study identifier
workflowid string Unique metric identifier
snapshot_date string date of analysis (yyyy-mm-dd)
n number Number of groups
n_at_risk number Number of groups where flag is -1 or 1
n_flagged number Number of groups where flag is -2 or 2
n_at_risk_or_flagged number number of groups where flag is -2, -1, 1, or 1

Example data

Flag Counts by Group

This dataset contains the number of at risk and flagged metrics at each snapshot by group. This dataset applies to these modules:

  • sparkline of flag counts by group

Longtiduinal data must be aggregated by groupid and snapshot_date prior to initializing the sparkline. For example:

const n = new Set(
    results_summary_over_time.map(d => d.groupid)
).size;

const flag_counts_by_group = d3.flatRollup(
    results_summary_over_time,
    groupid => {
        const n_at_risk = groupid
            .filter(d => Math.abs(+d.flag) === 1)
            .length;
        const n_flagged = groupid
            .filter(d => Math.abs(+d.flag) === 2)
            .length;
        const n_at_risk_or_flagged = n_at_risk + n_flagged;

        return {
            n,
            n_at_risk,
            n_flagged,
            n_at_risk_or_flagged,
        };
    },
    d => d.snapshot_date,
    d => d.groupid
);

Structure

  • array with one item/record per:
    • snapshot date
    • group ID

Flags

Property Type Description
studyid string Unique study identifier
groupid string Unique group identifier
snapshot_date string date of analysis (yyyy-mm-dd)
n number Number of metrics
n_at_risk number Number of metrics where flag is -1 or 1
n_flagged number Number of metrics where flag is -2 or 2
n_at_risk_or_flagged number number of metrics where flag is -2, -1, 1, or 1

Example data

Additional Analysis Ouput

This dataset contains additional analysis output for each snapshot, including confidence intervals of QTL analysis results. This dataset applies to these modules:

  • time series of QTL metric
  • sparkline of score/metric

Data must be filtered on a single workflow ID prior to initializing a chart. For example:

const resultsAnalysisOverTime = results_summary_over_time.filter(
    d => d.workflowid === 'qtl0004'
);

Structure

  • array with one item/record per:
    • snapshot date
    • workflow ID

Specification

Property Type Description
studyid string Unique study identifier
workflowid string Unique workflow identifier
param string Name of statistic
value number Value
gsm_analysis_date string date of analysis (yyyy-mm-dd)
snapshot_date string date of data snapshot (yyyy-mm-dd)

Clone this wiki locally