From 5734cbb0bd7a024e0f43020384849c815aed3984 Mon Sep 17 00:00:00 2001 From: edwardlavender Date: Tue, 21 May 2024 11:26:11 +0200 Subject: [PATCH] Update doc --- README.md | 2 +- src/002-states.jl | 50 ++++++++++++++++++++++++++---------- src/003-model-movement.jl | 12 ++++----- src/004-model-observation.jl | 6 ++--- src/005-data-assembly.jl | 2 +- src/007-particle-filter.jl | 2 +- src/010-Julia-from-R.jl | 6 ++--- 7 files changed, 51 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 5d37b9c..5e36c13 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ To collate real-world datasets for real-world analyses, use: * `assemble_yobs()` to assemble a hash-table; -This function expects a `Vector` of `DataFrame`s, one for each data type, that comprise a timeline of observations and associated model parameters, and a corresponding `Vector` of observation model (`ModelObs`) subtypes. +This function expects a `Vector` of `DataFrame`s, one for each data type, that comprise a timeline of observations and associated model parameters, and a corresponding `Vector` of observation model (`ModelObs`) sub-types. ## Modelling diff --git a/src/002-states.jl b/src/002-states.jl index b52915f..0e3e380 100644 --- a/src/002-states.jl +++ b/src/002-states.jl @@ -3,31 +3,53 @@ export State, StateXY, StateXYZ, StateXYZD """ State -`State` is an abstract type that defines the animal's state at a given time step. +`State` is an Abstract Type that defines the animal's state at a given time step. -# Subtypes +# Built-in sub-types -- `StateXY`: Used for two dimensional (x, y) states; -- `StateXYZ`: Used for three-dimensional (x, y, z) states; -- `StateXYZD`: Used for four-dimensional (x, y, z, direction) states; +The following sub-types are built-in: -# Fields +- `StateXY(map_value, x, y)`: Used for two dimensional (x, y) states ; +- `StateXYZD(map_value, x, y, z, angle)`: Used for four-dimensional (x, y, z, direction) states; -- `map_value`: The value of the map at coordinates (x, y), required for All `State`s; -- `x`, `y`: The animal's x and y coordinates, required for all `State`s; -- `z`: The animal's z coordinate, required for 3D `State`s; -- `angle`: The turning angle, required by `StateXYZD`; +These contain the following fields: -# Details +- `map_value`: The value of the movement map at coordinates (x, y), required for all `State`s (see [`ModelMove`](@ref)); +- `x`, `y`: Floats that define the animal's x and y coordinates, required for all `State`s; +- `z`: A float that defines the animal's z (depth) coordinate, required for all `State`s with a depth component; +- `angle`: A float that defines the turning angle, required by `StateXYZD`; -- All states must include `x`, `y` and `map_value` fields; -- For >= 3D states, the depth dimension must be named `z` (for [`Patter.simulate_move()`](@ref)); +# Custom sub-types + +To define a custom sub-type, such as `StateXYZ`, simply define a struct that is a sub-type of `Patter.State`: + +``` +struct StateXYZ <: Patter.State + # Map value + map_value::Float64 + # Coordinates + x::Float64 + y::Float64 + z::Float64 + end +``` + +New states should obey the following requirements: +- All states must include `map_value`, `x` and `y` fields; +- For states with a depth dimension, the depth field must be named `z` (for [`Patter.simulate_move()`](@ref)); - For `R` users, all fields must be of type `Float64` for [`Patter.r_get_states()`](@ref) to parse state vectors; + +To use a new state sub-type in the simulation of animal movements (via [`simulate_path_walk()`](@ref)) and particle-filtering algorithms, the following steps are also necessary: +- Define a corresponding [`ModelMove`](@ref) sub-type; +- (optional) Define a [`Patter.simulate_state_init()`](@ref) method for [`simulate_states_init()`](@ref) to simulate initial states; +- Define a [`Patter.simulate_step()`] method (for [`Patter.simulate_move`](@ref)) to update the state using a [`ModelMove`](@ref) instance; +- Define a [`Patter.logpdf_step)`] method (for [`Patter.logpdf_move`](@ref)) to evaluate the probability density of movement from one state to another; + ``` """ abstract type State end -# State subtypes: +# State sub-types: # * map_value, x, y are essential (see documentation) # * This is much faster & facilitates the implementation of the depth observation models diff --git a/src/003-model-movement.jl b/src/003-model-movement.jl index 72e4a55..b553460 100644 --- a/src/003-model-movement.jl +++ b/src/003-model-movement.jl @@ -13,11 +13,11 @@ export simulate_states_init `ModelMove` is an abstract type that defines the movement model. -# Subtypes +# sub-types -- ``: A subtype for two-dimensional (x, y) random walks, based distributions for step lengths (`dbn_length`) and turning angles (`dbn_angle`); -- `ModelMoveXY`: A subtype for three-dimensional (x, y, z) random walks, based on distributions for step lengths (`dbn_length`), turning angles (`dbn_angle`) and changes in depth (`dbn_z_delta`); -- `ModelMoveXYZD`: A subtype for four-dimensional (correlated) random walks, based on distributions for step lengths (`dbn_length`), changes in turning angle (`dbn_angle`) and changes in depth (`dbn_z_delta`); +- ``: A sub-type for two-dimensional (x, y) random walks, based distributions for step lengths (`dbn_length`) and turning angles (`dbn_angle`); +- `ModelMoveXY`: A sub-type for three-dimensional (x, y, z) random walks, based on distributions for step lengths (`dbn_length`), turning angles (`dbn_angle`) and changes in depth (`dbn_z_delta`); +- `ModelMoveXYZD`: A sub-type for four-dimensional (correlated) random walks, based on distributions for step lengths (`dbn_length`), changes in turning angle (`dbn_angle`) and changes in depth (`dbn_z_delta`); # Fields @@ -79,7 +79,7 @@ Simulate an initial state. This function is wrapped by the exported function [`simulate_states_init()`](@ref), which simulates a vector of states. # Arguments: -- `state_type`: An empty `State` subtype, such as `StateXY`, used for method dispatch only; +- `state_type`: An empty `State` sub-type, such as `StateXY`, used for method dispatch only; - `model`: A `MoveModel` instance; - `xlim`, `ylim`: Pairs of numbers that define the boundaries of the area within which `x` and `y` state values are sampled; @@ -111,7 +111,7 @@ end Simulate a vector of initial states for the simulation of movement paths and the particle filter. # Arguments -- `state_type`: An empty `State` subtype, such as `StateXY`, used for method dispatch only; +- `state_type`: An empty `State` sub-type, such as `StateXY`, used for method dispatch only; - `move`: A `MoveModel` instance; - `n`: The number of intial states to simulate; - `xlim`, `ylim`: (optional) Pairs of numbers that define the boundaries of the area within which `x` and `y` state values are sampled; diff --git a/src/004-model-observation.jl b/src/004-model-observation.jl index ae2c1f7..37daca0 100644 --- a/src/004-model-observation.jl +++ b/src/004-model-observation.jl @@ -11,9 +11,9 @@ export ModelObsDepthUniform, ModelObsDepthNormalTrunc, ModelObsDepthNormal # `ModelObs` -`ModelObs` is an Abstract Type that groups observation model structures. See below for built-in subtypes. +`ModelObs` is an Abstract Type that groups observation model structures. See below for built-in sub-types. -# Built-in subtypes +# Built-in sub-types ## `ModelObsAcousticLogisTrunc` @@ -103,7 +103,7 @@ struct ModelObsDepthNormal <: Patter.ModelObs end ``` -For communication with `R`, all subtypes should include a `sensor_id` field. +For communication with `R`, all sub-types should include a `sensor_id` field. Add corresponding methods to simulate observations via [`Patter.simulate_obs()`](@ref) and to evaluate log probabilities via [`Patter.logpdf_obs()`](@ref). diff --git a/src/005-data-assembly.jl b/src/005-data-assembly.jl index f6bf1ee..8b34626 100644 --- a/src/005-data-assembly.jl +++ b/src/005-data-assembly.jl @@ -49,7 +49,7 @@ Assemble a dictionary of observations (and associated model parameters) for the - `sensor_id`: A vector of sensor IDs; - `obs`: The observation; - Additional columns required to construct ModelObs instances (that is, model parameters); -- model_types: A Vector of ModelObs subtypes for each dataset. +- model_types: A Vector of ModelObs sub-types for each dataset. # Details diff --git a/src/007-particle-filter.jl b/src/007-particle-filter.jl index 32c0b2e..14cd2c2 100644 --- a/src/007-particle-filter.jl +++ b/src/007-particle-filter.jl @@ -82,7 +82,7 @@ A particle filtering algorithm that samples from `f(X_t | {Y_1 ... Y_t}) for t - The movement model describes movement from one time step to the next and therefore depends implicitly on the resolution of `timeline`. - The movement model should align with the [`State`] instances in `.xinit`. For example, a 2-dimensional state ([`StateXY`](@ref)) requires a corresponding movement model instance (i.e., [`ModelMoveXY`](@ref)). - `n_move`: An integer that defines the number of attempts used to find a legal move. - - All [`ModelMove`](@ref) subtypes contain a `map` field that defines the region(s) within which movements are allowed. + - All [`ModelMove`](@ref) sub-types contain a `map` field that defines the region(s) within which movements are allowed. - Each particle is moved up to `n_move` times, until a valid movement is simulated. - Particles that fail to generate a valid move are killed. - `n_record`: An integer that defines the number of particles to record at each time step. diff --git a/src/010-Julia-from-R.jl b/src/010-Julia-from-R.jl index a623d34..6428766 100644 --- a/src/010-Julia-from-R.jl +++ b/src/010-Julia-from-R.jl @@ -8,9 +8,9 @@ A collection of functions that facilitate the translation of inputs from R into # Details -* [`julia_get_xinit()`](@ref) gets a Vector of initial States from a DataFrame; -* [`julia_get_model_types()`](@ref) gets a Vector of `ModelObs` subtypes from a Vector of Strings; -* [`julia_get_models()`](@ref) gets a Vector of model instances from a Vector of DataFrames that contain parameters and a corresponding vector of model types; +* `Patter.julia_get_xinit()` gets a Vector of initial [`State`](@ref)s from a DataFrame; +* `Patter.julia_get_model_types()` gets a Vector of [`ModelObs`](@ref) sub-types from a Vector of Strings; +* `Patter.julia_get_models()` gets a `Vector` of [`ModelObs`](@ref) instances from a `Vector` of `DataFrame`s that contain parameters and a corresponding vector of [`ModelObs`](@ref) sub-types; """ function julia_get end