Examples

This section provides practical examples of using the DDI Toolkit.

DDI-Codebook Examples

Basic Metadata Extraction

from dartfx.ddi import ddicodebook

# Load codebook
cb = ddicodebook.loadxml('survey_data.xml')

# Access study metadata
if cb.studyDscr:
    title = cb.studyDscr.citation.titlStmt.titl.content
    print(f"Title: {title}")

DDI-CDI Assistant Framework

The CdiClassAssistant is the recommended way to work with DDI-CDI. It manages object lifecycles, identifiers, and RDF-ready structures.

Creating a DataSet with Variables

from dartfx.ddi.ddicdi import model_1_0_0 as model
from dartfx.ddi.ddicdi.assistants import CdiClassAssistant

# Create a dataset (automates identifier generation)
dataset = CdiClassAssistant.create(model.DataSet, name="MyDataset")

# Create variables and relate them
# Note how 'add_variable' is available because InstanceVariable
# is a valid property/association in the DataSet context
var1 = CdiClassAssistant.create(model.InstanceVariable, name="AGE")
dataset.add_variable(var1)

var2 = CdiClassAssistant.create(model.InstanceVariable, name="GENDER")
dataset.add_variable(var2)

Serialization to RDF

# Generate a standard rdflib graph
graph = dataset.to_rdf_graph()

# Export to Turtle
print(graph.serialize(format="turtle"))

Automated Identification

The Assistant framework uses a factory pattern to handle prefixing and unique IDs:

dataset = CdiClassAssistant.factory(
    model.DataSet,
    id_prefix="http://example.org/study/",
    id_suffix="dataset-01",
    name="Main Dataset"
)
print(dataset.id) # Output: http://example.org/study/dataset-01

Direct Model Usage

For power users who need to avoid the Assistant wrapper and work directly with the Pydantic models:

from dartfx.ddi.ddicdi import model_1_0_0 as model

# Create instance directly
irdi = model.InternationalRegistrationDataIdentifier(
    dataIdentifier="VAR001",
    registrationAuthorityIdentifier="TEST_AUTH"
)
identifier = model.Identifier(ddiIdentifier=irdi)
variable = model.InstanceVariable(identifier=identifier)

# Serialize directly
graph = variable.to_rdf_graph()

DDI-Codebook to DDI-CDI Mapping

Convenience utilities exist to transform legacy metadata into the modern CDI format:

from dartfx.ddi.utils import codebook_to_cdif
from dartfx.ddi import ddicodebook

cb = ddicodebook.loadxml('survey.xml')

# Maps the whole codebook to a dict of Assistants
resources = codebook_to_cdif(cb, baseuri="http://my-archive.org/data/")

for uri, assistant in resources.items():
    if isinstance(assistant.resource, model.InstanceVariable):
        print(f"Variable mapped: {uri}")

Specification Loader

Introspect the DDI-CDI structure:

from dartfx.ddi.ddicdi.specification import DdiCdiModel

cdi_spec = DdiCdiModel(root_dir='specifications/ddi-cdi-1.0')

# Find associations for a specific class
assoc = cdi_spec.get_resource_associations('cdi:InstanceVariable', cardinalities=True)
for uri, info in assoc.items():
    print(f"Association: {uri} (To: {info['to']['display']})")