odmlib.dataset_json_1_1

Dataset-JSON v1.1 support using the ODMElement/descriptor pattern.

Dataset-JSON v1.1 model package for odmlib.

Provides ODMElement-based classes conforming to the CDISC Dataset-JSON v1.1 specification, with JSON and NDJSON serialization support. Also provides a Define-XML v2.1 metadata flattener for converting Define-XML metadata into tabular Dataset-JSON datasets, and converters between Dataset-XML 1.0.1 and Dataset-JSON v1.1.

class odmlib.dataset_json_1_1.DatasetJSON(**kwargs)[source]

Bases: DatasetJSONElement

Root element for a Dataset-JSON v1.1 file.

Represents a single dataset (one per file) conforming to the CDISC Dataset-JSON v1.1 specification. Contains file-level metadata, column definitions, and row data.

datasetJSONCreationDateTime

ISO 8601 creation timestamp.

Type:: str, required

datasetJSONVersion

Specification version (pattern: 1.1(.N)?).

Type:: str, required

fileOID

Unique file identifier.

Type:: str

dbLastModifiedDateTime

ISO 8601 timestamp of last database modification.

Type:: str

originator

Organization that generated the file.

Type:: str

sourceSystem

Source system information object.

Type:: SourceSystem

studyOID

Study OID (foreign key to ODM Study).

Type:: str

metaDataVersionOID

MetaDataVersion OID (foreign key to ODM).

Type:: str

metaDataRef

URI to metadata file (e.g., Define-XML).

Type:: str

itemGroupOID

ItemGroupDef OID (foreign key to Define-XML).

Type:: str, required

records

Total number of records (>= 0).

Type:: int, required

name

Dataset name (e.g., “DM”, “AE”).

Type:: str, required

label

Dataset description.

Type:: str, required

columns

Column metadata definitions.

Type:: list[Column]

rows

Array of row arrays. Each row is a list of values matching the column order. None indicates missing values.

Type:: list

datasetJSONCreationDateTime: Descriptor for string-valued ODM attributes.

datasetJSONVersion: Descriptor for string-valued ODM attributes.

fileOID: Descriptor for string-valued ODM attributes.

dbLastModifiedDateTime: Descriptor for string-valued ODM attributes.

originator: Descriptor for string-valued ODM attributes.

sourceSystem

Descriptor for a single child ODM element.

Stores a reference to the element class and validates type on assignment. When accessed on an unset optional attribute, instantiates the element class with no arguments.

Parameters:

element_class (type) – The expected child element class.
namespace (str) – XML namespace prefix (default: “odm”).

studyOID: Descriptor for string-valued ODM attributes.

metaDataVersionOID: Descriptor for string-valued ODM attributes.

metaDataRef: Descriptor for string-valued ODM attributes.

itemGroupOID: Descriptor for string-valued ODM attributes.

records

Descriptor for non-negative integer attributes (value >= 0).

Combines integer type validation with non-negative constraint. Used for SignificantDigits and similar attributes.

name: Descriptor for the Name attribute of ODM elements.

label: Descriptor for string-valued ODM attributes.

columns

Descriptor for a list of child ODM elements.

Validates that all items assigned to the list are instances of the expected element class. Stored as a plain list in the instance.

Parameters:

element_class (type) – The class that all list items must be.
namespace (str) – XML namespace prefix (default: “odm”).

rows: Descriptor for list-valued attributes.

__init__(**kwargs)[source]

Initialize a DatasetJSON instance.

Ensures columns is always initialized (defaults to []) since it is required by the Dataset-JSON v1.1 schema.

property column_names: list

Return the list of column variable names.

Returns:: Variable names from each Column’s name attribute.
Return type:: list[str]

add_column(column)[source]

Append a Column to this dataset’s column list.

Parameters:: column (Column) – Column metadata to add.
Raises:: OdmlibTypeError – If column is not a Column instance.
Return type:: None

add_row(values)[source]

Append a row of values to this dataset.

Validates that the number of values matches the number of columns. Automatically increments the records count.

Parameters:: values (list) – List of values in column order. Use None for missing values.
Raises:: ValueError – If len(values) does not match len(columns).
Return type:: None

to_dict()[source]

Serialize to a spec-conformant Dataset-JSON v1.1 dictionary.

Omits empty rows for metadata-only mode (records > 0 but no row data transferred). All other behavior inherited from DatasetJSONElement.to_dict().

Returns:: Dataset-JSON v1.1 conformant dictionary.
Return type:: dict

to_json(indent=2)[source]

Serialize to a JSON string.

Parameters:: indent (int) – JSON indentation level (default: 2).
Returns:: JSON string representation.
Return type:: str

write_json(filename, indent=2)[source]

Write this dataset to a JSON file.

Parameters:

filename (str) – Output file path.
indent (int) – JSON indentation level (default: 2).

Return type:

None

write_ndjson(filename)[source]

Write this dataset to an NDJSON file.

NDJSON format: line 1 is the metadata (everything except rows), lines 2+ are one row array per line.

Parameters:: filename (str) – Output file path.
Return type:: None

classmethod from_dict(data)[source]

Construct a DatasetJSON from a dictionary.

Handles nested construction of Column and SourceSystem objects from their dict representations.

Parameters:: data (dict) – Dictionary with Dataset-JSON v1.1 fields.
Returns:: Constructed instance.
Return type:: DatasetJSON

classmethod from_json(json_string)[source]

Construct a DatasetJSON from a JSON string.

Parameters:: json_string (str) – JSON string with Dataset-JSON v1.1 fields.
Returns:: Constructed instance.
Return type:: DatasetJSON

classmethod read_json(filename)[source]

Read a DatasetJSON from a JSON file.

Parameters:: filename (str) – Input file path.
Returns:: Constructed instance.
Return type:: DatasetJSON

classmethod read_ndjson(filename)[source]

Read a DatasetJSON from an NDJSON file.

NDJSON format: line 1 is the metadata (everything except rows), lines 2+ are one row array per line.

Parameters:: filename (str) – Input file path.
Returns:: Constructed instance.
Return type:: DatasetJSON

namespace = 'odm'

class odmlib.dataset_json_1_1.Column(**kwargs)[source]

Bases: DatasetJSONElement

Column (variable) metadata for a Dataset-JSON v1.1 dataset.

Each column describes one variable in the dataset, including its OID, name, label, data type, and optional formatting information.

Parameters:: kwargs (Any)

itemOID

Variable OID (corresponds to ItemDef.OID in Define-XML).

Type:: str, required

name

Variable name (e.g., “STUDYID”, “AETERM”).

Type:: str, required

label

Human-readable variable description.

Type:: str, required

dataType

Logical data type. One of: “string”, “integer”, “decimal”, “float”, “double”, “boolean”, “datetime”, “date”, “time”, “URI”.

Type:: str, required

targetDataType

Target data type for type conversion. Only “integer” or “decimal” are valid.

Type:: str

length

Maximum variable length (must be >= 1).

Type:: int

displayFormat

SAS-style display format (e.g., “DATE9.”).

Type:: str

keySequence

Key variable ordering (must be >= 1).

Type:: int

itemOID: Descriptor for string-valued ODM attributes.

name: Descriptor for the Name attribute of ODM elements.

label: Descriptor for string-valued ODM attributes.

dataType

Descriptor that validates against an explicit list of permitted values.

Unlike ValidValues, the allowed values are provided at class definition time in the valid_values list argument.

targetDataType

Descriptor that validates against an explicit list of permitted values.

Unlike ValidValues, the allowed values are provided at class definition time in the valid_values list argument.

length

Descriptor for positive integer attributes (value > 0).

Combines integer type validation with positive value constraint. Used for Length, ItemGroupDataSeq, and similar attributes.

displayFormat: Descriptor for string-valued ODM attributes.

keySequence

Descriptor for positive integer attributes (value > 0).

Combines integer type validation with positive value constraint. Used for Length, ItemGroupDataSeq, and similar attributes.

namespace = 'odm'

class odmlib.dataset_json_1_1.SourceSystem(**kwargs)[source]

Bases: DatasetJSONElement

Source system information (optional nested object in Dataset-JSON v1.1).

Parameters:: kwargs (Any)

name

The name of the source system.

Type:: str, required

version

The version of the source system.

Type:: str, required

name: Descriptor for string-valued ODM attributes.

version: Descriptor for string-valued ODM attributes.

namespace = 'odm'

class odmlib.dataset_json_1_1.DefineFlattener(odm_root, study_idx=0)[source]

Bases: object

Convert Define-XML v2.1 metadata into tabular Dataset-JSON datasets.

Initializes with a loaded Define-XML v2.1 ODM root object and provides methods to flatten each metadata element type into a separate Dataset-JSON v1.1 dataset.

Parameters:

odm_root (Any) – A loaded Define-XML v2.1 ODM root object (from odmlib loader).
study_idx (int) – Index of the Study element to use (default: 0). For Define-XML, there is always exactly one Study.

Example:

import odmlib.define_loader as DL
import odmlib.loader as LD
from odmlib.dataset_json_1_1.define_flattener import DefineFlattener

loader = LD.ODMLoader(DL.XMLDefineLoader(model_package='define_2_1'))
loader.open_odm_document('define.xml')
odm = loader.root()

flattener = DefineFlattener(odm)
datasets = flattener.flatten_all()
flattener.write_all('/output/dir')

DATASET_JSON_VERSION = '1.1.0'

TABLE_NAMES = ['study', 'standards', 'datasets', 'variables', 'value_level', 'where_clauses', 'methods', 'comments', 'documents', 'codelists', 'codelist_terms']

EXTRA_TABLE_NAMES = ['aliases', 'origins']

flatten_all()[source]

Flatten all Define-XML metadata into Dataset-JSON datasets.

Returns:

Mapping of dataset name to DatasetJSON: for all 11 metadata tables.

Return type:

dict[str, DatasetJSON]

write_all(output_dir, indent=2)[source]

Write all metadata datasets to individual JSON files.

Parameters:

output_dir (str) – Directory to write files to. Created if it does not exist.
indent (int) – JSON indentation level (default: 2).

Returns:

List of written file paths.

Return type:

list[str]

flatten_study()[source]

Flatten ODM root + Study + GlobalVariables + MetaDataVersion.

Returns:: Single-row dataset with study-level metadata.
Return type:: DatasetJSON

flatten_standards()[source]

Flatten MetaDataVersion.Standards.Standard elements.

Returns:

One row per Standard element. Empty if Standards: are not loaded (known limitation).

Return type:

DatasetJSON

flatten_datasets()[source]

Flatten MetaDataVersion.ItemGroupDef elements.

Returns:: One row per ItemGroupDef (dataset definition).
Return type:: DatasetJSON

flatten_variables()[source]

Flatten ItemRef + ItemDef pairs within each ItemGroupDef.

Returns:: One row per variable (ItemRef+ItemDef) per dataset.
Return type:: DatasetJSON

flatten_value_level()[source]

Flatten ValueListDef ItemRef entries with joined ItemDef metadata.

Returns:: One row per ItemRef within each ValueListDef.
Return type:: DatasetJSON

flatten_where_clauses()[source]

Flatten WhereClauseDef RangeCheck elements.

Returns:: One row per RangeCheck within each WhereClauseDef.
Return type:: DatasetJSON

flatten_methods()[source]

Flatten MethodDef elements with FormalExpression denormalization.

For methods with multiple FormalExpressions, produces one row per FormalExpression (repeating the parent fields) to ensure no data loss for round-tripping.

Returns:

One row per MethodDef (or per FormalExpression: if multiple exist).

Return type:

DatasetJSON

flatten_comments()[source]

Flatten CommentDef elements.

Returns:: One row per CommentDef.
Return type:: DatasetJSON

flatten_documents()[source]

Flatten leaf (external document reference) elements.

Returns:: One row per leaf element.
Return type:: DatasetJSON

flatten_codelists()[source]

Flatten CodeList elements.

Returns:: One row per CodeList.
Return type:: DatasetJSON

flatten_codelist_terms()[source]

Flatten CodeListItem and EnumeratedItem elements within CodeLists.

Returns:: One row per CodeListItem or EnumeratedItem.
Return type:: DatasetJSON

flatten_aliases()[source]

Flatten Alias elements from every element type that carries them.

Normalized one-row-per-Alias table keyed by the owning element. Covers ItemGroupDef, ItemDef, CodeList, and the CodeListItem / EnumeratedItem terms (which the codelist_terms table cannot hold an Alias for). Member disambiguates a codelist term by its CodedValue; it is empty for the OID-addressable element types.

Returns:: One row per Alias.
Return type:: DatasetJSON

flatten_origins()[source]

Flatten the full ItemDef Origin trees (one row per Origin).

The inline OriginType / OriginSource columns on the variables and value_level tables only capture the first Origin’s Type and Source. This table captures every Origin with its Description (text and language) and DocumentRef leafIDs, enabling lossless rebuild.

Returns:: One row per Origin within each ItemDef.
Return type:: DatasetJSON

odmlib.dataset_json_1_1.dataset_xml_to_dataset_json(odm_obj, define_mdv=None)[source]

Convert a Dataset-XML 1.0.1 ODM object to Dataset-JSON v1.1.

Produces one DatasetJSON per ItemGroupOID, matching the Dataset-JSON v1.1 specification (one dataset per file).

Multiple ItemGroupData rows with the same ItemGroupOID are merged into one DatasetJSON. The column set is the union of all ItemOID values observed across all rows for that group.

Parameters:

odm_obj (Any) – An ODM root object from the dataset_1_0_1 model.
define_mdv (Any | None) – Optional MetaDataVersion from a loaded Define-XML document. When provided, column labels, types, and lengths are read from ItemDef elements.

Returns:

Mapping of dataset name to DatasetJSON.: Dataset name is derived from the ItemGroupOID suffix (e.g., "IG.AE" → "AE").

Return type:

dict[str, DatasetJSON]

odmlib.dataset_json_1_1.dataset_json_to_dataset_xml(dataset_json, dataset_xml_model, study_oid=None, mdv_oid=None)[source]

Convert a Dataset-JSON v1.1 DatasetJSON to a Dataset-XML ODM object.

Parameters:

dataset_json (DatasetJSON) – A DatasetJSON.
dataset_xml_model (Any) – The odmlib.dataset_1_0_1.model module containing ODM, ClinicalData, ItemGroupData, and ItemData classes.
study_oid (str | None) – Study OID override. If None, uses dataset_json.studyOID.
mdv_oid (str | None) – MetaDataVersion OID override. If None, uses dataset_json.metaDataVersionOID.

Returns:

An odmlib ODM root object with ClinicalData.

Return type:

Any

odmlib.dataset_json_1_1.model

Dataset-JSON v1.1 model using the ODMElement/descriptor pattern.

This module defines ODMElement-based classes conforming to the CDISC Dataset-JSON v1.1 specification. The model represents one dataset per file with column-oriented metadata and row data as arrays of arrays.

Classes:: DatasetJSONElement – base class disabling XML serialization SourceSystem – optional source system metadata object Column – column (variable) metadata DatasetJSON – root element for a Dataset-JSON v1.1 file
Reference:: CDISC Dataset-JSON v1.1 specification and JSON schema.

class odmlib.dataset_json_1_1.model.DatasetJSONElement(**kwargs)[source]

Bases: ODMElement

Base class for Dataset-JSON v1.1 elements.

Overrides XML serialization (not applicable for Dataset-JSON) and provides a to_dict() that handles mixed list types (ODMElement lists and plain data arrays) and omits None-valued optional fields.

Parameters:: kwargs (Any)

namespace = 'dsjson'

to_xml(parent_elem=None, top_elem=None)[source]

Dataset-JSON does not support XML serialization.

Raises:: NotImplementedError – Always.

to_xml_string(*, xml_declaration=False)[source]

Dataset-JSON does not support XML serialization.

Accepts the same keyword as ODMElement.to_xml_string() so that to_xml_string(xml_declaration=True) raises the intended NotImplementedError rather than a TypeError.

Raises:: NotImplementedError – Always.

to_element()[source]

Dataset-JSON does not support XML serialization.

Overridden explicitly so the failure comes from here rather than from inside to_xml_string(), which would give a confusing traceback.

Raises:: NotImplementedError – Always.

write_xml(odm_file, odm_writer=None)[source]

Dataset-JSON does not support XML serialization.

Raises:: NotImplementedError – Always.

to_dict()[source]

Serialize this element to a Python dictionary.

Handles mixed list types: lists of ODMElement children are recursively serialized via to_dict(), while plain data lists (e.g., rows) pass through unchanged. None-valued optional fields are omitted.

Returns:: Spec-conformant dictionary representation.
Return type:: dict

class odmlib.dataset_json_1_1.model.SourceSystem(**kwargs)[source]

Bases: DatasetJSONElement

Source system information (optional nested object in Dataset-JSON v1.1).

Parameters:: kwargs (Any)

name

The name of the source system.

Type:: str, required

version

The version of the source system.

Type:: str, required

name: Descriptor for string-valued ODM attributes.

version: Descriptor for string-valued ODM attributes.

namespace = 'odm'

class odmlib.dataset_json_1_1.model.Column(**kwargs)[source]

Bases: DatasetJSONElement

Column (variable) metadata for a Dataset-JSON v1.1 dataset.

Each column describes one variable in the dataset, including its OID, name, label, data type, and optional formatting information.

Parameters:: kwargs (Any)

itemOID

Variable OID (corresponds to ItemDef.OID in Define-XML).

Type:: str, required

name

Variable name (e.g., “STUDYID”, “AETERM”).

Type:: str, required

label

Human-readable variable description.

Type:: str, required

dataType

Logical data type. One of: “string”, “integer”, “decimal”, “float”, “double”, “boolean”, “datetime”, “date”, “time”, “URI”.

Type:: str, required

targetDataType

Target data type for type conversion. Only “integer” or “decimal” are valid.

Type:: str

length

Maximum variable length (must be >= 1).

Type:: int

displayFormat

SAS-style display format (e.g., “DATE9.”).

Type:: str

keySequence

Key variable ordering (must be >= 1).

Type:: int

itemOID: Descriptor for string-valued ODM attributes.

name: Descriptor for the Name attribute of ODM elements.

label: Descriptor for string-valued ODM attributes.

dataType

Descriptor that validates against an explicit list of permitted values.

Unlike ValidValues, the allowed values are provided at class definition time in the valid_values list argument.

targetDataType

Descriptor that validates against an explicit list of permitted values.

Unlike ValidValues, the allowed values are provided at class definition time in the valid_values list argument.

length

Descriptor for positive integer attributes (value > 0).

Combines integer type validation with positive value constraint. Used for Length, ItemGroupDataSeq, and similar attributes.

displayFormat: Descriptor for string-valued ODM attributes.

keySequence

Descriptor for positive integer attributes (value > 0).

Combines integer type validation with positive value constraint. Used for Length, ItemGroupDataSeq, and similar attributes.

namespace = 'odm'

class odmlib.dataset_json_1_1.model.DatasetJSON(**kwargs)[source]

Bases: DatasetJSONElement

Root element for a Dataset-JSON v1.1 file.

Represents a single dataset (one per file) conforming to the CDISC Dataset-JSON v1.1 specification. Contains file-level metadata, column definitions, and row data.

datasetJSONCreationDateTime

ISO 8601 creation timestamp.

Type:: str, required

datasetJSONVersion

Specification version (pattern: 1.1(.N)?).

Type:: str, required

fileOID

Unique file identifier.

Type:: str

dbLastModifiedDateTime

ISO 8601 timestamp of last database modification.

Type:: str

originator

Organization that generated the file.

Type:: str

sourceSystem

Source system information object.

Type:: SourceSystem

studyOID

Study OID (foreign key to ODM Study).

Type:: str

metaDataVersionOID

MetaDataVersion OID (foreign key to ODM).

Type:: str

metaDataRef

URI to metadata file (e.g., Define-XML).

Type:: str

itemGroupOID

ItemGroupDef OID (foreign key to Define-XML).

Type:: str, required

records

Total number of records (>= 0).

Type:: int, required

name

Dataset name (e.g., “DM”, “AE”).

Type:: str, required

label

Dataset description.

Type:: str, required

columns

Column metadata definitions.

Type:: list[Column]

rows

Array of row arrays. Each row is a list of values matching the column order. None indicates missing values.

Type:: list

datasetJSONCreationDateTime: Descriptor for string-valued ODM attributes.

datasetJSONVersion: Descriptor for string-valued ODM attributes.

fileOID: Descriptor for string-valued ODM attributes.

dbLastModifiedDateTime: Descriptor for string-valued ODM attributes.

originator: Descriptor for string-valued ODM attributes.

sourceSystem

Descriptor for a single child ODM element.

Stores a reference to the element class and validates type on assignment. When accessed on an unset optional attribute, instantiates the element class with no arguments.

Parameters:

element_class (type) – The expected child element class.
namespace (str) – XML namespace prefix (default: “odm”).

studyOID: Descriptor for string-valued ODM attributes.

metaDataVersionOID: Descriptor for string-valued ODM attributes.

metaDataRef: Descriptor for string-valued ODM attributes.

itemGroupOID: Descriptor for string-valued ODM attributes.

records

Descriptor for non-negative integer attributes (value >= 0).

Combines integer type validation with non-negative constraint. Used for SignificantDigits and similar attributes.

name: Descriptor for the Name attribute of ODM elements.

label: Descriptor for string-valued ODM attributes.

columns

Descriptor for a list of child ODM elements.

Validates that all items assigned to the list are instances of the expected element class. Stored as a plain list in the instance.

Parameters:

element_class (type) – The class that all list items must be.
namespace (str) – XML namespace prefix (default: “odm”).

rows: Descriptor for list-valued attributes.

__init__(**kwargs)[source]

Initialize a DatasetJSON instance.

Ensures columns is always initialized (defaults to []) since it is required by the Dataset-JSON v1.1 schema.

property column_names: list

Return the list of column variable names.

Returns:: Variable names from each Column’s name attribute.
Return type:: list[str]

add_column(column)[source]

Append a Column to this dataset’s column list.

Parameters:: column (Column) – Column metadata to add.
Raises:: OdmlibTypeError – If column is not a Column instance.
Return type:: None

add_row(values)[source]

Append a row of values to this dataset.

Validates that the number of values matches the number of columns. Automatically increments the records count.

Parameters:: values (list) – List of values in column order. Use None for missing values.
Raises:: ValueError – If len(values) does not match len(columns).
Return type:: None

to_dict()[source]

Serialize to a spec-conformant Dataset-JSON v1.1 dictionary.

Omits empty rows for metadata-only mode (records > 0 but no row data transferred). All other behavior inherited from DatasetJSONElement.to_dict().

Returns:: Dataset-JSON v1.1 conformant dictionary.
Return type:: dict

to_json(indent=2)[source]

Serialize to a JSON string.

Parameters:: indent (int) – JSON indentation level (default: 2).
Returns:: JSON string representation.
Return type:: str

write_json(filename, indent=2)[source]

Write this dataset to a JSON file.

Parameters:

filename (str) – Output file path.
indent (int) – JSON indentation level (default: 2).

Return type:

None

write_ndjson(filename)[source]

Write this dataset to an NDJSON file.

NDJSON format: line 1 is the metadata (everything except rows), lines 2+ are one row array per line.

Parameters:: filename (str) – Output file path.
Return type:: None

classmethod from_dict(data)[source]

Construct a DatasetJSON from a dictionary.

Handles nested construction of Column and SourceSystem objects from their dict representations.

Parameters:: data (dict) – Dictionary with Dataset-JSON v1.1 fields.
Returns:: Constructed instance.
Return type:: DatasetJSON

classmethod from_json(json_string)[source]

Construct a DatasetJSON from a JSON string.

Parameters:: json_string (str) – JSON string with Dataset-JSON v1.1 fields.
Returns:: Constructed instance.
Return type:: DatasetJSON

classmethod read_json(filename)[source]

Read a DatasetJSON from a JSON file.

Parameters:: filename (str) – Input file path.
Returns:: Constructed instance.
Return type:: DatasetJSON

classmethod read_ndjson(filename)[source]

Read a DatasetJSON from an NDJSON file.

NDJSON format: line 1 is the metadata (everything except rows), lines 2+ are one row array per line.

Parameters:: filename (str) – Input file path.
Returns:: Constructed instance.
Return type:: DatasetJSON

namespace = 'odm'

odmlib.dataset_json_1_1.define_flattener

Flatten Define-XML v2.1 metadata into tabular Dataset-JSON v1.1 datasets.

This module converts a loaded Define-XML v2.1 ODM object hierarchy into a set of Dataset-JSON v1.1 datasets, one per metadata table. Each table captures a different aspect of the Define-XML metadata in a flat, tabular format suitable for analysis and round-tripping.

Classes:: DefineFlattener – converts Define-XML v2.1 to Dataset-JSON tables
Target datasets (11 core):: study, standards, datasets, variables, value_level, where_clauses, methods, comments, documents, codelists, codelist_terms
Additional datasets (lossless-roundtrip extensions, optional on read):: aliases, origins

class odmlib.dataset_json_1_1.define_flattener.DefineFlattener(odm_root, study_idx=0)[source]

Bases: object

Convert Define-XML v2.1 metadata into tabular Dataset-JSON datasets.

Initializes with a loaded Define-XML v2.1 ODM root object and provides methods to flatten each metadata element type into a separate Dataset-JSON v1.1 dataset.

Parameters:

odm_root (Any) – A loaded Define-XML v2.1 ODM root object (from odmlib loader).
study_idx (int) – Index of the Study element to use (default: 0). For Define-XML, there is always exactly one Study.

Example:

import odmlib.define_loader as DL
import odmlib.loader as LD
from odmlib.dataset_json_1_1.define_flattener import DefineFlattener

loader = LD.ODMLoader(DL.XMLDefineLoader(model_package='define_2_1'))
loader.open_odm_document('define.xml')
odm = loader.root()

flattener = DefineFlattener(odm)
datasets = flattener.flatten_all()
flattener.write_all('/output/dir')

DATASET_JSON_VERSION = '1.1.0'

TABLE_NAMES = ['study', 'standards', 'datasets', 'variables', 'value_level', 'where_clauses', 'methods', 'comments', 'documents', 'codelists', 'codelist_terms']

EXTRA_TABLE_NAMES = ['aliases', 'origins']

flatten_all()[source]

Flatten all Define-XML metadata into Dataset-JSON datasets.

Returns:

Mapping of dataset name to DatasetJSON: for all 11 metadata tables.

Return type:

dict[str, DatasetJSON]

write_all(output_dir, indent=2)[source]

Write all metadata datasets to individual JSON files.

Parameters:

output_dir (str) – Directory to write files to. Created if it does not exist.
indent (int) – JSON indentation level (default: 2).

Returns:

List of written file paths.

Return type:

list[str]

flatten_study()[source]

Flatten ODM root + Study + GlobalVariables + MetaDataVersion.

Returns:: Single-row dataset with study-level metadata.
Return type:: DatasetJSON

flatten_standards()[source]

Flatten MetaDataVersion.Standards.Standard elements.

Returns:

One row per Standard element. Empty if Standards: are not loaded (known limitation).

Return type:

DatasetJSON

flatten_datasets()[source]

Flatten MetaDataVersion.ItemGroupDef elements.

Returns:: One row per ItemGroupDef (dataset definition).
Return type:: DatasetJSON

flatten_variables()[source]

Flatten ItemRef + ItemDef pairs within each ItemGroupDef.

Returns:: One row per variable (ItemRef+ItemDef) per dataset.
Return type:: DatasetJSON

flatten_value_level()[source]

Flatten ValueListDef ItemRef entries with joined ItemDef metadata.

Returns:: One row per ItemRef within each ValueListDef.
Return type:: DatasetJSON

flatten_where_clauses()[source]

Flatten WhereClauseDef RangeCheck elements.

Returns:: One row per RangeCheck within each WhereClauseDef.
Return type:: DatasetJSON

flatten_methods()[source]

Flatten MethodDef elements with FormalExpression denormalization.

For methods with multiple FormalExpressions, produces one row per FormalExpression (repeating the parent fields) to ensure no data loss for round-tripping.

Returns:

One row per MethodDef (or per FormalExpression: if multiple exist).

Return type:

DatasetJSON

flatten_comments()[source]

Flatten CommentDef elements.

Returns:: One row per CommentDef.
Return type:: DatasetJSON

flatten_documents()[source]

Flatten leaf (external document reference) elements.

Returns:: One row per leaf element.
Return type:: DatasetJSON

flatten_codelists()[source]

Flatten CodeList elements.

Returns:: One row per CodeList.
Return type:: DatasetJSON

flatten_codelist_terms()[source]

Flatten CodeListItem and EnumeratedItem elements within CodeLists.

Returns:: One row per CodeListItem or EnumeratedItem.
Return type:: DatasetJSON

flatten_aliases()[source]

Flatten Alias elements from every element type that carries them.

Normalized one-row-per-Alias table keyed by the owning element. Covers ItemGroupDef, ItemDef, CodeList, and the CodeListItem / EnumeratedItem terms (which the codelist_terms table cannot hold an Alias for). Member disambiguates a codelist term by its CodedValue; it is empty for the OID-addressable element types.

Returns:: One row per Alias.
Return type:: DatasetJSON

flatten_origins()[source]

Flatten the full ItemDef Origin trees (one row per Origin).

The inline OriginType / OriginSource columns on the variables and value_level tables only capture the first Origin’s Type and Source. This table captures every Origin with its Description (text and language) and DocumentRef leafIDs, enabling lossless rebuild.

Returns:: One row per Origin within each ItemDef.
Return type:: DatasetJSON

odmlib.dataset_json_1_1.converter

Converters between Dataset-XML 1.0.1 and Dataset-JSON v1.1.

Provides utilities to convert between odmlib Dataset-XML objects and the ODMElement-based Dataset-JSON v1.1 model. Produces one DatasetJSON per ItemGroupOID (one dataset per file), matching the Dataset-JSON v1.1 specification.

Functions:: dataset_xml_to_dataset_json() – Dataset-XML → dict of DatasetJSON dataset_json_to_dataset_xml() – DatasetJSON → Dataset-XML ODM object

odmlib.dataset_json_1_1.converter.dataset_xml_to_dataset_json(odm_obj, define_mdv=None)[source]

Convert a Dataset-XML 1.0.1 ODM object to Dataset-JSON v1.1.

Produces one DatasetJSON per ItemGroupOID, matching the Dataset-JSON v1.1 specification (one dataset per file).

Multiple ItemGroupData rows with the same ItemGroupOID are merged into one DatasetJSON. The column set is the union of all ItemOID values observed across all rows for that group.

Parameters:

odm_obj (Any) – An ODM root object from the dataset_1_0_1 model.
define_mdv (Any | None) – Optional MetaDataVersion from a loaded Define-XML document. When provided, column labels, types, and lengths are read from ItemDef elements.

Returns:

Mapping of dataset name to DatasetJSON.: Dataset name is derived from the ItemGroupOID suffix (e.g., "IG.AE" → "AE").

Return type:

dict[str, DatasetJSON]

odmlib.dataset_json_1_1.converter.dataset_json_to_dataset_xml(dataset_json, dataset_xml_model, study_oid=None, mdv_oid=None)[source]

Convert a Dataset-JSON v1.1 DatasetJSON to a Dataset-XML ODM object.

Parameters:

dataset_json (DatasetJSON) – A DatasetJSON.
dataset_xml_model (Any) – The odmlib.dataset_1_0_1.model module containing ODM, ClinicalData, ItemGroupData, and ItemData classes.
study_oid (str | None) – Study OID override. If None, uses dataset_json.studyOID.
mdv_oid (str | None) – MetaDataVersion OID override. If None, uses dataset_json.metaDataVersionOID.

Returns:

An odmlib ODM root object with ClinicalData.

Return type:

Any

odmlib.dataset_json_1_1.define_builder

Reconstruct Define-XML v2.1 from flattened Dataset-JSON v1.1 datasets.

This module is the inverse of define_flattener. It takes the 11 tabular Dataset-JSON datasets produced by DefineFlattener and reconstructs a full odmlib Define-XML v2.1 object tree that can be written to XML.

Classes:: DefineBuilder – reconstructs Define-XML v2.1 from Dataset-JSON tables
Target datasets consumed (11 total):: study, standards, datasets, variables, value_level, where_clauses, methods, comments, documents, codelists, codelist_terms

class odmlib.dataset_json_1_1.define_builder.DefineBuilder(datasets)[source]

Bases: object

Reconstruct a Define-XML v2.1 ODM object tree from Dataset-JSON tables.

Takes the same dict[str, DatasetJSON] that DefineFlattener.flatten_all() returns and rebuilds the full odmlib object hierarchy.

Parameters:: datasets (dict[str, DatasetJSON]) – Mapping of table name to DatasetJSON, with keys: study, standards, datasets, variables, value_level, where_clauses, methods, comments, documents, codelists, codelist_terms.

Example:

from odmlib.dataset_json_1_1 import DefineFlattener, DefineBuilder

flattener = DefineFlattener(odm_root)
flat = flattener.flatten_all()
rebuilt = DefineBuilder(flat).build()
rebuilt.write_xml('rebuilt_define.xml')

TABLE_NAMES = ['study', 'standards', 'datasets', 'variables', 'value_level', 'where_clauses', 'methods', 'comments', 'documents', 'codelists', 'codelist_terms']

EXTRA_TABLE_NAMES = ['aliases', 'origins']

add_post_build_hook(hook)[source]

Register a callable invoked with the assembled ODM root.

The hook runs just before build() returns, enabling insertion of Define-XML elements the 11 datasets cannot express (e.g. Alias, full Origin/DocumentRef trees, AnnotatedCRF). If the hook returns a non-None value it replaces the ODM root.

Parameters:: hook – Callable taking the DEF.ODM root; may mutate it in place or return a replacement.
Returns:: self, for chaining.
Return type:: DefineBuilder

build()[source]

Reconstruct the full Define-XML v2.1 ODM object tree.

Returns:: A complete odmlib Define-XML v2.1 root object.
Return type:: DEF.ODM

classmethod read_all(input_dir)[source]

Load 11 Dataset-JSON files from a directory.

Expects files named {table_name}.json for each table in TABLE_NAMES.

Parameters:: input_dir (str) – Directory containing the JSON files.
Returns:: Mapping suitable for the constructor.
Return type:: dict[str, DatasetJSON]