{"id":7284,"library":"hdmf","title":"HDMF: Hierarchical Data Modeling Framework","description":"HDMF (Hierarchical Data Modeling Framework) is a Python package designed for standardizing, reading, and writing hierarchical object data. It provides APIs for defining data models, interacting with various storage backends, and representing data using Python objects. Developed as a core component of the Neurodata Without Borders (NWB) project, HDMF offers a flexible and extensible approach to data modeling for scientific communities. The library is actively maintained, with frequent releases, currently at version 5.1.0.","status":"active","version":"5.1.0","language":"en","source_language":"en","source_url":"https://github.com/hdmf-dev/hdmf","tags":["data modeling","scientific data","HDF5","NWB","neuroscience","data standards"],"install":[{"cmd":"pip install hdmf","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for HDF5-based I/O, which is the primary and most common storage backend for HDMF.","package":"h5py","optional":false},{"reason":"Fundamental library for numerical operations and array handling, widely used within HDMF data structures.","package":"numpy","optional":false}],"imports":[{"symbol":"GroupSpec","correct":"from hdmf.spec import GroupSpec"},{"symbol":"DatasetSpec","correct":"from hdmf.spec import DatasetSpec"},{"symbol":"NamespaceBuilder","correct":"from hdmf.spec import NamespaceBuilder"},{"symbol":"DynamicTable","correct":"from hdmf.common import DynamicTable"},{"symbol":"HDF5IO","correct":"from hdmf.backends.hdf5 import HDF5IO"},{"note":"The `hdmf.build.map` module and its contents (e.g., `TypeMap`) were refactored or removed in HDMF 4.0.0. Use `hdmf.build` or specific symbols directly.","wrong":"from hdmf.build.map import TypeMap","symbol":"*","correct":"from hdmf.build import BuildManager"}],"quickstart":{"code":"import os\nfrom hdmf.spec import GroupSpec, DatasetSpec, NamespaceBuilder\nfrom hdmf.common import DynamicTable, VectorData\nfrom hdmf.backends.hdf5 import HDF5IO\n\n# 1. Define a custom data type specification\nmy_dataset_spec = DatasetSpec(name='my_data', doc='An example dataset', dtype='float32')\nmy_group_spec = GroupSpec(name='MyTypeContainer', doc='A custom data type container', datasets=[my_dataset_spec])\n\n# 2. Create a namespace for your specification\nnamespace_builder = NamespaceBuilder(\n    doc='My Custom HDMF Extension',\n    name='my_extension',\n    full_name='My Custom Extension',\n    version='0.1.0',\n    auto_detect_namespace=True\n)\n# In a real scenario, you would save this to a YAML file and load it\n# For quickstart, we'll demonstrate using built-in common types\n\n# 3. Work with common HDMF data types, e.g., DynamicTable\ntable = DynamicTable(name='example_table', description='An example table of items')\ntable.add_column('item_name', 'Name of the item', dtype='text')\ntable.add_column('quantity', 'Quantity of the item', dtype='int')\n\ntable.add_row(item_name='Apple', quantity=10)\ntable.add_row(item_name='Banana', quantity=5)\n\n# 4. Save to HDF5 file\nfile_name = 'my_hdmf_data.h5'\nwith HDF5IO(file_name, 'w') as io:\n    io.write(table)\n\nprint(f\"DynamicTable saved to {file_name}\")\n\n# 5. Read from HDF5 file\nwith HDF5IO(file_name, 'r') as io:\n    read_table = io.read()\n\nprint(\"\\nRead DynamicTable:\")\nprint(read_table)\n\n# Clean up\nos.remove(file_name)","lang":"python","description":"This quickstart demonstrates how to define a simple data specification, use a common HDMF data type (DynamicTable), and perform basic HDF5 file I/O operations (write and read) using the `hdmf.backends.hdf5.HDF5IO` backend."},"warnings":[{"fix":"Review your code for direct manipulation of `TypeMap` or reliance on its internal structure. Adapt to the new spec resolution system and lazy class generation. Consult the HDMF 5.0.0 changelog for specific API updates.","message":"HDMF 5.0.0 introduced significant changes to the spec resolution system and `TypeMap` functionality. `TypeMap.load_namespaces` was refactored, `TypeMap.container_types` property was removed, and `TypeSource` became a frozen dataclass.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Update your code to use the modern equivalents for these removed components. For instance, replace imports from `hdmf.build.map` with `hdmf.build`. If you relied on the removed data structures, consider using `DynamicTable`, `VectorData`, or `VectorIndex` from `hdmf.common`.","message":"HDMF 4.0.0 removed several deprecated classes and methods, including `Array`, `AbstractSortedArray`, `SortedArray`, `LinSpace`, `Query`, `RegionSlicer`, `DataRegion`, `fmt_docval_args`, `call_docval_func`, `get_container_cls`, `add_child`, and `set_dataio` (refactored to `set_data_io`). The `hdmf.build.map` module was also removed; imports should now be directly from `hdmf.build`.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Ensure your `pandas` installation is version 2.x or earlier. If you require `pandas` 3.x, check HDMF's changelog for updates on `pandas` 3.x compatibility.","message":"HDMF versions 4.3.1 and later (until explicitly stated otherwise in future releases) restrict `pandas` to versions less than 3 (`<3`). Using `pandas` 3.x with these HDMF versions may lead to compatibility issues, particularly with string data types and data ingestion.","severity":"gotcha","affected_versions":">=4.3.1 (until pandas 3.x support is added)"},{"fix":"Pin `numcodecs` to a version less than 0.16 in your project dependencies (e.g., `numcodecs<0.16`).","message":"For HDMF 4.0.0 and later, `numcodecs` is restricted to versions less than 0.16 (`<0.16`) due to incompatibilities with `zarr<3`. If you are working with Zarr storage backends, ensure these version constraints are met.","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Change your imports to use `hdmf.build` directly for builder-related components. For example, replace `from hdmf.build.map import TypeMap` with `from hdmf.build import BuildManager` (or the specific class you need).","cause":"The `hdmf.build.map` module was removed in HDMF 4.0.0.","error":"ModuleNotFoundError: No module named 'hdmf.build.map'"},{"fix":"Revisit the HDMF 4.0.0 changelog and documentation to find the correct method for adding children to containers, or restructure your code to use appropriate container management.","cause":"The `add_child` method was removed in HDMF 4.0.0 as part of API refactoring.","error":"AttributeError: 'Container' object has no attribute 'add_child'"},{"fix":"Consult the HDMF 5.0.0 changelog and documentation regarding the new `TypeSource` constructor and the refactored `TypeMap.load_namespaces` for updated usage patterns.","cause":"`TypeSource` was converted to a frozen dataclass in HDMF 5.0.0, and its constructor arguments may have changed or been refactored.","error":"TypeError: TypeSource() got an unexpected keyword argument 'source_path'"}]}