A standardized naturalistic audio stimulus dataset with unsupervised labeling.

1. function [varargout] = textAnalysis(data,varargin)
2. % textAnalysis Perform text cleaning and first-step clustering to compute a similarity matrix
3. %
4. % similarityAll = textAnalysis(data) cleans participant-generated text
5. % responses and runs the first step of the two-stage semantic
6. % categorization analysis. The function returns a SoundNum-by-SoundNum
7. % similarity matrix describing how consistently two sounds are placed in
8. % the same semantic cluster across iterations.
9. %
10. % [similarityAll, allSilChoice, silhouetteAvg] = textAnalysis(data, ...)
11. % also returns the selected number of clusters for each iteration and the
12. % silhouette scores for all tested cluster numbers.
13. %
14. % INPUTS
15. %
16. % data - A matrix of strings of size ParticipantNum-by-SoundNum.
17. % Each entry contains the participant’s textual label or
18. % guess for that sound. Empty or missing responses should be
19. % represented as "".
20. %
21. % numiter - (Optional) Number of iterations for the first-step
22. % clustering procedure. In each iteration, the function
23. % embeds all unique cleaned guesses into a semantic space
24. % and runs k-means clustering to identify the optimal
25. % cluster solution.
26. % Default: 1000
27. %
28. % clusterRange - (Optional) Two-element vector specifying the range of
29. % cluster numbers to test during each iteration. The
30. % function computes silhouette scores for each cluster
31. % solution in this range and selects the cluster number
32. % with the highest silhouette value.
33. % Default: [5 25]
34. %
35. % randseed - (Optional) Random seed for reproducibility.
36. % Default: 1
37. %
38. % stopwords - (Optional) List of stop words to remove from text
39. % responses. These strings will be replaced by empty
40. % entries before embedding.
41. % Default:
42. % [stopWords('Language','en'), "voice","noise","sound", ...
43. % "noises","sounds","voices","answer"]
44. %
45. % OUTPUTS
46. %
47. % similarityAll - A SoundNum-by-SoundNum matrix. Element (i,j) represents
48. % the normalized number of times sound i and sound j
49. % were assigned to the same k-means cluster across all
50. % iterations.
51. %
52. % allSilChoice - A numiter-by-1 vector containing the chosen number of
53. % clusters for each iteration (i.e., the cluster count
54. % with maximum silhouette score in that iteration).
55. %
56. % silhouetteAvg - A matrix storing the silhouette score curves for all
57. % tested cluster numbers across all iterations.
58. %
59. % DESCRIPTION
60. %
61. % This function implements the first step of the semantic categorization
62. % pipeline described in the study. All participant guesses are cleaned
63. % (stop-word removal, deletion of nonsense entries, autocorrection)
64. % and then embedded into a 200-dimensional GloVe semantic space. In each
65. % iteration, unique embedded guesses are clustered using k-means across a
66. % specified range of cluster numbers. The optimal cluster solution is
67. % selected via silhouette analysis. The full set of guesses is then used
68. % to assign each sound to a cluster for that iteration. Repeating this
69. % procedure numiter times yields a consensus-based similarity matrix
70. % measuring how often each pair of sounds co-clusters.
71. %
72. % This matrix serves as input to the second-stage clustering procedure
73. % described in the main analysis pipeline.
74. %
75. % See also: kmeans, silhouette, stopWords
77. numiter = 1000;
78. clusterRange = [5,25];
79. randseed = 1;
81. if nargin >= 2
82. if ~isempty(varargin{1})
83. numiter = varargin{1};
84. end
85. end
87. disp(['Chosen number of iterations: ' num2str(numiter)])
89. if nargin >= 3
90. if ~isempty(varargin{2})
91. clusterRange = varargin{2};
92. end
93. end
95. if ~numel(clusterRange) == 2
96. error('Range of clusters argument must contain a lower and upper bound')
97. end
99. if clusterRange(1) > clusterRange(2)
100. error('Cluster range lower bound should be the first entry')
101. end
103. if nargin >= 4
104. if ~isempty(varargin{3})
105. randseed = varargin{3};
106. end
107. end
110. disp('Loading embedding space')
111. % Loading the glove twitter word embedding
112. try
113. emb = readWordEmbedding('glove.twitter.27B.200d.txt');
114. catch ME
115. error(['Failed to load the GloVe embedding file. ', ...
116. 'Please ensure that the file exists and that the path is correct.\n', ...
117. 'Specified path: %s\nOriginal error: %s'], 'glove.twitter.27B.200d.txt', ME.message);
118. end
122. % Define stopwords list (MATLAB's built-in stopwords list)
123. stopwords = stopWords('Language','en');
124. % Adding our own list of stop words
125. % Perhaps add an option for the user to enter their own stop words here?
126. stopwords = [stopwords "voice" "noise" "sound" "noises" "sounds" "voices" "answer"];
128. if nargin >= 5
129. stopwords = [varargin{5}];
130. end
132. % Tokenize the data
133. documents = tokenizedDocument(data);
134. % Turn every word into lower case
135. documents = lower(documents);
136. % Apply MATLAB's autocorrect function
137. documents = correctSpelling(documents);
138. % Remove stop words
139. documents = removeWords(documents, stopwords);
141. % Initialize an empty cell to store embeddings
142. docVectors = cell(numel(documents), 1);
143. disp('Pre-processing text data')
144. % Pre-processing of the text data
145. for i = 1:numel(documents)
146. if strcmp(data(i), "No answer") % Answers that were left empty were automatically filled with No answer
147. docVectors{i} = single(zeros(1, emb.Dimension)); % Handle missing data
148. continue
149. end
150. words = string(documents(i));
151. wordVectors = word2vec(emb, words); % Retrieve word vectors
152. wordVectors = wordVectors(~any(isnan(wordVectors), 2), :); % Remove missing words
153. if ~isempty(wordVectors)
154. % Average the word vectors for each document
155. % This is a quick way to handle guesses with multiple words
156. docVectors{i} = mean(wordVectors, 1);
157. else
158. docVectors{i} = single(zeros(1, emb.Dimension)); % Handle documents with no match
159. end
160. end
163. % Selecting unique and non-empty guesses words only
164. docMatrix = cell2mat(docVectors); % Convert to matrix format
165. % Selecting the non-empty guesses first:
166. % Turning matrix to logical with 1 when any value in the matrix is not empty
167. nonEmptyData = docMatrix ~= 0;
168. % Turning matrix into vector of 1 iff all values in that row is empty (i.e. No Answer)
169. emptyVec = zeros([1,length(nonEmptyData)]);
170. for i = 1:length(nonEmptyData)
171. emptyVec(i) = all(nonEmptyData(i,:) == 0);
172. end
173. % Only 1 iff all values in that row is not empty
174. nonEmptyDataRow = ~emptyVec;
175. % Selecting non-empty guess
176. fullMat = docMatrix(nonEmptyDataRow,:);
177. % Saving the index of the empty guesses
178. emptyIdx = find(emptyVec);
179. % Creating a function that will insert these empty guesses back
180. % This will be used after running the k-means
181. insert = @(n,x,a) [x(1:a-1), n, x(a:end)];
182. % Creating the matrix with the unique guesses only
183. [X, ~, ic] = unique(fullMat , 'rows');
185. % Performing the first step of the algorithm
186. disp('Running the first step of the k-means')
187. sumSim = zeros([length(data) length(data)]);
188. silhouetteAvg = zeros([numiter,clusterRange(2)]);
189. for itr = 1:numiter
190. % Perform K-means clustering
191. disp(['Iteration Number: ' num2str(itr)])
192. % Choosing the number of clusters for this iteration
193. avg = zeros([1,clusterRange(2)]);
194. % Running the algorithm multiple times to check which number of
195. % clusters results in the maximum number of clusters
196. for r = clusterRange(1):clusterRange(2)
197. rng(itr * randseed) % Set random seed
198. idx = kmeans(X, r, 'Replicates', 5,'Distance','cosine');
199. silhouetteScores = (silhouette(gather(X), gather(idx)));
200. avg(r) = mean(silhouetteScores);
201. end
202. % Save the average silhouette score for every run of the k-means
203. silhouetteAvg(itr,:) = avg;
204. % Find the run that produced the highest avg silhouette score
205. numClusters = find(avg == max(avg(clusterRange(1):clusterRange(2))), 1);
206. disp(['Chosen Number of Clusters: ' num2str(numClusters)])
207. % Run the k-means again with the chosen number of clusters
208. rng(itr * randseed)
209. idxMain = kmeans(X, numClusters, 'Replicates', 5, 'Distance','cosine');
210. % Insert the non-unique guesses
211. OGIDX = zeros([1,length(ic)]);
212. for ii = 1:length(ic)
213. OGIDX(ii) = idxMain(ic(ii));
215. end
216. idxMain = OGIDX;
217. % Insert the 'No Answer' guesses as zeros
218. for ii = 1:length(find(emptyVec))
219. idxMain = insert(0,idxMain,emptyIdx(ii));
220. end
221. % Reshape the classification of the guesses into the original format
222. % (Participant x Guess)
223. idxMain = idxMain';
224. idxReshaped = reshape(idxMain,size(data,1),size(data,2));
225. % Count the number of times a sound had a guess in a certain cluster
226. sumsOfCluster = zeros([numClusters, size(data,2)]);
227. for i = 1:numClusters
228. for ii = 1:size(data,2)
229. sumsOfCluster(i,ii) = gather(sum(idxReshaped(:,ii) == i));
230. end
231. end
232. % Find the cluster that the guesses of each of the sounds was
233. % classified to the most and take that as the classification for that
234. % sounds
235. [~, idxSum] = max(sumsOfCluster, [], 1);
236. % Create a sound x sound matrix which contains information about which
237. % sound was classified with another one. For example: if the value at
238. % row 2 and column 3 is 1, then sound 2 and sound 3 were classified in
239. % the same category
240. similarity = zeros(size(data,2));
241. for i = 1:length(idxSum)
242. similarity(i,:) = idxSum == idxSum(i);
243. end
244. % Save that matrix for each iteration
245. sumSim = sumSim + similarity;
247. end
249. allSilChoice = zeros([1,numiter]);
251. % Save the chosen number of clusters for each iteration
252. for i = 1:length(silhouetteAvg)
253. allSilChoice(i) = find(silhouetteAvg(i,:) == max(silhouetteAvg(i,clusterRange(1):clusterRange(2))), 1);
254. end
256. % Create a similarity matrix by dividing the resulting matrix from last
257. % step with the number of iterations. This is easier to use with
258. % classification algorithms
259. similarityAll = sumSim/numiter;
261. varargout{1} = similarityAll;
262. varargout{2} = allSilChoice;
263. varargout{3} = silhouetteAvg;
265. end

textAnalysis.m at commit 7955dde, under MIT · at the source