Define new variables

Note

If you don’t need to define new variables, you can skip this page entirely.

To introduce a new variable into Data Commons, you use an MCF file to explicitly assign it a new DCID. Variables can live in a single file with the .mcf suffix, or be split across several files — your choice.

File structure

An MCF file is a set of nodes. Here’s how three related variables are declared:

Node: dcid:br/Prevalence_PhysicalActivity_Person_Adult
typeOf: dcid:StatisticalVariable
name: "Prevalência de prática regular de atividade física entre adultos (%)"
populationType: dcid:Person
measuredProperty: dcid:percent

Node: dcid:br/Prevalence_PhysicalActivity_Person_Adult_Female
typeOf: dcid:StatisticalVariable
name: "Prevalência de prática regular de atividade física entre adultos (%) [Feminino]"
populationType: dcid:Person
measuredProperty: dcid:percent
gender: dcid:Female

Node: dcid:br/Prevalence_PhysicalActivity_Person_Adult_Male
typeOf: dcid:StatisticalVariable
name: "Prevalência de prática regular de atividade física entre adultos (%) [Masculino]"
populationType: dcid:Person
measuredProperty: dcid:percent
gender: dcid:Male

The variables above cover physical activity among adults. Because the data is also available for the “male” and “female” groups, two more variables are needed — partial combinations of attributes must be represented independently.

Every field that references an existing concept must be prefixed with dcid: or dcs:. All other values go in quotes. The order of nodes and of their fields doesn’t matter.

Required fields

Field	Description
Node	The DCID of the new variable — up to 256 characters.
typeOf	For statistical variables, always dcid:StatisticalVariable.
populationType	The type of thing being measured; must be an existing Class (otherwise a new entity has to be created).
measuredProperty	The property being measured. Must be a property of the population type — browse them at https://datacommons.org/browser/<populationType>.

Optional fields

Field	Description
description	A textual description of the variable.
statType	Defaults to dcid:measuredValue. Other values include minValue, maxValue, meanValue, medianValue, sumValue, varianceValue, marginOfError, stdError.
measurementQualifier	Important when the time interval changes the variable’s meaning or values swing a lot by period. Possible values: Weekly, Monthly, Annual.
measurementDenominator	For variables defined as a percentage or ratio, points to the statistical variable in the denominator. For per-capita, the value would be Count_Person.

Finally, you can define properties that act as constraints on the populationType. In the example, gender is a property of Person used to restrict the variable to a specific population group.

Naming conventions

Variable DCIDs follow a few conventions: names are in English, use PascalCase, are prefixed with dcid:br/, and use _ to separate properties. The general format is:

br/statType_measuredProperty_populationType_constraintValue1_constraintValue2

Some specific cases:

• When statType is the default value, it can be omitted from the name.
• When measurementQualifier is set, add its value as a prefix (at the start of the name).
• When measurementDenominator is set, add the suffix AsAFractionOf_<value>.
• For constraints, order the values alphabetically.

Examples that follow these conventions:

br/Count_Person
br/Count_Person_Female
br/Prevalence_PhysicalActivity_Person_Adult

Grouping variables

By default, variables show up in the Statistical Variable Explorer under predefined categories. To make a variable easier to discover, associate it with one or more groups.

Groups are technically optional and unlimited in number, and can even be organized hierarchically. By convention, though, every variable on the platform should belong to at least one group. Group identifiers are in English, use PascalCase, and take the prefix dcid:br/g/.

Here a group for physical-activity variables is defined as a subgroup of the health area:

Node: dcid:br/Prevalence_PhysicalActivity_Person_Adult
...
memberOf: dcid:br/g/PhysicalActivity

Node: dcid:br/Prevalence_PhysicalActivity_Person_Adult_Female
...
memberOf: dcid:br/g/PhysicalActivity

Node: dcid:br/Prevalence_PhysicalActivity_Person_Adult_Male
...
memberOf: dcid:br/g/PhysicalActivity

Node: dcid:br/g/PhysicalActivity
typeOf: dcid:StatVarGroup
name: "Atividade Física"
specializationOf: dcid:dc/br/g/Health

A variable can belong to as many groups as needed — list several identifiers in memberOf, separated by commas.

The four fields used to define a group are all required:

Field	Description
Node	The DCID of the group. English, PascalCase, prefix br/g/.
typeOf	For statistical-variable groups, always dcid:StatVarGroup.
name	The title shown in the Statistical Variable Explorer.
specializationOf	Defines the hierarchy between groups. For top-level groups, the value is dcid:dc/g/Root.

Note

Most of the big thematic areas are already defined in Brasil Data Commons, so you’ll rarely need to create a group directly under dcid:dc/g/Root. In most cases, just find the most appropriate thematic area and define your new group as a specialization of an existing one.

Next, tie everything together in the configuration file.