ParaMonte MATLAB 3.0.0
Parallel Monte Carlo and Machine Learning Library
See the latest version documentation.
readSample.m
Go to the documentation of this file.
1%> \brief
2%> Return a list of objects of superclass [pm.sampling.FileContentsSample](@ref FileContentsSample)
3%> containing the contents of a (set of) ParaMonte simulation output sample file(s) whose paths match
4%> the specified input ``pattern`` or the simulation specification ``sampler.spec.outputFileName``.<br>
5%>
6%> \warning
7%> This function is to be only used for post-processing of the output sample file(s) of an already finished simulation.<br>
8%> Although possible, this method is **not** meant to be called by all processes in MPI-parallel simulations.<br>
9%>
10%> \param[in] sampler : The input object of superclass [pm.sampling.Sampler](@ref Sampler)
11%> whose type and properties determine the type of the output object(s).<br>
12%> (**optional**. If empty, it is set to [pm.sampling.Sampler()](@ref Sampler).)
13%> \param[in] pattern : The input scalar MATLAB string containing the pattern matching
14%> the desired sample file(s) whose contents is to be read.<br>
15%> The specified ``pattern`` only needs to partially identify
16%> the name of the simulation to which the sample file belongs.<br>
17%> For example, specifying ``"./mydir/mysim"`` as input will
18%> lead to a search for file(s) beginning with ``"mysim"`` and
19%> ending with ``"_sample.txt"`` inside the directory ``"./mydir/"``.<br>
20%> If there are multiple files matching in the input ``pattern``,
21%> then all such files will be read and returned as elements of a list.<br>
22%> If the specified pattern is a valid existing URL, the file will be
23%> downloaded as a temporary file to the local system, its contents
24%> shall be parsed and the file will be subsequently removed.<br>
25%> If the input ``pattern`` is empty, then the method will search
26%> for any possible candidate files with the appropriate suffix
27%> in the current working directory.<br>
28%> (**optional**. If empty, it is set to ``sampler.spec.outputFileName`` or if empty, it is set to ``"./"``.)
29%> \param[in] sep : The input MATLAB string containing the field separator used in the file(s).<br>
30%> (**optional**. If empty, it is set to ``sampler.spec.outputSeparator`` or if empty, it is automatically inferred.)
31%>
32%> \return
33%> ``sampleList`` : The output MATLAB cell array of objects of superclass [pm.sampling.FileContentsSample](@ref FileContentsSample),
34%> each of which corresponds to the contents of a unique ParaMonte sampler sample file.<br>
35%> <ol>
36%> <li> If the input argument ``sampler`` is of type [pm.sampling.Sampler](@ref Sampler),
37%> then the output array elements are of type [pm.sampling.FileContentsSample](@ref FileContentsSample).<br>
38%> <li> If the input argument ``sampler`` is of type [pm.sampling.Paradram](@ref Paradram),
39%> then the output array elements are of type [pm.sampling.FileContentsSample](@ref FileContentsSample).<br>
40%> </ol>
41%>
42%> \interface{readSample}
43%> \code{.m}
44%>
45%> sampleList = pm.sampling.readSample();
46%> sampleList = pm.sampling.readSample([]);
47%> sampleList = pm.sampling.readSample([], []);
48%> sampleList = pm.sampling.readSample([], [], []);
49%> sampleList = pm.sampling.readSample([], pattern);
50%> sampleList = pm.sampling.readSample([], [], sep);
51%> sampleList = pm.sampling.readSample([], pattern, sep);
52%> sampleList = pm.sampling.readSample(sampler, pattern, sep);
53%>
54%> \endcode
55%>
56%> \note
57%> See the documentation of the subclasses of [pm.sampling.Sampler](@ref Sampler)
58%> (e.g., [pm.sampling.Paradram](@ref Paradram)) for example usage in action.<br>
59%>
60%> \example{readSample}
61%> \code{.m}
62%>
63%> sampler = pm.sampling.Sampler();
64%>
65%> sampleList = pm.sampling.readSample([], "./out/test_run_");
66%> sampleList = pm.sampling.readSample(sampler, "./out/test_run_");
67%>
68%> sampler.spec.outputFileName = "./out/test_run_";
69%>
70%> sampleList = pm.sampling.readSample(sampler, []);
71%> sampleList = pm.sampling.readSample(sampler);
72%>
73%> sampler.spec.outputSeparator = ",";
74%> pm.sampling.readSample(sampler, "./out/test_run_");
75%> pm.sampling.readSample(sampler, "./out/test_run_", []);
76%> sampleList = pm.sampling.readSample(sampler, "./out/test_run_", ",");
77%>
78%> \endcode
79%>
80%> \final{readSample}
81%>
82%> \author
83%> \AmirShahmoradi, Saturday Nov 2 2024, 11:11 PM, Dallas, TX.<br>
84%> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
85function sampleList = readSample(sampler, pattern, sep)
86
87 if nargin < 1
88 sampler = [];
89 end
90 if isempty(sampler)
91 sampler = pm.sampling.Sampler();
92 end
93
94 if nargin < 2
95 if 0 < pm.array.len(sampler.spec.outputFileName)
96 pattern = string(sampler.spec.outputFileName);
97 else
98 pattern = [];
99 end
100 end
101
102 if nargin < 3
103 if 0 < pm.array.len(sampler.spec.outputSeparator)
104 sep = string(sampler.spec.outputSeparator);
105 else
106 sep = [];
107 end
108 end
109
110 pathList = sampler.findfile("sample", pattern);
111 sampleList = cell(numel(pathList), 1);
112
113 for ifile = numel(pathList) : -1 : 1
114
115 if ~sampler.silent
116 disp("processing file: """ + pathList(ifile) + """");
117 end
118
119 if isequal(class(sampler), "pm.sampling.Sampler")
120 sampleList{ifile} = pm.sampling.FileContentsSample(pathList(ifile), sampler.silent, sep);
121 elseif isequal(class(sampler), "pm.sampling.Paradram")
122 sampleList{ifile} = pm.sampling.FileContentsSampleDRAM(pathList(ifile), sampler.silent, sep);
123 else
124 help("pm.sampling.readSample")
125 disp("class(sampler)");
126 disp( class(sampler) );
127 error ( newline ...
128 + "Invalid input ``sampler`` object type." + newline ...
129 + "See the documentation displayed above for more " + newline ...
130 + "information on possible values for ``sampler`` argument." + newline ...
131 + newline ...
132 );
133 end
134
135 end
136
137end
function name(in vendor)
Return the MPI library name as used in naming the ParaMonte MATLAB shared library directories.
function list()
Return a list of MATLAB strings containing the names of OS platforms supported by the ParaMonte MATLA...
This is the base class for generating objects that contain the contents of a sample/chain file genera...
This is the ParaDRAM class for generating instances of serial and parallel Delayed-Rejection Adaptive...
Definition: Paradram.m:18
This is the base class for the ParaMonte sampler routines.
Definition: Sampler.m:21
function parallel()
Return a scalar MATLAB logical that is true if and only if the current installation of MATLAB contain...
function readSample(in sampler, in pattern, in sep)
Return a list of objects of superclass pm.sampling.FileContentsSample containing the contents of a (s...
function which(in vendor)
Return the a MATLAB string containing the path to the first mpiexec executable binary found in system...