High Level API Reference
File
A File represents a specific data source of a NIX back-end for example an NIX HDF5 file. All entities of the nix data model must exist in the context of an open File object. Therefore NIX entities can’t be initialized via their constructors but only through the factory methods of their respective parent entity.
Working with files
1file = File.open("test.h5", FileMode.ReadWrite)
2# do some work
3file.close()
File open modes
File API
- class nixio.File(path, mode='a', compression=Compression.Auto, auto_update_timestamps=True)
- property auto_update_timestamps
If enabled, automatically updates the ‘updated_at’ attribute when an object’s data or attributes are changed.
- Type
bool
- property blocks
A property containing all blocks of a file. Blocks can be obtained by their name, id or index. Blocks can be deleted from the list, when a block is deleted all its content (data arrays, tags and sources) will be also deleted from the file. Adding new Block is done via the create_block method of File. This is a read-only attribute.
- close()
Closes an open file.
- copy_section(obj, children=True, keep_id=True, name='')
Copy a section to the file.
- Parameters
obj (nixio.Section) – The Section to be copied
children (bool) – Specify if the copy should be recursive
keep_id (bool) – Specify if the id should be kept
name (str) – Name of copied section, Default is name of source section
- Returns
The copied section
- Return type
- create_block(name='', type_='', compression=Compression.Auto, copy_from=None, keep_copy_id=True)
Create a new block inside the file.
- Parameters
name (str) – The name of the block to create.
type (str) – The type of the block.
compression – No, DeflateNormal, Auto (default: Auto)
copy_from (nixio.Block) – The Block to be copied, None in normal mode
keep_copy_id (bool) – Specify if the id should be copied in copy mode
- Returns
The newly created block.
- Return type
- create_section(name, type_='undefined', oid=None)
Create a new metadata section inside the file.
- Parameters
name (str) – The name of the section to create.
type (str) – The type of the section.
oid (str) – object id, UUID string as specified in RFC 4122. If no id is provided, an id will be generated and assigned.
- Returns
The newly created section.
- Return type
- property created_at
The creation time of the file. This is a read-only property. Use force_created_at in order to change the creation time.
- Return type
int
- find_sections(filtr=<function File.<lambda>>, limit=None)
Get all sections and their child sections recursively.
This method traverses the trees of all sections. The traversal is accomplished via breadth first and can be limited in depth. On each node or section a filter is applied. If the filter returns true the respective section will be added to the result list. By default a filter is used that accepts all sections.
- Parameters
filtr (function) – A filter function
limit (int) – The maximum depth of traversal
- Returns
A list containing the matching sections.
- Return type
list of nixio.Section
- flush()
- force_created_at(time=None)
Sets the creation time created_at to the given time (default: current time).
- Parameters
time (int) – The time to set
- force_updated_at(time=None)
Sets the update time updated_at to the given time. (default: current time)
- Parameters
time (int) – The time to set (default: now)
- property format
The format of the file. This read only property should always have the value ‘nix’.
- Type
str
- property id
- is_open()
Checks whether a file is open or closed.
- Returns
True if the file is open, False otherwise.
- Return type
bool
- classmethod open(path, mode='a', compression=Compression.Auto, backend=None, auto_update_timestamps=True)
Open a NIX file, or create it if it does not exist.
- Parameters
path – Path to file
mode – FileMode ReadOnly, ReadWrite, or Overwrite. (default: ReadWrite)
compression – No, DeflateNormal, Auto (default: Auto)
auto_update_timestamps – Enable/disable automatic updating of ‘updated_at’ timestamp. (default: True)
- Returns
nixio.File object
- pprint(indent=2, max_length=120, extra=True, max_depth=3)
Pretty Printing the Data and MetaData Tree of the whole File
- Parameters
indent (int) – The length of one indentation space
max_length (int) – Maximum length of each line of output
extra (bool) – True to print extra information of Entities
max_depth (int) – Maximum recursion being printed in MetaData tree
- property sections
A property containing all root Sections of a file. Specific root Sections can be obtained by their name, id or index. Sections can be deleted from this list. Notice: when a section is deleted all its child section and properties will be removed too. Adding a new Section is done via the crate_section method of File. This is a read-only property.
- property updated_at
The time of the last update of the file. This is a read-only property. Use force_updated_at in order to change the update time.
- Return type
int
- validate()
- property version
The file format version.
- Type
tuple
Block
The Block entity is a top-level, summarizing element that allows to group the other data entities belonging for example to the same recording session. All data entities such as Source, DataArray, DataFrame, Tag and MultiTag have to be associated with one Block.
Create a new Block
A block can only be created on an existing file object. Do not use the blocks constructors for this purpose.
1block = file.create_block("session one", "recordingsession");
Working with blocks
After a block was created it can be used to create further entities. See the documentation of Source, DataArray, DataFrame, Tag and MultiTag for more information. The next example shows how some properties of a block can be accessed.
1block = file.blocks[some_id]
2
3# add metadata to a block
4section = file.sections[sec_id]
5block.metadata = section
6
7# get associated metadata from a block
8block.metadata
9
10# remove associated metadata from a block
11block.metadata = None
Deleting a block
When a block is deleted from a file all contained data e.g. sources, data arrays and tags will be removed too.
1del file.blocks[some_id]
Block API
- class nixio.Block(nixfile, nixparent, h5group, compression=Compression.Auto)
- create_data_array(name='', array_type='', dtype=None, shape=None, data=None, compression=Compression.Auto, copy_from=None, keep_copy_id=True, label=None, unit=None)
Create/copy a new data array for this block. Either
shape
ordata
must be given. If both are given their shape must agree. Ifdtype
is not specified it will default to 64-bit floating points.- Parameters
name (str) – The name of the data array to create/copy.
array_type (str) – The type of the data array.
dtype (
numpy.dtype
) – Which data-type to use for storageshape (tuple of int or long) – Layout (dimensionality and extent)
data (array-like data) – Data to write after storage has been created
compression (
Compression
) – En-/disable dataset compression.copy_from (nixio.DataArray) – The DataArray to be copied, None in normal mode
keep_copy_id (bool) – Specify if the id should be copied in copy mode
label (str) – The label, defaults to None.
unit (str) – The unit of the stored data. Defaults to None.
- Returns
The newly created data array.
- Return type
- create_data_frame(name='', type_='', col_dict=None, col_names=None, col_dtypes=None, data=None, compression=Compression.No, copy_from=None, keep_copy_id=True)
Create/copy a new data frame for this block. Either
col_dict
orcol_name
andcol_dtypes
must be given. If both are given,col_dict
will be used.- Parameters
name (str) – The name of the data frame to create/copy.
type (str) – The type of the data frame.
col_dict (dict or OrderedDict of {str: type}) – The dictionary that specifies column names and data type in each column
col_names (tuples or list or np.array of string) – The collection of name of all columns in order
col_dtypes (tuples or list or np.array of type) – The collection of data type of all columns in order
data (array-like data with compound data type as specified in the columns) – Data to write after storage has been created
compression (
Compression
) – En-/disable dataset compression.copy_from (nixio.DataFrame) – The DataFrame to be copied, None in normal mode
keep_copy_id (bool) – Specify if the id should be copied in copy mode
- Returns
The newly created data frame.
- Return type
- create_group(name, type_)
Create a new group on this block.
- Parameters
name (str) – The name of the group to create.
type (str) – The type of the group.
- Returns
The newly created group.
- Return type
- create_multi_tag(name='', type_='', positions=None, extents=None, copy_from=None, keep_copy_id=True)
Create/copy a new multi tag for this block.
- Parameters
name (str) – The name of the tag to create/copy.
type (str) – The type of tag.
positions (nixio.DataArray) – A data array defining all positions of the tag.
copy_from (nixio.MultiTag) – The MultiTag to be copied, None in normal mode
keep_copy_id (bool) – Specify if the id should be copied in copy mode
- Returns
The newly created tag.
- Return type
- classmethod create_new(nixparent, h5parent, name, type_, compression)
- create_source(name, type_)
Create a new source on this block.
- Parameters
name (str) – The name of the source to create.
type (str) – The type of the source.
- Returns
The newly created source.
- Return type
- create_tag(name='', type_='', position=0, copy_from=None, keep_copy_id=True)
Create/copy a new tag for this block.
- Parameters
name (str) – The name of the tag to create/copy.
type (str) – The type of tag.
position – Coordinates of the start position in units of the respective data dimension.
copy_from (nixio.Tag) – The Tag to be copied, None in normal mode
keep_copy_id (bool) – Specify if the id should be copied in copy mode
- Returns
The newly created tag.
- Return type
- property created_at
The creation time of the entity. This is a read-only property. Use force_created_at in order to change the creation time.
- Return type
int
- property data_arrays
A property containing all data arrays of a block. DataArray entities can be obtained via their index or by their id. Data arrays can be deleted from the list. Adding a data array is done using the Blocks create_data_array method. This is a read only attribute.
- property data_frames
- property definition
The definition of the entity. The definition can contain a textual description of the entity. This is an optional read-write property, and can be None if no definition is available.
- Type
str
- property file
Reference to the NIX File object. This is a read-only property.
- Return type
- find_sources(filtr=<function Block.<lambda>>, limit=None)
Get all sources in this block recursively.
This method traverses the tree of all sources in the block. The traversal is accomplished via breadth first and can be limited in depth. On each node or source a filter is applied. If the filter returns true the respective source will be added to the result list. By default a filter is used that accepts all sources.
- Parameters
filtr (function) – A filter function
limit (int) – The maximum depth of traversal
- Returns
A list containing the matching sources.
- Return type
list of nixio.Source
- force_created_at(time=None)
Sets the creation time created_at to the given time (default: current time).
- Parameters
time (int) – The time to set.
- force_updated_at(time=None)
Sets the update time updated_at to the given time. (default: current time)
- Parameters
time (int) – The time to set.
- property groups
A property containing all groups of a block. Group entities can be obtained via their index or by their id. Groups can be deleted from the list. Adding a Group is done using the Blocks create_group method. This is a read only attribute.
- property id
A property providing the ID of the Entity. The id is generated automatically, therefore the property is read-only.
- Return type
str
- property metadata
Associated metadata of the entity. Sections attached to the entity via this attribute can provide additional annotations. This is an optional read-write property, and can be None if no metadata is available.
- Type
- property multi_tags
A property containing all multi tags of a block. MultiTag entities can be obtained via their index or by their id. Tags can be deleted from the list. Adding tags is done using the Blocks create_multi_tag method. This is a read only attribute.
- property name
The name of an entity. The name serves as a human readable identifier. This is a read-only property; entities cannot be renamed.
- Type
str
- pprint(indent=2, max_length=120, extra=True, start_depth=0)
Pretty Printing the Data and MetaData Tree of the whole File
- Parameters
indent (int) – The length of one indentation space
max_length (int) – Maximum length of each line of output
extra (bool) – True to print extra information of Entities
start_depth (int) – Starting depth of indentation
- property sources
A property containing all sources of a block. Sources can be obtained via their index or by their id. Sources can be deleted from the list. Adding sources is done using the Blocks create_source method. This is a read only attribute.
- property tags
A property containing all tags of a block. Tag entities can be obtained via their index or by their id. Tags can be deleted from the list. Adding tags is done using the Blocks create_tag method. This is a read only attribute.
- property type
The type of the entity. The type is used in order to add semantic meaning to the entity. This is a read-write property, but it can’t be set to None.
- Type
str
- property updated_at
The time of the last update of the entity. This is a read-only property. Use force_updated_at in order to change the update time.
- Return type
int
DataArray
The DataArray is the core entity of the NIX data model, its purpose is to store arbitrary n-dimensional data. In addition to the common fields id, name, type, and definition the DataArray stores sufficient information to understand the physical nature of the stored data.
A guiding principle of the data model is provides enough information to create a plot of the stored data. In order to do so, the DataArray defines a property dataType which provides the physical type of the stored data (for example 16 bit integer or double precision IEEE floatingpoint number). The property unit specifies the SI unit of the values stored in the DataArray whereas the label defines what is given in this units. Together, both specify what corresponds to the the y-axis of a plot.
In some cases it is much more efficient or convenient to store data not as floating point numbers but rather as (16 bit) integer values as, for example read from a data acquisition board. In order to convert such data to the correct values, we follow the approach taken by the comedi data-acquisition library (http://www.comedi.org) and provide polynomCoefficients and an expansionOrigin.
Create and delete a DataArray
A DataArray can only be created at an existing block. Do not use the DataArrays constructors for this purpose.
1data_array = block.crate_data_array("matrix", "data");
2del block.data_arrays[data_array]
DataArray API
- class nixio.DataArray(nixfile, nixparent, h5group)
- append(data, axis=0)
Append
data
to the DataSet along theaxis
specified.- Parameters
data – The data to append. Shape must agree except for the specified axis
axis – Along which axis to append the data to
- append_range_dimension(ticks=None, label=None, unit=None)
Append a new RangeDimension to the list of existing dimension descriptors.
- Parameters
ticks (list of float) – The ticks of the RangeDimension to create.
label (str) – The label of the dimension
unit (str) – The physical unit of the dimension
- Returns
The newly created RangeDimension.
- Return type
- append_range_dimension_using_self(index=None)
Convenience function to append a new RangeDimension to the list of existing dimensions that uses the DataArray itself as provider for the ticks. This is a replacement for rdim = array.append_range_dimension() rdim.link_data_array(self, index)
- Parameters
index – The slice of the DataArray that contains the tick values. This must be a vector of the data. Defaults to [-1], i.e. the full first dimension.
- Type
list of int
- Returns
the newly created nixio.RangeDimension
- Return type
- append_sampled_dimension(sampling_interval, label=None, unit=None, offset=None)
Append a new SampledDimension to the list of existing dimension descriptors.
- Parameters
sampling_interval (float) – The sampling interval of the SetDimension to create.
label (str) – The label of the dimension
unit (str) – The physical unit of the dimension
offset (float) – The offset between 0 and the first sample
- Returns
The newly created SampledDimension.
- Return type
- append_set_dimension(labels=None)
Append a new SetDimension to the list of existing dimension descriptors.
- Parameters
labels (list or convertible to list) – The set of sample labels
- Returns
The newly created SetDimension.
- Return type
- classmethod create_new(nixfile, nixparent, h5parent, name, type_, data_type, shape, compression)
- property created_at
The creation time of the entity. This is a read-only property. Use force_created_at in order to change the creation time.
- Return type
int
- property data_extent
The size of the data.
- Type
tuple of int
- property data_type
The data type of the data stored in the DataArray. This is a read only property.
- Type
- property definition
The definition of the entity. The definition can contain a textual description of the entity. This is an optional read-write property, and can be None if no definition is available.
- Type
str
- delete_dimensions()
Delete all the dimension descriptors for this DataArray.
- property dimensions
A property containing all dimensions of a DataArray. Dimensions can be obtained via their index. Adding dimensions is done using the respective append methods for dimension descriptors. This is a read only attribute.
- Type
Container of dimension descriptors.
- property dtype
The data type of the data stored in the DataArray. This is a read only property.
- Returns
The data type
- Return type
- property expansion_origin
The expansion origin of the calibration polynomial. This is a read-write property and can be set to None. The default value is 0.
- Type
float
- property file
Reference to the NIX File object. This is a read-only property.
- Return type
- force_created_at(time=None)
Sets the creation time created_at to the given time (default: current time).
- Parameters
time (int) – The time to set.
- force_updated_at(time=None)
Sets the update time updated_at to the given time. (default: current time)
- Parameters
time (int) – The time to set.
- get_slice(positions, extents=None, mode=DataSliceMode.Index)
Reads a slice of the data. The slice can be specified either in indices or in data coordinates. For example, if the DataArray stores 1D data spanning one second in time sampled with 1kHz (1000 data points). If one wants to read the data of the interval 0.25 to 0.5 seconds, one can use either of the following statements:
- ```
interval_data = data_array.get_slice([250], [500], mode=DataSliceMode.Index)[:] interval_data = data_array.get_slice([0.25],[0.25], mode=DataSliceMode.Data)[:]
Note: The extents are not the end positions but the extent of the slice!
- Parameters
positions (list length must match dimensionality of the data.) – Specifies the start of the data slice. List of either indices or data positions depending on the DataSliceMode.
extents (list, defaults to None) – Specifies the extents of the slice for each dimension.
mode (nixio.DataSliceMode) – Specifies how positions and extents are interpreted, they are either treated as indices (DataSliceMode.Index) or as positions in data coordinates (DataSliceMode.Data), Defaults to nixio.DataSliceMode.Index.
- Raises
nixio.IncompatibleDimensions: if length of positions or, if given, extents does not match the rank of the data.
- Raises
ValueError: if an invalid slice mode is given
- Returns
A nixio.DataView object
- Return type
nixio.DataView
- property id
A property providing the ID of the Entity. The id is generated automatically, therefore the property is read-only.
- Return type
str
- iter_dimensions()
1-based index dimension iterator. The method returns a generator which returns the index starting from one and the dimensions.
- property label
The label of the DataArray. The label corresponds to the label of the x-axis of a plot. This is a read-write property and can be set to None.
- Type
str
- len()
Length of the first dimension. Equivalent to DataSet.shape[0].
- Type
int or long
- property metadata
Associated metadata of the entity. Sections attached to the entity via this attribute can provide additional annotations. This is an optional read-write property, and can be None if no metadata is available.
- Type
- property name
The name of an entity. The name serves as a human readable identifier. This is a read-only property; entities cannot be renamed.
- Type
str
- property polynom_coefficients
The polynomial coefficients for the calibration. By default this is set to a {0.0, 1.0} for a linear calibration with zero offset. This is a read-write property and can be set to None
- Return type
list of float
- read_direct(data)
Directly read all data stored in the
DataSet
intodata
. The supplied data must be anumpy.ndarray
that matches the DataSet’s shape, must have C-style contiguous memory layout and must be writeable (seenumpy.ndarray.flags
andndarray
for more information).- Parameters
data (
numpy.ndarray
) – The array where data is being read into
- property shape
- Type
tuple of data array dimensions.
- property size
Number of elements in the DataSet, i.e. the product of the elements in
shape
.- Type
int
- property sources
A property containing all Sources referenced by the DataArray. Sources can be obtained by index or their id. Sources can be removed from the list, but removing a referenced Source will not remove it from the file. New Sources can be added using the append method of the list. This is a read only attribute.
- property type
The type of the entity. The type is used in order to add semantic meaning to the entity. This is a read-write property, but it can’t be set to None.
- Type
str
- property unit
The unit of the values stored in the DataArray. This is a read-write property and can be set to None.
- Type
str
- property updated_at
The time of the last update of the entity. This is a read-only property. Use force_updated_at in order to change the update time.
- Return type
int
- write_direct(data)
Directly write all of
data
to theDataSet
. The supplied data must be anumpy.ndarray
that matches the DataSet’s shape and must have C-style contiguous memory layout (seenumpy.ndarray.flags
andndarray
for more information).- Parameters
data (
numpy.ndarray
) – The array which contents is being written
DataSet
The DataSet object is used for data input/output to the underlying storage.
- class nixio.data_array.DataSet
Data IO object for DataArray.
- append(data, axis=0)
Append
data
to the DataSet along theaxis
specified.- Parameters
data – The data to append. Shape must agree except for the specified axis
axis – Along which axis to append the data to
- property data_extent
The size of the data.
- Type
tuple of int
- property data_type
The data type of the data stored in the DataArray. This is a read only property.
- Type
- property dtype
- Type
numpy.dtype
object holding type information about the data stored in the DataSet.
- len()
Length of the first dimension. Equivalent to DataSet.shape[0].
- Type
int or long
- read_direct(data)
Directly read all data stored in the
DataSet
intodata
. The supplied data must be anumpy.ndarray
that matches the DataSet’s shape, must have C-style contiguous memory layout and must be writeable (seenumpy.ndarray.flags
andndarray
for more information).- Parameters
data (
numpy.ndarray
) – The array where data is being read into
- property shape
- Type
tuple of data array dimensions.
- property size
Number of elements in the DataSet, i.e. the product of the elements in
shape
.- Type
int
- write_direct(data)
Directly write all of
data
to theDataSet
. The supplied data must be anumpy.ndarray
that matches the DataSet’s shape and must have C-style contiguous memory layout (seenumpy.ndarray.flags
andndarray
for more information).- Parameters
data (
numpy.ndarray
) – The array which contents is being written
DataFrame
The DataFrame presents data in a rows-and-columns format.
Create and delete a DataFrame
1data_array = block.create_data_frame("table", "df", col_dict={}, data=[]);
2del block.data_frames[data_frame]
DataFrame API
- class nixio.DataFrame(nixfile, nixparent, h5group)
- append(data, axis=0)
Append
data
to the DataSet along theaxis
specified.- Parameters
data – The data to append. Shape must agree except for the specified axis
axis – Along which axis to append the data to
- append_column(column, name, datatype=None)
Append a new column to the DataFrame In case of string, it will be better to set explicitly the datatype.
- Parameters
column (array-like data) – The new column
name (str) – The name of new column
datatype (nixio.DataType) – The DataType of new column
- append_rows(data)
Append a new row to the DataFrame. The data supplied must be iterable.
- Parameters
data (array-like data) – The new row
- property column_names
The dtype is the list of names of all columns in the DatFrame. This is a read only property.
- Type
list of str
- property columns
The dtype is the list of names and data types of all columns in the DatFrame. This is a read only property.
- Type
list of tuples
- classmethod create_new(nixfile, nixparent, h5parent, name, type_, shape, col_dtype, compression)
- property created_at
The creation time of the entity. This is a read-only property. Use force_created_at in order to change the creation time.
- Return type
int
- property data_extent
The size of the data.
- Type
tuple of int
- property data_type
The data type of the data stored in the DataArray. This is a read only property.
- Type
- property definition
The definition of the entity. The definition can contain a textual description of the entity. This is an optional read-write property, and can be None if no definition is available.
- Type
str
- property df_shape
The df_shape is the shape of the DataFrame in (number of rows, number of columns) format. This is a read only property.
- Type
tuple
- property dtype
The dtype is the list of DataTypes of all columns in the DatFrame. This is a read only property.
- Type
list of DataType
- property file
Reference to the NIX File object. This is a read-only property.
- Return type
- force_created_at(time=None)
Sets the creation time created_at to the given time (default: current time).
- Parameters
time (int) – The time to set.
- force_updated_at(time=None)
Sets the update time updated_at to the given time. (default: current time)
- Parameters
time (int) – The time to set.
- property id
A property providing the ID of the Entity. The id is generated automatically, therefore the property is read-only.
- Return type
str
- len()
Length of the first dimension. Equivalent to DataSet.shape[0].
- Type
int or long
- property metadata
Associated metadata of the entity. Sections attached to the entity via this attribute can provide additional annotations. This is an optional read-write property, and can be None if no metadata is available.
- Type
- property name
The name of an entity. The name serves as a human readable identifier. This is a read-only property; entities cannot be renamed.
- Type
str
- print_table(row_sl=None, col_sl=None)
Print the whole DataFrame as a table
- Parameters
row_sl (slice or iterable of int) – Rows to be printed; None for printing all rows
col_sl (slice or iterable of int) – Columns to be printed; None for printing all columns
- read_cell(position=None, col_name=None, row_idx=None)
Read a cell in the DataFrame
- Parameters
position (tuple or list or array with length 2) – Position of the targeted cell
col_name (str) – The column name in which the targeted cell belongs to
row_idx (list of int) – A length 1 list that specify on which row the targeted cell is located
- read_columns(index=None, name=None, slc=None, group_by_cols=False)
Read one or multiple (part of) column(s) in the DataFrame
- Parameters
index (list of int) – Index of column(s) to be returned
name (list of str) – Name of column(s) to be returned
slc (slice) – The part of each column to be returned
group_by_cols (bool) – True for group return values by columns, False for group by rows. Only applicable for reading multiple columns
- read_direct(data)
Directly read all data stored in the
DataSet
intodata
. The supplied data must be anumpy.ndarray
that matches the DataSet’s shape, must have C-style contiguous memory layout and must be writeable (seenumpy.ndarray.flags
andndarray
for more information).- Parameters
data (
numpy.ndarray
) – The array where data is being read into
- read_rows(index)
Read one or multiple row(s) in the DataFrame
- Parameters
index (list of int) – Index of row(s) to be returned
- row_count()
Return the total number of rows
- property shape
- Type
tuple of data array dimensions.
- property size
Number of elements in the DataSet, i.e. the product of the elements in
shape
.- Type
int
- property type
The type of the entity. The type is used in order to add semantic meaning to the entity. This is a read-write property, but it can’t be set to None.
- Type
str
- property units
The unit of the values stored in the DataFrame. This is a read-write property and can be set to None.
- Type
array of str
- property updated_at
The time of the last update of the entity. This is a read-only property. Use force_updated_at in order to change the update time.
- Return type
int
- write_cell(cell, position=None, col_name=None, row_idx=None)
Overwrite a cell in the DataFrame
- Parameters
cell (same type as the specified column) – The new cell
position (tuple or list or array with length 2) – Position of the targeted cell
col_name (str) – The column name in which the targeted cell belongs to
row_idx (list of int) – A length 1 list that specify on which row the targeted cell is located
- write_column(column, index=None, name=None)
Overwrite an existing column. Either index or name of the column should be provided.
- Parameters
column (array-like data) – The new column
index (string) – The index of the column that is written to
name (str) – The name of the column that is written to
- write_direct(data)
Directly write all of
data
to theDataSet
. The supplied data must be anumpy.ndarray
that matches the DataSet’s shape and must have C-style contiguous memory layout (seenumpy.ndarray.flags
andndarray
for more information).- Parameters
data (
numpy.ndarray
) – The array which contents is being written
- write_rows(rows, index)
Overwrite one or multiple existing row(s)
- Parameters
rows ((nested) array-like data) – The new rows(s) and their data
index (list of int) – Index of rows(s) to be overwritten
- write_to_csv(filename, mode='w')
Export the whole DataFrame to a CSV file
- Parameters
filename (str) – The resulted/ targeted CSV file to write to/ create
mode (str) – The column name in which the targeted cell belongs to
Source
- class nixio.Source(nixfile, nixparent, h5group)
- classmethod create_new(nixfile, nixparent, h5parent, name, type_)
- create_source(name, type_)
Create a new source as a child of the current Source.
- Parameters
name (str) – The name of the source to create.
type (str) – The type of the source.
- Returns
The newly created source.
- Return type
- property created_at
The creation time of the entity. This is a read-only property. Use force_created_at in order to change the creation time.
- Return type
int
- property definition
The definition of the entity. The definition can contain a textual description of the entity. This is an optional read-write property, and can be None if no definition is available.
- Type
str
- property file
Reference to the NIX File object. This is a read-only property.
- Return type
- find_sources(filtr=<function Source.<lambda>>, limit=None)
Get all child sources of this source recursively.
This method traverses the tree of all sources. The traversal is accomplished via breadth first and can be limited in depth. On each node or source a filter is applied. If the filter returns true the respective source will be added to the result list. By default a filter is used that accepts all sources.
- Parameters
filtr (function) – A filter function
limit (int) – The maximum depth of traversal
- Returns
A list containing the matching sources.
- Return type
list of nixio.Source
- force_created_at(time=None)
Sets the creation time created_at to the given time (default: current time).
- Parameters
time (int) – The time to set.
- force_updated_at(time=None)
Sets the update time updated_at to the given time. (default: current time)
- Parameters
time (int) – The time to set.
- property id
A property providing the ID of the Entity. The id is generated automatically, therefore the property is read-only.
- Return type
str
- property metadata
Associated metadata of the entity. Sections attached to the entity via this attribute can provide additional annotations. This is an optional read-write property, and can be None if no metadata is available.
- Type
- property name
The name of an entity. The name serves as a human readable identifier. This is a read-only property; entities cannot be renamed.
- Type
str
- property parent_block
Returns the block this source is contained in.
- Returns
the Block containing this source
- Return type
- property parent_source
Get the parent source of this source. If this source is at the root, None will be returned
- Returns
the parent source
- Return type
Source or None
- property referring_data_arrays
Returns all DataArray entities linking to this source.
- Returns
all DataArrays referring to this source.
- Return type
list
- property referring_multi_tags
Returns all MultiTag entities linking to this source.
- Returns
all MultiTags referring to this source.
- Return type
list
- property referring_objects
Returns the list of entities that link to this source.
- Returns
all objects referring to this source.
- Return type
list
- property referring_tags
Returns all Tag entities linking to this source.
- Returns
all Tags referring to this source.
- Return type
list
- property sources
A property containing child sources of a Source. Sources can be obtained via their name, index, id. Sources can be deleted from the list. Adding sources is done using the Blocks create_source method. This is a read only attribute.
- property type
The type of the entity. The type is used in order to add semantic meaning to the entity. This is a read-write property, but it can’t be set to None.
- Type
str
- property updated_at
The time of the last update of the entity. This is a read-only property. Use force_updated_at in order to change the update time.
- Return type
int
Group
Groups establish a simple way of grouping entities that in some way belong together. The Group exists inside a Block and can contain (link) DataArrays, Tags, and MultiTags. As any other nix-entity, the Groups is named, has a type, and a definition property. Additionally, it contains data_arrays, tags, and multi_tags lists. As indicated before, the group does only link the entities. Thus, deleting elements from the lists does not remove them from file, it merely removes the link from the group.
1data_array = block.create_data_array("matrix", "data");
2tag = block.create_tag("a tag", "event", [0.0, 1.0])
3group = block.create_group("things that belong together", "group")
4group.tags.append(tag)
5group.data_arrays.append(data_array)
6
7del group.data_arrays[data_array]
8del group.tags[tag]
Group API
- class nixio.Group(nixfile, nixparent, h5group)
- classmethod create_new(nixfile, nixparent, h5parent, name, type_)
- property created_at
The creation time of the entity. This is a read-only property. Use force_created_at in order to change the creation time.
- Return type
int
- property data_arrays
A property containing all data arrays referenced by the group. Referenced data arrays can be obtained by index or their id. References can be removed from the list, removing a referenced DataArray will not remove it from the file. New references can be added using the append method of the list. This is a read only attribute.
- property data_frames
A property containing all data frames referenced by the group. Referenced data frames can be obtained by index or their id. References can be removed from the list, removing a referenced DataFrame will not remove it from the file. New references can be added using the append method of the list. This is a read only attribute.
- property definition
The definition of the entity. The definition can contain a textual description of the entity. This is an optional read-write property, and can be None if no definition is available.
- Type
str
- property file
Reference to the NIX File object. This is a read-only property.
- Return type
- force_created_at(time=None)
Sets the creation time created_at to the given time (default: current time).
- Parameters
time (int) – The time to set.
- force_updated_at(time=None)
Sets the update time updated_at to the given time. (default: current time)
- Parameters
time (int) – The time to set.
- property id
A property providing the ID of the Entity. The id is generated automatically, therefore the property is read-only.
- Return type
str
- property metadata
Associated metadata of the entity. Sections attached to the entity via this attribute can provide additional annotations. This is an optional read-write property, and can be None if no metadata is available.
- Type
- property multi_tags
A property containing all MultiTags referenced by the group. MultiTags can be obtained by index or their id. MultiTags can be removed from the list, removing a referenced MultiTag will not remove it from the file. New MultiTags can be added using the append method of the list. This is a read only attribute.
- property name
The name of an entity. The name serves as a human readable identifier. This is a read-only property; entities cannot be renamed.
- Type
str
- property sources
A property containing all Sources referenced by the Group. Sources can be obtained by index or their id. Sources can be removed from the list, but removing a referenced Source will not remove it from the file. New Sources can be added using the append method of the list. This is a read only attribute.
- property tags
A property containing all tags referenced by the group. Tags can be obtained by index or their id. Tags can be removed from the list, removing a referenced Tag will not remove it from the file. New Tags can be added using the append method of the list. This is a read only attribute.
- property type
The type of the entity. The type is used in order to add semantic meaning to the entity. This is a read-write property, but it can’t be set to None.
- Type
str
- property updated_at
The time of the last update of the entity. This is a read-only property. Use force_updated_at in order to change the update time.
- Return type
int
Section
Metadata stored in a NIX file can be accessed directly from an open file.
Create and delete sub sections
1sub = section.create_section("a name", "type")
2del section.sections[sub]
Add and remove properties
Properties can be created using the create_property method. Existing properties can be accessed and deleted directly from the respective section.
1section.create_property("one", [1])
2section.create_property("two", [2])
3
4# iterate over properties
5for p in section:
6 print(p)
7
8# access by name
9one = section["one"]
10
11# convert properties into a dict
12dct = dict(section.items())
13
14# delete properties
15del section["one"]
16del section["two"]
Section API
- class nixio.Section(nixfile, nixparent, h5group)
- copy_section(obj, children=True, keep_id=True, name='')
Copy a section to the section.
- Parameters
obj (nixio.Section) – The Section to be copied
children (bool) – Specify if the copy should be recursive
keep_id (bool) – Specify if the id should be kept
name (str) – Name of copied section, Default is name of source section
- Returns
The copied section
- Return type
- classmethod create_new(nixfile, nixparent, h5parent, name, type_, oid=None)
- create_property(name='', values_or_dtype=0, oid=None, copy_from=None, keep_copy_id=True)
Add a new property to the section.
- Parameters
name (str) – The name of the property to create/copy.
values_or_dtype (list of values or a nixio.DataType) – The values of the property or a valid DataType.
oid (str) – object id, UUID string as specified in RFC 4122. If no id is provided, an id will be generated and assigned.
copy_from (nixio.Property) – The Property to be copied, None in normal mode
keep_copy_id (bool) – Specify if the id should be copied in copy mode
- Returns
The newly created property.
- Return type
- create_section(name, type_='undefined', oid=None)
Creates a new subsection that is a child of this section entity.
- Parameters
name (str) – The name of the section to create.
type (str) – The type of the section.
oid (str) – object id, UUID string as specified in RFC 4122. If no id is provided, an id will be generated and assigned.
- Returns
The newly created section.
- Return type
- property created_at
The creation time of the entity. This is a read-only property. Use force_created_at in order to change the creation time.
- Return type
int
- property definition
The definition of the entity. The definition can contain a textual description of the entity. This is an optional read-write property, and can be None if no definition is available.
- Type
str
- property file
Reference to the NIX File object. This is a read-only property.
- Return type
Get all related sections of this section.
The result can be filtered. On each related section a filter is applied. If the filter returns true the respective section will be added to the result list. By default a filter is used that accepts all sections.
- Parameters
filtr (function) – A filter function
- Returns
A list containing the matching related sections.
- Return type
list of nixio.Section
- find_sections(filtr=<function Section.<lambda>>, limit=None)
Get all child sections recursively. This method traverses the trees of all sections. The traversal is accomplished via breadth first and can be limited in depth. On each node or section a filter is applied. If the filter returns true the respective section will be added to the result list. By default a filter is used that accepts all sections.
- Parameters
filtr (function) – A filter function
limit (int) – The maximum depth of traversal
- Returns
A list containing the matching sections.
- Return type
list of nixio.Section
- force_created_at(time=None)
Sets the creation time created_at to the given time (default: current time).
- Parameters
time (int) – The time to set.
- force_updated_at(time=None)
Sets the update time updated_at to the given time. (default: current time)
- Parameters
time (int) – The time to set.
- property id
A property providing the ID of the Entity. The id is generated automatically, therefore the property is read-only.
- Return type
str
- inherited_properties()
- items()
- property link
Link to another section. If a section is linked to another section, the linking section inherits all properties from the target section. This is an optional read-write property and may be set to None.
- Type
- property name
The name of an entity. The name serves as a human readable identifier. This is a read-only property; entities cannot be renamed.
- Type
str
- property parent
The parent section. This is a read-only property. For root sections this property is always None.
Accessing this property can be slow when the metadata tree is large.
- Type
- pprint(indent=2, max_depth=1, max_length=80, current_depth=0)
Pretty print method.
- Parameters
indent (int) – The number of indentation spaces per recursion
max_depth (int) – The maximum times of recursion
max_length (int) – The maximum length of each line of output
current_depth (int) – The current times of recursion
- property props
A property containing all Property entities associated with the section. Properties can be accessed by name, index, or id. Properties can be deleted from the list. Adding new Properties is done using the create_property method. This is a read-only attribute.
- Type
Container of nixio.Property
- property reference
- property referring_blocks
- property referring_data_arrays
- property referring_groups
- property referring_multi_tags
- property referring_objects
- property referring_sources
- property referring_tags
- property repository
URL to the terminology repository the section is associated with. This is an optional read-write property and may be set to None.
- Type
str
- property sections
A property providing all child Sections of a Section. Child sections can be accessed by name, index, or id. Sections can also be deleted: if a Section is deleted, all its properties and child Sections are removed from the file too. Adding new Sections is achieved using the create_section method. This is a read-only attribute.
- Type
Container of nixio.Section
- property type
The type of the entity. The type is used in order to add semantic meaning to the entity. This is a read-write property, but it can’t be set to None.
- Type
str
- property updated_at
The time of the last update of the entity. This is a read-only property. Use force_updated_at in order to change the update time.
- Return type
int
Property
- class nixio.Property(nixfile, nixparent, h5dataset)
An odML Property
- classmethod create_new(nixfile, nixparent, h5parent, name, dtype, shape=None, oid=None)
- property created_at
The creation time of the entity. This is a read-only property. Use force_created_at in order to change the creation time.
- Return type
int
- property data_type
- property definition
The definition of the entity. The definition can contain a textual description of the entity. This is an optional read-write property, and can be None if no definition is available.
- Type
str
- delete_values()
- property dependency
- property dependency_value
- extend_values(data)
Extends values to existing data. Suitable when new data is nested or original data is long.
- property file
Reference to the NIX File object. This is a read-only property.
- Return type
- force_created_at(time=None)
Sets the creation time created_at to the given time (default: current time).
- Parameters
time (int) – The time to set.
- force_updated_at(time=None)
Sets the update time updated_at to the given time. (default: current time)
- Parameters
time (int) – The time to set.
- property id
A property providing the ID of the Entity. The id is generated automatically, therefore the property is read-only.
- Return type
str
- property name
The name of an entity. The name serves as a human readable identifier. This is a read-only property; entities cannot be renamed.
- Type
str
- property odml_type
- pprint(indent=2, max_length=80, current_depth=- 1)
Pretty print method. Method is called in Section.pprint()
- property reference
- property type
The type of the entity. The type is used in order to add semantic meaning to the entity. This is a read-write property, but it can’t be set to None.
- Type
str
- property uncertainty
- property unit
- property updated_at
The time of the last update of the entity. This is a read-only property. Use force_updated_at in order to change the update time.
- Return type
int
- property value_origin
- property values