Commit a5baf982 authored by Victor's avatar Victor
Browse files

changes in the doc, and reorganising writing of accessors

parent c988767d
......@@ -18,11 +18,15 @@ using ABMEv
```
## The `Agent` structure
This package is an Agent Based Model, where the atomic structure is the `Agent`, which is defined by a history of traits, a death rate and a birth rate.
This package is an Agent Based Model, where the atomic structure is the `Agent`. It has four attributes
- the ancestors' history of traits, and the corresponding time where the traits have changed,
- a death rate and a birth rate.
```julia
mutable struct Agent{T,U}
# history of traits for geotraits
x_history::Array{U}
# birth time of ancestors
t_history::Array{U,1}
# death rate
d::Float64
#birth rate
......@@ -88,7 +92,7 @@ worldall,p["tspan"] = runWorld_store_G(p,world0);
using Plots
Plots.plot(worldall,p)
```
As of now, no mode is implemented.
As of now, no mode is implemented. For further examples, check the folder `examples` in source code.
#### Specific parameters
- ```dt_saving = 10.```
......@@ -131,34 +135,43 @@ using Distributed;addprocs()
```
Parallelism only works with Wright Fisher model.
## Properties of agents
### Main accessors
You can access properties of the agent using the following functions
- `get_xarray(world::Array{Agent{T}},trait::Int) where T`
Returns trait of every agents of `world` in the form of an array which dimensions corresponds to the input.
Particularly suited for an array `world` corresponding to one time step, or a time series from a **Wright Fisher simulation**.
>TODO: implement the possibility of getting geotrait
- `get_geo(a::Agent{U,T},t::Number) where {U,T}`: returns the geotrait
- `get_x(a::Agent,t::Number,i::Integer)` returns trait `i` of the agent. Geotrait corresponds to dimension `i=0`. If you do not want to access geotrait, you can also use `get_x(a::Agent,i::Integer)`.
### World accessors
You can access properties of the world of agents using the following functions
- `get_x(world::Array{T},t::Number,trait::Integer) where {T <: Agent}`
Returns trait of every agents of world in the form of an array which dimensions corresponds to the input. If trait = 0 , we return the geotrait. One can also use `get_x(world::Array{T},trait::Integer) where {T <: Agent}` if no need for geotrait
- `get_xarray(world::Array{T,1},t::Number,geotrait::Bool=false) where {T <: Agent}`
Returns every traits of every agents of `world` in the form **of a one dimensional array** (in contrast to `get_x`). If `geotrait=true` the geotrait is also added to the set of trait, in the last line. If you do not want to specify `t` (only useful for geotrait), it is also possible to use `get_xarray(world::Array{T,1}) where {T <: Agent}`.
- `get_xarray(world::Array{T,1},geotrait=false) where {T <: Agent}`
Returns every traits of every agents of world in the form of an array
If geotrait = true, then a last trait dimension is added, corresponding to geotrait.
- `get_xhist(world::Vector{Agent},geotrait = false)`
- `get_xhist(world::Vector{Agent},geotrait = false)` : :warning: This method is broken.
Returns the trait history of every agents of world in the form of an 3 dimensional array,
with
- - first dimension as the agent index
- - second as time index
- - third as trait index
- first dimension as the agent index
- second as time index
- third as trait index
If geotrait = true, then a last trait dimension is added, corresponding to geotrait.
Note that because number of ancestors are different between agents, we return an array which size corresponds to the minimum of agents ancestors,
and return the last generations, dropping the youngest ones
- `world2df(world::Array{T,1}; geotrait = false) where {T <: Agent}`
- `world2df(world::Array{T,1},t::Number,geotrait = false) where {T <: Agent}`
Converts the array of agent world to a datafram, where each column corresponds to a trait of the
agent, and an extra column captures fitness.
Each row corresponds to an agent
Converts the array of agent world to a dataframe, where each column corresponds to a trait of the agent, and an extra column captures fitness.
Each row corresponds to an agent.
Again, if one do not want to feed `t` (no need for geotrait), it is possible to use `world2df(world::Array{T,1}) where {T <: Agent}`.
### Other accessors
> TODO: describe the following accessors
......@@ -174,10 +187,11 @@ get_fitness(a::Agent) = a.b - a.d
get_dim(a::Agent) = size(a.x_history,1)
get_nancestors(a::Agent) = size(a.x_history,2)
```
> Todo : implement geotrait in `get_xhist`
## Plotting
ABMEv comes with Plot recipes:
`function plot(world::Array{U},p;what=["x","H"],trait = 1) where U <: Union{Missing,Agent{T}} where T`.
`plot(world::Array{U},p;what=["x","H"],trait = 1) where U <: Union{Missing,Agent{T}} where T`.
An example to use it:
```julia
......@@ -185,10 +199,10 @@ using Plots;pyplot()
Plots.plot(worldall,p_default,what=["x"],trait=2)
```
You can specify what you want to plot in the array ```what```:
- ```"x"``` returns a scatter plot `(xaxis = time, yaxis = trait value)` where trait component is specified by ```trait=2```
- `"xs"` only works for agent type `MixedAgent`, because it needs a discrete geographical space. It returns a scatter plot `(xaxis = geographical component, yaxis = trait value)`
- ```"geo"``` returns a scatter plot where trait is the *geotrait* computed from first component
- ```"3dgeo"``` plots a 3d diagram with x axis as geotrait and y axis as the second component
- ```"x"``` returns a scatter plot `(xaxis = time, yaxis = trait)` . Geotrait corresponds to `trait=0`
- `"xs"` only works for agent type `MixedAgent`, because it needs a discrete geographical space. It returns a scatter plot `(xaxis = geographical component, yaxis = trait value)`. Very similar to a `histogram2d` plot, with nicer look.
- ```"3dgeo"``` plots a 3d diagram with x axis as geotrait and y axis as the second component. :warning: this is probably weekend
- ```"3d"``` plots a 3d diagram with first and second component as x and y axis
- ```"var"``` plots the variance of the component specified by ```trait=2``` :question: with respect to time?
- ```"vargeo"``` plots the variance of the geotrait
......
......@@ -38,8 +38,6 @@ function new_world_G(nagents::Int,p::Dict; spread = 1., offset = 0.)
end
# returns trait i of the agent
get_xhist(a::Agent,i::Number) = a.x_history[Int(i),:]
get_xhist(a::Agent) = a.x_history
get_x(a::Agent) = a.x_history[:,end]
function get_geo(a::Agent{U,T},t::Number) where {U,T}
tarray = vcat(a.t_history[2:end],convert(T,t))
......@@ -49,27 +47,26 @@ end
# This method can acces geotrait, while the second not
get_x(a::Agent,t::Number,i::Integer) = i > 0 ? a.x_history[Int(i),end] : get_geo(a,t)
get_x(a::Agent,i::Integer) = a.x_history[Int(i),end]
get_xhist(a::Agent,i::Number) = a.x_history[Int(i),:]
get_xhist(a::Agent) = a.x_history
get_d(a::Agent) = a.d
get_b(a::Agent) = a.b
get_fitness(a::Agent) = a.b - a.d
get_dim(a::Agent) = size(a.x_history,1)
get_nancestors(a::Agent) = size(a.x_history,2)
get_x(world::Array{T},trait::Integer) where {T <: Agent} = trait > 0 ? reshape(hcat(get_x.(world,trait)),size(world,1),size(world,2)) : throw(ErrorException("Not the right method, need `t` as an argument"))
"""
get_xarray(world::Array{Agent},trait::Int)
Mainly works for WF-type world
get_x(world::Array{T},t::Number,trait::Integer) where {T <: Agent}
Returns trait of every agents of world in the form of an array which dimensions corresponds to the input.
If trait = 0 , we return the geotrait.
Particularly suited for an array world corresponding to a timeseries.
"""
get_x(world::Array{T},trait::Integer) where {T <: Agent} = trait > 0 ? reshape(hcat(get_x.(world,trait)),size(world,1),size(world,2)) : throw(ErrorException("Not the right method, need `t` as an argument"))
get_x(world::Array{T},t::Number,trait::Integer) where {T <: Agent} = trait > 0 ? reshape(hcat(get_x.(world,trait)),size(world,1),size(world,2)) : reshape(hcat(get_geo.(world,t)),size(world,1),size(world,2))
"""
get_xarray(world::Array{Agent,1})
Returns every traits of every agents of world in the form of an array
If geotrait = true, then a last trait dimension is added, corresponding to geotrait.
"""
function get_xarray(world::Array{T,1}) where {T <: Agent}
return hcat(get_x.(world)...)
......@@ -83,26 +80,26 @@ function get_xarray(world::Array{T,1},t::Number,geotrait::Bool=false) where {T <
return xarray
end
"""
get_xhist(world::Vector{Agent},geotrait = false)
Returns the trait history of every agents of world in the form of an 3 dimensional array,
with
- first dimension as the agent index
- second as time index
- third as trait index
If geotrait = true, then a last trait dimension is added, corresponding to geotrait.
Note that because number of ancestors are different between agents, we return an array which size corresponds to the minimum of agents ancestors,
and return the last generations, dropping the youngest ones
"""
function get_xhist(world::Vector{T}) where {T <: Agent}
hist = minimum(get_nancestors.(world))
ntraits = get_dim(first(world));
xhist = zeros(length(world), hist, ntraits + geotrait);
for (i,a) in enumerate(world)
xhist[i,:,1:end-geotrait] = get_xhist(a)[:,end-hist+1:end]';
end
return xhist
end
# """
# get_xhist(world::Vector{Agent},geotrait = false)
# Returns the trait history of every agents of world in the form of an 3 dimensional array,
# with
# - first dimension as the agent index
# - second as time index
# - third as trait index
# If geotrait = true, then a last trait dimension is added, corresponding to geotrait.
# Note that because number of ancestors are different between agents, we return an array which size corresponds to the minimum of agents ancestors,
# and return the last generations, dropping the youngest ones
# """
# function get_xhist(world::Vector{T}) where {T <: Agent}
# hist = minimum(get_nancestors.(world))
# ntraits = get_dim(first(world));
# xhist = zeros(length(world), hist, ntraits + geotrait);
# for (i,a) in enumerate(world)
# xhist[i,:,1:end-geotrait] = get_xhist(a)[:,end-hist+1:end]';
# end
# return xhist
# end
# TODO: This method broken, when one ask for the geotraits
# function get_xhist(world::Vector{T},t::Number,geotrait = false) where {T <: Agent}
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment