{"id":10244,"library":"somacore","title":"somacore","description":"somacore provides the Python-language API specification and base utilities for the SOMA (Scalable Open Multi-omics Array) system. It defines abstract base classes and protocols for core SOMA objects like Experiment, Measurement, DataFrame, and Arrays. As of version 1.0.29, it focuses on defining the SOMA data model for interoperability. The library is actively maintained with frequent updates, often aligning with updates to the broader SOMA specification.","status":"active","version":"1.0.29","language":"en","source_language":"en","source_url":"https://github.com/single-cell-data/somacore","tags":["data science","genomics","bioinformatics","data format","specification","multi-omics"],"install":[{"cmd":"pip install somacore","lang":"bash","label":"Install somacore"}],"dependencies":[{"reason":"Used for version parsing and compatibility checks.","package":"packaging","optional":false},{"reason":"Provides backports for newer typing features, especially Protocols, for wider Python version compatibility.","package":"typing_extensions","optional":false}],"imports":[{"symbol":"SOMAObject","correct":"from somacore import SOMAObject"},{"note":"Core SOMA types are typically imported directly from the top-level `somacore` package.","wrong":"from somacore.base import DataFrame","symbol":"DataFrame","correct":"from somacore import DataFrame"},{"symbol":"Axis","correct":"from somacore import Axis"},{"symbol":"OpenMode","correct":"from somacore import OpenMode"},{"symbol":"query","correct":"from somacore.query import query"}],"quickstart":{"code":"import somacore\nfrom somacore import AxisType, OpenMode, SOMAObject\n\n# somacore provides abstract base classes (Protocols)\n# for SOMA objects and related concepts.\nprint(f\"somacore version: {somacore.__version__}\")\n\n# You can import and inspect enumeration types\nprint(f\"Available Axis Types: {list(AxisType)}\")\nprint(f\"Read mode for opening objects: {OpenMode.READ}\")\n\n# SOMAObject is a core Protocol (an Abstract Base Class for type hinting)\nprint(f\"SOMAObject is a {type(SOMAObject).__name__}\")\n\n# You cannot instantiate these protocols directly;\n# they are meant for type checking and as interfaces for implementations.\n# For example, this would raise a TypeError:\n# try:\n#     obj = SOMAObject(\"some_uri\")\n# except TypeError as e:\n#     print(f\"\\nCannot instantiate SOMAObject directly: {e}\")\n\nprint(\"\\nsomacore defines the SOMA API. For concrete implementations,\")\nprint(\"refer to libraries like `tiledbsoma` which implement these protocols.\")","lang":"python","description":"This quickstart demonstrates importing core `somacore` types and enumerations. It highlights that `somacore` provides abstract definitions and protocols for the SOMA data model, which are not directly instantiable. Instead, concrete implementations (like `tiledbsoma`) are required to create and manipulate SOMA objects. The example shows how to access the library version and inspect available enumeration values."},"warnings":[{"fix":"Update your code to conform to the SOMA API v1.0 specification. Consult `somacore` 1.x documentation and migration guides for your chosen SOMA implementation (e.g., `tiledbsoma`) to adapt to the new API.","message":"The SOMA API specification underwent significant changes with the 1.0.0 release. Code written for `somacore` 0.x (and earlier versions of SOMA implementations) is generally incompatible with `somacore` 1.x.","severity":"breaking","affected_versions":"0.x"},{"fix":"To work with actual SOMA objects and data, you must install and use a specific SOMA implementation library (e.g., `tiledbsoma`), which provides concrete classes that adhere to the `somacore` protocols and handles data persistence.","message":"`somacore` solely defines the SOMA API specification and provides abstract types (Protocols/ABCs). It does not provide concrete, instantiable SOMA objects, data storage mechanisms, or I/O operations itself.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use concrete SOMA object classes provided by an implementation library (e.g., `tiledbsoma.SOMACollection`) when creating or interacting with SOMA data structures. `somacore` types should primarily be used for type hinting.","message":"SOMA objects (e.g., `Experiment`, `DataFrame`) are represented as Python `Protocol`s in `somacore`. While they define interfaces for type checking, they are not intended for direct instantiation or subclassing by users without a concrete implementation.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Import and use concrete SOMA object classes provided by an implementation library, such as `tiledbsoma.SOMACollection` or `tiledbsoma.SOMADataFrame`, which adhere to the `somacore` protocols.","cause":"Attempting to create an instance of an abstract SOMA type (protocol) directly from `somacore`.","error":"TypeError: SOMAObject cannot be instantiated directly"},{"fix":"`somacore` provides abstract definitions. For concrete SOMA objects like `Experiment` or `DataFrame` that you can instantiate and populate, you need to import them from a specific SOMA implementation library (e.g., `from tiledbsoma import Experiment`).","cause":"Expecting `somacore` to expose concrete SOMA implementation classes directly, rather than abstract definitions.","error":"AttributeError: module 'somacore' has no attribute 'Experiment' (or similar for other concrete classes like 'DataFrame')"},{"fix":"Concrete SOMA objects like `Experiment` are typically provided by SOMA implementation libraries (e.g., `tiledbsoma`) and imported from their top-level package, not from `somacore` or its submodules. Check the documentation of your chosen SOMA implementation.","cause":"Trying to import a specific, concrete SOMA object like `Experiment` from a sub-module of `somacore` based on an incorrect assumption about its structure.","error":"ModuleNotFoundError: No module named 'somacore.experiment'"}]}