nwb-linkml/docs/index.md

306 lines
9.4 KiB
Markdown

# nwb-linkml
```{role} feature
```
A translation of the [Neurodata Without Borders](https://www.nwb.org/) standard
to [LinkML](https://linkml.io/).
```{admonition} Quick Links
* [Quickstart](guide/quickstart) - Some stuff this package does
* [Purpose](intro/purpose) - Why this package exists
* [Overview](guide/overview) - Overview of how it works
* [API Docs](api/nwb_linkml/index) - Ok *really* how it works
```
`nwb-linkml` is an independent implementation of the standard capable of:
* Translating schemas written in the {index}`NWB Schema Language` to LinkML.
* Manage multiple versions of NWB schemas with dependencies
* Generating pydantic models from nwb-flavored LinkML
* Read NWB files (including those that use custom, embedded schemas)
* {feature}`Coming Soon` Write/edit NWB files
* {feature}`Coming Soon` Export NWB to a Relational Database
* {feature}`Coming Soon` Export NWB to a Triple Store
## Example Translation
## TimeSeries
(Abbreviated for clarity)
`````{tab-set}
````{tab-item} NWB schema
```yaml
groups:
- neurodata_type_def: TimeSeries
neurodata_type_inc: NWBDataInterface
doc: General purpose time series.
attributes:
- name: description
dtype: text
default_value: no description
doc: Description of the time series.
required: false
- name: comments
dtype: text
default_value: no comments
doc: Human-readable comments about the TimeSeries. This second descriptive field
can be used to store additional information, or descriptive information if the
primary description field is populated with a computer-readable string.
required: false
datasets:
- name: data
dims:
- - num_times
- - num_times
- num_DIM2
- - num_times
- num_DIM2
- num_DIM3
- - num_times
- num_DIM2
- num_DIM3
- num_DIM4
shape:
- - null
- - null
- null
- - null
- null
- null
- - null
- null
- null
- null
doc: Data values. Data can be in 1-D, 2-D, 3-D, or 4-D. The first dimension
should always represent time. This can also be used to store binary data
(e.g., image frames). This can also be a link to data stored in an external file.
attributes:
- name: conversion
dtype: float32
default_value: 1.0
doc: Scalar to multiply each element in data (...)
required: false
- name: timestamps
dtype: float64
dims:
- num_times
shape:
- null
doc: Timestamps for samples stored in data, in seconds, relative to the
common experiment master-clock stored in NWBFile.timestamps_reference_time.
quantity: '?'
attributes:
- name: interval
dtype: int32
value: 1
doc: Value is '1'
- name: unit
dtype: text
value: seconds
doc: Unit of measurement for timestamps, which is fixed to 'seconds'.
```
````
````{tab-item} LinkML
```yaml
classes:
TimeSeries:
name: TimeSeries
description: General purpose time series.
is_a: NWBDataInterface
attributes:
name:
name: name
identifier: true
range: string
required: true
description:
name: description
description: Description of the time series.
range: text
comments:
name: comments
description: Human-readable comments about the TimeSeries. This second descriptive
field can be used to store additional information, or descriptive information
if the primary description field is populated with a computer-readable string.
range: text
data:
name: data
description: Data values. Data can be in 1-D, 2-D, 3-D, or 4-D. The first
dimension should always represent time. This can also be used to store binary
data (e.g., image frames). This can also be a link to data stored in an
external file.
multivalued: false
range: TimeSeries__data
required: true
timestamps:
name: timestamps
description: Timestamps for samples stored in data, in seconds, relative to
the common experiment master-clock stored in NWBFile.timestamps_reference_time.
multivalued: false
range: TimeSeries__timestamps__Array
required: false
tree_root: true
TimeSeries__data:
name: TimeSeries__data
description: Data values. Data can be in 1-D, 2-D, 3-D, or 4-D. The first dimension
should always represent time. This can also be used to store binary data (e.g.,
image frames). This can also be a link to data stored in an external file.
attributes:
name:
name: name
ifabsent: string(data)
identifier: true
range: string
required: true
equals_string: data
conversion:
name: conversion
description: Scalar to multiply each element in data to convert it to the
specified 'unit'. If the data are stored in acquisition system units or
other units that require a conversion to be interpretable, multiply the
data by 'conversion' to convert the data to the specified 'unit'. e.g. if
the data acquisition system stores values in this object as signed 16-bit
integers (int16 range -32,768 to 32,767) that correspond to a 5V range (-2.5V
to 2.5V), and the data acquisition system gain is 8000X, then the 'conversion'
multiplier to get from raw data acquisition values to recorded volts is
2.5/32768/8000 = 9.5367e-9.
range: float32
array:
name: array
range: TimeSeries__data__Array
TimeSeries__data__Array:
name: TimeSeries__data__Array
is_a: Arraylike
attributes:
num_times:
name: num_times
range: AnyType
required: true
num_DIM2:
name: num_DIM2
range: AnyType
required: false
num_DIM3:
name: num_DIM3
range: AnyType
required: false
num_DIM4:
name: num_DIM4
range: AnyType
required: false
TimeSeries__timestamps__Array:
name: TimeSeries__timestamps__Array
is_a: Arraylike
attributes:
num_times:
name: num_times
range: float64
required: true
```
````
````{tab-item} Pydantic
```python
class TimeSeries(NWBDataInterface):
"""
General purpose time series.
"""
linkml_meta: ClassVar[LinkML_Meta] = Field(LinkML_Meta(tree_root=True), frozen=True)
name: str = Field(...)
description: Optional[str] = Field(None, description="""Description of the time series.""")
comments: Optional[str] = Field(None, description="""Human-readable comments about the TimeSeries. This second descriptive field can be used to store additional information, or descriptive information if the primary description field is populated with a computer-readable string.""")
data: TimeSeriesData = Field(..., description="""Data values. Data can be in 1-D, 2-D, 3-D, or 4-D. The first dimension should always represent time. This can also be used to store binary data (e.g., image frames). This can also be a link to data stored in an external file.""")
timestamps: Optional[NDArray[Shape["* num_times"], Float64]] = Field(None, description="""Timestamps for samples stored in data, in seconds, relative to the common experiment master-clock stored in NWBFile.timestamps_reference_time.""")
class TimeSeriesData(ConfiguredBaseModel):
"""
Data values. Data can be in 1-D, 2-D, 3-D, or 4-D. The first dimension should always represent time. This can also be used to store binary data (e.g., image frames). This can also be a link to data stored in an external file.
"""
linkml_meta: ClassVar[LinkML_Meta] = Field(LinkML_Meta(), frozen=True)
name: Literal["data"] = Field("data")
conversion: Optional[float] = Field(None, description="""Scalar to multiply each element in data to convert it to the specified 'unit'. If the data are stored in acquisition system units or other units that require a conversion to be interpretable, multiply the data by 'conversion' to convert the data to the specified 'unit'. e.g. if the data acquisition system stores values in this object as signed 16-bit integers (int16 range -32,768 to 32,767) that correspond to a 5V range (-2.5V to 2.5V), and the data acquisition system gain is 8000X, then the 'conversion' multiplier to get from raw data acquisition values to recorded volts is 2.5/32768/8000 = 9.5367e-9.""")
array: Optional[Union[
NDArray[Shape["* num_times"], Any],
NDArray[Shape["* num_times, * num_DIM2"], Any],
NDArray[Shape["* num_times, * num_DIM2, * num_DIM3"], Any],
NDArray[Shape["* num_times, * num_DIM2, * num_DIM3, * num_DIM4"], Any]
]] = Field(None)
```
````
`````
```{toctree}
:caption: Intro
:maxdepth: 3
:hidden:
intro/purpose
intro/nwb
intro/translation
```
```{toctree}
:caption: Guide
:maxdepth: 1
:hidden:
guide/quickstart
guide/overview
```
````{only} minimal
```{toctree}
:caption: API
:maxdepth: 3
:hidden:
api/nwb_linkml/index
api/nwb_schema_language/index
api/nwb_linkml/schema/index
```
````
````{only} full
```{toctree}
:caption: API
:maxdepth: 3
:hidden:
api/nwb_linkml/index
api/nwb_schema_language/index
api/models/nwb_linkml.models
api/nwb_linkml/schema/index
```
````
````{only} minimal
```{toctree}
:caption: Notes
:maxdepth: 3
:hidden:
_notes/linkml
_notes/pynwb
_notes/schema
_notes/translation
```
````
```{toctree}
:caption: Meta
:hidden:
meta/todo
meta/changelog
genindex
```