larvaworld.lib.process.import_aux ================================= .. py:module:: larvaworld.lib.process.import_aux .. autoapi-nested-parse:: Helper methods used for importing data Functions --------- .. autoapisummary:: larvaworld.lib.process.import_aux.init_endpoint_dataframe_from_timeseries larvaworld.lib.process.import_aux.read_timeseries_from_raw_files_per_parameter larvaworld.lib.process.import_aux.read_timeseries_from_raw_files_per_larva larvaworld.lib.process.import_aux.get_Schleyer_metadata_inv_x larvaworld.lib.process.import_aux.constrain_selected_tracks larvaworld.lib.process.import_aux.match_larva_ids_including_by_length larvaworld.lib.process.import_aux.match_larva_ids larvaworld.lib.process.import_aux.concatenate_larva_tracks larvaworld.lib.process.import_aux.complete_timeseries_with_nans larvaworld.lib.process.import_aux.empty_2index_timeseries_df larvaworld.lib.process.import_aux.finalize_timeseries_dataframe larvaworld.lib.process.import_aux.generate_dataframes larvaworld.lib.process.import_aux.interpolate_timeseries_dataframe Module Contents --------------- .. py:function:: init_endpoint_dataframe_from_timeseries(df: pandas.DataFrame, dt: float) -> pandas.DataFrame Initializes a dataframe for endpoint metrics from a timeseries dataframe. Parameters ---------- df : pandas.DataFrame The timeseries dataframe dt : float The timeseries timestep in seconds Returns ------- pandas.DataFrame .. py:function:: read_timeseries_from_raw_files_per_parameter(pref: str, tracker: Optional[Any] = None, dt: Optional[float] = None, Npoints: Optional[int] = None, Ncontour: Optional[int] = None) -> pandas.DataFrame Reads timeseries data stored in txt files of the lab-specific Jovanic format and returns them as a pd.Dataframe. Parameters ---------- pref : string 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. Npoints : integer, optional The number of midline points tracked for each larva. If not provided it is set to the lab-format's default value Ncontour : integer, optional The number of contour points tracked for each larva. If not provided it is set to the lab-format's default value dt : float, optional The tracker timestep. If not provided it is set to the lab-format's default value Returns ------- pandas.DataFrame .. py:function:: read_timeseries_from_raw_files_per_larva(files: list[str], read_sequence: list[str], save_mode: str = 'semifull', store_sequence: Optional[list[str]] = None, tracker: Optional[Any] = 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 ---------- files : list List of the absolute filepaths of the data files. read_sequence : list of strings The sequence of parameters found in each file save_mode : string The mode defining the columns to store Used if store_sequence is not provided store_sequence : list of strings, optional The sequence of parameters to store If not provided it is set to the lab-format's default value inv_x : boolean Whether to invert x axis. Defaults to False Returns ------- list of pandas.DataFrame .. py:function:: 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') .. py:function:: constrain_selected_tracks(df: pandas.DataFrame, max_Nagents: Optional[int] = None, time_slice: Optional[tuple[float, float]] = None, min_duration_in_sec: float = 0.0, **kwargs: Any) -> pandas.DataFrame Applies constraints to the tracks included in timeseries data. Parameters ---------- df : pandas.DataFrame The timeseries dataframe max_Nagents : integer, optional The maximum number of larvae allowed in the dataset. time_slice : tuple, optional Use only a defined time slice of the tracs in seconds. min_duration_in_sec : float Only include tracks longer than a given duration in seconds. Defaults to 0.0 Returns ------- pandas.DataFrame .. py:function:: 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 ---------- s : pandas.DataFrame The timeseries dataframe e : pandas.DataFrame The endpoint dataframe pars : list The spatial parameters to use for computing vincinity. Defaults to ['head_x', 'head_y'] wl : float Coefficient for body-length similarity. Defaults to 100 wt : float Coefficient for temporal vincinity. Defaults to 0.1 max_error : float Maximum accepted error Defaults to 600 Nidx : integer Closest number of neighboring tracs to chec. Defaults to 20 Returns ------- pandas.DataFrame .. py:function:: match_larva_ids(df: pandas.DataFrame, Npoints: int, dt: float, e: Optional[pandas.DataFrame] = None, **kwargs: Any) -> pandas.DataFrame Computes larval body-lengths and then applies a matching-ID algorithm to concatenate segmented tracks. Parameters ---------- df : pandas.DataFrame The timeseries dataframe Npoints : integer The number of midline points tracked for each larva. dt : float The timeseries timestep in seconds e : pandas.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 .. py:function:: concatenate_larva_tracks(dfs: list[pandas.DataFrame], dt: float) -> pandas.DataFrame Concatenate multiple single tracks to a single dataframe Parameters ---------- dfs : list of pd.DataFrame The single tracks dt : float The tracking timestep Returns ------- pd.DataFrame .. py:function:: complete_timeseries_with_nans(s0: pandas.DataFrame) -> pandas.DataFrame Fill the non-existing ticks with nans Parameters ---------- s0 : pd.DataFrame The timeseries dataframe Returns ------- pd.DataFrame .. py:function:: empty_2index_timeseries_df(s0: pandas.DataFrame) -> pandas.DataFrame Generate an empty dataframe with complete ticks based on an existing Parameters ---------- s0 : pd.DataFrame The timeseries dataframe Returns ------- pd.DataFrame .. py:function:: 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 ---------- s : pd.DataFrame The timeseries dataframe complete_ticks : boolean Whether to complete timeseries missing ticks with nans Defaults to False interpolate_ticks : boolean Whether to interpolate timeseries into a fixed timestep timeseries Defaults to False Returns ------- pd.DataFrame .. py:function:: generate_dataframes(dfs: list[pandas.DataFrame], dt: float, complete_ticks: bool = True, **kwargs: Any) -> tuple[Optional[pandas.DataFrame], Optional[pandas.DataFrame]] 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 ... ) .. py:function:: interpolate_timeseries_dataframe(s0: pandas.DataFrame) -> pandas.DataFrame Interplolate irregular-timestep timeseries to regular-timestep Parameters ---------- s0 : pd.DataFrame The timeseries dataframe Returns ------- pd.DataFrame