Add documentation for label_threshold

[JohannesWiesner]

Summary

Hey, how exactly does label_threshold work in nimare.dataset.Dataset.get_studies_by_label? I only came across this neurostars post:

https://neurostars.org/t/how-to-extract-neurosynth-studies-with-specific-features-in-nimare/19000/4?u=johanneswiesner

Additional details

Could this be added in the docs?

https://nimare.readthedocs.io/en/latest/generated/nimare.dataset.Dataset.html#nimare.dataset.Dataset.get_studies_by_label

[jdkent]

Good question!

Preamble

The function is general purpose such that the numbers could represent any probability/importance-like measure where higher means "more likely to be in this category".

Pragmatically with respect to neurosynth, label_threshold refers to the measure "term frequency inverse document frequency" (tf-idf). Where term frequency is number_of_times_term_is_mentioned / total_terms_in_document and inverse document frequency is total_number_of_documents_in_corpus / number_of_documents_term_occurs_in

and then term frequency is multiplied by inverse document frequency to give you a measure how important a particular term is for a particular document relative to a corpus of documents.

To give some intuition, if the word "sleep" occurs 10 times in a document (named sleepy.txt) containing 100 terms, term frequency is 10 / 100 = .10 and if our corpus is 50 documents and this is the only document where sleep was mentioned, we get log(50 / 1) (we take log or some other transform to constrain outliers and get a nice distribution).

So the tf-idf is (10 / 100) * log(50 /1) = 0.1 * ~1.7 = 0.17

What does label_threshold do?

the function nimare.dataset.Dataset.get_studies_by_label returns a list of study_ids from the Dataset where the tf-idf for the piece of text (typically abstract or full text) is greater than label_threshold. label_threshold is the threshold tf-idf that the study text must be greater than to be in the list.

Does that clear up how label_threshold works?