PenDataSegment Class

class PenDataSegmentCategory

A PenDataSegmentCategory is only created by the MarkWrite GUI App, representing the root segment of a MarkWriteProject segment tree (project.segtree). Currently MarkWrite only supports a single root segment node, which covers the all pendata samples.

When a user creates a Segment in the MarkWrite GUI App, a PenDataSegment is created, which is a subclass of this class.

---

class PenDataSegment

Parent Class: PenDataSegmentCategory

PenDataSegment class is used to store a single segments information. Other than the project's root segment, which is an instance of the parent PenDataSegmentCategory class, all segments within a project are instances of PenDataSegment.

.init(self, name=None, pendata=None, parent=None, fulltimerange=None, id=None)

PenDataSegment class is used when a segment is created within the MarkWrite App.

pendata is a slice from the project.pendata ndarray, containing only the samples that fall within the segments time period.

If fulltimerange arg is provided, the segments starttime , endtime properties equal fulltimerange[0] , fulltimerange[1], otherwise the segments starttime equals self.pendata['time'][0] and self.endtime equals pendata['time'][-1].

Arguments:

• name: basestring
  Name for the project.
• pendata: ndarray
  A slice from the project.pendata ndarray, containing only the samples that fall within the segments time period.
• parent: PenDataSegment
  Proxy to the parent segment
• fulltimerange: [float, float]
  Exact start and end times to use for the segment.
• id: int
  Segment id. id arg is only used when recreating segments from a saved .mpw file.

Attributes \ Properties

.name

Name of the project.

Returns: basestring

.id

A unique value identifying the segment.

Returns: int

.pendata

Property containing the pen samples contained within the segment's time range. 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.

Returns: 1D ndarray
Each element of array is a single pen sample, using dtype markwrite.file_io.markwrite_pendata

.nonzeropressurependata

Return the pen samples contained within the segment time period where the samples pressure value is greater than 0.

Returns: 1D ndarray
Each element of array is a single pen sample, using dtype markwrite.file_io.markwrite_pendata

.zeropressurependata

Return the pen samples contained within the segment time period where the samples pressure value is equal to 0.

Returns: 1D ndarray
Each element of array is a single pen sample, using dtype markwrite.file_io.markwrite_pendata

.locked

Property indicating if the segment is in a locked state or not. If a segment is locked, it can not be deleted from the project and it's name can not be set.

Returns: bool

.cond_vars

This property is only of use when the current project was created from loading an ioHub HDF5 file.

Returns the experiment condition variables associated with the Trial Segment (l1seg) of the current segment's (which may be self).

Returns: ndarray
The dtype of .cond_vars is dependent on the iohub condition variable table created by the experiment runtime.

.children

If the current segment has children, return them as a list of PenDataSegment objects. Child segments are returned sorted by segment start time.

Returns: list
list element type is PenDataSegment

.parent

Return the parent of the current segment, or None if the current segment is the root segment of the project.

Returns: PenDataSegment
If current segment is root, parent will be None

.project

Return a proxy to the MarkWriteProject that the segment is part of.

Returns: MarkWriteProject

.path

Return a list of segment names, representing the current segment's position within the project segment hierarchy. The first element of the path list is always the project's root segment name. The last element of the path list is the current parent segment's name.

Returns: list
list elements will be of type basestring

.tree

Return a list of PenDataSegments. The first element of the list is the parent of the current segment. The last element of the list is always the root segment.

Returns: list
list elements will be of type PenDataSegment

.level

The number of parent segments to reach the root segment. The root segment has level == 0.

Returns: int

.l1seg

Return the current segment's level 1 parent.

Returns: PenDataSegment

.starttime

Return the current segment's sec.msec start time. Depending on app settings and other conditions when the segment was created, a segments starttime may not equal the segment's first sample time. starttime will always be <= self.pendata['time'][0]

Returns: float
sec.msec time format

.endtime

Return the current segment's sec.msec end time.

Depending on app settings and other conditions when the segment was created, a segments endtime may not equal the segment's last sample time. endtime will always be >= self.pendata['time'][-1]

Returns: float
sec.msec time format

.duration

Return the duration of the segment, which is equal to self.endtime - self.starttime.

Returns: float
sec.msec time format

.timerange

Return the segment's starttime and endtime

Returns: (float, float)
Both array elements are in sec.msec time format.

.pointcount

Return the number of pen samples that are contained in the segment.

Returns: int

---

Methods

.calculateTrimmedSegmentIndexBoundsFromTimeRange(self, starttime, endtime)

This method should only be used by the MarkWrite GUI app.

Calculates the first and last array indices in self.project.pendata that would be used for creating a segment with the uncorrected time range provided by starttime, endtime.

Arguments:

• starttime: float
• endtime: float
  args are times in sec.msec format

Returns: (int, int)
start and end index in project.pendata. Base is 0.
If no samples were found within the given time period, and empty list is returned.

.getChildIndex(self, segment)

Return the index of segment within the current segments children.

Arguments:

• segment: PenDataSegment

Returns: int

.hasChildren(self)

Return True if the current segment has >= 1 child segment.

Arguments:
None

Returns: bool

.isRoot(self)

Return True if the current segment is the top level, root, segment of the project. If True, then the current segment will equal the project.segtree object.

Arguments:
None

Returns: bool

.getRoot(self)

Return the root segment for the project.

Arguments:
None

Returns: PenDataSegmentCategory

.getLevelCount(self)

Return the maximum level depth in the project segment tree.

Arguments:
None

Returns: int

.getLeveledSegments(self)

Return a dict with all segment levels as the keys, and a list of all the PenDataSegments at a given level, regardless of parent, as the dict values.

Arguments:
None

Returns: dict

.contains(self, *args, **kwargs)

Returns True if all arguments passed to the method evaluate to be 'within' the current segment. The definition of 'within' depends on each arg data type or kwarg name.

arg data types	kwarg name	evaluation
float, np.float, np.float32, np.float64	time	self.starttime <= time <= self.endtime
list or tuple of two floats	position	np.any(self.pendata[X_FIELD]==x & self.pendata[Y_FIELD]==y)
int, long, np.int, np.int16, np.int32, np.int64	pressure	np.any(self.pendata['pressure']==v)
list or tuple of two ints	timeperiod	timeperiod[0] > self.starttime and timeperiod[1] < self.endtime
basestring	tag	self.name is tag
PenDataSegment	child	child.id in self._childsegment_ids

Returns: bool

.addChild(self, segment)

This method can only be used by the MarkWrite GUI app.

Arguments:

• segment: PenDataSegment

Returns: None

.removeChild(self, segment)

This method can only be used by the MarkWrite GUI app.

Arguments:

• segment: PenDataSegment

Returns: None

.hasChildren(self)

Return True if the current segment has >= 1 child segment.

Arguments:
None

Returns: bool

---