larvaworld.lib.process.import_aux

Helper methods used for importing data

Functions

init_endpoint_dataframe_from_timeseries(→ pandas.DataFrame)	Initializes a dataframe for endpoint metrics from a timeseries dataframe.
read_timeseries_from_raw_files_per_parameter(...)	Reads timeseries data stored in txt files of the lab-specific Jovanic format and returns them as a pd.Dataframe.
read_timeseries_from_raw_files_per_larva(...)	Reads timeseries data stored in txt files of the lab-specific Jovanic format and returns them as a list of pd.Dataframe.
get_Schleyer_metadata_inv_x(→ bool)	Determine if x-axis should be inverted based on Schleyer lab metadata.
constrain_selected_tracks(→ pandas.DataFrame)	Applies constraints to the tracks included in timeseries data.
match_larva_ids_including_by_length(→ pandas.DataFrame)	Applies a matching-ID algorithm to concatenate segmented tracs.
match_larva_ids(→ pandas.DataFrame)	Computes larval body-lengths and then applies a matching-ID algorithm to concatenate segmented tracks.
concatenate_larva_tracks(→ pandas.DataFrame)	Concatenate multiple single tracks to a single dataframe
complete_timeseries_with_nans(→ pandas.DataFrame)	Fill the non-existing ticks with nans
empty_2index_timeseries_df(→ pandas.DataFrame)	Generate an empty dataframe with complete ticks based on an existing
finalize_timeseries_dataframe(→ pandas.DataFrame)	Finalize the timeseries dataframe setting the double-index
generate_dataframes(...)	Generate timeseries and endpoint DataFrames from single tracks.
interpolate_timeseries_dataframe(→ pandas.DataFrame)	Interplolate irregular-timestep timeseries to regular-timestep

Module Contents

larvaworld.lib.process.import_aux.init_endpoint_dataframe_from_timeseries(df: pandas.DataFrame, dt: float) → pandas.DataFrame

Initializes a dataframe for endpoint metrics from a timeseries dataframe.

Parameters

dfpandas.DataFrame

The timeseries dataframe

dtfloat

The timeseries timestep in seconds

Returns

pandas.DataFrame

larvaworld.lib.process.import_aux.read_timeseries_from_raw_files_per_parameter(pref: str, tracker: Any | None = None, dt: float | None = None, Npoints: int | None = None, Ncontour: int | None = None) → pandas.DataFrame

Reads timeseries data stored in txt files of the lab-specific Jovanic format and returns them as a pd.Dataframe.

Parameters

prefstring

The prefix used for detecting the txt files. This includes the absolute folder the files are located in plus any filename prefix unique to the specific dataset’s files.

Npointsinteger, optional

The number of midline points tracked for each larva. If not provided it is set to the lab-format’s default value

Ncontourinteger, optional

The number of contour points tracked for each larva. If not provided it is set to the lab-format’s default value

dtfloat, optional

The tracker timestep. If not provided it is set to the lab-format’s default value

Returns

pandas.DataFrame

larvaworld.lib.process.import_aux.read_timeseries_from_raw_files_per_larva(files: list[str], read_sequence: list[str], save_mode: str = 'semifull', store_sequence: list[str] | None = None, tracker: Any | None = None, inv_x: bool = False) → list[pandas.DataFrame]

Reads timeseries data stored in txt files of the lab-specific Jovanic format and returns them as a list of pd.Dataframe.

Parameters

fileslist

List of the absolute filepaths of the data files.

read_sequencelist of strings

The sequence of parameters found in each file

save_modestring

The mode defining the columns to store Used if store_sequence is not provided

store_sequencelist of strings, optional

The sequence of parameters to store If not provided it is set to the lab-format’s default value

inv_xboolean

Whether to invert x axis. Defaults to False

Returns

list of pandas.DataFrame

larvaworld.lib.process.import_aux.get_Schleyer_metadata_inv_x(dir: str) → bool

Determine if x-axis should be inverted based on Schleyer lab metadata.

Reads metadata file to check odor side configuration and returns whether x-axis inversion is needed for consistent data orientation.

Args:

dir: Directory containing vidAndLogs/metadata.txt file.

Returns:

True if x-axis should be inverted (odor on right), False otherwise.

Example:

>>> inv_x = get_Schleyer_metadata_inv_x('/path/to/dataset')

larvaworld.lib.process.import_aux.constrain_selected_tracks(df: pandas.DataFrame, max_Nagents: int | None = None, time_slice: tuple[float, float] | None = None, min_duration_in_sec: float = 0.0, **kwargs: Any) → pandas.DataFrame

Applies constraints to the tracks included in timeseries data.

Parameters

dfpandas.DataFrame

The timeseries dataframe

max_Nagentsinteger, optional

The maximum number of larvae allowed in the dataset.

time_slicetuple, optional

Use only a defined time slice of the tracs in seconds.

min_duration_in_secfloat

Only include tracks longer than a given duration in seconds. Defaults to 0.0

Returns

pandas.DataFrame

larvaworld.lib.process.import_aux.match_larva_ids_including_by_length(s: pandas.DataFrame, e: pandas.DataFrame, pars: list[str] = ['head_x', 'head_y'], wl: float = 100, wt: float = 0.1, ws: float = 0.5, max_error: float = 600, Nidx: int = 20, verbose: int = 1) → pandas.DataFrame

Applies a matching-ID algorithm to concatenate segmented tracs.

Parameters

spandas.DataFrame

The timeseries dataframe

epandas.DataFrame

The endpoint dataframe

parslist

The spatial parameters to use for computing vincinity. Defaults to [‘head_x’, ‘head_y’]

wlfloat

Coefficient for body-length similarity. Defaults to 100

wtfloat

Coefficient for temporal vincinity. Defaults to 0.1

max_errorfloat

Maximum accepted error Defaults to 600

Nidxinteger

Closest number of neighboring tracs to chec. Defaults to 20

Returns

pandas.DataFrame

larvaworld.lib.process.import_aux.match_larva_ids(df: pandas.DataFrame, Npoints: int, dt: float, e: pandas.DataFrame | None = None, **kwargs: Any) → pandas.DataFrame

Computes larval body-lengths and then applies a matching-ID algorithm to concatenate segmented tracks.

Parameters

dfpandas.DataFrame

The timeseries dataframe

Npointsinteger

The number of midline points tracked for each larva.

dtfloat

The timeseries timestep in seconds

epandas.DataFrame, optional

The endpoint dataframe If not provided it is initialized from df

**kwargs: keyword arguments

Additional keyword arguments to be passed to the match_larva_ids_including_by_length function.

Returns

pandas.DataFrame

larvaworld.lib.process.import_aux.concatenate_larva_tracks(dfs: list[pandas.DataFrame], dt: float) → pandas.DataFrame

Concatenate multiple single tracks to a single dataframe

Parameters

dfslist of pd.DataFrame

The single tracks

dtfloat

The tracking timestep

Returns

pd.DataFrame

larvaworld.lib.process.import_aux.complete_timeseries_with_nans(s0: pandas.DataFrame) → pandas.DataFrame

Fill the non-existing ticks with nans

Parameters

s0pd.DataFrame

The timeseries dataframe

Returns

pd.DataFrame

larvaworld.lib.process.import_aux.empty_2index_timeseries_df(s0: pandas.DataFrame) → pandas.DataFrame

Generate an empty dataframe with complete ticks based on an existing

Parameters

s0pd.DataFrame

The timeseries dataframe

Returns

pd.DataFrame

larvaworld.lib.process.import_aux.finalize_timeseries_dataframe(s: pandas.DataFrame, complete_ticks: bool = True, interpolate_ticks: bool = False) → pandas.DataFrame

Finalize the timeseries dataframe setting the double-index

Parameters

spd.DataFrame

The timeseries dataframe

complete_ticksboolean

Whether to complete timeseries missing ticks with nans Defaults to False

interpolate_ticksboolean

Whether to interpolate timeseries into a fixed timestep timeseries Defaults to False

Returns

pd.DataFrame

larvaworld.lib.process.import_aux.generate_dataframes(dfs: list[pandas.DataFrame], dt: float, complete_ticks: bool = True, **kwargs: Any) → tuple[pandas.DataFrame | None, pandas.DataFrame | None]

Generate timeseries and endpoint DataFrames from single tracks.

Concatenates individual larva tracks and computes endpoint metrics, with optional tick completion and interpolation.

Args:

dfs: List of single-track DataFrames. dt: Tracking timestep in seconds. complete_ticks: If True, fill missing ticks with NaNs. **kwargs: Additional arguments passed to concatenate_larva_tracks.

Returns:

Tuple of (step_df, endpoint_df), or (None, None) if no valid tracks.

Example:

>>> step_df, end_df = generate_dataframes(
...     dfs=[track1, track2],
...     dt=0.1,
...     complete_ticks=True
... )

larvaworld.lib.process.import_aux.interpolate_timeseries_dataframe(s0: pandas.DataFrame) → pandas.DataFrame

Interplolate irregular-timestep timeseries to regular-timestep

Parameters

s0pd.DataFrame

The timeseries dataframe

Returns

pd.DataFrame