Deploy preview for PR 654

Author: penelopeysm

pr-previews/654/search.json

@@ -1146,7 +1146,7 @@
     "href": "usage/sampling-options/index.html#specifying-initial-parameters",
     "title": "MCMC Sampling Options",
     "section": "Specifying initial parameters",
-    "text": "Specifying initial parameters\nIn Turing.jl, initial parameters for MCMC sampling can be specified using the initial_params keyword argument.\nFor single-chain sampling, the AbstractMCMC interface generally expects that you provide a completely flattened vector of parameters.\n\nchn = sample(demo_model(), MH(), 5; initial_params=[1.0, -5.0])\nchn[:x][1], chn[:y][1]\n\n(1.0, -5.0)\n\n\n\n\n\n\n\n\nNote\n\n\n\nNote that a number of samplers use warm-up steps by default (see the Thinning and Warmup section below), so chn[:param][1] may not correspond to the exact initial parameters you provided. MH() does not do this, which is why we use it here.\n\n\nNote that for Turing models, the use of Vector can be extremely error-prone as the order of parameters in the flattened vector is not always obvious (especially if there are parameters with non-trivial types). In general, parameters should be provided in the order they are defined in the model. A relatively ‘safe’ way of obtaining parameters in the correct order is to first generate a VarInfo, and then linearise that:\n\nusing DynamicPPL\nvi = VarInfo(demo_model())\ninitial_params = vi[:]\n\n2-element Vector{Float64}:\n -0.3483855030130556\n -0.5612681142085717\n\n\nTo avoid this situation, you can also use NamedTuple to specify initial parameters.\n\nchn = sample(demo_model(), MH(), 5; initial_params=(y=2.0, x=-6.0))\nchn[:x][1], chn[:y][1]\n\n(-6.0, 2.0)\n\n\nThis works even for parameters with more complex types.\n\n@model function demo_complex()\n    x ~ LKJCholesky(3, 0.5)\n    y ~ MvNormal(zeros(3), I)\nend\ninit_x, init_y = rand(LKJCholesky(3, 0.5)), rand(MvNormal(zeros(3), I))\nchn = sample(demo_complex(), MH(), 5; initial_params=(x=init_x, y=init_y));\n\nFor multiple-chain sampling, the initial_params keyword argument should be a vector with length equal to the number of chains being sampled. Each element of this vector should be the initial parameters for the corresponding chain, as described above. Thus, for example, a vector of vectors, or a vector of NamedTuples, can be used. If you want to use the same initial parameters for all chains, you can use fill:\n\ninitial_params = fill((x=1.0, y=-5.0), 3)\nchn = sample(demo_model(), MH(), MCMCThreads(), 5, 3; initial_params=initial_params)\nchn[:x][1,:], chn[:y][1,:]\n\n\n┌ Warning: Only a single thread available: MCMC chains are not sampled in parallel\n└ @ AbstractMCMC ~/.julia/packages/AbstractMCMC/nQLlh/src/sample.jl:410\n\n\n\n\n([1.0, 1.0, 1.0], [-5.0, -5.0, -5.0])\n\n\n\n\n\n\n\n\nImportantUpcoming changes in Turing v0.41\n\n\n\nIn Turing v0.41, instead of providing initial parameters, users will have to provide what is conceptually an initialisation strategy. The keyword argument is still initial_params, but the permitted values will either be:\n\nInitFromPrior(): generate initial parameters by sampling from the prior\nInitFromUniform(lower, upper): generate initial parameters by sampling uniformly from the given bounds in linked space\nInitFromParams(namedtuple_or_dict): use the provided initial parameters, supplied either as a NamedTuple or a Dict{<:VarName}\n\nInitialisation with Vector will be fully removed due to its inherent ambiguity. Initialisation with a raw NamedTuple will still be supported (it will simply be wrapped in InitFromParams()); but we expect to remove this eventually, so it will be more future-proof to use InitFromParams() directly.",
+    "text": "Specifying initial parameters\nIn Turing.jl, initial parameters for MCMC sampling can be specified using the initial_params keyword argument.\nFor single-chain sampling, the AbstractMCMC interface generally expects that you provide a completely flattened vector of parameters.\n\nchn = sample(demo_model(), MH(), 5; initial_params=[1.0, -5.0])\nchn[:x][1], chn[:y][1]\n\n(1.0, -5.0)\n\n\n\n\n\n\n\n\nNote\n\n\n\nNote that a number of samplers use warm-up steps by default (see the Thinning and Warmup section below), so chn[:param][1] may not correspond to the exact initial parameters you provided. MH() does not do this, which is why we use it here.\n\n\nNote that for Turing models, the use of Vector can be extremely error-prone as the order of parameters in the flattened vector is not always obvious (especially if there are parameters with non-trivial types). In general, parameters should be provided in the order they are defined in the model. A relatively ‘safe’ way of obtaining parameters in the correct order is to first generate a VarInfo, and then linearise that:\n\nusing DynamicPPL\nvi = VarInfo(demo_model())\ninitial_params = vi[:]\n\n2-element Vector{Float64}:\n -0.3483855030130556\n -0.5612681142085717\n\n\nTo avoid this situation, you can also use NamedTuple to specify initial parameters.\n\nchn = sample(demo_model(), MH(), 5; initial_params=(y=2.0, x=-6.0))\nchn[:x][1], chn[:y][1]\n\n(-6.0, 2.0)\n\n\nThis works even for parameters with more complex types.\n\n@model function demo_complex()\n    x ~ LKJCholesky(3, 0.5)\n    y ~ MvNormal(zeros(3), I)\nend\ninit_x, init_y = rand(LKJCholesky(3, 0.5)), rand(MvNormal(zeros(3), I))\nchn = sample(demo_complex(), MH(), 5; initial_params=(x=init_x, y=init_y));\n\nFor multiple-chain sampling, the initial_params keyword argument should be a vector with length equal to the number of chains being sampled. Each element of this vector should be the initial parameters for the corresponding chain, as described above. Thus, for example, a vector of vectors, or a vector of NamedTuples, can be used. If you want to use the same initial parameters for all chains, you can use fill:\n\ninitial_params = fill((x=1.0, y=-5.0), 3)\nchn = sample(demo_model(), MH(), MCMCThreads(), 5, 3; initial_params=initial_params)\nchn[:x][1,:], chn[:y][1,:]\n\n\n┌ Warning: Only a single thread available: MCMC chains are not sampled in parallel\n└ @ AbstractMCMC ~/.julia/packages/AbstractMCMC/nQLlh/src/sample.jl:410\n\n\n\n\n([1.0, 1.0, 1.0], [-5.0, -5.0, -5.0])\n\n\n\n\n\n\n\n\nImportantUpcoming changes in Turing v0.41\n\n\n\nIn Turing v0.41, instead of providing initial parameters, users will have to provide what is conceptually an initialisation strategy. The keyword argument is still initial_params, but the permitted values (for single-chain sampling) will either be:\n\nInitFromPrior(): generate initial parameters by sampling from the prior\nInitFromUniform(lower, upper): generate initial parameters by sampling uniformly from the given bounds in linked space\nInitFromParams(namedtuple_or_dict): use the provided initial parameters, supplied either as a NamedTuple or a Dict{<:VarName}\n\nInitialisation with Vector will be fully removed due to its inherent ambiguity. Initialisation with a raw NamedTuple will still be supported (it will simply be wrapped in InitFromParams()); but we expect to remove this eventually, so it will be more future-proof to use InitFromParams() directly.\nFor multiple chains, the same as above applies: the initial_params keyword argument should be a vector of initialisation strategies, one per chain.",
     "crumbs": [
       "Get Started",
       "User Guide",
@@ -1158,7 +1158,7 @@
     "href": "usage/sampling-options/index.html#saving-and-resuming-sampling",
     "title": "MCMC Sampling Options",
     "section": "Saving and resuming sampling",
-    "text": "Saving and resuming sampling\nBy default, MCMC sampling starts from scratch, using the initial parameters provided. You can, however, resume sampling from a previous chain. This is useful to, for example, perform sampling in batches, or to inspect intermediate results.\nFirstly, the previous chain must have been run using the save_state=true argument.\n\nrng = Xoshiro(468)\n\nchn1 = sample(rng, demo_model(), MH(), 5; save_state=true);\n\nFor MCMCChains.Chains, this results in the final sampler state being stored inside the chain metadata. You can access it using DynamicPPL.loadstate:\n\nsaved_state = DynamicPPL.loadstate(chn1)\ntypeof(saved_state)\n\nTuring.Inference.MHState{VarInfo{@NamedTuple{x::DynamicPPL.Metadata{Dict{VarName{:x, typeof(identity)}, Int64}, Vector{Normal{Float64}}, Vector{VarName{:x, typeof(identity)}}, Vector{Float64}}, y::DynamicPPL.Metadata{Dict{VarName{:y, typeof(identity)}, Int64}, Vector{Normal{Float64}}, Vector{VarName{:y, typeof(identity)}}, Vector{Float64}}}, DynamicPPL.AccumulatorTuple{3, @NamedTuple{LogPrior::LogPriorAccumulator{Float64}, LogJacobian::LogJacobianAccumulator{Float64}, LogLikelihood::LogLikelihoodAccumulator{Float64}}}}, Float64}\n\n\n\n\n\n\n\n\nNote\n\n\n\nYou can also directly access the saved sampler state with chn1.info.samplerstate, but we recommend not using this as it relies on the internal structure of MCMCChains.Chains.\n\n\nSampling can then be resumed from this state by providing it as the initial_state keyword argument.\n\nchn2 = sample(demo_model(), MH(), 5; initial_state=saved_state)\n\nChains MCMC chain (5×5×1 Array{Float64, 3}):\n\nIterations        = 1:1:5\nNumber of chains  = 1\nSamples per chain = 5\nWall duration     = 0.08 seconds\nCompute duration  = 0.08 seconds\nparameters        = x, y\ninternals         = lp, logprior, loglikelihood\n\nUse `describe(chains)` for summary statistics and quantiles.\n\n\nNote that the exact format saved in chn.info.samplerstate, and that expected by initial_state, depends on the invocation of sample used. For single-chain sampling, the saved state, and the required initial state, is just a single sampler state. For multiple-chain sampling, it is a vector of states, one per chain.\nThis means that, for example, after sampling a single chain, you could sample three chains that branch off from that final state:\n\ninitial_states = fill(saved_state, 3)\nchn3 = sample(demo_model(), MH(), MCMCThreads(), 5, 3; initial_state=initial_states)\n\n\n┌ Warning: Only a single thread available: MCMC chains are not sampled in parallel\n└ @ AbstractMCMC ~/.julia/packages/AbstractMCMC/nQLlh/src/sample.jl:410\n\n\n\n\nChains MCMC chain (5×5×3 Array{Float64, 3}):\n\nIterations        = 1:1:5\nNumber of chains  = 3\nSamples per chain = 5\nWall duration     = 0.04 seconds\nCompute duration  = 0.02 seconds\nparameters        = x, y\ninternals         = lp, logprior, loglikelihood\n\nUse `describe(chains)` for summary statistics and quantiles.\n\n\n\n\n\n\n\n\nNoteInitial states versus initial parameters\n\n\n\nThe initial_state and initial_params keyword arguments are mutually exclusive. If both are provided, initial_params will be silently ignored.\n\nchn2 = sample(rng, demo_model(), MH(), 5;\n    initial_state=saved_state, initial_params=(x=0.0, y=0.0)\n)\nchn2[:x][1], chn2[:y][1]\n\n(-0.29864819524237707, 2.2292859419961677)\n\n\nIn general, the saved state will contain a set of parameters (which will be the last parameters in the previous chain). However, the saved state not only specifies parameters but also other internal variables required by the sampler. For example, the MH state contains a cached log-density of the current parameters, which is later used for calculating the acceptance ratio.\nFinally, note that the first sample in the resumed chain will not be the same as the last sample in the previous chain; it will be the sample immediately after that.\n\n# In general these will not be the same (although it _could_ be if the MH step\n# was rejected -- that is why we seed the sampling in this section).\nchn1[:x][end], chn2[:x][1]\n\n(-0.2787323372767189, -0.29864819524237707)",
+    "text": "Saving and resuming sampling\nBy default, MCMC sampling starts from scratch, using the initial parameters provided. You can, however, resume sampling from a previous chain. This is useful to, for example, perform sampling in batches, or to inspect intermediate results.\nFirstly, the previous chain must have been run using the save_state=true argument.\n\nrng = Xoshiro(468)\n\nchn1 = sample(rng, demo_model(), MH(), 5; save_state=true);\n\nFor MCMCChains.Chains, this results in the final sampler state being stored inside the chain metadata. You can access it using DynamicPPL.loadstate:\n\nsaved_state = DynamicPPL.loadstate(chn1)\ntypeof(saved_state)\n\nTuring.Inference.MHState{VarInfo{@NamedTuple{x::DynamicPPL.Metadata{Dict{VarName{:x, typeof(identity)}, Int64}, Vector{Normal{Float64}}, Vector{VarName{:x, typeof(identity)}}, Vector{Float64}}, y::DynamicPPL.Metadata{Dict{VarName{:y, typeof(identity)}, Int64}, Vector{Normal{Float64}}, Vector{VarName{:y, typeof(identity)}}, Vector{Float64}}}, DynamicPPL.AccumulatorTuple{3, @NamedTuple{LogPrior::LogPriorAccumulator{Float64}, LogJacobian::LogJacobianAccumulator{Float64}, LogLikelihood::LogLikelihoodAccumulator{Float64}}}}, Float64}\n\n\n\n\n\n\n\n\nNote\n\n\n\nYou can also directly access the saved sampler state with chn1.info.samplerstate, but we recommend not using this as it relies on the internal structure of MCMCChains.Chains.\n\n\nSampling can then be resumed from this state by providing it as the initial_state keyword argument.\n\nchn2 = sample(demo_model(), MH(), 5; initial_state=saved_state)\n\nChains MCMC chain (5×5×1 Array{Float64, 3}):\n\nIterations        = 1:1:5\nNumber of chains  = 1\nSamples per chain = 5\nWall duration     = 0.08 seconds\nCompute duration  = 0.08 seconds\nparameters        = x, y\ninternals         = lp, logprior, loglikelihood\n\nUse `describe(chains)` for summary statistics and quantiles.\n\n\nNote that the exact format saved in chn.info.samplerstate, and that expected by initial_state, depends on the invocation of sample used. For single-chain sampling, the saved state, and the required initial state, is just a single sampler state. For multiple-chain sampling, it is a vector of states, one per chain.\nThis means that, for example, after sampling a single chain, you could sample three chains that branch off from that final state:\n\ninitial_states = fill(saved_state, 3)\nchn3 = sample(demo_model(), MH(), MCMCThreads(), 5, 3; initial_state=initial_states)\n\n\n┌ Warning: Only a single thread available: MCMC chains are not sampled in parallel\n└ @ AbstractMCMC ~/.julia/packages/AbstractMCMC/nQLlh/src/sample.jl:410\n\n\n\n\nChains MCMC chain (5×5×3 Array{Float64, 3}):\n\nIterations        = 1:1:5\nNumber of chains  = 3\nSamples per chain = 5\nWall duration     = 0.05 seconds\nCompute duration  = 0.02 seconds\nparameters        = x, y\ninternals         = lp, logprior, loglikelihood\n\nUse `describe(chains)` for summary statistics and quantiles.\n\n\n\n\n\n\n\n\nNoteInitial states versus initial parameters\n\n\n\nThe initial_state and initial_params keyword arguments are mutually exclusive. If both are provided, initial_params will be silently ignored.\n\nchn2 = sample(rng, demo_model(), MH(), 5;\n    initial_state=saved_state, initial_params=(x=0.0, y=0.0)\n)\nchn2[:x][1], chn2[:y][1]\n\n(-0.29864819524237707, 2.2292859419961677)\n\n\nIn general, the saved state will contain a set of parameters (which will be the last parameters in the previous chain). However, the saved state not only specifies parameters but also other internal variables required by the sampler. For example, the MH state contains a cached log-density of the current parameters, which is later used for calculating the acceptance ratio.\nFinally, note that the first sample in the resumed chain will not be the same as the last sample in the previous chain; it will be the sample immediately after that.\n\n# In general these will not be the same (although it _could_ be if the MH step\n# was rejected -- that is why we seed the sampling in this section).\nchn1[:x][end], chn2[:x][1]\n\n(-0.2787323372767189, -0.29864819524237707)",
     "crumbs": [
       "Get Started",
       "User Guide",