gclda.model module

Class and functions for model-related stuff.

class gclda.model.Model(dataset, n_topics=100, n_regions=2, symmetric=False, alpha=0.1, beta=0.01, gamma=0.01, delta=1.0, dobs=25, roi_size=50.0, seed_init=1)

Bases: future.types.newobject.newobject

Class object for a gcLDA model.

Creates a gcLDA model using a dataset object and hyperparameter arguments.

Parameters:

dataset : gclda.dataset.Dataset

Dataset object containing data needed for model.

n_topics : int, optional

Number of topics to generate in model. The default is 100.

n_regions : int, optional

Number of subregions per topic (>=1). The default is 2.

alpha : float, optional

Prior count on topics for each document. The default is 0.1.

beta : float, optional

Prior count on word-types for each topic. The default is 0.01.

gamma : float, optional

Prior count added to y-counts when sampling z assignments. The default is 0.01.

delta : float, optional

Prior count on subregions for each topic. The default is 1.0.

dobs : int, optional

Spatial region ‘default observations’ (# observations weighting Sigma estimates in direction of default ‘roi_size’ value). The default is 25.

roi_size : float, optional

Default spatial ‘region of interest’ size (default value of diagonals in covariance matrix for spatial distribution, which the distributions are biased towards). The default is 50.0.

symmetric : bool, optional

Whether or not to use symmetry constraint on subregions. Symmetry requires n_regions = 2. The default is False.

seed_init : int, optional

Initial value of random seed. The default is 1.

Attributes:

model_name : str

Identifier (based on parameter values) for the model.

wtoken_topic_idx : numpy.ndarray of numpy.int64

A number-of-words-by-1 vector of word->topic assignments.

peak_topic_idx : numpy.ndarray of numpy.int64

A number-of-peaks-by-1 vector of peak->topic assignments.

peak_region_idx : numpy.ndarray of numpy.int64

A number-of-peaks-by-1 vector of peak->region assignments.

n_peak_tokens_doc_by_topic : numpy.ndarray of numpy.int64

An n-documents-by-n-topics array. Each cell is the number of peak-tokens for a given document assigned to a given topic.

n_peak_tokens_region_by_topic : numpy.ndarray of numpy.int64

An n-regions-by-n-topics array. Each cell is the number of peak-tokens for a given region assigned to a given topic.

n_word_tokens_word_by_topic : numpy.ndarray of numpy.int64

An n-words-by-n-topics array. Each cell is the number of word-tokens for a given word assigned to a given topic.

n_word_tokens_doc_by_topic : numpy.ndarray of numpy.int64

An n-documents-by-n-topics array. Each cell is the number of word-tokens for a given document assigned to a given topic.

total_n_word_tokens_by_topic : numpy.ndarray of numpy.int64

A 1-by-number-of-words vector. Total number of word-tokens assigned to each topic (across all documents).

Methods

compute_log_likelihood([dataset, update_vectors])	Compute Log-likelihood of a dataset object given current model.
display_model_summary([debug])	Print model summary to console.
get_spatial_probs()	Get conditional probability of selecting each voxel in the brain mask given each topic.
load(filename)	Load a pickled Model instance from file.
run_complete_iteration([loglikely_freq, verbose])	Run a complete update cycle (sample z, sample y&r, update regions).
save(filename)	Pickle the Model instance to the provided file.
save_model_params(outputdir[, n_top_words])	Run all export-methods: calls all save-methods to export parameters to files.
save_topic_figures(outputdir[, …])	Save Topic Figures: Spatial distributions and Linguistic distributions for top K words.

next

compute_log_likelihood(dataset=None, update_vectors=True)

Compute Log-likelihood of a dataset object given current model.

Computes the log-likelihood of data in any dataset object (either train or test) given the posterior predictive distributions over peaks and word-types for the model. Note that this is not computing the joint log-likelihood of model parameters and data.

Parameters:

dataset : gclda.Dataset, optional

The dataset for which log-likelihoods will be calculated. If not provided, log-likelihood will be calculated for the model’s dataset.

update_vectors : bool, optional

Whether to update model’s log-likelihood vectors or not.

Returns:

x_loglikely : float

Total log-likelihood of all peak tokens.

w_loglikely : float

Total log-likelihood of all word tokens.

tot_loglikely : float

Total log-likelihood of peak + word tokens.

References

[1] Newman, D., Asuncion, A., Smyth, P., & Welling, M. (2009). Distributed algorithms for topic models. Journal of Machine Learning Research, 10(Aug), 1801-1828.

display_model_summary(debug=False)

Print model summary to console.

Parameters:

debug : bool, optional

Setting debug to True will print out additional information useful for debugging the model. Default = False.

get_spatial_probs()

Get conditional probability of selecting each voxel in the brain mask given each topic.

Returns:

p_voxel_g_topic : numpy.ndarray of numpy.float64

A voxel-by-topic array of conditional probabilities: p(voxel|topic). For cell ij, the value is the probability of voxel i being selected given topic j has already been selected.

p_topic_g_voxel : numpy.ndarray of numpy.float64

A voxel-by-topic array of conditional probabilities: p(topic|voxel). For cell ij, the value is the probability of topic j being selected given voxel i is active.

classmethod load(filename)

Load a pickled Model instance from file. If the filename ends with ‘z’, it will be assumed that the file is compressed, and gzip will be used to load it. Otherwise, it will be assumed that the file is not compressed.

next()

run_complete_iteration(loglikely_freq=1, verbose=2)

Run a complete update cycle (sample z, sample y&r, update regions).

Parameters:

loglikely_freq : int, optional

The frequency with which log-likelihood is updated. Default value is 1 (log-likelihood is updated every iteration).

verbose : {0, 1, 2}, optional

Determines how much info is printed to console. 0 = none, 1 = a little, 2 = a lot. Default value is 2.

save(filename)

Pickle the Model instance to the provided file. If the filename ends with ‘z’, gzip will be used to write out a compressed file. Otherwise, an uncompressed file will be created.

save_model_params(outputdir, n_top_words=15)

Run all export-methods: calls all save-methods to export parameters to files.

Parameters:

outputdir : str

The name of the output directory.

n_top_words : int, optional

The number of words associated with each topic to report in topic word probabilities file.

save_topic_figures(outputdir, backgroundpeakfreq=10, n_top_words=12)

Save Topic Figures: Spatial distributions and Linguistic distributions for top K words.

Parameters:

outputdir : str

Output directory for topic figures.

backgroundpeakfreq : int, optional

Determines what proportion of peaks we show in the background of each figure. Default = 10.

n_top_words : int, optional

The number of words per topic to include in the figures. Default = 12.