somacore

1.0.29 · active · verified Fri Apr 17

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.

Common errors

```
TypeError: SOMAObject cannot be instantiated directly
```
cause Attempting to create an instance of an abstract SOMA type (protocol) directly from `somacore`.

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.
```
AttributeError: module 'somacore' has no attribute 'Experiment' (or similar for other concrete classes like 'DataFrame')
```
cause Expecting `somacore` to expose concrete SOMA implementation classes directly, rather than abstract definitions.

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`).
```
ModuleNotFoundError: No module named 'somacore.experiment'
```
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.

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.

Warnings

breaking 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.
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.
gotcha `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.
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.
gotcha 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.
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.

Install

pip install somacore Install somacore

Imports

SOMAObject
```
from somacore import SOMAObject
```
DataFrame
wrong:
```
from somacore.base import DataFrame
```
correct:
```
from somacore import DataFrame
```
Core SOMA types are typically imported directly from the top-level `somacore` package.
Axis
```
from somacore import Axis
```
OpenMode
```
from somacore import OpenMode
```
query
```
from somacore.query import query
```

Quickstart

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.

import somacore
from somacore import AxisType, OpenMode, SOMAObject

# somacore provides abstract base classes (Protocols)
# for SOMA objects and related concepts.
print(f"somacore version: {somacore.__version__}")

# You can import and inspect enumeration types
print(f"Available Axis Types: {list(AxisType)}")
print(f"Read mode for opening objects: {OpenMode.READ}")

# SOMAObject is a core Protocol (an Abstract Base Class for type hinting)
print(f"SOMAObject is a {type(SOMAObject).__name__}")

# You cannot instantiate these protocols directly;
# they are meant for type checking and as interfaces for implementations.
# For example, this would raise a TypeError:
# try:
#     obj = SOMAObject("some_uri")
# except TypeError as e:
#     print(f"\nCannot instantiate SOMAObject directly: {e}")

print("\nsomacore defines the SOMA API. For concrete implementations,")
print("refer to libraries like `tiledbsoma` which implement these protocols.")

view raw JSON →