Update doc

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
 

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
 

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;

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). 
 

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
 

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.

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