-
Notifications
You must be signed in to change notification settings - Fork 5
MarkWriteProject Class
The MarkWriteProject class represents a MarkWrite project created using the MarkWrite Application or markwrite package API. Information about imported data, etc., is stored in the class.
A MarkWriteProject instance can be saved to a .mwp file. The saved .mwp file can be reopened from within the MarkWrite application or using the markwrite package API.
Name of the project.
Returns: basestring
When a source data file is loaded to create a new project, all sample timestamps are normalized by subtracting timebase_offset from the sample original time field.
Returns: float sec.msec format
Attribute containing all pen samples loaded from the source
data file. Each element of the array is a single pen sample stored using
a datatype defined in markwrite.file_io.markwrite_pendata_format, which has
the following fields:
| Name | Description | Data Type |
|---|---|---|
| time | Pen sample timestamp (sec.msec format) | float64 |
| x | Horizontal pen position (unit of measure varies across different input data file types) | int32 |
| y | Vertical pen position (unit of measure varies across different input data file types) | int32 |
| pressure | Pen pressure (0 means pen was hovering) | int16 |
| state | Status flags assigned to pen sample. | uint8 |
| x_filtered | Filtered horizontal pen position | float64 |
| y_filtered | Filtered Vertical pen position | float64 |
| pressure_filtered | Filtered Pen pressure | float64 |
| x_velocity | Horizontal velocity of pen | float64 |
| y_velocity | Vertical velocity of pen | float64 |
| xy_velocity | Absolute 2D velocity of pen | float64 |
| xy_acceleration | Acceleration of pen | float64 |
| segment_id | ID of last PenDataSegment created that included the sample |
uint16 |
Since each pen sample is represented as an ndarray, pen sample fields can be accessed using the field name or an array index.
Examples:
apd = project.allpendata
first_ten_samples = apd[0:10]
avg_pressure_for_10_samples = first_ten_samples['pressure'].mean()
last_sample = apd[-1]
last_sample_xy_position = last_sample[['x','y']]
Returns: 1D ndarray
Each element of array is a single pen sample, using dtype markwrite.file_io.markwrite_pendata
Same as project pendata attribute.
Property containing all pen samples that are within at least one Segment.
Returns: 1D numpy array
Each element of array is a ren sample, using dtype markwrite.file_io.markwrite_pendata
Property containing all pen samples that are not associated with any Segments.
Returns: 1D numpy array
Each element of array is a ren sample, using dtype markwrite.file_io.markwrite_pendata
The root PenDataSegmentCategory, containing the PenDataSegment hierarchy created by a user within the MarkWrite GUI App.
Returns: PenDataSegmentCategory instance
For projects created from a HDF5 or TXYP source data file, the 'pendata' is split into 1 - N sample Series. This attribute contains an an ndarray of length N, each element being a Series boundary ndarray with dtype
series_dtype = np.dtype({'names': ['id', 'start_ix', 'start_time', 'end_ix', 'end_time'],
'formats': [np.uint16, np.uint32, np.float64, np.uint32, np.float64]})
Returns: ndarray of series_dtype elements
When a new project is created from a source data file, the pendata is parsed into a set of pen sample pressed Runs.
This attribute contains an a ndarray of length N, each element being a Run boundary ndarray with dtype
run_dtype = np.dtype({
'names': ['id', 'parent_id', 'start_ix', 'start_time', 'end_ix','end_time'],
'formats': [np.uint16, np.uint16, np.uint32, np.float64, np.uint32,np.float64]
})
Returns: ndarray of run_dtype elements
When a new project is created from a source data file, the pendata is parsed into a set of pen Strokes.
This attribute contains an a ndarray of length N, each element being a Stroke boundary ndarray with dtype
stroke_dtype = np.dtype({
'names': ['id', 'parent_id', 'start_ix', 'start_time', 'end_ix','end_time'],
'formats': [np.uint16, np.uint16, np.uint32, np.float64, np.uint32,np.float64]
})
Returns: ndarray of stroke_dtype elements
Contains information about the original source data file loaded to create the project. Information is stored as a set of key:value pairs in a dict.
Returns: dict
If the source data file used to create the project was an ioHub HDF5 file, the conditionvariables table from the hdf5 file is saved here as an ndarray.
Returns: ndarray dtype is dependent on how the experiment defined the table in the hdf5 file.
Only if the source data file used to create the project was an ioHub HDF5 file, the 'pendata' is split into 1 - N Trials. This attribute contains an an ndarray of length N, each element being a Trial boundary ndarray with dtype
trial_dtype = np.dtype({
'names': ['cvrow_ix', 'start_ix', 'start_time', 'end_ix', 'end_time'],
'formats': [np.int32, np.uint32, np.float64, np.uint32, np.float64]
})
Returns: ndarray of trial_dtype elements
When a new project is created, the markwrite api searches for a file containing a list of predefined segment tags to make available within the MarkWrite GUI App.
Returns: list of basestrings
Create a new project from a supported input source data file, or reopen a previously saved MarkWrite project.
When creating a MarkWriteProject instance in a custom script, the mwapp param should be None. If loading an hdf5 file the tstart_cond_name and tend_cond_name parameters specify the experiment condition variable names to use for parsing pen data into Level 1 Trial Segments.
-
name: basestring
Name for the project. -
file_path: basestring
Path to source data or existing MarkWrite project file. -
mwapp: MarkWriteMainWindow instance
Use None if creating Project class instance from within a custom script. -
tstart_cond_name: basestring
Condition variable name for trial start times (hdf5 only). -
tend_cond_name: basestring
Condition variable name for trial end times (hdf5 only).
Return the time of the last sample* contained within the next pen sample grouping unit relative to the project data time 'current_time'.
| Pen Sample Grouping Unit | unit_lookup_table project attribute |
|---|---|
| Sample Series | series_boundaries |
| Sample Run | run_boundaries |
| Stroke | stroke_boundaries |
*If adjust_end_time is True, the second to last sample time is returned.
-
unit_lookup_table: MarkWriteProject instance attribute
Valid attributes are.series_boundaries,.run_boundaries, or.stroke_boundaries. -
current_time: float
Time in sec.msec format. - adjust_end_time: bool
Returns: float
(time in sec.msec format)
Return the time of the first sample contained within the next pen sample grouping unit relative to current_time project data time.
| Pen Sample Grouping Unit | unit_lookup_table project attribute |
|---|---|
| Sample Series | series_boundaries |
| Sample Run | run_boundaries |
| Stroke | stroke_boundaries |
-
unit_lookup_table: MarkWriteProject instance attribute
Valid attributes are.series_boundaries,.run_boundaries, or.stroke_boundaries. -
current_time: float
Time in sec.msec format.
Returns: float
Time in sec.msec format.
Return the time of the last sample* contained within the previous pen sample grouping unit relative to the project data time 'current_time'.
| Pen Sample Grouping Unit | unit_lookup_table project attribute |
|---|---|
| Sample Series | series_boundaries |
| Sample Run | run_boundaries |
| Stroke | stroke_boundaries |
*If adjust_end_time is True, the second to last sample time is returned.
-
unit_lookup_table: MarkWriteProject instance attribute
Valid attributes are.series_boundaries,.run_boundaries, or.stroke_boundaries. -
current_time: float
Time in sec.msec format. - adjust_end_time: bool
Returns: float
(time in sec.msec format)
Return the time of the first sample contained within the previous pen sample grouping unit relative to current_time project data time.
| Pen Sample Grouping Unit | unit_lookup_table project attribute |
|---|---|
| Sample Series | series_boundaries |
| Sample Run | run_boundaries |
| Stroke | stroke_boundaries |
-
unit_lookup_table: MarkWriteProject instance attribute
Valid attributes are.series_boundaries,.run_boundaries, or.stroke_boundaries. -
current_time: float
Time in sec.msec format.
Returns: float
Time in sec.msec format.
Given the pen samples ndarray 'pendata', return the sub-array that only contains samples with time >= tstart and <= tend.
- tstart: float (sec.msec time format)
- tend: float (sec.msec time format)
- pendata: ndarray of dtype markwrite.file_io.markwrite_pendata_format
Returns:
ndarray of dtype markwrite.file_io.markwrite_pendata_format
Find sample Series that occur relative to the atime param, a
sec.msec time in the normalized project data time space.
By default the Series that contains atime is returned, or None if atime
is outside any of the sample Series.
The positions argument can be used to request additional or
alternative sample Series relative to atime:
- 'current': default
- 'previous': return the Series that occurred prior to the current Series
- 'next': return the Series that occurred after to the current Series
- 'all': return ['previous', 'current', 'next'] Series
-
atime: float
The time to find the series for (if any) -
position: basestring or list there of
Valid tokens are 'all', 'current', 'previous', 'next', or a list with >= 1 of these tokens.
Returns: dict
Return a record from the series_boundaries ndarray for the sample Series that contains sample_index.
If the sample at pendata[sample_index] is not within a Series, return None.
- sample_index: int (valid value range 0 : len(pendata)-1)
Returns:
Record / row from series_boundaries attribute, or None
Return a record from the run_boundaries ndarray for the sample Run that contains sample_index.
If the sample at pendata[sample_index] is not within a Run, return None.
- sample_index: int (valid value range 0 : len(pendata)-1)
Returns:
Record / row from run_boundaries attribute, or None
Return a record from the stroke_boundaries ndarray for the pen Stroke that contains sample_index.
If the sample at pendata[sample_index] is not within a pen Stroke, return None.
-
sample_index: int
Valid value range 0 to len(pendata)-1.
Returns:
Record / row from stroke_boundaries attribute, or None
Returns the trial condition variable data for the given sample. None is returned if no trial condition variables were found for the given sample.
sample can be one of:
- int: index of sample in
project.pendata - float: time of sample
- ndarray: a row from the
project.pendatandarray.
- sample: int, float, or ndarray
Returns: ndarray or None
Save the project object to disk. The project is saved to the current project file path, overwriting the existing file.
Returns: bool
True if save was successful, False otherwise
Save the project object to disk using the file path specified by tofile.
tofile must include the path and name for the project file. Relative paths are first converted to an absolute path. If the file directory does not exist, it will be created if possible. If the directory can not be created, the project will not be saved.
If a file already exists at topath, it will be overwritten with this projects serialized data.
-
tofile: basestring
path to save project file
Returns: bool
True if save was successful, False otherwise
Return a dict representation of the project, suitable for serialization using packages like pickle. When a project is saved to a .mwp file, the return value of this method is what gets pickled as the file contents.
Returns: dict
Close the MarkWrite project. Attempts to leave project instance in a state that allows for clean GCing.
DO NOT call saveAs or save methods on a project that is closed!** Return a bool indicating if the close operation was successful or not.
Returns: bool