odmlib.dataframe

Optional Pandas DataFrame integration for odmlib.

Note

Requires the pandas package. Install with:

pip install odmlib[dataframe]

Optional Pandas DataFrame integration for odmlib.

Provides convenience functions to export odmlib metadata and clinical data to Pandas DataFrames and to construct odmlib element lists from DataFrames.

Pandas is an optional dependency. If it is not installed, importing this module succeeds but calling any function raises ImportError with a helpful install hint.

Install with:

pip install odmlib[dataframe]

or:

pip install pandas

Functions

metadata_to_dataframe()

Export a list of odmlib metadata elements (e.g., all ItemDef objects in a MetaDataVersion) as a DataFrame with one row per element.

clinical_data_to_dataframe()

Flatten a hierarchical ODM 1.3.2 ClinicalData object (SubjectData → StudyEventData → FormData → ItemGroupData → ItemData) into a tabular DataFrame with one row per subject-event-form-group record.

dataset_to_dataframe()

Flatten a Dataset-XML 1.0.1 ClinicalData object (no SubjectData hierarchy) into a tabular DataFrame with one row per ItemGroupData record.

dataset_json_to_dataframe()

Convert a DatasetJSON object to a DataFrame.

define_metadata_to_dataframes()

Flatten all Define-XML v2.1 metadata into a dict of DataFrames, one per metadata table (study, datasets, variables, codelists, etc.).

dataframe_to_items()

Create odmlib element instances from a DataFrame (one row → one element).

Example:

import odmlib.odm_1_3_2.model as ODM
import odmlib.loader as LD
import odmlib.odm_loader as OL
from odmlib.dataframe import metadata_to_dataframe

loader = LD.ODMLoader(OL.XMLODMLoader())
loader.open_odm_document("study.xml")
mdv = loader.MetaDataVersion()

df = metadata_to_dataframe(mdv, "ItemDef")
print(df[["OID", "Name", "DataType"]].to_string())
odmlib.dataframe.metadata_to_dataframe(mdv, element_type, attributes=None)[source]

Export odmlib metadata elements to a Pandas DataFrame.

Extracts all elements of element_type from a MetaDataVersion and returns a DataFrame with one row per element. Only scalar attributes (str, int, float, bool, None) are included as columns; child element lists and nested objects are excluded.

Parameters:

  • mdv (Any) – A MetaDataVersion odmlib object (ODM 1.3.2, Define-XML 2.0, or Define-XML 2.1).

  • element_type (str) – Name of the element list to export. Examples: "ItemDef", "ItemGroupDef", "CodeList", "StudyEventDef", "FormDef".

  • attributes (Optional[list[str]]) – Optional list of attribute names to include as columns. If None, all scalar attributes found on any element are included (union across all elements).

Returns:

A pandas.DataFrame with one row per element and one column per scalar attribute.

Raises:

ImportError – If pandas is not installed.

Return type:

pd.DataFrame

Example:

df = metadata_to_dataframe(mdv, "ItemDef")
print(df[["OID", "Name", "DataType"]].head())
odmlib.dataframe.clinical_data_to_dataframe(clinical_data, item_group_oid)[source]

Export ODM 1.3.2 clinical data for one ItemGroup to a DataFrame.

Traverses the full hierarchy SubjectData → StudyEventData → FormData → ItemGroupData → ItemData and collects rows where ItemGroupData.ItemGroupOID matches item_group_oid.

Parameters:

  • clinical_data (Any) – A ClinicalData odmlib object from the odm_1_3_2 model.

  • item_group_oid (str) – OID of the ItemGroupDef to extract (e.g., "IG.VS").

Returns:

A pandas.DataFrame with one row per matching record. Columns include "SubjectKey" plus one column per ItemOID found in those records.

Raises:

ImportError – If pandas is not installed.

Return type:

pd.DataFrame

odmlib.dataframe.dataset_to_dataframe(clinical_data)[source]

Export Dataset-XML 1.0.1 ClinicalData to a Pandas DataFrame.

For the simpler Dataset-XML 1.0.1 structure, which does not have the SubjectData hierarchy. Each ItemGroupData row becomes one row in the DataFrame.

Parameters:

clinical_data (Any) – A ClinicalData odmlib object from the dataset_1_0_1 model.

Returns:

A pandas.DataFrame with one row per ItemGroupData record. Columns include "ItemGroupOID", "ItemGroupDataSeq", and one column per ItemOID found in any record.

Raises:

ImportError – If pandas is not installed.

Return type:

pd.DataFrame

odmlib.dataframe.dataset_json_to_dataframe(dataset)[source]

Convert a Dataset-JSON v1.1 dataset object to a Pandas DataFrame.

Column names come from the DatasetJSON.column_names property and row data from DatasetJSON.rows (list of lists).

Parameters:

dataset (Any) – An odmlib.dataset_json_1_1.model.DatasetJSON object.

Returns:

A pandas.DataFrame with one row per record and columns named by variable name.

Raises:

ImportError – If pandas is not installed.

Return type:

pd.DataFrame

Example:

from odmlib.dataset_json_1_1 import DatasetJSON
from odmlib.dataframe import dataset_json_to_dataframe

ds = DatasetJSON.read_json("ae.json")
df = dataset_json_to_dataframe(ds)
print(df.head())
odmlib.dataframe.define_metadata_to_dataframes(odm_root, study_idx=0)[source]

Flatten Define-XML v2.1 metadata into a dict of Pandas DataFrames.

Uses DefineFlattener internally to convert a loaded Define-XML v2.1 ODM root object into tabular Dataset-JSON datasets, then converts each to a DataFrame.

The returned dict maps dataset names to DataFrames. Dataset names are: study, standards, datasets, variables, value_level, where_clauses, methods, comments, documents, codelists, codelist_terms.

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).

Returns:

Mapping of dataset name to DataFrame.

Return type:

dict[str, pandas.DataFrame]

Raises:

ImportError – If pandas is not installed.

Example:

import odmlib.define_loader as DL
import odmlib.loader as LD
from odmlib.dataframe import define_metadata_to_dataframes

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

dfs = define_metadata_to_dataframes(odm)
print(dfs['variables'][['DatasetOID', 'Name', 'DataType']].head())
odmlib.dataframe.dataframe_to_dataset_json(df, name, label, item_group_oid, dataset_json_version='1.1.0', creation_datetime=None)[source]

Convert a Pandas DataFrame to a Dataset-JSON v1.1 DatasetJSON object.

Each DataFrame column becomes a Dataset-JSON Column with dataType inferred from the pandas dtype (int → "integer", float → "decimal", otherwise "string").

Parameters:

  • df (pd.DataFrame) – Source DataFrame.

  • name (str) – Dataset name (e.g., "DM", "AE").

  • label (str) – Dataset label/description.

  • item_group_oid (str) – ItemGroupDef OID for this dataset.

  • dataset_json_version (str) – Dataset-JSON version string (default: "1.1.0").

  • creation_datetime (Optional[str]) – ISO 8601 creation timestamp. If None, the current UTC time is used.

Returns:

A DatasetJSON instance.

Raises:

ImportError – If pandas is not installed.

Return type:

Any

Example:

import pandas as pd
from odmlib.dataframe import dataframe_to_dataset_json

df = pd.DataFrame({
    "STUDYID": ["CDISC01", "CDISC01"],
    "USUBJID": ["001", "002"],
    "AGE": [65, 72],
})
ds = dataframe_to_dataset_json(df, "DM", "Demographics", "IG.DM")
ds.write_json("dm.json")
odmlib.dataframe.dataframe_to_items(df, model_module, element_type='ItemDef', column_mapping=None)[source]

Create odmlib elements from a Pandas DataFrame.

Each row of the DataFrame becomes one odmlib element instance of type element_type. Columns that map to valid attribute names are passed as keyword arguments to the constructor. Rows that fail to construct a valid element are silently skipped.

Parameters:

  • df (pd.DataFrame) – Source DataFrame where each row represents one element.

  • model_module (Any) – The odmlib model module containing element_type (e.g., odmlib.odm_1_3_2.model).

  • element_type (str) – Class name to instantiate (default "ItemDef").

  • column_mapping (Optional[dict[str, str]]) – Optional dict mapping DataFrame column names to odmlib attribute names. If None, column names must match attribute names exactly.

Returns:

List of odmlib element instances (one per successfully constructed row).

Raises:
Return type:

list[Any]

Example:

import odmlib.odm_1_3_2.model as ODM
import pandas as pd
from odmlib.dataframe import dataframe_to_items

df = pd.DataFrame([
    {"OID": "IT.AGE", "Name": "AGE", "DataType": "integer"},
    {"OID": "IT.SEX", "Name": "SEX", "DataType": "text"},
])
items = dataframe_to_items(df, ODM, "ItemDef")
for item in items:
    mdv.ItemDef.append(item)