larvaworld.lib.model.modules.intermitter ======================================== .. py:module:: larvaworld.lib.model.modules.intermitter Classes ------- .. autoapisummary:: larvaworld.lib.model.modules.intermitter.Intermitter larvaworld.lib.model.modules.intermitter.OfflineIntermitter larvaworld.lib.model.modules.intermitter.BranchIntermitter larvaworld.lib.model.modules.intermitter.FittedIntermitter Functions --------- .. autoapisummary:: larvaworld.lib.model.modules.intermitter.get_EEB_poly1d larvaworld.lib.model.modules.intermitter.get_EEB_time_fractions Module Contents --------------- .. py:class:: Intermitter(**kwargs: Any) Bases: :py:obj:`larvaworld.lib.model.modules.oscillator.Timer` Intermitter module for run/pause/feed behavioral state control. Manages transitions between locomotor states (running, pausing, feeding) using stochastic bout generators. Controls exploitation-exploration balance (EEB) for feeding decisions and tracks behavioral statistics. Attributes: EEB: Exploitation-exploration balance (0=exploit, 1=explore) EEB_decay: Exponential decay of EEB when no food detected crawl_freq: Default crawling frequency (Hz) feed_freq: Default feeding frequency (Hz) run_mode: Generation mode ('stridechain' or 'exec') feeder_reoccurence_rate: Feed reoccurrence probability feed_bouts: Whether feeding epochs are generated pause_dist: Temporal distribution params for pause epochs stridechain_dist: Stride-number distribution for run epochs run_dist: Temporal distribution for run epochs cur_state: Current behavioral state ('exec', 'pause', or 'feed') Example: >>> intermitter = Intermitter(EEB=0.3, crawl_freq=1.42, feed_freq=2.0) >>> state = intermitter.step(stride_completed=True, on_food=False) .. py:attribute:: EEB .. py:attribute:: EEB_decay .. py:attribute:: crawl_freq .. py:attribute:: feed_freq .. py:attribute:: run_mode .. py:attribute:: feeder_reoccurence_rate .. py:attribute:: feed_bouts .. py:attribute:: pause_dist .. py:attribute:: stridechain_dist .. py:attribute:: run_dist .. py:attribute:: cur_state :value: None .. py:attribute:: pause_generator .. py:attribute:: Nstrides :value: 0 .. py:attribute:: Nstridechains :value: 0 .. py:attribute:: Nruns :value: 0 .. py:attribute:: Npauses :value: 0 .. py:attribute:: Nfeeds :value: 0 .. py:attribute:: Nfeedchains :value: 0 .. py:attribute:: Nfeeds_success :value: 0 .. py:attribute:: Nfeeds_fail :value: 0 .. py:attribute:: base_EEB .. py:attribute:: exp_Nstrides :value: None .. py:attribute:: cur_Nstrides :value: 0 .. py:attribute:: exp_Trun :value: None .. py:attribute:: exp_Tpause :value: None .. py:attribute:: cur_Nfeeds :value: None .. py:attribute:: stridechain_lengths :value: [] .. py:attribute:: stridechain_durs :value: [] .. py:attribute:: feedchain_lengths :value: [] .. py:attribute:: feedchain_durs :value: [] .. py:attribute:: pause_durs :value: [] .. py:attribute:: run_durs :value: [] .. py:attribute:: feed_durs :value: [] .. py:attribute:: stride_durs :value: [] .. py:property:: pause_completed :type: bool .. py:property:: run_completed :type: bool .. py:property:: stridechain_completed :type: bool .. py:method:: alternate_crawlNpause(stride_completed: bool = False) -> None .. py:property:: feed_repeated :type: bool .. py:method:: alternate_exploreNexploit(feed_motion: bool = False, on_food: bool = False) -> None .. py:method:: register(bout: str | None = None) -> None .. py:method:: update_state(stride_completed: bool = False, feed_motion: bool = False, on_food: bool = False) -> str | None .. py:method:: step(**kwargs: Any) -> str | None .. py:method:: generate_stridechain() -> int .. py:method:: generate_run() -> float .. py:method:: interrupt_locomotion() -> None .. py:method:: trigger_locomotion(force: bool = False) -> None .. py:method:: generate_pause() -> float .. py:method:: build_dict() -> dict[str, Any] .. py:method:: save_dict(path: str | None = None, dic: dict[str, Any] | None = None) -> None .. py:property:: active_bouts :type: tuple[int | None, int | None, float | None, float | None] .. py:property:: mean_feed_freq :type: float .. py:class:: OfflineIntermitter(**kwargs: Any) Bases: :py:obj:`Intermitter` Offline intermitter with fixed-frequency stride/feed detection. Extends Intermitter with tick-based stride and feed detection at fixed intervals (offline mode, no real-time physics). Example: >>> offline_int = OfflineIntermitter(EEB=0.5, crawl_freq=1.5, dt=0.1) >>> state = offline_int.step(on_food=True) .. py:attribute:: crawl_ticks .. py:method:: step(stride_completed: bool | None = None, feed_motion: bool | None = None, on_food: bool = True) -> str | None .. py:class:: BranchIntermitter(**kwargs: Any) Bases: :py:obj:`Intermitter` Branch intermitter with critical dynamics for pause/run generation. Extends Intermitter using exponential (exp_bout) and critical (critical_bout) distributions for more realistic behavioral branching. No feeding bouts in this mode. Attributes: feed_bouts: Fixed to False (no feeding) beta: Beta coefficient for exponential bout distribution c: Critical parameter for criticality function sigma: ISING branching coefficient Example: >>> branch_int = BranchIntermitter(beta=4.7, c=0.7, sigma=1.0, dt=0.1) >>> state = branch_int.step(stride_completed=True) .. py:attribute:: feed_bouts .. py:attribute:: beta .. py:attribute:: c .. py:attribute:: sigma .. py:method:: generate_stridechain() -> int .. py:method:: generate_pause() -> float .. py:class:: FittedIntermitter(refID: str, **kwargs: Any) Bases: :py:obj:`OfflineIntermitter` Fitted intermitter using reference dataset parameters. Constructs OfflineIntermitter from stored reference dataset configurations (crawl/feed frequencies, bout distributions). Args: refID: Reference dataset ID to load intermitter config from **kwargs: Override parameters (optional) Example: >>> fitted_int = FittedIntermitter(refID='exploration') >>> state = fitted_int.step(on_food=False) .. py:function:: get_EEB_poly1d(max_dur: float = 60 * 60, **kws: Any) -> numpy.poly1d Compute polynomial fit of EEB vs mean feeding frequency. Simulates intermitter across EEB range (0-1) and fits polynomial to map feeding frequency back to EEB parameter. Args: max_dur: Maximum simulation duration (seconds) **kws: Intermitter configuration keyword arguments Returns: Polynomial (degree 5) mapping feed frequency to EEB Example: >>> poly = get_EEB_poly1d(crawl_freq=1.42, feed_freq=2.0, dt=0.1) >>> eeb_estimate = poly(0.15) # For feed_freq=0.15 .. py:function:: get_EEB_time_fractions(refID: str | None = None, dt: float | None = None, max_dur: float = 60 * 60, **kwargs: Any) -> pandas.DataFrame Compute time fractions for behavioral states across EEB range. Simulates intermitter across EEB values (0-1) and computes duration ratios for crawl/pause/feed states. Returns DataFrame for analysis and visualization. Args: refID: Reference dataset ID for intermitter config (optional) dt: Time step override (optional) max_dur: Maximum simulation duration (seconds) **kwargs: Intermitter configuration if refID not provided Returns: DataFrame with EEB values and corresponding time fraction ratios Example: >>> df = get_EEB_time_fractions(refID='exploration', dt=0.1) >>> print(df[['EEB', 'crawl ratio', 'pause ratio']])