TimeseriesInput¶

class TimeseriesInput(file=None, sidecar=None, extra_def_dicts=None, name=None)[source]: A BIDS time series tabular file.

Methods

`TimeseriesInput.__init__`([file, sidecar, ...])	Constructor for the TimeseriesInput class.
`TimeseriesInput.assemble`([mapper, ...])	Assembles the HED strings.
`TimeseriesInput.column_metadata`()	Return the metadata for each column.
`TimeseriesInput.combine_dataframe`(dataframe)	Combine all columns in the given dataframe into a single HED string series,
`TimeseriesInput.convert_to_form`(hed_schema, ...)	Convert all tags in underlying dataframe to the specified form.
`TimeseriesInput.convert_to_long`(hed_schema)	Convert all tags in underlying dataframe to long form.
`TimeseriesInput.convert_to_short`(hed_schema)	Convert all tags in underlying dataframe to short form.
`TimeseriesInput.expand_defs`(hed_schema, def_dict)	Shrinks any def-expand found in the underlying dataframe.
`TimeseriesInput.get_column_refs`()	Return a list of column refs for this file.
`TimeseriesInput.get_def_dict`(hed_schema[, ...])	Return the definition dict for this file.
`TimeseriesInput.get_worksheet`([worksheet_name])	Get the requested worksheet.
`TimeseriesInput.reset_mapper`(new_mapper)	Set mapper to a different view of the file.
`TimeseriesInput.set_cell`(row_number, ...[, ...])	Replace the specified cell with transformed text.
`TimeseriesInput.shrink_defs`(hed_schema)	Shrinks any def-expand found in the underlying dataframe.
`TimeseriesInput.to_csv`([file])	Write to file or return as a string.
`TimeseriesInput.to_excel`(file)	Output to an Excel file.
`TimeseriesInput.validate`(hed_schema[, ...])	Creates a SpreadsheetValidator and returns all issues with this file.

Attributes

`TimeseriesInput.EXCEL_EXTENSION`
`TimeseriesInput.HED_COLUMN_NAME`
`TimeseriesInput.TEXT_EXTENSION`
`TimeseriesInput.columns`	Returns a list of the column names.
`TimeseriesInput.dataframe`	The underlying dataframe.
`TimeseriesInput.dataframe_a`	Return the assembled dataframe Probably a placeholder name.
`TimeseriesInput.has_column_names`	True if dataframe has column names.
`TimeseriesInput.loaded_workbook`	The underlying loaded workbooks.
`TimeseriesInput.name`	Name of the data.
`TimeseriesInput.needs_sorting`	Return True if this both has an onset column, and it needs sorting.
`TimeseriesInput.onsets`	Return the onset column if it exists.
`TimeseriesInput.series_a`	Return the assembled dataframe as a series.
`TimeseriesInput.series_filtered`	Return the assembled dataframe as a series, with rows that have the same onset combined.
`TimeseriesInput.worksheet_name`	The worksheet name.

TimeseriesInput.__init__(file=None, sidecar=None, extra_def_dicts=None, name=None)[source]¶

Constructor for the TimeseriesInput class.

Parameters:

file (str or file like) – A tsv file to open.
sidecar (str or Sidecar) – A json sidecar to pull metadata from.
extra_def_dicts (DefinitionDict, list, or None) – Additional definition dictionaries.
name (str) – The name to display for this file for error purposes.

Notes

The extra_def_dicts are external definitions that override the ones in the object.

TimeseriesInput.assemble(mapper=None, skip_curly_braces=False)¶

Assembles the HED strings.

Parameters:

mapper (ColumnMapper or None) – Generally pass none here unless you want special behavior.
skip_curly_braces (bool) – If True, don’t plug in curly brace values into columns.

Returns:

The assembled dataframe.

Return type:

Dataframe

TimeseriesInput.column_metadata()¶

Return the metadata for each column.

Returns:: Number/ColumnMeta pairs.
Return type:: dict

static TimeseriesInput.combine_dataframe(dataframe)¶

Combine all columns in the given dataframe into a single HED string series,: skipping empty columns and columns with empty strings.

Parameters:: dataframe (Dataframe) – The dataframe to combin
Returns:: The assembled series.
Return type:: Series

TimeseriesInput.convert_to_form(hed_schema, tag_form)¶

Convert all tags in underlying dataframe to the specified form.

Parameters:

hed_schema (HedSchema) – The schema to use to convert tags.
tag_form (str) – HedTag property to convert tags to. Most cases should use convert_to_short or convert_to_long below.

TimeseriesInput.convert_to_long(hed_schema)¶

Convert all tags in underlying dataframe to long form.

Parameters:: hed_schema (HedSchema or None) – The schema to use to convert tags.

TimeseriesInput.convert_to_short(hed_schema)¶

Convert all tags in underlying dataframe to short form.

Parameters:: hed_schema (HedSchema) – The schema to use to convert tags.

TimeseriesInput.expand_defs(hed_schema, def_dict)¶

Shrinks any def-expand found in the underlying dataframe.

Parameters:

hed_schema (HedSchema or None) – The schema to use to identify defs.
def_dict (DefinitionDict) – The definitions to expand.

TimeseriesInput.get_column_refs()¶

Return a list of column refs for this file.

Default implementation returns none.

Returns:: A list of unique column refs found.
Return type:: column_refs(list)

TimeseriesInput.get_def_dict(hed_schema, extra_def_dicts=None)¶

Return the definition dict for this file.

Note: Baseclass implementation returns just extra_def_dicts.

Parameters:

hed_schema (HedSchema) – Identifies tags to find definitions(if needed).
extra_def_dicts (list, DefinitionDict, or None) – Extra dicts to add to the list.

Returns:

A single definition dict representing all the data(and extra def dicts).

Return type:

DefinitionDict

TimeseriesInput.get_worksheet(worksheet_name=None)¶

Get the requested worksheet.

Parameters:: worksheet_name (str or None) – The name of the requested worksheet by name or the first one if None.
Returns:: The workbook request.
Return type:: openpyxl.workbook.Workbook

Notes

If None, returns the first worksheet.

Raises:

KeyError –

The specified worksheet name does not exist.

TimeseriesInput.reset_mapper(new_mapper)¶

Set mapper to a different view of the file.

Parameters:: new_mapper (ColumnMapper) – A column mapper to be associated with this base input.

TimeseriesInput.set_cell(row_number, column_number, new_string_obj, tag_form='short_tag')¶

Replace the specified cell with transformed text.

Parameters:

row_number (int) – The row number of the spreadsheet to set.
column_number (int) – The column number of the spreadsheet to set.
new_string_obj (HedString) – Object with text to put in the given cell.
tag_form (str) – Version of the tags (short_tag, long_tag, base_tag, etc)

Notes

Any attribute of a HedTag that returns a string is a valid value of tag_form.

Raises:

ValueError –
- There is not a loaded dataframe.
KeyError –
- The indicated row/column does not exist.
AttributeError –
- The indicated tag_form is not an attribute of HedTag.

TimeseriesInput.shrink_defs(hed_schema)¶

Shrinks any def-expand found in the underlying dataframe.

Parameters:: hed_schema (HedSchema or None) – The schema to use to identify defs.

TimeseriesInput.to_csv(file=None)¶

Write to file or return as a string.

Parameters:

file (str, file-like, or None) – Location to save this file. If None, return as string.

Returns:

None if file is given or the contents as a str if file is None.

Return type:

None or str

Raises:

OSError –

Cannot open the indicated file.

TimeseriesInput.to_excel(file)¶

Output to an Excel file.

Parameters:

file (str or file-like) – Location to save this base input.

Raises:

ValueError –
- If empty file object was passed.
OSError –
- Cannot open the indicated file.

TimeseriesInput.validate(hed_schema, extra_def_dicts=None, name=None, error_handler=None)¶

Creates a SpreadsheetValidator and returns all issues with this file.

Parameters:

hed_schema (HedSchema) – The schema to use for validation.
extra_def_dicts (list of DefDict or DefDict) – All definitions to use for validation.
name (str) – The name to report errors from this file as.
error_handler (ErrorHandler) – Error context to use. Creates a new one if None.

Returns:

A list of issues for a HED string.

Return type:

issues (list of dict)

TimeseriesInput.EXCEL_EXTENSION = ['.xlsx']¶

TimeseriesInput.HED_COLUMN_NAME = 'HED'¶

TimeseriesInput.TEXT_EXTENSION = ['.tsv', '.txt']¶

TimeseriesInput.columns¶

Returns a list of the column names.

Empty if no column names.

Returns:: The column names.
Return type:: columns(list)

TimeseriesInput.dataframe¶: The underlying dataframe.

TimeseriesInput.dataframe_a¶

Return the assembled dataframe Probably a placeholder name.

Returns:: the assembled dataframe
Return type:: Dataframe

TimeseriesInput.has_column_names¶: True if dataframe has column names.

TimeseriesInput.loaded_workbook¶: The underlying loaded workbooks.

TimeseriesInput.name¶: Name of the data.

TimeseriesInput.needs_sorting¶: Return True if this both has an onset column, and it needs sorting.

TimeseriesInput.onsets¶: Return the onset column if it exists.

TimeseriesInput.series_a¶

Return the assembled dataframe as a series.

Returns:: the assembled dataframe with columns merged.
Return type:: Series

TimeseriesInput.series_filtered¶

Return the assembled dataframe as a series, with rows that have the same onset combined.

Returns:: the assembled dataframe with columns merged, and the rows filtered together.
Return type:: Series or None

TimeseriesInput.worksheet_name¶: The worksheet name.