Commit 54cef043 authored by Le Galiot Agathe's avatar Le Galiot Agathe
Browse files

change user_guide explanation

parent 7f9d8af2
......@@ -95,7 +95,12 @@ Mathematical framework
The objective is to understand statistical systems thanks to the estimation of model parameters using experimental data.
We want to create a model which modelised the best way possible what we want to study in order to analyse it.
In other terms the objective is to find f, :math:`\theta`, mn, on, so that the experimental observations fit the best way possible y for each time step.
Note that x can either be hidden state variables or observed data. y is thus x filtered in order to keep only the state variable that were actually measured experimentally (which exclude the hidden state variables)
Note that x can either be hidden state variables or observed data.
y is x filtered in order to keep only the state variable that were actually measured experimentally (which exclude the hidden state variables)
For example, imagine you run a simulation, it will compute every variable of the vector x at each time step.
But what you observed in real life will only be on specific variable at specific time.
The function g will thus filter x to keep only the observed variable of vector x.
Adjustin structures & functions
......@@ -177,47 +182,61 @@ For example "TC_model_name" can become "greenlab-arabidopsis"
using Adjustin
str_m must be the same name as folder database/control/TC_model_name and database/observations/TC_model_name
and database/parameters/TC_model_name and database/state/TC_model_name. Add folder TC_model_name manually if it doesn't already exist.
If you are using a preexisting package in Adjustin it must also be the same name, as the file in the package Adjustin located at src/models/TC_model_name.jl.
If you are writing a new model it must be the same name as the file in Adjustin application at location database/models/TC_model_name/TC_model_name_version.jl
.. code-block:: julia
str_m = "TC_model_name"
str_c must be the same as file located in database/control/TC_model_name/TC_controle_file_name.jl
str_x must be the same as file located in database/state/TC_model_name/TC_state_file_name.jl
str_p must be the same as file located in database/parameters/TC_model_name/TC_parameters_file_name.jl
str_d can be anything
.. code-block:: julia
str_c = "TC_controle_file_name"
str_x = "TC_state_file_name"
str_p = "TC_parameters_file_name"
str_d = "TC_results_part_of_file_name"
str_cfg = "TC_configuration_file_name"
str_d = "TC_results_part_of_file_name"
str_dir = create_results_direTCory(; title = str_d)
load_local_model(str_m) #use load_model(str_m) instead if you are using a preexistant model defined in Adjustin package
load_state(str_m, str_x)
load_control(str_m, str_c)
load_parameters(str_m, str_p)
load_configuration("algo*",str_m, str_cfg) # for example load_configuration("gls",str_m, str_cfg)
The observation noise, on, is optionnal
TC_field_name_observed must be the same as one of the field in the struct ObservationNoise in Adjustin:src/models/TC_model_name.jl
which is also the same as one of the field in the struct State in Adjustin:src/models/TC_model_name.jl
If you are using the functions load_*, which unable to have a cleaner code and not everything in a single file
(you could also not use the functions load_* and declare directly your parameters, states, controls and configurations directly in your main file)
then you must be careful of the names put as input of those functions.
Indeed the functions load* will look for the input name in a specific location. You must make sure these are correct (see below).
Note that you will have to create those files in the appropriate location.
Note also that in the example above we loaded a local model which is in the Adjustinapplication repository, in the database (see below).
However if you are using a preexisting model in Adjustin (Adjustin comes with a set of precoded model),
the model file will be in the Adjustin package (not adjustinapplications) located at src/models/TC_model_name.jl.
obs in the beginning of obs_TC_field_name_observed must be there.
::
TC_kind can be : additive-normal/multiplicative-normal/multiplicative-lognormal/additive-uniform/multiplicative-uniform
database
|configuration
|estimation
|algo*
|TC_model_name
TC_configuration_file_name
|sensitivity_analysis
|algo*
|TC_model_name
TC_configuration_file_name
|control
|TC_model_name
TC_controle_file_name.jl
|observations
|TC_model_name
|parameters
|TC_model_name
TC_parameters_file_name.jl
|state
|TC_model_name
TC_state_file_name.jl
|models
|TC_model_name #if you add your own model and not use a preexisting one in adjustin
How TC_int_param_noise_1 and 2 are used is detailed in Adjustin src/core/noise.jl in function noise!()
.. code-block:: julia
......@@ -228,10 +247,18 @@ How TC_int_param_noise_1 and 2 are used is detailed in Adjustin src/core/noise.j
(TC_int_param_noise_1, TC_int_param_noise_2),
))
The modelling noise mn is optionnal
TC_field_name_det (det for deterministic) must be the same as one of the field in the struct State in Adjustin:src/models/TC_model_name.jl
TC_field_name_sto (sto for stochastic) must be the same as one of the field in the struct State in Adjustin:src/models/TC_model_name.jl
)
The observation noise, on, is optionnal
TC_field_name_observed must be the same as one of the field in the struct ObservationNoise in Adjustin:src/models/TC_model_name.jl
which is also the same as one of the field in the struct State in Adjustin:src/models/TC_model_name.jl
obs in the beginning of obs_TC_field_name_observed must be there.
TC_kind can be : additive-normal/multiplicative-normal/multiplicative-lognormal/additive-uniform/multiplicative-uniform
How TC_int_param_noise_1 and 2 are used is detailed in Adjustin src/core/noise.jl in function noise!()
.. code-block:: julia
......@@ -241,11 +268,12 @@ TC_field_name_sto (sto for stochastic) must be the same as one of the field in t
"TC_string_kind",
(TC_int_param_noise_1, TC_int_param_noise_1)),
g will be a list of Observer. '\r\n'
As seen above, an observer is a structure containing the name of the object we want to observe (usually fields in state and/or observation noise), a function to retrieve the value of this object, the timeline on witch we are observing it, and the number of arguments that the function needs.
`all` (see below) is optional
it is added (usually more in simulations than estimations) if you want to observed all fields in the state
and not only the stochastic ones
The modelling noise mn is optionnal
TC_field_name_det (det for deterministic) must be the same as one of the field in the struct State in Adjustin:src/models/TC_model_name.jl
TC_field_name_sto (sto for stochastic) must be the same as one of the field in the struct State in Adjustin:src/models/TC_model_name.jl
)
.. code-block:: julia
......@@ -253,42 +281,56 @@ and not only the stochastic ones
tml = 1:tmax
g = create_observation_function([ObserverModel("all,obs_TC_field_name_observed", tml)])
g will be a list of Observer. '\r\n'
As seen above, an observer is a structure containing the name of the object we want to observe (usually fields in state and/or observation noise), a function to retrieve the value of this object, the timeline on witch we are observing it, and the number of arguments that the function needs.
`all` (see above) is optional
it is added (usually more in simulations than estimations) if you want to observed all fields in the state
and not only the stochastic (i.e observed) ones
OR
another way to compute g, if observation data are imported (for estimation), is :
.. code-block:: julia
so_exp = load_from_obs("database/observations/TC_model_name/TC_observation_file_name.obs")
g = create_observation_function(eval(Meta.parse(get_observation_function(so_exp))))
We can then launch the simulation
This is another way to compute g, if observation data are imported (for estimation) and you want to make sure
that you have matching (.i.e same timeline and same observed variables) simulation data and observation data to be able to compare them.
.. code-block:: julia
so = simulate(f, g, x0, u, p; mn = mn, on = on)
OR the estimation algorithm
see cfg parameters in Adjustin : src/algorithms/estimation/TC_algo_estimation.jl
We can then launch the simulation
OR
.. code-block:: julia
cfg = ConfigurationTC_algo_estimation(...)
so = TC_algo_estimation(f, g, x0, u, p, so_exp, cfg; mn = mn, on = on,)
OR the sensitivity_analysis
see cfg parameters in Adjustin : src/algorithms/sensitivity_analysis/TC_algo_sensitivity_analysis.jl
the estimation algorithm
see cfg parameters in Adjustin : src/algorithms/estimation/TC_algo_estimation.jl
OR
.. code-block:: julia
cfg = ConfigurationTC_algo_sensitivity_analysis(...)
so = TC_algo_sensitivity_analysis(f, g, x0, u, p, cfg; mn = mn, on = on)
We can then explicitly save the results but by activating flag_plot or flag_write in the algorithme configuration, there is automtically saved results
the sensitivity_analysis
see cfg parameters in Adjustin : src/algorithms/sensitivity_analysis/TC_algo_sensitivity_analysis.jl
.. code-block:: julia
save_to_obs(TC_what_you_want_to_save, str_dir * "TC_what_you_want_to_save.obs")
We can then explicitly save the results but by activating flag_plot or flag_write in the algorithme configuration, there is automatically saved results
* model.jl template - located in Adjustin : src/models/model.jl
......
Search.setIndex({docnames:["index","src/developer_guide","src/installation_guide","src/user_guide"],envversion:{"sphinx.domains.c":2,"sphinx.domains.changeset":1,"sphinx.domains.citation":1,"sphinx.domains.cpp":3,"sphinx.domains.index":1,"sphinx.domains.javascript":2,"sphinx.domains.math":2,"sphinx.domains.python":3,"sphinx.domains.rst":2,"sphinx.domains.std":2,sphinx:56},filenames:["index.rst","src\\developer_guide.rst","src\\installation_guide.rst","src\\user_guide.rst"],objects:{},objnames:{},objtypes:{},terms:{"1":3,"2":3,"2009viaudg":[1,2],"3":2,"default":2,"do":[1,2,3],"final":[1,3],"import":[2,3],"int":3,"new":[1,3],"return":3,"true":3,"try":1,A:3,And:1,As:3,For:3,If:[1,2,3],In:[2,3],It:[1,2,3],OR:3,One:3,The:[0,1,2,3],Then:3,There:3,To:[0,3],__dir__:3,abc_pop_mc:3,abc_simpl:3,abc_smc:3,abc_subsim:3,abl:[2,3],abov:3,access:2,account:3,activ:[2,3],actual:3,ad:[1,2],add:[2,3],addit:3,adjustin:1,adjustin_path_databas:3,adjustin_path_result:3,adjustinappl:[2,3],adjustincor:[],after:3,afterward:1,again:1,algo_:3,all:3,allow:1,alpha:3,alreadi:[2,3],also:[2,3],alt:2,amwg:3,an:[2,3],analys:3,ani:[1,2],anoth:[2,3],anyth:3,applic:0,ar:[1,2,3],arabidopsi:3,argument:3,arrai:3,associ:2,atom:[1,2],attribut:3,automata:3,automaticali:2,automt:3,avoid:1,back:1,bash:[1,2],bayesian:3,becaus:[1,3],becom:3,befor:1,begin:3,being:3,belief:3,below:[2,3],best:3,beta:3,better:3,between:3,big:3,block:[],branch:[1,2],bug:3,c:2,call:3,can:[1,2,3],carlo:3,cd:2,centralesupelec:[1,2],cf:[2,3],cfg:3,chain:3,chang:[1,2,3],check:2,checkout:[1,2],choic:3,chose:2,client:2,clone:2,close:1,code:[2,3],come:3,command:[1,2],commit:1,compil:1,comput:[2,3],confid:3,configur:[2,3],configurationtc_algo_estim:3,configurationtc_algo_sensitivity_analysi:3,consid:3,contain:[0,1,3],continu:2,control:3,core:3,correct:2,could:1,cours:2,cpf:3,creat:[1,3],create_observation_funct:3,create_observer_funct:3,create_results_diretcori:3,ctrl:3,current:[2,3],data:3,databas:3,decrib:3,defin:3,degre:3,delet:3,depend:2,depositori:2,desir:3,det:3,determinist:3,dev:[1,2],develop:0,deviat:3,dictionari:3,differ:[2,3],directli:1,directori:[1,2],distribut:3,doesn:3,done:[1,2],download:[1,2],dure:2,e:[2,3],each:3,editor:[2,3],either:3,end:[1,2,3],enkf:3,enter:3,env:3,environ:[1,2,3],error:3,estim:[0,3],etc:3,eval:3,everi:3,everyth:[1,2,3],everytim:1,exactli:2,exampl:[0,2],exclud:3,execut:[2,3],exist:3,experiment:3,explicitli:3,extern:3,f:3,famili:3,faster:1,fetch:[1,2],few:[1,3],field:3,file:[1,2,3],filter:3,find:3,first:[2,3],fit:3,fix:3,flag_plot:3,flag_writ:3,folder:[0,1,3],follow:[2,3],form:3,fr:[1,2],free:1,frequenc:3,frequenti:3,frequentist:3,from:[2,3],g:3,galiota_branch:2,gener:3,get:1,get_observation_funct:3,git:[1,2],gitlab:[1,2],gl:3,gls_vector:3,go:[1,2,3],gr:2,greenlab:3,gsobol:3,handl:3,have:[2,3],helper:3,here:3,hidden:3,how:[0,3],howev:[1,2],http:[1,2],i:[2,3],imperfect:3,implement:[1,3],includ:2,incorpor:3,indic:[1,2,3],influenc:3,inform:3,input:3,input_output:3,insid:3,instal:1,installation_guid:0,instead:3,interpret:3,interv:3,ip:3,itselft:3,jl:3,julia:[0,1,2],julia_vers:[1,2],juno:2,just:[1,3],keep:3,kei:2,kf:3,kind:3,knowledg:3,known:3,label:3,labellist:3,last:[],later:3,launch:3,layout:2,let:[1,3],lign:3,like:[1,2,3],limit:3,line:[1,2,3],list:3,ll_det:3,ll_sto:3,lna:3,load:3,load_control:3,load_from_ob:3,load_local_model:3,load_model:3,load_paramet:3,load_stat:3,local:[1,2],locat:[2,3],lognorm:3,m:1,macro:3,mail:[],main:3,make:1,manual:3,markov:3,master:2,math:3,mcmc:3,mcmc_abc:3,mcmc_simplifi:3,mean:3,measur:3,memori:3,messag:1,meta:3,method:3,mic:2,might:2,mn:3,mn_:3,model:0,modelis:3,modellingnois:3,modifi:1,mont:3,more:[1,3],multiindex:3,multipl:[2,3],must:[2,3],mutabl:3,n:3,name:[1,3],natur:3,nbr_arg:3,necessari:3,need:[1,2,3],next:[2,3],nois:3,noisi:3,normal:3,notat:3,note:[2,3],noth:3,now:[1,2,3],number:3,o:3,ob:3,object:3,obs_tc_field_name_observ:3,obs_tc_field_name_observed1:3,obs_tc_field_name_observed2:3,observ:3,observation_funct:3,observation_nois:3,observationnois:3,observationtuplelist:3,observermodel:3,ofl:3,ol:3,om1:3,om2:3,om3:3,om:3,oml:3,on_:3,onc:3,one:[2,3],ones:3,onli:[1,3],open:[1,2,3],option:[2,3],optionn:3,order:3,organis:0,origin:[1,2],other:3,otherwis:3,otll:3,our:3,own:3,p:3,packag:[0,1,2,3],parallel_abc:3,paramet:[0,3],pars:3,part:3,particl:3,pass:3,past:2,path:2,path_to_adjustin:2,path_to_julia:2,phenomenon:3,pkg:[1,2],plot:3,pmmh:3,possibl:[1,3],preexist:3,press:[2,3],previou:1,print:3,prior:3,probability_density_funct:3,probabl:3,problem:2,process:3,project:[1,2],properli:2,push:1,put:3,pygmalion:3,quickli:1,random:3,readm:3,recognis:1,recov:[2,3],rememb:2,repl:2,replac:1,repositori:0,repres:3,research:[1,2],result:3,retriev:3,revis:1,right:1,rn:3,root:1,s:[1,2,3],same:[1,2,3],sampl:3,save:3,save_to_ob:3,saw:3,section:[1,3],see:[1,2,3],seen:[1,3],select:3,sens:3,sensitivity_analysi:[0,3],sequenti:3,set:[2,3],should:[2,3],simpli:1,simul:[0,3],sir:3,slightli:2,smc:3,smc_abc:3,smoothli:1,so:[1,2,3],so_:3,so_exp:3,sobol:3,sobol_gl:3,specif:[2,3],src:3,stand:3,standard:3,start:3,state:3,statist:3,statu:2,step:[1,2,3],sto:3,stochast:3,store:[2,3],str_c:3,str_d:3,str_dir:3,str_m:3,str_p:3,str_x:3,string:3,struct:3,studi:3,system:3,system_observ:3,systemobserv:3,t1:3,t2:3,t:[1,3],take:3,tc_:3,tc_algo_estim:3,tc_algo_sensitivity_analysi:3,tc_controle_file_nam:3,tc_field_name_det:3,tc_field_name_observ:3,tc_field_name_observed1:3,tc_field_name_observed2:3,tc_field_name_sto:3,tc_fieldc1:3,tc_fieldc2:3,tc_fieldm1:3,tc_fieldm2:3,tc_fieldp1:3,tc_fieldp2:3,tc_fields1:3,tc_int:3,tc_int_param_noise_1:3,tc_int_param_noise_2:3,tc_kind:3,tc_model_nam:3,tc_model_name_vers:3,tc_observation_file_nam:3,tc_parameters_file_nam:3,tc_results_part_of_file_nam:3,tc_state_file_nam:3,tc_string_kind:3,tc_type_field_name_observ:3,tc_type_field_name_sto:3,tc_type_fieldc1:3,tc_type_fieldc2:3,tc_type_fieldm1:3,tc_type_fieldm2:3,tc_type_fieldp1:3,tc_type_fieldp2:3,tc_type_fields1:3,tc_what_you_want_to_sav:3,term:3,termin:2,than:3,thank:3,thei:[2,3],them:[2,3],theta:3,theta_:3,thi:[0,1,2,3],those:3,thrown:3,thu:[2,3],time:[2,3],timelin:3,timestep:3,tip:1,titl:3,tmax:3,tml:3,tn:3,toml:2,transit:3,tupl:3,two:3,type:3,u:3,u_:3,uber:2,ui:2,ukf:3,uniform:3,until:1,up:[1,2],us:[0,1,3],user:2,usual:3,v1:2,valu:3,variabl:3,variou:3,vector:3,version:2,vl:3,wa:2,wai:3,want:[1,2,3],we:3,were:[1,3],what:[2,3],when:[1,2,3],where:[2,3],which:[0,2,3],whole:[1,3],witch:3,wl:3,word:3,work:[1,2],workaround:1,would:2,writ:2,write:[2,3],x0:3,x:3,x_:3,x_t1_om1:3,x_t1_om2:3,x_t1_om3:3,x_t2_om1:3,x_t2_om2:3,x_t2_om3:3,x_tn_om1:3,x_tn_om2:3,x_tn_om3:3,xn:3,xnplus1:3,y:3,y_:3,you:[1,2,3],your:[1,2],your_app_her:3,your_branch_nam:1,your_model:3},titles:["Welcome to Adjustin\u2019s documentation!","Developper guide","Installation guide","User guide"],titleterms:{"function":3,"try":3,ad:3,add:1,adjustin:[0,2,3],algorithm:[1,3],applic:[2,3],detail:3,develop:2,developp:[0,1],document:0,exampl:3,framework:3,fucntion:1,guid:[0,1,2,3],instal:[0,2],mathemat:3,model:[1,3],nois:1,onli:2,out:3,probabl:1,s:0,simul:1,structur:3,templat:3,test:3,understand:3,us:2,user:[0,3],welcom:0,work:3,workflow:1,your:3}})
\ No newline at end of file
Search.setIndex({docnames:["index","src/developer_guide","src/installation_guide","src/user_guide"],envversion:{"sphinx.domains.c":2,"sphinx.domains.changeset":1,"sphinx.domains.citation":1,"sphinx.domains.cpp":3,"sphinx.domains.index":1,"sphinx.domains.javascript":2,"sphinx.domains.math":2,"sphinx.domains.python":3,"sphinx.domains.rst":2,"sphinx.domains.std":2,sphinx:56},filenames:["index.rst","src\\developer_guide.rst","src\\installation_guide.rst","src\\user_guide.rst"],objects:{},objnames:{},objtypes:{},terms:{"1":3,"2":3,"2009viaudg":[1,2],"3":2,"default":2,"do":[1,2,3],"final":[1,3],"import":[2,3],"int":3,"new":[1,3],"return":3,"true":3,"try":1,A:3,And:1,As:3,But:3,For:3,If:[1,2,3],In:[2,3],It:[1,2,3],OR:3,One:3,The:[0,1,2,3],Then:3,There:3,To:[0,3],__dir__:3,abc_pop_mc:3,abc_simpl:3,abc_smc:3,abc_subsim:3,abl:[2,3],abov:3,access:2,account:3,activ:[2,3],actual:3,ad:[1,2],add:[2,3],addit:3,adjustin:1,adjustin_path_databas:3,adjustin_path_result:3,adjustinappl:[2,3],adjustincor:[],after:3,afterward:1,again:1,algo:3,algo_:3,all:3,allow:1,alpha:3,alreadi:2,also:[2,3],alt:2,amwg:3,an:[2,3],analys:3,ani:[1,2],anoth:[2,3],anyth:[],applic:0,appropri:3,ar:[1,2,3],arabidopsi:3,argument:3,arrai:3,associ:2,atom:[1,2],attribut:3,automat:3,automata:3,automaticali:2,automt:[],avoid:1,back:1,bash:[1,2],bayesian:3,becaus:[1,3],becom:3,befor:1,begin:3,being:3,belief:3,below:[2,3],best:3,beta:3,better:3,between:3,big:3,block:[],branch:[1,2],bug:3,c:2,call:3,can:[1,2,3],care:3,carlo:3,cd:2,centralesupelec:[1,2],cf:[2,3],cfg:3,chain:3,chang:[1,2,3],check:2,checkout:[1,2],choic:3,chose:2,cleaner:3,client:2,clone:2,close:1,code:[2,3],come:3,command:[1,2],commit:1,compar:3,compil:1,comput:[2,3],confid:3,configur:[2,3],configurationtc_algo_estim:3,configurationtc_algo_sensitivity_analysi:3,consid:3,contain:[0,1,3],continu:2,control:3,core:3,correct:[2,3],could:[1,3],cours:2,cpf:3,creat:[1,3],create_observation_funct:3,create_observer_funct:3,create_results_diretcori:3,ctrl:3,current:[2,3],data:3,databas:3,declar:3,decrib:3,defin:3,degre:3,delet:3,depend:2,depositori:2,desir:3,det:3,determinist:3,dev:[1,2],develop:0,deviat:3,dictionari:3,differ:[2,3],directli:[1,3],directori:[1,2],distribut:3,doesn:[],done:[1,2],download:[1,2],dure:2,e:[2,3],each:3,editor:[2,3],either:3,end:[1,2,3],enkf:3,enter:3,env:3,environ:[1,2,3],error:3,estim:[0,3],etc:3,eval:3,everi:3,everyth:[1,2,3],everytim:1,exactli:2,exampl:[0,2],exclud:3,execut:[2,3],exist:[],experiment:3,explicitli:3,extern:3,f:3,famili:3,faster:1,fetch:[1,2],few:[1,3],field:3,file:[1,2,3],filter:3,find:3,first:[2,3],fit:3,fix:3,flag_plot:3,flag_writ:3,folder:[0,1,3],follow:[2,3],form:3,fr:[1,2],free:1,frequenc:3,frequenti:3,frequentist:3,from:[2,3],g:3,galiota_branch:2,gener:3,get:1,get_observation_funct:3,git:[1,2],gitlab:[1,2],gl:3,gls_vector:3,go:[1,2,3],gr:2,greenlab:3,gsobol:3,handl:3,have:[2,3],helper:3,here:3,hidden:3,how:[0,3],howev:[1,2,3],http:[1,2],i:[2,3],imagin:3,imperfect:3,implement:[1,3],includ:2,incorpor:3,inde:3,indic:[1,2,3],influenc:3,inform:3,input:3,input_output:3,insid:3,instal:1,installation_guid:0,instead:3,interpret:3,interv:3,ip:3,itselft:3,jl:3,julia:[0,1,2],julia_vers:[1,2],juno:2,just:[1,3],keep:3,kei:2,kf:3,kind:3,knowledg:3,known:3,label:3,labellist:3,last:[],later:3,launch:3,layout:2,let:[1,3],life:3,lign:3,like:[1,2,3],limit:3,line:[1,2,3],list:3,ll_det:3,ll_sto:3,lna:3,load:3,load_:3,load_configur:3,load_control:3,load_from_ob:3,load_local_model:3,load_model:3,load_paramet:3,load_stat:3,local:[1,2,3],locat:[2,3],lognorm:3,look:3,m:1,macro:3,mail:[],main:3,make:[1,3],manual:[],markov:3,master:2,match:3,math:3,mcmc:3,mcmc_abc:3,mcmc_simplifi:3,mean:3,measur:3,memori:3,messag:1,meta:3,method:3,mic:2,might:2,mn:3,mn_:3,model:0,modelis:3,modellingnois:3,modifi:1,mont:3,more:[1,3],multiindex:3,multipl:[2,3],must:[2,3],mutabl:3,n:3,name:[1,3],natur:3,nbr_arg:3,necessari:3,need:[1,2,3],next:[2,3],nois:3,noisi:3,normal:3,notat:3,note:[2,3],noth:3,now:[1,2,3],number:3,o:3,ob:3,object:3,obs_tc_field_name_observ:3,obs_tc_field_name_observed1:3,obs_tc_field_name_observed2:3,observ:3,observation_funct:3,observation_nois:3,observationnois:3,observationtuplelist:3,observermodel:3,ofl:3,ol:3,om1:3,om2:3,om3:3,om:3,oml:3,on_:3,onc:3,one:[2,3],ones:3,onli:[1,3],open:[1,2,3],option:[2,3],optionn:3,order:3,organis:0,origin:[1,2],other:3,otherwis:3,otll:3,our:3,own:3,p:3,packag:[0,1,2,3],parallel_abc:3,paramet:[0,3],pars:3,part:3,particl:3,pass:3,past:2,path:2,path_to_adjustin:2,path_to_julia:2,phenomenon:3,pkg:[1,2],plot:3,pmmh:3,possibl:[1,3],precod:3,preexist:3,press:[2,3],previou:1,print:3,prior:3,probability_density_funct:3,probabl:3,problem:2,process:3,project:[1,2],properli:2,push:1,put:3,pygmalion:3,quickli:1,random:3,readm:3,real:3,recognis:1,recov:[2,3],rememb:2,repl:2,replac:1,repositori:[0,3],repres:3,research:[1,2],result:3,retriev:3,revis:1,right:1,rn:3,root:1,run:3,s:[1,2,3],same:[1,2,3],sampl:3,save:3,save_to_ob:3,saw:3,section:[1,3],see:[1,2,3],seen:[1,3],select:3,sens:3,sensitivity_analysi:[0,3],sequenti:3,set:[2,3],should:[2,3],simpli:1,simul:[0,3],singl:3,sir:3,slightli:2,smc:3,smc_abc:3,smoothli:1,so:[1,2,3],so_:3,so_exp:3,sobol:3,sobol_gl:3,specif:[2,3],src:3,stand:3,standard:3,start:3,state:3,statist:3,statu:2,step:[1,2,3],sto:3,stochast:3,store:[2,3],str_c:3,str_cfg:3,str_d:3,str_dir:3,str_m:3,str_p:3,str_x:3,string:3,struct:3,studi:3,sure:3,system:3,system_observ:3,systemobserv:3,t1:3,t2:3,t:[1,3],take:3,tc_:3,tc_algo_estim:3,tc_algo_sensitivity_analysi:3,tc_configuration_file_nam:3,tc_controle_file_nam:3,tc_field_name_det:3,tc_field_name_observ:3,tc_field_name_observed1:3,tc_field_name_observed2:3,tc_field_name_sto:3,tc_fieldc1:3,tc_fieldc2:3,tc_fieldm1:3,tc_fieldm2:3,tc_fieldp1:3,tc_fieldp2:3,tc_fields1:3,tc_int:3,tc_int_param_noise_1:3,tc_int_param_noise_2:3,tc_kind:3,tc_model_nam:3,tc_model_name_vers:[],tc_observation_file_nam:3,tc_parameters_file_nam:3,tc_results_part_of_file_nam:3,tc_state_file_nam:3,tc_string_kind:3,tc_type_field_name_observ:3,tc_type_field_name_sto:3,tc_type_fieldc1:3,tc_type_fieldc2:3,tc_type_fieldm1:3,tc_type_fieldm2:3,tc_type_fieldp1:3,tc_type_fieldp2:3,tc_type_fields1:3,tc_what_you_want_to_sav:3,term:3,termin:2,than:3,thank:3,thei:[2,3],them:[2,3],theta:3,theta_:3,thi:[0,1,2,3],those:3,thrown:3,thu:[2,3],time:[2,3],timelin:3,timestep:3,tip:1,titl:3,tmax:3,tml:3,tn:3,toml:2,transit:3,tupl:3,two:3,type:3,u:3,u_:3,uber:2,ui:2,ukf:3,unabl:3,uniform:3,until:1,up:[1,2],us:[0,1,3],user:2,usual:3,v1:2,valu:3,variabl:3,variou:3,vector:3,version:2,vl:3,wa:2,wai:3,want:[1,2,3],we:3,were:[1,3],what:[2,3],when:[1,2,3],where:[2,3],which:[0,2,3],whole:[1,3],witch:3,wl:3,word:3,work:[1,2],workaround:1,would:2,writ:2,write:[2,3],x0:3,x:3,x_:3,x_t1_om1:3,x_t1_om2:3,x_t1_om3:3,x_t2_om1:3,x_t2_om2:3,x_t2_om3:3,x_tn_om1:3,x_tn_om2:3,x_tn_om3:3,xn:3,xnplus1:3,y:3,y_:3,you:[1,2,3],your:[1,2],your_app_her:3,your_branch_nam:1,your_model:3},titles:["Welcome to Adjustin\u2019s documentation!","Developper guide","Installation guide","User guide"],titleterms:{"function":3,"try":3,ad:3,add:1,adjustin:[0,2,3],algorithm:[1,3],applic:[2,3],detail:3,develop:2,developp:[0,1],document:0,exampl:3,framework:3,fucntion:1,guid:[0,1,2,3],instal:[0,2],mathemat:3,model:[1,3],nois:1,onli:2,out:3,probabl:1,s:0,simul:1,structur:3,templat:3,test:3,understand:3,us:2,user:[0,3],welcom:0,work:3,workflow:1,your:3}})
\ No newline at end of file
......@@ -250,7 +250,11 @@ y_{n} &amp;= g(x_{n}, \theta_{n}, on_{n})"/></p>
<p>The objective is to understand statistical systems thanks to the estimation of model parameters using experimental data.
We want to create a model which modelised the best way possible what we want to study in order to analyse it.
In other terms the objective is to find f, <img class="math" src="../_images/math/8a87f04e7d7cca18343c084cceca5237fae62491.png" alt="\theta"/>, mn, on, so that the experimental observations fit the best way possible y for each time step.
Note that x can either be hidden state variables or observed data. y is thus x filtered in order to keep only the state variable that were actually measured experimentally (which exclude the hidden state variables)</p>
Note that x can either be hidden state variables or observed data.
y is x filtered in order to keep only the state variable that were actually measured experimentally (which exclude the hidden state variables)
For example, imagine you run a simulation, it will compute every variable of the vector x at each time step.
But what you observed in real life will only be on specific variable at specific time.
The function g will thus filter x to keep only the observed variable of vector x.</p>
</div>
<div class="section" id="adjustin-structures-functions">
<h3>Adjustin structures &amp; functions<a class="headerlink" href="#adjustin-structures-functions" title="Permalink to this headline"></a></h3>
......@@ -328,35 +332,56 @@ For example “TC_model_name” can become “greenlab-arabidopsis”</p>
<span class="k">using</span> <span class="n">Adjustin</span>
</pre></div>
</div>
<p>str_m must be the same name as folder database/control/TC_model_name and database/observations/TC_model_name
and database/parameters/TC_model_name and database/state/TC_model_name. Add folder TC_model_name manually if it doesn’t already exist.
If you are using a preexisting package in Adjustin it must also be the same name, as the file in the package Adjustin located at src/models/TC_model_name.jl.
If you are writing a new model it must be the same name as the file in Adjustin application at location database/models/TC_model_name/TC_model_name_version.jl</p>
<div class="highlight-julia notranslate"><div class="highlight"><pre><span></span><span class="n">str_m</span> <span class="o">=</span> <span class="s">&quot;TC_model_name&quot;</span>
</pre></div>
</div>
<p>str_c must be the same as file located in database/control/TC_model_name/TC_controle_file_name.jl</p>
<p>str_x must be the same as file located in database/state/TC_model_name/TC_state_file_name.jl</p>
<p>str_p must be the same as file located in database/parameters/TC_model_name/TC_parameters_file_name.jl</p>
<p>str_d can be anything</p>
<div class="highlight-julia notranslate"><div class="highlight"><pre><span></span><span class="n">str_c</span> <span class="o">=</span> <span class="s">&quot;TC_controle_file_name&quot;</span>
<span class="n">str_c</span> <span class="o">=</span> <span class="s">&quot;TC_controle_file_name&quot;</span>
<span class="n">str_x</span> <span class="o">=</span> <span class="s">&quot;TC_state_file_name&quot;</span>
<span class="n">str_p</span> <span class="o">=</span> <span class="s">&quot;TC_parameters_file_name&quot;</span>
<span class="n">str_d</span> <span class="o">=</span> <span class="s">&quot;TC_results_part_of_file_name&quot;</span>
<span class="n">str_cfg</span> <span class="o">=</span> <span class="s">&quot;TC_configuration_file_name&quot;</span>
<span class="n">str_d</span> <span class="o">=</span> <span class="s">&quot;TC_results_part_of_file_name&quot;</span>
<span class="n">str_dir</span> <span class="o">=</span> <span class="n">create_results_direTCory</span><span class="p">(;</span> <span class="n">title</span> <span class="o">=</span> <span class="n">str_d</span><span class="p">)</span>
<span class="n">load_local_model</span><span class="p">(</span><span class="n">str_m</span><span class="p">)</span> <span class="c">#use load_model(str_m) instead if you are using a preexistant model defined in Adjustin package</span>
<span class="n">load_state</span><span class="p">(</span><span class="n">str_m</span><span class="p">,</span> <span class="n">str_x</span><span class="p">)</span>
<span class="n">load_control</span><span class="p">(</span><span class="n">str_m</span><span class="p">,</span> <span class="n">str_c</span><span class="p">)</span>
<span class="n">load_parameters</span><span class="p">(</span><span class="n">str_m</span><span class="p">,</span> <span class="n">str_p</span><span class="p">)</span>
<span class="n">load_configuration</span><span class="p">(</span><span class="s">&quot;algo*&quot;</span><span class="p">,</span><span class="n">str_m</span><span class="p">,</span> <span class="n">str_cfg</span><span class="p">)</span> <span class="c"># for example load_configuration(&quot;gls&quot;,str_m, str_cfg)</span>
</pre></div>
</div>
<p>If you are using the functions load_*, which unable to have a cleaner code and not everything in a single file
(you could also not use the functions load_* and declare directly your parameters, states, controls and configurations directly in your main file)
then you must be careful of the names put as input of those functions.
Indeed the functions load* will look for the input name in a specific location. You must make sure these are correct (see below).
Note that you will have to create those files in the appropriate location.
Note also that in the example above we loaded a local model which is in the Adjustinapplication repository, in the database (see below).
However if you are using a preexisting model in Adjustin (Adjustin comes with a set of precoded model),
the model file will be in the Adjustin package (not adjustinapplications) located at src/models/TC_model_name.jl.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">database</span>
<span class="o">|</span><span class="n">configuration</span>
<span class="o">|</span><span class="n">estimation</span>
<span class="o">|</span><span class="n">algo</span><span class="o">*</span>
<span class="o">|</span><span class="n">TC_model_name</span>
<span class="n">TC_configuration_file_name</span>
<span class="o">|</span><span class="n">sensitivity_analysis</span>
<span class="o">|</span><span class="n">algo</span><span class="o">*</span>
<span class="o">|</span><span class="n">TC_model_name</span>
<span class="n">TC_configuration_file_name</span>
<span class="o">|</span><span class="n">control</span>
<span class="o">|</span><span class="n">TC_model_name</span>
<span class="n">TC_controle_file_name</span><span class="o">.</span><span class="n">jl</span>
<span class="o">|</span><span class="n">observations</span>
<span class="o">|</span><span class="n">TC_model_name</span>
<span class="o">|</span><span class="n">parameters</span>
<span class="o">|</span><span class="n">TC_model_name</span>
<span class="n">TC_parameters_file_name</span><span class="o">.</span><span class="n">jl</span>
<span class="o">|</span><span class="n">state</span>
<span class="o">|</span><span class="n">TC_model_name</span>
<span class="n">TC_state_file_name</span><span class="o">.</span><span class="n">jl</span>
<span class="o">|</span><span class="n">models</span>
<span class="o">|</span><span class="n">TC_model_name</span> <span class="c1">#if you add your own model and not use a preexisting one in adjustin</span>
</pre></div>
</div>
<p>The observation noise, on, is optionnal
TC_field_name_observed must be the same as one of the field in the struct ObservationNoise in Adjustin:src/models/TC_model_name.jl
which is also the same as one of the field in the struct State in Adjustin:src/models/TC_model_name.jl</p>
<p>obs in the beginning of obs_TC_field_name_observed must be there.</p>
<p>TC_kind can be : additive-normal/multiplicative-normal/multiplicative-lognormal/additive-uniform/multiplicative-uniform</p>
<p>How TC_int_param_noise_1 and 2 are used is detailed in Adjustin src/core/noise.jl in function noise!()</p>
<div class="highlight-julia notranslate"><div class="highlight"><pre><span></span><span class="n">on</span> <span class="o">=</span> <span class="n">ObservationNoise</span><span class="p">(</span><span class="n">Noise</span><span class="p">(</span>
<span class="p">[</span><span class="s">&quot;TC_field_name_observed&quot;</span><span class="p">],</span>
<span class="p">[</span><span class="s">&quot;obs_TC_field_name_observed&quot;</span><span class="p">],</span>
......@@ -365,10 +390,12 @@ which is also the same as one of the field in the struct State in Adjustin:src/m
<span class="p">))</span>
</pre></div>
</div>
<p>The modelling noise mn is optionnal
TC_field_name_det (det for deterministic) must be the same as one of the field in the struct State in Adjustin:src/models/TC_model_name.jl
TC_field_name_sto (sto for stochastic) must be the same as one of the field in the struct State in Adjustin:src/models/TC_model_name.jl
)</p>
<p>The observation noise, on, is optionnal
TC_field_name_observed must be the same as one of the field in the struct ObservationNoise in Adjustin:src/models/TC_model_name.jl
which is also the same as one of the field in the struct State in Adjustin:src/models/TC_model_name.jl</p>
<p>obs in the beginning of obs_TC_field_name_observed must be there.</p>
<p>TC_kind can be : additive-normal/multiplicative-normal/multiplicative-lognormal/additive-uniform/multiplicative-uniform</p>
<p>How TC_int_param_noise_1 and 2 are used is detailed in Adjustin src/core/noise.jl in function noise!()</p>
<div class="highlight-julia notranslate"><div class="highlight"><pre><span></span><span class="n">mn</span> <span class="o">=</span> <span class="n">ModellingNoise</span><span class="p">(</span><span class="n">Noise</span><span class="p">(</span>
<span class="p">[</span><span class="s">&quot;TC_field_name_det&quot;</span><span class="p">],</span>
<span class="p">[</span><span class="s">&quot;TC_field_name_sto&quot;</span><span class="p">],</span>
......@@ -376,42 +403,49 @@ TC_field_name_sto (sto for stochastic) must be the same as one of the field in t
<span class="p">(</span><span class="n">TC_int_param_noise_1</span><span class="p">,</span> <span class="n">TC_int_param_noise_1</span><span class="p">)),</span>
</pre></div>
</div>
<p>g will be a list of Observer. ‘rn’
As seen above, an observer is a structure containing the name of the object we want to observe (usually fields in state and/or observation noise), a function to retrieve the value of this object, the timeline on witch we are observing it, and the number of arguments that the function needs.
<cite>all</cite> (see below) is optional
it is added (usually more in simulations than estimations) if you want to observed all fields in the state
and not only the stochastic ones</p>
<p>The modelling noise mn is optionnal
TC_field_name_det (det for deterministic) must be the same as one of the field in the struct State in Adjustin:src/models/TC_model_name.jl
TC_field_name_sto (sto for stochastic) must be the same as one of the field in the struct State in Adjustin:src/models/TC_model_name.jl
)</p>
<div class="highlight-julia notranslate"><div class="highlight"><pre><span></span><span class="n">tmax</span> <span class="o">=</span> <span class="n">TC_int</span>
<span class="n">tml</span> <span class="o">=</span> <span class="mi">1</span><span class="o">:</span><span class="n">tmax</span>
<span class="n">g</span> <span class="o">=</span> <span class="n">create_observation_function</span><span class="p">([</span><span class="n">ObserverModel</span><span class="p">(</span><span class="s">&quot;all,obs_TC_field_name_observed&quot;</span><span class="p">,</span> <span class="n">tml</span><span class="p">)])</span>
</pre></div>
</div>
<p>OR
another way to compute g, if observation data are imported (for estimation), is :</p>
<p>g will be a list of Observer. ‘rn’
As seen above, an observer is a structure containing the name of the object we want to observe (usually fields in state and/or observation noise), a function to retrieve the value of this object, the timeline on witch we are observing it, and the number of arguments that the function needs.
<cite>all</cite> (see above) is optional
it is added (usually more in simulations than estimations) if you want to observed all fields in the state
and not only the stochastic (i.e observed) ones</p>
<p>OR</p>
<div class="highlight-julia notranslate"><div class="highlight"><pre><span></span><span class="n">so_exp</span> <span class="o">=</span> <span class="n">load_from_obs</span><span class="p">(</span><span class="s">&quot;database/observations/TC_model_name/TC_observation_file_name.obs&quot;</span><span class="p">)</span>
<span class="n">g</span> <span class="o">=</span> <span class="n">create_observation_function</span><span class="p">(</span><span class="n">eval</span><span class="p">(</span><span class="n">Meta</span><span class="o">.</span><span class="n">parse</span><span class="p">(</span><span class="n">get_observation_function</span><span class="p">(</span><span class="n">so_exp</span><span class="p">))))</span>
</pre></div>
</div>
<p>We can then launch the simulation</p>
<p>This is another way to compute g, if observation data are imported (for estimation) and you want to make sure
that you have matching (.i.e same timeline and same observed variables) simulation data and observation data to be able to compare them.</p>
<div class="highlight-julia notranslate"><div class="highlight"><pre><span></span><span class="n">so</span> <span class="o">=</span> <span class="n">simulate</span><span class="p">(</span><span class="n">f</span><span class="p">,</span> <span class="n">g</span><span class="p">,</span> <span class="n">x0</span><span class="p">,</span> <span class="n">u</span><span class="p">,</span> <span class="n">p</span><span class="p">;</span> <span class="n">mn</span> <span class="o">=</span> <span class="n">mn</span><span class="p">,</span> <span class="n">on</span> <span class="o">=</span> <span class="n">on</span><span class="p">)</span>
</pre></div>
</div>
<p>OR the estimation algorithm
see cfg parameters in Adjustin : src/algorithms/estimation/TC_algo_estimation.jl</p>
<p>We can then launch the simulation</p>
<p>OR</p>
<div class="highlight-julia notranslate"><div class="highlight"><pre><span></span><span class="n">cfg</span> <span class="o">=</span> <span class="n">ConfigurationTC_algo_estimation</span><span class="p">(</span><span class="o">...</span><span class="p">)</span>
<span class="n">so</span> <span class="o">=</span> <span class="n">TC_algo_estimation</span><span class="p">(</span><span class="n">f</span><span class="p">,</span> <span class="n">g</span><span class="p">,</span> <span class="n">x0</span><span class="p">,</span> <span class="n">u</span><span class="p">,</span> <span class="n">p</span><span class="p">,</span> <span class="n">so_exp</span><span class="p">,</span> <span class="n">cfg</span><span class="p">;</span> <span class="n">mn</span> <span class="o">=</span> <span class="n">mn</span><span class="p">,</span> <span class="n">on</span> <span class="o">=</span> <span class="n">on</span><span class="p">,)</span>
</pre></div>
</div>
<p>OR the sensitivity_analysis
see cfg parameters in Adjustin : src/algorithms/sensitivity_analysis/TC_algo_sensitivity_analysis.jl</p>
<p>the estimation algorithm
see cfg parameters in Adjustin : src/algorithms/estimation/TC_algo_estimation.jl</p>
<p>OR</p>
<div class="highlight-julia notranslate"><div class="highlight"><pre><span></span><span class="n">cfg</span> <span class="o">=</span> <span class="n">ConfigurationTC_algo_sensitivity_analysis</span><span class="p">(</span><span class="o">...</span><span class="p">)</span>
<span class="n">so</span> <span class="o">=</span> <span class="n">TC_algo_sensitivity_analysis</span><span class="p">(</span><span class="n">f</span><span class="p">,</span> <span class="n">g</span><span class="p">,</span> <span class="n">x0</span><span class="p">,</span> <span class="n">u</span><span class="p">,</span> <span class="n">p</span><span class="p">,</span> <span class="n">cfg</span><span class="p">;</span> <span class="n">mn</span> <span class="o">=</span> <span class="n">mn</span><span class="p">,</span> <span class="n">on</span> <span class="o">=</span> <span class="n">on</span><span class="p">)</span>
</pre></div>
</div>
<p>We can then explicitly save the results but by activating flag_plot or flag_write in the algorithme configuration, there is automtically saved results</p>
<p>the sensitivity_analysis
see cfg parameters in Adjustin : src/algorithms/sensitivity_analysis/TC_algo_sensitivity_analysis.jl</p>
<div class="highlight-julia notranslate"><div class="highlight"><pre><span></span><span class="n">save_to_obs</span><span class="p">(</span><span class="n">TC_what_you_want_to_save</span><span class="p">,</span> <span class="n">str_dir</span> <span class="o">*</span> <span class="s">&quot;TC_what_you_want_to_save.obs&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>We can then explicitly save the results but by activating flag_plot or flag_write in the algorithme configuration, there is automatically saved results</p>
<ul class="simple">
<li><p>model.jl template - located in Adjustin : src/models/model.jl</p></li>
</ul>
......
Markdown is supported
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