nex5file package

Submodules

nex5file.filedata module

class nex5file.filedata.FileData(tsFrequency: float = 10000, comment: str = '')

Bases: object

FileData: Class for Managing Data in .nex and .nex5 Data Files.

Parameters:

timestamp_frequencyHz (float) – The timestamp frequency in Hertz. Defaults to 100,000 Hertz.

Raises:

ValueError – If timestamp_frequencyHz is less than or equal to 0.

Example:

from nex5file.filedata import FileData

# Create a FileData instance with a custom timestamp frequency
file_data = FileData(timestamp_frequencyHz=50000, comment="Sample Data")

# Add an event variable to the data
file_data.AddEvent("EventVariable", [1.0, 2.0, 3.0])

# Retrieve a variable by name
event_var = file_data["EventVariable"]

# Get the timestamp frequency
timestamp_frequency = file_data.GetTimestampFrequency()

AddContSingleFragmentValuesInt16(contName: str, samplingRate: float, startTimestamp: float, contValuesAsInt16: list, rawToMV: float, rawOffset: float) → None

Add a continuous variable with a single fragment by specifying int16 values and scaling to the FileData instance.

Parameters:

• contName (str) – The name of the continuous variable.

• samplingRate (float) – The sampling rate of the continuous variable in Hertz.

• startTimestamp (float) – The timestamp at the start of the first fragment in seconds.

• contValuesAsInt16 (numpy array of type np.int16) – The continuous values as int16 values.

• rawToMV (float) – Conversion factor from AD units to millivolts (millivolts).

• rawOffset (float) – Offset in millivolts.

Example:

file_data.AddContSingleFragmentValuesInt16("ContVariable", 1000.0, 0.0, [100, 200, 300], 0.1, 0.0)

AddContVarWithFloatsAllTimestamps(contName: str, samplingRate: float, allTimestamps: list, contValues: list) → None

Add a continuous variable with float values and all the timestamps to the data.

Parameters:

• contName (str) – The name of the continuous variable.

• samplingRate (float) – The sampling rate of the continuous variable in Hertz.

• allTimestamps (numpy array of type np.float64) – The timestamps for all data points in seconds.

• contValues (numpy array of type np.float32) – The continuous values in millivolts.

Example:

timestamps = [0.0, 0.001, 0.002]
values = [1.0, 2.0, 3.0]
file_data.AddContVarWithFloatsAllTimestamps("ContVariable", 1000.0, timestamps, values)

AddContVarWithFloatsSingleFragment(contName: str, samplingRate: float, startTimestamp: float, contValues: list) → None

Add a continuous variable with float values and a single fragment to the FileData instance.

Parameters:

• contName (str) – The name of the continuous variable.

• samplingRate (float) – The sampling rate of the continuous variable in Hertz.

• startTimestamp (float) – The timestamp at the start of the first fragment in seconds.

• contValues (List[float]) – The continuous values in millivolts.

Example:

file_data.AddContVarWithFloatsSingleFragment("ContVariable", 1000.0, 0.0, [1.0, 2.0, 3.0])

AddEvent(evName: str, evTimestamps: list) → None

Add an event variable to the FileData instance.

Parameters:

• evName (str) – The name of the event variable.

• evTimestamps (List[float]) – Event timestamps in seconds.

Example:

file_data.AddEvent("EventVariable", [1.0, 2.0, 3.0])

AddIntervalAsPairsStartEnd(intName: str, intervalsAsPairs) → None

Add an interval variable to the FileData instance using start and end pairs.

Parameters:

• intName (str) – The name of the interval variable.

• intervalsAsPairs (list of tuples) – List of interval start and end pairs in seconds.

Example:

intervals = [(0.0, 1.0), (1.5, 2.0)]
file_data.AddIntervalAsPairsStartEnd("IntervalVariable", intervals)

AddMarker(markerName, timestamps: list, fieldNames: list, fields)

Add a marker variable to the FileData instance.

Parameters:

• markerName (str) – The name of the marker variable.

• timestamps (List[float]) – The timestamps in seconds.

• fieldNames (List[str]) – The names of marker fields.

• fields (list) – List of marker fields. Each element of the list contains values for a field.

Raises:

ValueError – If the number of field names does not match the number of fields or if the length of any field does not match the length of timestamps.

Example:

field_names = ["Field1", "Field2"]
fields = [[1.0, 2.0], [3.0, 'abc']]
file_data.AddMarker("MarkerVariable", [0.0, 1.0], field_names, fields)

AddNeuron(nrName: str, nrTimestamps: list, wire: int = 0, unit: int = 0, xPosition: float = 0, yPosition: float = 0) → None

Add a neuron variable to the FileData instance.

Parameters:

• nrName (str) – The name of the neuron variable.

• nrTimestamps (List[float]) – Neuron timestamps in seconds.

• wire (int) – The wire number. Defaults to 0.

• unit (int) – The unit number. Defaults to 0.

• xPosition (float) – The x-position in range [0,100]. Defaults to 0.

• yPosition (float) – The y-position in range [0,100]. Defaults to 0.

Example:

file_data.AddNeuron("NeuronVariable", [1.0, 2.0, 3.0])

AddWaveVarWithFloats(waveName: str, samplingRate: float, timestamps: list, waveValues: list) → None

Add a waveform variable with float values to the data.

Parameters:

• waveName (str) – The name of the waveform variable.

• samplingRate (float) – The sampling rate of the waveform variable in Hertz.

• timestamps (numpy array of type np.float64) – The timestamps in seconds.

• waveValues (numpy array of type np.float32) – The waveform values as a numpy array. Each column represents a waveform.

Example:

wave_name = "WaveformVariable"
sampling_rate = 1000.0  # Hertz
timestamps = [0.0, 1.0, 2.0]
wave_values = [[2, 3, 4, 1], [5, 6, 7, 2]

file_data.AddWaveVarWithFloats(wave_name, sampling_rate, timestamps, wave_values)

ContinuousNames() → list

Get the list of continuous variable names in the FileData instance.

Returns:

A list of continuous variable names.

Return type:

List[str]

DeleteVariable(name: str) → None

Delete a variable from the FileData instance by its name.

Parameters:

name (str) – The name of the Variable to be deleted.

Raises:

ValueError – If no Variable with the specified name exists in the FileData instance.

EventNames() → list

Get the list of event variable names in the FileData instance.

Returns:

A list of event variable names.

Return type:

List[str]

GetDocComment() → str

Get the comment of the FileData instance.

Returns:

The comment of the FileData instance.

Return type:

str

GetDocEndTime() → float

Get the end time of the data in the FileData instance in seconds.

Returns:

The end time in seconds.

Return type:

float

GetDocStartTime() → float

Get the start time of the data in the FileData instance in seconds.

Returns:

The start time in seconds.

Return type:

float

GetTimestampFrequency() → float

Get the timestamp frequency of the FileData instance in Hertz.

Returns:

The timestamp frequency in Hertz.

Return type:

float

IntervalNames() → list

Get the list of interval variable names in the FileData instance.

Returns:

A list of interval variable names.

Return type:

List[str]

MarkerNames() → list

Get the list of marker variable names in the FileData instance.

Returns:

A list of marker variable names.

Return type:

List[str]

NeuronNames() → list

Get the list of neuron variable names in the FileData instance.

Returns:

A list of neuron variable names.

Return type:

List[str]

PopVectorNames() → list

Get the list of population vector variable names in the FileData instance.

Returns:

A list of population vector variable names.

Return type:

List[str]

WaveNames() → list

Get the list of waveform variable names in the FileData instance.

Returns:

A list of waveform variable names.

Return type:

List[str]

nex5file.variables module

class nex5file.variables.ContinuousVariable(varHeader: VariableHeader = VariableHeader(Type=-1, Version=0, Name='', DataOffset=0, Count=0, TsDataType=0, ContDataType=0, SamplingRate=0, Units='', ADtoMV=0, MVOffset=0, NPointsWave=0, PreThrTime=0, MarkerDataType=0, NMarkers=0, MarkerLength=0, ContFragIndexType=0, Padding='', Gain=0, Filter=0, Wire=0, Unit=0, XPos=0, YPos=0))

Bases: Variable

Represents a continuous variable. The variable contains continuous values and their timestamps.

ContinuousValues() → list

Get a copy of the continuous values in millivolts.

Returns:

A copy of the continuous values as a numpy array.

Return type:

numpy array of type np.float64

FragmentCounts() → list

Get a copy of the fragment counts.

Returns:

A copy of the fragment counts as a numpy array.

Return type:

numpy array of type np.int64

FragmentTimestamps() → list

Get a copy of the fragment timestamps in seconds.

Returns:

A copy of the fragment timestamps as a numpy array.

Return type:

numpy array of type np.float64

SamplingRate() → float

Get the sampling rate of the continuous data.

Returns:

The sampling rate.

Return type:

float

class nex5file.variables.EventVariable(varHeader: VariableHeader = VariableHeader(Type=-1, Version=0, Name='', DataOffset=0, Count=0, TsDataType=0, ContDataType=0, SamplingRate=0, Units='', ADtoMV=0, MVOffset=0, NPointsWave=0, PreThrTime=0, MarkerDataType=0, NMarkers=0, MarkerLength=0, ContFragIndexType=0, Padding='', Gain=0, Filter=0, Wire=0, Unit=0, XPos=0, YPos=0))

Bases: Variable

Represents an event variable (event name and a list of timestamps).

Timestamps() → list

Get a copy of the timestamps in seconds.

Returns:

A copy of the timestamps (in seconds) as a numpy array.

Return type:

numpy array of type np.float64

class nex5file.variables.IntervalVariable(varHeader: VariableHeader = VariableHeader(Type=-1, Version=0, Name='', DataOffset=0, Count=0, TsDataType=0, ContDataType=0, SamplingRate=0, Units='', ADtoMV=0, MVOffset=0, NPointsWave=0, PreThrTime=0, MarkerDataType=0, NMarkers=0, MarkerLength=0, ContFragIndexType=0, Padding='', Gain=0, Filter=0, Wire=0, Unit=0, XPos=0, YPos=0))

Bases: Variable

Represents an interval variable (a variable name and interval start and end times).

Intervals() → list

Get a list of intervals represented as two lists – the first list is a list of interval starts, the second list is a list of interval ends.

Returns:

a list of intervals represented as two lists – the first list is a list of interval starts, the second list is a list of interval ends.

Return type:

list

class nex5file.variables.MarkerVariable(varHeader: VariableHeader = VariableHeader(Type=-1, Version=0, Name='', DataOffset=0, Count=0, TsDataType=0, ContDataType=0, SamplingRate=0, Units='', ADtoMV=0, MVOffset=0, NPointsWave=0, PreThrTime=0, MarkerDataType=0, NMarkers=0, MarkerLength=0, ContFragIndexType=0, Padding='', Gain=0, Filter=0, Wire=0, Unit=0, XPos=0, YPos=0))

Bases: Variable

Represents a marker variable with. Each marker is a timestamp with one or more associated string values.

MarkerFieldNames() → list

Get a copy of the marker field names.

Returns:

A copy of the marker field names.

Return type:

List[str]

Markers() → list

Get a copy of the marker fields.

Returns:

A copy of the marker fields.

Return type:

List[List[str]]

Timestamps() → list

Get a copy of the timestamps associated with the markers.

Returns:

A copy of the timestamps as a numpy array.

Return type:

numpy array of type np.float64

class nex5file.variables.NeuronVariable(varHeader: VariableHeader = VariableHeader(Type=-1, Version=0, Name='', DataOffset=0, Count=0, TsDataType=0, ContDataType=0, SamplingRate=0, Units='', ADtoMV=0, MVOffset=0, NPointsWave=0, PreThrTime=0, MarkerDataType=0, NMarkers=0, MarkerLength=0, ContFragIndexType=0, Padding='', Gain=0, Filter=0, Wire=0, Unit=0, XPos=0, YPos=0))

Bases: EventVariable

Represents a neuron variable (a variable name, timestamps and wire and unit information).

Timestamps() → list

Get a copy of the timestamps in seconds.

Returns:

A copy of the timestamps (in seconds) as a numpy array.

Return type:

numpy array of type np.float64

class nex5file.variables.NexFileVarType

Bases: object

Constants for .nex and .nex5 variable types.

class nex5file.variables.PopulationVector(varHeader: VariableHeader = VariableHeader(Type=-1, Version=0, Name='', DataOffset=0, Count=0, TsDataType=0, ContDataType=0, SamplingRate=0, Units='', ADtoMV=0, MVOffset=0, NPointsWave=0, PreThrTime=0, MarkerDataType=0, NMarkers=0, MarkerLength=0, ContFragIndexType=0, Padding='', Gain=0, Filter=0, Wire=0, Unit=0, XPos=0, YPos=0))

Bases: Variable

Represents a population vector variable (a variable name and a list of weights).

Weights() → list

Get a copy of the population vector weights.

Returns:

A copy of the weights as a numpy array.

Return type:

List[float]

class nex5file.variables.Variable(varHeader: VariableHeader = VariableHeader(Type=-1, Version=0, Name='', DataOffset=0, Count=0, TsDataType=0, ContDataType=0, SamplingRate=0, Units='', ADtoMV=0, MVOffset=0, NPointsWave=0, PreThrTime=0, MarkerDataType=0, NMarkers=0, MarkerLength=0, ContFragIndexType=0, Padding='', Gain=0, Filter=0, Wire=0, Unit=0, XPos=0, YPos=0))

Bases: object

Represents a variable stored in .nex of .nex5 file.

Metadata() → dict

Get the metadata associated with the variable.

Returns:

A dictionary containing metadata about the variable (name, wire number for neurons etc.).

Return type:

dict

class nex5file.variables.WaveformVariable(varHeader: VariableHeader = VariableHeader(Type=-1, Version=0, Name='', DataOffset=0, Count=0, TsDataType=0, ContDataType=0, SamplingRate=0, Units='', ADtoMV=0, MVOffset=0, NPointsWave=0, PreThrTime=0, MarkerDataType=0, NMarkers=0, MarkerLength=0, ContFragIndexType=0, Padding='', Gain=0, Filter=0, Wire=0, Unit=0, XPos=0, YPos=0))

Bases: Variable

Represents a waveform variable (each waveform is a timestamps and array of waveform values).

NumPointsInWave() → int

Get the number of points in the waveform.

Returns:

The number of points in the waveform.

Return type:

int

PreThresholdTime() → float

Get the pre-threshold time.

Returns:

The pre-threshold time.

Return type:

float

SamplingRate() → float

Get the sampling rate of the waveform.

Returns:

The sampling rate.

Return type:

float

Timestamps() → list

Get a copy of the timestamps.

Returns:

A copy of the timestamps as a numpy array.

Return type:

numpy array of type np.float64

WaveformValues() → list

Get a copy of the waveform values.

Returns:

A copy of the waveform values as a numpy array.

Return type:

numpy array of type np.float32

nex5file.reader module

class nex5file.reader.Reader

Bases: object

This class provides functionality for reading both .nex and .nex5 files and extracting their data.

ReadNex5File(filePath: str) → FileData

Read a .nex5 file and return its data.

Parameters:

filePath (str) – Path to the .nex5 file.

Returns:

A FileData object containing the data from the file.

Return type:

FileData

Raises:

ValueError – If the file format is invalid.

Example:

reader = Reader()
data = reader.ReadNex5File(r"C:\path\to\your\file.nex5")

ReadNex5FileVariables(filePath: str, varNames: list) → FileData

Read specified variables from .nex5 file and return a FileData object.

Parameters:

• filePath (str) – Path to the .nex5 file.

• list (varNames) – a list of variable names.

Returns:

A FileData object containing variable data from the file.

Return type:

FileData

Raises:

ValueError – If the file format is invalid.

Example

Read only continuous channels from .nex file

reader = Reader()
data = reader.ReadNex5HeadersOnly(r"C:\path\to\your\file.nex5")
contNames = data.ContinuousNames()
data_cont = reader.ReadNex5FileVariables(r"C:\path\to\your\file.nex5", contNames)

ReadNex5HeadersOnly(filePath: str) → FileData

Read .nex5 file headers and return a FileData object with no data. The returned FileData object can be used to obtain the names of variables in the file. The names can then be used to load only specific variables from a .nex5 file using ReadNex5FileVariables method.

Parameters:

filePath (str) – Path to the .nex5 file.

Returns:

A FileData object containing variable headers from the file.

Return type:

FileData

Raises:

ValueError – If the file format is invalid.

Example:

# read only continuous channels from .nex file
reader = Reader()
data = reader.ReadNex5HeadersOnly(r"C:\path\to\your\file.nex5")
contNames = data.ContinuousNames()
data_cont = reader.ReadNex5FileVariables(r"C:\path\to\your\file.nex5", contNames)

ReadNexFile(filePath: str) → FileData

Read a .nex file and return its data.

Parameters:

filePath (str) – Path to the .nex file.

Returns:

A FileData object containing the data from the file.

Return type:

FileData

Raises:

ValueError – If the file format is invalid.

Example:

reader = Reader()
data = reader.ReadNexFile(r"C:\path\to\your\file.nex")

ReadNexFileVariables(filePath: str, varNames: list) → FileData

Read specified variables from .nex file and return a FileData object.

Parameters:

• filePath (str) – Path to the .nex file.

• list (varNames) – a list of variable names.

Returns:

A FileData object containing variable data from the file.

Return type:

FileData

Raises:

ValueError – If the file format is invalid.

Example

Read only continuous channels from .nex file

reader = Reader()
data = reader.ReadNexHeadersOnly(r"C:\path\to\your\file.nex")
contNames = data.ContinuousNames()
data_cont = reader.ReadNexFileVariables(r"C:\path\to\your\file.nex", contNames)

ReadNexHeadersOnly(filePath: str) → FileData

Read .nex file headers and return a FileData object with no data. The returned FileData object can be used to obtain the names of variables in the file. The names can then be used to load only specific variables from a .nex file using ReadNexFileVariables method.

Parameters:

filePath (str) – Path to the .nex file.

Returns:

A FileData object containing variable headers from the file.

Return type:

FileData

Raises:

ValueError – If the file format is invalid.

Example

Read only continuous channels from .nex file

reader = Reader()
data = reader.ReadNexHeadersOnly(r"C:\path\to\your\file.nex")
contNames = data.ContinuousNames()
data_cont = reader.ReadNexFileVariables(r"C:\path\to\your\file.nex", contNames)

nex5file.writer module

class nex5file.writer.Writer

Bases: object

.nex and .nex5 writer class

This class provides methods for writing data to .nex and .nex5 files.

WriteNex5File(data: FileData, filePath: str) → None

Write data to a .nex5 file.

This method writes data from a FileData object to a .nex5 file located at the specified ‘filePath’.

If filePath ends with ‘.nex’, writes data using nex data format.

Parameters:

• data (FileData) – A FileData object containing the data to be written.

• filePath (str) – The path to the .nex5 file to be created or updated.

Example

To write data to a .nex5 file:

writer = Writer()
writer.WriteNex5File(file_data, r"C:path\to\your\file.nex5")

WriteNexFile(data: FileData, filePath: str) → None

Write data to a .nex file.

This method writes data from a FileData object to a .nex file located at the specified ‘filePath’.

If filePath ends with ‘.nex5’, writes data using nex5 data format.

Parameters:

• data (FileData) – A FileData object containing the data to be written.

• filePath (str) – The path to the .nex file to be created or updated.

Raises:

ValueError – If the maximum timestamp exceeds the 32-bit range, preventing it from being saved as a .nex file.

Example

To write data to a .nex file:

writer = Writer()
writer.WriteNexFile(file_data, r"C:\path\to\your\file.nex")

Module contents