Submit

korus.app.app_util.add.add_annotations(conn, deployment_id, job_id, logger, timestamp_parser=None)

Interactive session for adding new annotations to the database.

Args:

conn: sqlite3.Connection

Database connection

deployment_id: int, list(int)

Deployment index or indices

job_id: int

Annotation job index

logger: korus.app.app_util.ui.InputLogger

Input logger

timestamp_parser: callable

Given a filename (str) returns the UTC timestamp embedded in the filename as a datetime object. Only required if some of the annotations reference audio files not present in the database.

Returns:

None

korus.app.app_util.add.add_data_storage_location(conn, logger)

Interactive session for adding a new data storage location to the database.

Args:

conn: sqlite3.Connection

Database connection

logger: korus.app.app_util.ui.InputLogger

Input logger

Returns:

: int

Row index of the new entry

korus.app.app_util.add.add_deployment(conn, logger)

Interactive session for adding a new deployment to the database.

Args:

conn: sqlite3.Connection

Database connection

logger: korus.app.app_util.ui.InputLogger

Input logger

Returns:

: int

Row index of the new entry

korus.app.app_util.add.add_files(conn, deployment_id, start_utc, end_utc, logger)

Interactive session for adding a new audio files to the database.

Args:

conn: sqlite3.Connection

Database connection

deployment_id: int

Deployment index

start_utc, end_utc: datetime.datetime

UTC time range

logger: korus.app.app_util.ui.InputLogger

Input logger

Returns:

: int

Row index of the last added audio file

korus.app.app_util.add.add_job(conn, logger)

Interactive session for adding a new annotation job to the database.

TODO: remove background_sound

Args:

conn: sqlite3.Connection

Database connection

logger: korus.app.app_util.ui.InputLogger

Input logger

Returns:

: int

Row index of the new entry

korus.app.app_util.add.add_tags(conn, tags)

Interactive session for adding new annotations to the database.

Args:

conn: sqlite3.Connection

Database connection

tags: str, list(str)

Tag name(s)

Returns:

None

korus.app.app_util.add.create_timestamp_parser(group=None, logger=None)

Interative session for creating a timestamp parser

Args:

group: str

Group that the parameter belongs to. Optional. Parameter names must be unique within groups.

logger: korus.app.app_util.ui.InputLogger

Input logger

Returns:

timestamp_parser: callable

Takes a string as input and returns a datetime object

korus.app.app_util.add.edit_row_manually(idx, row)

Edit an annotation manually.

The annotation data is saved to a temporary YAML file. The user is prompted via the console to edit and save the file, then hit ENTER to proceed.

Datetime objects are converted to strings using the format %Y-%m-%d %H:%M:%S.%f

Args:

idx: int

Index

row: pandas Series

Values

Returns:

row: pandas Series

The edited values. Returns None if the user elects to ignore/skip the entry.

korus.app.app_util.add.from_raven(input_path, tax, granularity, sep=None, timestamp_parser=None, interactive=True, progress_bar=False)

Loads entries from a RavenPro selections table

Args:

input_path: str, list(str)

Path to the RavenPro selection table(s). Use of wildcards is allowed.

tax: korus.tax.AcousticTaxonomy

Annotation taxonomy

sep: str

Character used to separate columns in the selection table. If None, tries to auto-detect the separator character.

granularity: str

Default granularity of annotations. Optional.

timestamp_parser: callable

Given a filename (str) returns the UTC timestamp embedded in the filename as a datetime object. Optional.

interactive: bool

If True (default), the user will be prompted via the console to fix any invalid data. If False, entries with invalid data will be flagged by setting valid=0.

progress_bar: bool

Display progress bar. Default is False.

Returns:

df_out: pandas.DataFrame

Table of selections

Raises:

FileNotFoundError: if the input file does not exist. ValueError: if the input table contains fields with invalid data types

korus.app.app_util.add.print_annotation_summary(conn, indices=None)

Print annotation summary

Args:

conn: sqlite3.Connection

Database connection

indices: list(int)

Indices in the annotation table. Optional.

korus.app.app_util.add.save_changes_to_db(conn)

Helper function for saving changes to the database

korus.app.app_util.add.terminate(conn, save=True)

Helper function for gracefully terminating the program

korus.app.app_util.add.unique_from_list(x)

Helper function for extracting unique values from a pandas DataFrame column which contains list objects

Args:

x: pandas.Series

The column containing the list objects

Returns:

value_count: dict

Unique values and the number of times they each occur, sorted in order of decreasing occurrence frequency.

korus.app.app_util.add.validate_annotations(df, tax, interactive=True, progress_bar=False)

Helper function for validating annotation data.

Also parses ambiguous label assignments separated by slash (/). The function checks the confident/tentative label columns for occurrences of slash (/) characters. When ambiguous labels are found, they are moved to the ambiguous columns. If they occur in the confident column, they are replaced by the last common ancestor node in the taxonomy. If they occur in the tentative column, they are replaced by a ‘null’ value.

Notes: Expects columns ambiguous_sound_source, ambiguous_sound_type, tag to be of type object.

Args:

df: pandas DataFrame

Selection table

tax: korus.tax.AcousticTaxonomy

Annotation taxonomy

interactive: bool

If True (default), the user will be prompted via the console to fix any invalid data. If False, entries with invalid data will be flagged by setting valid=0.

progress_bar: bool

Display progress bar. Default is False.

Returns:

df: pandas DataFrame

Selection table with ambiguous assignments resolved.

korus.app.app_util.add.validate_label(x, tax)

Validate a label against a taxonomy of allowed values.

Args:

x: str

Label to be validated. OBS: If None or empty string, no validation is performed.

tax: Korus.tax.AcousticTaxonomy

Taxonomy of allowed labels, against which x will be validated

Returns:

x: str

The validated label.

Raises:

ValueError: if the label is found to be invalid

korus.app.app_util.add.validate_label_interactive(x, tax, label_map, idx, row, note='')

Interactive session for validating a label against a taxonomy of allowed values.

If the label is found to be invalid, the user is prompted via the terminal for an alternative label.

Args:

x: str

Label to be validated

tax: Korus.tax.AcousticTaxonomy

Taxonomy of allowed labels, against which x will be validated

label_map: dict

Mapping for invalid labels

idx: int

Row index. Only used for interactive prompt.

row: pandas Series

Row values. Only used for interactive prompt.

note: str

Optional note, appended to the console message.

Returns:

y: str

The validated label.

label_map: dict

The updated label map.

Raises:

ValueError: if the user requests to switch to manual editing mode