File handling¶
The File entity encapsulates all information of a dataset. File entities keep some general information such as creation time and date, format version etc. It is the entry-point to a NIX file.
File modes¶
A NIX file can be opened in one of three modes:
nixio.FileMode.Overwrite
Used for creating a new file or overwriting any content in an existing one!nixio.FileMode.ReadWrite
Opens a file if it exists or otherwise creates a new one. Does not overwrite existing content.nixio.FileMode.ReadOnly
Opens an existing file. The content can not be changed. Will raise an error when the provided path is invalid (e.g. the file does not exist).
Creating a new file¶
import nixio
import datetime as dt
file_name = 'file_create_example.nix'
# create a new file overwriting any existing content
nixfile = nixio.File.open(file_name, nixio.FileMode.Overwrite)
print("Nix file: %s\n\tformat: %s\n\tversion: %s\n\tcreated at: %s" % (file_name, nixfile.format, nixfile.version,
str(dt.datetime.fromtimestamp(nixfile.created_at))))
nixfile.close()
As mentioned above, using nixio.FileMode.Overwrite
will destroy any existing content of the file. By default, if the FileMode
flag is not specified, a file is opened in the FileMode.ReadWrite
mode.
In this tutorial files will always have the extension *.nix
. This is not specified in the library and you are free to use any file extension.
Opening existing files¶
Use nixio.FileMode.ReadWrite
or nixio.FileMode.ReadOnly
to open
an existing file to work with the data. If you want to overwrite any
existing content in order to replace the file use
nixio.FileMode.Overwite
.
In ReadOnly
mode, you cannot change the file content:
# re-open file for read-only access
nixfile = nixio.File.open(file_name, nixio.FileMode.ReadOnly)
# this command will fail putting out an error
try:
nixfile.create_block("test block", "test")
except ValueError:
print("Error caught: cannot create a new group in nix.FileMode.ReadOnly mode")
nixfile.close()
In order to change the file content the file needs to be opened in ReadWrite
mode:
# re-open for read-write access, creating new entities will work
nixfile = nixio.File.open(file_name, nixio.FileMode.ReadWrite)
nixfile.create_block("test block", "test")
nixfile.close()
Trying to open an non-existing file in ReadOnly
mode will lead to an
error!
nonexistingfilename = "nonexistingfile.nix"
try:
nixfile = nixio.File.open(nonexistingfilename, nixio.FileMode.ReadOnly)
except RuntimeError as e:
print("Error caught: %s" % str(e))
print("One cannot open a file, that is not existing and forbidding the library to write it.")
Enabling compression¶
By default, data stored inside a NIX file will not be compressed. You can switch on compression during file opening.
nixfile = nixio.File.open(file_name, mode=nixio.FileMode.Overwrite, compression=nixio.Compression.DeflateNormal)
nixfile.close()
Compression is handled transparently by the hdf5-library, no further
user interaction is required. Compression reduces reading and writing
performance. You can choose to switch off compression on individual
DataArrays by passing the nixio.Compression.No
flag at
the time of creation.