Skip to content

Latest commit

 

History

History
206 lines (170 loc) · 10.1 KB

api.md

File metadata and controls

206 lines (170 loc) · 10.1 KB

@nextstrain/evofr-viz

evofr.exports.PanelDisplay

Display a panel of small-multiple graphs for different locations. This component should be provided data obtained via the useModelData hook. The params prop defines the graphs to be drawn. The styles prop defines any style overrides to the graphs. The locations prop allows you to define a subset of locations for which to draw graphs.

Kind: static React Component of @nextstrain/evofr-viz

Param Type Description
data ModelDataWrapper see useModelData
params GraphParameters
styles SmallMultipleStyles
locations Array | undefined default (undefined) displays all available locations

Example

// typical usage is to use a preset graph type
<PanelDisplay data={...} params={{preset: "frequency"}}/>

Example

// an example of defining the params yourself
// this will create a temporal line graph using the `I_smooth` key
<PanelDisplay data={...} params={{
  graphType: "lines",
  key: 'I_smooth',
  interval:  ['I_smooth_HDI_95_lower', 'I_smooth_HDI_95_upper'],
  intervalOpacity: 0.3,
  yDomain: getDomainUsingKey('I_smooth_HDI_95_upper'),
  tooltipXY: displayTopVariants(),
}}/>

Example

// custom styling can be provided which is applied to each small-multiple
<PanelDisplay data={...}
   styles={{height: 300, width: 400}}
   params={{preset: "stackedIncidence"}}
/>

evofr.exports.useModelData ⇒ ModelDataWrapper

Fetch and parse the model data (JSON). See the config type definition to understand the expected options. This returns an object containing the modelData (type: modelData) and any error messages. If an error is encountered we also print this to the console (console.error()). The return value is designed to be passed to a component's as its data prop.

Warning: Ensure the config object is not (re-)created within your react component, as this will trigger a re-fetch of the data and subsequent re-rendering of the graphs.

Kind: static constant of @nextstrain/evofr-viz

Param Type
config DatasetConfig

Example

const mlrData = useModelData(
  modelName: "MLR",
  modelUrl: "https://nextstrain-data.s3.amazonaws.com/files/workflows/forecasts-ncov/gisaid/nextstrain_clades/global/mlr/latest_results.json"
);

@nextstrain/evofr-viz~GraphParameters : Object

Configuration for how a graph is to be visualised. All/any of these properties may be set by the component. If a preset is set then it will be expanded into a meaningful set of these properties (see expandParams()).

Note that a deep equality check will be used to decide when (if) the params for an individual small-multiple have changes and the graph should therefore re-draw. Because functions are compared by reference you must memoize any functions or provide a consistent reference to them. A common case to avoid is defining the function within a react component (or within the prop declaration), as that function will be re-created each time the component renders.

Kind: inner typedef of @nextstrain/evofr-viz
Properties

Name Type Description
[preset] "stackedIncidence" | "R_t" | "growthAdvantage" | "frequency" Load a set of preset parameters. Any parameters re-defined here will overwrite those which come from the preset.
[graphType] "points" | "lines" | "stream"
[key] String
[interval] Array.<String>
[intervalOpacity] Number
[intervalStrokeWidth] Number
[dashedLines] Array.<Number> horizontal dashed lines
[xDomain] function | Array Function's this gives access to properties on the D3Graph instance
[yDomain] function | Array.<Number> Function's this gives access to properties on the D3Graph instance
[forecastLine] Boolean
[yTickFmt] function
[tooltipPt] function Function to return HTML when tooltip is attached to a point.
[tooltipXY] function Function to return HTML when tooltip is over any part of the graph.

@nextstrain/evofr-viz~TimePoint : Map

An data point representing a model estimate at a certain date Extra keys (e.g. "freq") are added in a data-dependent manner. Note that key suffixes _forecast are removed - i.e. a point associated with "freq_forecast" is stores under the "freq" key in this Map.

Kind: inner typedef of @nextstrain/evofr-viz
Properties

Name Type
date string | undefined

@nextstrain/evofr-viz~VariantPoint : Map

An data point representing a model estimate for a variant. The keys defined directly here are not specific to any date. Date-specific estimates are specified via temporal Extra keys (e.g. "ga") are added in a data-dependent manner.

Kind: inner typedef of @nextstrain/evofr-viz
Properties

Name Type Description
variant string | undefined Variant name
temporal Array | undefined Array of TimePoint estimates

@nextstrain/evofr-viz~ModelData : Map

Currently this Map represents the model data in its entirety and is generated ahead of time via the useModelData hook. This may change to a structure where the points, domains etc are generated by the visualisation component in the future. See NOTES.md for more.

Kind: inner typedef of @nextstrain/evofr-viz
Properties

Name Type Description
points Points
variants Array modelJson.metadata.variants
dates Array sorted array of YYYY-MM-DD dates, guaranteed not to have any holes. These dates bridge both modelJson.metadata.dates and modelJson.metadata.forecast_dates.
locations Array modelJson.metadata.location
dateIdx Map lookup for date string -> idx in dates array
variantColors Map provided via DatasetConfig. Overrides data set in the JSON. Default colors set if not provided.
variantDisplayNames Map provided via DatasetConfig. Overrides data set in the JSON. Keys used if not provided.
pivot String Currently the final entry in the model's list of variants
nowcastFinalDate string
updated string
domains Object

@nextstrain/evofr-viz~ModelDataWrapper : Object

Kind: inner typedef of @nextstrain/evofr-viz
Properties

Name Type Description
modelData ModelData | undefined
error String | undefined Errors encountered during JSON fetch / parse

@nextstrain/evofr-viz~DatasetConfig : Object

Configuration for the datasets to fetch & parse Currently the library is only built for forecasts-ncov model data and so there are hardcoded expectations. These will be lifted up and made config-options so that this library is pathogen agnostic.

Kind: inner typedef of @nextstrain/evofr-viz
Properties

Name Type Description
modelName string Name of the model - used to improve clarity of error messages
modelUrl string Address to fetch the model JSON from
[sites] Set list of sites to extract from JSON. If not provided we will use the sites set in the JSON metadata.
[variantColors] Map.<string, string> colors for the variants specified in the model JSONs. A default colour scale is available.
[variantDisplayNames] Map.<string, string> display names for the variants specified in the model JSONs. If not provided we use the keys as names.