neurosynth / neurosynth

Neurosynth core tools

Note: this package is no longer actively maintained; most of its functionality has been integrated into the much more expansive NiMARE package, which we recommend using instead.

What is Neurosynth?

Neurosynth is a Python package for large-scale synthesis of functional neuroimaging data.

Code status

• travis-ci.org (master branch)

• 

Installation

Dependencies:

• NumPy/SciPy
• pandas
• NiBabel
• ply
• scikit-learn

We recommend installing the core scientific packages (NumPy, SciPy, pandas, sklearn) via a distribution like https://store.continuum.io/cshop/anaconda/, which will keep clutter and conflicts to a minimum. The other packages can be installed with pip using the requirements file:

> pip install -r requirements.txt

Or by name:

> pip install nibabel ply

Assuming you have those packages in working order, the easiest way to install Neurosynth is from the command line with pip:

> pip install neurosynth

Alternatively, if you want the latest development version, you can install directly from the github repo:

> pip install -e git+https://github.com/neurosynth/neurosynth.git#egg=neurosynth

Depending on your operating system, you may need superuser privileges (prefix the above line with 'sudo').

That's it! You should now be ready to roll.

Documentation

Documentation, including a full API reference, is available here(caution: work in progress).

Usage

Running analyses in Neurosynth is pretty straightforward. We're working on a user manual; in the meantime, you can take a look at the code in the /examples directory for an illustration of some common uses cases (some of the examples are in IPython Notebook format; you can view these online by entering the URL of the raw example on github into the online IPython Notebook Viewer--for example this tutorial provides a nice overview). The rest of this Quickstart guide just covers the bare minimum.

The NeuroSynth dataset resides in a separate submodule located here. Probably the easiest way to get the most recent data though is from within the Neurosynth package itself:

import neurosynth as ns
ns.dataset.download(path='.', unpack=True)

...which should download the latest database files and save them to the current directory. Alternatively, you can manually download the data files from the neurosynth-data repository. The latest dataset is always stored in current_data.tar.gz in the root folder. Older datasets are also available in the archive folder.

The dataset archive (current_data.tar.gz) contains 2 files: database.txt and features.txt. These contain the activations and meta-analysis tags for Neurosynth, respectively.

Once you have the data in place, you can generate a new Dataset instance from the database.txt file:

> from neurosynth.base.dataset import Dataset
> dataset = Dataset('data/database.txt')

This should take several minutes to process. Note that this is a memory-intensive operation, and may be very slow on machines with less than 8 GB of RAM.

Once initialized, the Dataset instance contains activation data from nearly 10,000 published neuroimaging articles. But it doesn't yet have any features attached to those data, so let's add some:

> dataset.add_features('data/features.txt')

Now our Dataset has both activation data and some features we can use to manipulate the data with. In this case, the features are just term-based tags--i.e., words that occur in the abstracts of the articles from which the dataset is drawn (for details, see this [Nature Methods] paper, or the Neurosynth website).

We can now do various kinds of analyses with the data. For example, we can use the features we just added to perform automated large-scale meta-analyses. Let's see what features we have:

> dataset.get_feature_names()
['phonetic', 'associative', 'cues', 'visually', ... ]

We can use these features--either in isolation or in combination--to select articles for inclusion in a meta-analysis. For example, suppose we want to run a meta-analysis of emotion studies. We could operationally define a study of emotion as one in which the authors used words starting with 'emo' with high frequency:

> ids = dataset.get_studies(features='emo*', frequency_threshold=0.001)

Here we're asking for a list of IDs of all studies that use words starting with 'emo' (e.g.,'emotion', 'emotional', 'emotionally', etc.) at a frequency of 1 in 1,000 words or greater (in other words, if an article has 5,000 words of text, it will only be included in our set if it uses words starting with 'emo' at least 5 times).

> len(ids)
639

The resulting set includes 639 studies.

Once we've got a set of studies we're happy with, we can run a simple meta-analysis, prefixing all output files with the string 'emotion' to distinguish them from other analyses we might run:

> from neurosynth.analysis import meta
> ma = meta.MetaAnalysis(dataset, ids)
> ma.save_results('some_directory/emotion')

You should now have a set of Nifti-format brain images on your drive that display various meta-analytic results. The image names are somewhat cryptic; see the Documentation for details. It's important to note that the meta-analysis routines currently implemented in Neurosynth aren't very sophisticated; they're designed primarily for efficiency (most analyses should take just a few seconds), and take multiple shortcuts as compared to other packages like ALE or MKDA. But with that caveat in mind (and one that will hopefully be remedied in the near future), Neurosynth gives you a streamlined and quick way of running large-scale meta-analyses of fMRI data.

Getting help

For a more comprehensive set of examples, see this tutorial--also included in IPython Notebook form in the examples/ folder (along with several other simpler examples).

For bugs or feature requests, please create a new issue. If you run into problems installing or using the software, try posting to the Neurosynth Google group or email Tal Yarkoni.

neurosynth's Issues

get_image_data missing ability to filter by voxels

In Image Table, get_image_data says it supports filtering by voxels but it doesn't. Wrapper for this function in Dataset does not mention this support. I updated this function to says it does but is unimplemented.

I also added a paralel get_feature_data function w/ the same problem except features instead of voxels.

I'll fix if Tal agrees w/ adding get_feature_data function and this functionality. Seems necessary for limiting classification to certain features

"result" never defined

https://github.com/NeuroSynth/Neurosynth/blob/master/neurosynth/base/imageutils.py#L140

Provide data/test_dataset.txt

I see no way to fetch/create the test_dataset.txt

fix voxel and study thresholding in cluster

The min_studies_per_voxel and min_voxels_per_study arguments don't work properly.

bugs in get_ids_by_mask & get_ids_by_peaks

• get_ids_by_peaks could not get vox_dims because it was never set.
  ** adding self.vox_dims = self.get_header().get_zooms() to Mask in mask.py fixes this
• get_ids_by_peaks still has problem with get_image_data value.
  ** says multiple values for get_image_data
• get_ids_by_mask has problem with transposing image_table data
  ** complains no T because this is not being applied on actual data
  ** I tried changing line to self.image_table.data.T but for some odd reason that didnt' fix the problem

I tried to fix these issues on a pull request but that version is still broken

Bug in Decoder

Unable to create a Decoder object using decoder = decode.Decoder(dataset)

Traceback (most recent call last):
File "", line 1, in
File "neurosynth/analysis/decode.py", line 52, in init
self.load_features(features, image_type=image_type)
File "neurosynth/analysis/decode.py", line 117, in load_features
self._load_features_from_dataset(features, image_type=image_type)
File "neurosynth/analysis/decode.py", line 136, in _load_features_from_dataset
self.dataset, self.feature_names, image_type=image_type)
File "neurosynth/analysis/meta.py", line 46, in analyze_features
result[:, i] = ma.images[image_type]
KeyError: None

pA > 1?

Hello, I have a question about how pA and pFgA images are calculated in the MetaAnalysis class.

Say I try to do a meta-analytic contrast on two terms "beliefs" and "percept":

import neurosynth as ns
dataset = ns.Dataset.load('database.pkl')
ids = dataset.get_studies(features='beliefs')
ids2 = dataset.get_studies(features='percept')
meta = ns.MetaAnalysis(dataset=dataset, ids=ids, ids2=ids2)

Now I thought the pA map is supposed to be a probability of baseline activation, but I noticed it's often greater than 1, which didn't make much sense to me:

>>> len(meta.images['pA'])
228453
>>> np.sum(meta.images['pA'] > 1)
130505

In this line, the pA image is calculated by dividing the number of activations of each voxel in the entire database, by the size of given study universe (in this case the total number of studies is only 120), which seems to be the reason why it's greater than 1. Afterwards, the pFgA image also seems to be based on this pA image, but both pAgF and pF seem to be restricted to the given study universe, rather than the entire dataset.

I guess this is only an issue with these two images when contrasting two terms. Is it some specific consideration that pA and pAgF are rescaled?

Thanks!

PyPI out of sync with github release

I found some discrepancies between Neurosynth on PyPI and here.

For example, the github on PyPI shows the following images for MetaAnalysis objects:

        self.images = {
        'pA_pF_emp_prior': pA,
        'pFgA_emp_prior': pFgA,
        'pAgF': pAgF,
        ('pA_pF=%0.2f' % prior): pA_prior,
        ('pFgA_pF=%0.2f' % prior): pFgA_prior,
        'consistency_z': pAgF_z,
        'specificity_z': pFgA_z,
        ('consistency_z_FDR_%s' % q): pAgF_z_FDR,
        ('specificity_z_FDR_%s' % q): pFgA_z_FDR,
        ('pFgA_emp_prior_FDR_%s' % q): pFgA_FDR,
        ('pFgA_pF=%0.2f_FDR_%s' % (prior, q)): pFgA_prior_FDR
    }

whereas the one on github shows these:

        self.images = {
        'pA': pA,
        'pAgF': pAgF,
        'pFgA': pFgA,
        ('pAgF_given_pF=%0.2f' % prior): pAgF_prior,
        ('pFgA_given_pF=%0.2f' % prior): pFgA_prior,
        'pAgF_z': pAgF_z,
        'pFgA_z': pFgA_z,
        ('pAgF_z_FDR_%s' % q): pAgF_z_FDR,
        ('pFgA_z_FDR_%s' % q): pFgA_z_FDR
    }

This can be easily seen by downloading the 0.3.5 release from PyPI and the one from here.

Oddly enough, I can find no mention of "consistency_z" and such terms in this entire github repo, so perhaps PyPI is pulling from someone else's forked neurosynth repo?

get_ids_by_expression() not working anymore

From examples:

ids = dataset.get_ids_by_expression('emo* &~ (reward* | pain*)', threshold=0.001)

Error:
/usr/local/lib/python2.7/site-packages/pandas/core/generic.pyc in getattr(self, name)
1813 return self[name]
1814 raise AttributeError("'%s' object has no attribute '%s'" %
-> 1815 (type(self).name, name))
1816
1817 def setattr(self, name, value):

AttributeError: 'Series' object has no attribute 'items'

Could this be related to switching to PANDAS ?

add masking option to decoder

Decoder should take an optional mask and use only in-mask voxels for decoding.

"dataset.get_ids_by_features" in examples

Hi Tal et al.,

It seems there has been an update in the structure of the "dataset" class. I found the following line in the example (in neurosynth_demo.py) didn't work any more.

ids = dataset.get_ids_by_expression('emo* &~ (reward* | pain*)', threshold=0.001)

I made it work by adding "feature_table" like this:
ids = dataset.feature_table.get_ids_by_expression('emo* &~ (reward* | pain*)', threshold=0.001)

So it seems the example (neurosynth_demo.py) needs an update. Or did I something wrong?

Thanks,
Wani

Loading Dataset Fails with IndexError

I get the following error when trying to load the database.txt file, which was downloaded according the instructions in this project's readme.

I am using python 2.7 and have nibabel 1.3 installed, as well as the newest numpy/scipy (latest in macports).

website: outdated link to the paper

was not sure where website sources are so, in FAQ you refer to http://pilab.colorado.edu/publications/Yarkoni_NatureMethods_2011.pdf which is not longer avail. I guess should be http://www.talyarkoni.org/papers/Yarkoni_et_al_Nature_Methods.pdf ?

Move tests under testkraut and may be even provide neurosynth.test()

Now tests would also be installed among other python modules (bad) and in any case better to keep them under neurosynth so later on anyone could just do e.g. "nosetests neurosynth" on installed instance to verify its correct operation

4d support for image decoding

Currently the decoding tools only support 3d nifti volumes. We should add 4d support. This should be pretty straightforward; e.g., here's a working script that just splits 4d into 3d up front (but we should do something a bit more principled and detect and handle this seamlessly inside the decoder):

import neurosynth as ns
from neurosynth import Dataset, Decoder
import nibabel as nb
from nilearn.image import resample_img

image = 'my_4d_img.nii.gz'

ns.dataset.download('.', unpack=True)
dataset = Dataset('database.txt', 'features.txt')

# Read image and split 3D volumes into a list
img_4d = nb.load(image)
volumes = nb.funcs.four_to_three(img_4d)

# Resample images to MNI152 dimensions if needed
if volumes[0].shape != (91, 109, 91):
    aff = dataset.masker.volume.get_affine()
    volumes = [resample_img(x, aff, (91, 109, 91)) for x in volumes]

# Initialize decoder and decode
features = ['emotion', 'social', 'memory', 'visual', 'auditory', 'pain',
            'reward']
dec = Decoder(dataset, features=features)
names = ['vol_%d' % (i+1) for i in range(len(volumes))]
dec.decode(volumes, 'decoded_4d_image.txt',
           names=names)

roi_mask flag is broken in cluster.py

This feature should mask within an assigned ROI within the dataset object. Right now I don't believe it is ever used. There are a couple of ways to do this, but we have to be careful that we can still write out the images in the correct space in the end.

This will be important for any ROI based clustering

Extracting info based on coordinate

Hi neurosynth!

This is not a real issue but more of a question.
I want to extract the info from the neurosynth.org/locations/ for Maps/Associations for different MNI coordinates automatically. I have started based on the tutorial (copied bellow) but couldn't figure out how to get those info.
I would appreciate if you could show me the right way or tell me where I should look to find the solution.

from neurosynth import Dataset
from neurosynth import meta, decode, network
import neurosynth as ns
ns.dataset.download(path='.', unpack=True)
from neurosynth.base.dataset import Dataset
dataset = Dataset('database.txt')

average_within_regions does not take Nifiti location string

This was commented out which apparently does what I'm looking for
if not type(regions).module.startswith('numpy'):
regions = dataset.masker.mask(regions)

Not sure why so I uncommented it to add back this functionality (which I need)

cross_validation is deprecated in sklearn 0.20.2

Using the current version of sklearn raises errors from analysis/classify.py in cross_val_fit

It looks like they moved cross_validation.StratifiedKFold to model_selection.StratifiedKFold

Reverting to sklearn 0.16.0 seems to work for now.

add Year to the "Studies" table?

when exploring related studies (e.g. http://neurosynth.org/locations/?x=30&y=-4&z=52#studies) it might be valuable to know how old/new that publication is and/or sort by the year altogether.

Tutorials - the best and the greatest!

hey @yarikoptic and team! I wanted to see if (after the big neurohack events) this tutorial was still the best and the greatest for getting started with neurosynth:

http://nbviewer.jupyter.org/github/neurosynth/neurosynth/blob/master/examples/neurosynth_demo.ipynb

I'm putting together an interactive lesson with neurosynth + cognitive atlas, and if this one is top of the list, I'll start my version from it. I know there was a lot of cool / new content generated with you and @arokem so I wanted to make sure I started with the creamiest of the corn in this brain crop. Thanks much!

travis is broken for python 2.7

Travis seems to be broken for Python 2.7

I submitted a patch that allowed Python 3 users to load a pickled dataset made in Python 2.7. Actually turns out it wasn't that necessary because I just rebuilt my datasets and posted them to the repos of my papers. But in any case, that commit failed a single test on travis that indicates the test dataset was not loaded properly. Reverting my commit (in test_travis branch), did not fix the issue, indicating it has something to do with travis changing, not the neurosynth code. I can't test that easily as I don't have Python 2.7 on my computer at the moment, but will try to take a look later.

DOI for releases

How about associating a DOI with a release: https://github.com/neurosynth/neurosynth/releases/tag/0.3.3, for example with https://zenodo.org/record/32508 so I can cite NeuroSynth not once, but multiple times, for the different releases? :)

distance_mask argument in Clusterer does nothing

The distance_mask argument in the Clusterer initializer currently does nothing and needs to be implemented.

iPython Notebook Needs Update!

The iPython notebook here:

http://nbviewer.ipython.org/github/neurosynth/neurosynth/blob/master/examples/neurosynth_demo.ipynb

should be updated to reflect the current state of the database. Specifically, this part:

"Here we're asking for a list of IDs of all studies that use words starting with 'emo' (e.g.,'emotion', 'emotional', 'emotionally', etc.) at a frequency of 1 in 1,000 words or greater (in other words, if an article has 5,000 words of text, it will only be included in our set if it uses words starting with 'emo' at least 5 times). Let's find out how many studies are in our list:"

should be changed because the weights are no longer "this many words in 1000" frequencies, they are tf-idf (normalized) frequencies.

Change the name to something more snappy

dataset.get_image_data() results in segmentation fault

With new dataset of 9000+ studies, segmentation fault occurs (out of memory?) when converting sparse matrix to nparry dense. Usually I just end up pulling dataset.image_table.data out directly for us if algorithm/procedure supports it. Oh I guess I could turn the dense flag to False, but either way default behavior is problematic.

memory-map data arrays

Currently Neurosynth stores both key tables (activation data and feature data) in memory, which creates major problems for people with < 8 GB of RAM. This should be handled by adding an option at Dataset construction or load time to use memory-mapped arrays wherever possible.

Duecredit integration

Is there any interest in incorporating citations via duecredit? I can take a crack at it if there is.

Can no longer load multiple feature maps on same viewer in new beta release

I'm really liking the new interface a lot, but one annoying thing is that you can no longer compare different feature maps on the same viewer.

-luke

Discretized Values for Forward Inference Maps

It seems that all of the values across forward inference maps are discretized instead of continuous. For example, the z-score forward inference map for "mentalize" only occurs in multiples of 1.04 staring from 0.06.

Move resources UNDER neurosynth or into some other logical location

ATM it installs it among Python modules:

/usr/local/lib/python2.7/dist-packages/resources

and actually may be it is not needed at all? (provides MNI atlas atm, which could be also found under /usr/share/data/fsl-mni152-templates/MNI152_T1_2mm_brain.nii.gz on Debian systems)

feature based clustering returns dense array

Some possible bugs in the new cluster code I noticed when trying out feature based clustering:

1. get_ids_by_features returns a dense array. Later the magic() code assumes a sparse array, so I added the ability to pass a dense flag to get_ids_by_features. This required changing the dataset. Fixed here: 4483860
2. When outputting the clustering I had to change this line to np.float32 rather than float. Otherwise I got error from nibabel (1.3) saying that the datatype was not recognized

 header.set_data_dtype(np.float32)

By the way, I tried to switch to nibabel 2.x but I keep getting this error I was getting before (which is why I switched back to 1.x) saying __dataobj not found. Any clue what's up with that?

3. Some minor stuff which I'm guessing is just to be implemement but might as well point out

• Why is filename required? Thus far, its not used
• Both the ref and roi data use features, even though cocativation_features is a flag

Fix swagger docs and add alias for v2 API

Hello @neurosynth team,

Trying to access http://neurosynth.org/api/v2. Bit, could not found the link to api. Is there any planned maintenance right now ?

Thank you.

need to add check for nibabel version

neurosynth.base.dataset.Dataset.save() fails with earlier versions of nibabel (problem discovered with 1.1.0-dev, works fine with 1.4). Need to include a check for an up-to-date version - not sure where you want to include this test, maybe upon import of the dataset module?

Add topic modeling to analysis.reduce

I am trying to use sklearn's LDA on the feature table, with the same parameters as were used in the Latent Structure modeling paper, but the topics I'm getting back are not nearly as cohesive as the ones on Neurosynth. I noticed that the Neurosynth ones look similar to the full text models from the Latent Structure repository. Are the Neurosynth topic models from the full text or the article abstracts?

It could also be something I'm doing wrong. I took a look at the scripts in the Latent Structure repository, but I'm trying to avoid MALLET in favor of sklearn, if possible. Here is what I have so far:

from __future__ import division
import numpy as np
from sklearn.decomposition import LatentDirichletAllocation as LDA
import pandas as pd


def get_top_words(model, feature_names, n_top_words=40):
    topic_words = []
    for topic in model.components_:
        top_words = [feature_names[i] for i in topic.argsort()[:-n_top_words-1:-1]]
        topic_words += [top_words]
    return topic_words

n_topics = 50
data = pd.read_csv('features.txt', delimiter='\t', index_col='pmid')
X = data.as_matrix()

# doc_topic_prior = alpha
# topic_word_prior = beta
model = LDA(n_topics=n_topics,
            doc_topic_prior=50./n_topics,
            topic_word_prior=0.1)
Xpred = model.fit_transform(X)

topic_words = get_top_words(model, data.columns.tolist())
topic_keys = {'topic_{0:03d}'.format(i): topic_words[i] for i in range(n_topics)}

topic_names = ['topic_{0:03d}'.format(i) for i in range(n_topics)]

pmid_topics = pd.DataFrame(columns=topic_names, data=Xpred, index=data.index)

With this code, I'm getting terms like this (top 40 from topic 5):
['sex', 'little known', 'individuals', 'mood', 'carriers', 'strength', 'sad', 'dysfunction', 'interactions', 'given', 'discrimination', 'volume', 'abilities', 'loss', 'free', '17', '44', 'coherence', 'young', 'making', 'indicate', 'hz', 'sensory', 'allows', 'average', 'sensitive', 'nouns', 'gains', 'detect', 'slow', 'function', 'magnetic', 'impaired', 'thirty', 'connectivity', '20', 'network', 'vocal', 'quantitative', 'consolidation']

As you can see, the topic is a lot noisier than the ones on the website.

"Default mode network" topic returns error

http://neurosynth.org/analyses/4463/

neurosynth-data & decoding error

Dear all,

I am using the decoding function of the neurosynth and noticed the problem that the recently released neurosynth-data (data_0.7.July_2018.tar.gz) cannot be used for the decoding.

See below:
"ValueError: shapes (20,14371) and (10903,24) not aligned: 14371 (dim 1) != 10903 (dim 0)"
The error happened here: x = average_within_regions(decoder.dataset, imgs_to_decode).astype(float).

This line will generated the varaible x with the 14371 columns (instead of 10903).

This problem can be solved using the previously released neurosynth-data (e.g. data_0.5.February_2015.tar.gz)

Best,
Wei

Difference between code and website in number of studies around coordinates

Running get_studies for a peak with a 6mm radius gives me roughly the same number of studies as a Locations search with 12mm radius on the website. I haven't looked into the code, so I don't know which one is right.

Results:

Seed	web r=6	web r=12	code r=6 (02/15 data)
0 0 0	343	1424	1386
20 20 20	95	601	545
46 -40 46	488	2010	1757
-46 -40 46	518	2157	1830
0 32 20	273	1364	1181
0 -48 30	334	1459	1208
-28 -18 -18	299	1345	1212
28 -18 -18	291	1250	1095

database import

Hi,
when I was trying to import the database using other tools (such as MATLAB, Excel etc.) I ran into the following problem:

The delimiter in the database.txt (found in github) is not really consistent, at times 2x \t, at times 3x \t, and sometimes space+3\t.
This makes it difficult to import the data and it'd be nice if it were somewhat more standardized.
Best,
Johannes

What should be the neurosynth's logo?

worth adding some to the neurosynth organization's profile

scipy.stats.ss deprecated

scipy.stats.ss has been fully depreciated, which makes analysis/stats.py unhappy.

(It should be a trivial fix to just drop in the old ss code? But you don't want me mucking around)

Missing dependency: ply

I installed neurosynth with pip:

  pip install neurosynth --user

and I am missing a module called ply:

4th dimensional Nifti image using masker.get_image

Some masks I'm loading are three dimensional but coded as 4 dimensional w/ the 4th dimension being 1. When using masker.get_image(output='vector'), it will fail the test for being in the dataset's space and simply return a 4th dimensional array, which is not the appropriate output.

This is problematic in particular because save_img in img_utils saves a 3 dim img as 4 dimensional.

ply requirement

Readme.md says ply is optional. Present pip version (0.3.3) needs ply. The present Github requirement.txt has ply. Don't you want install_requires setup from requirements.txt?

features.txt cannot be loaded

I get the following error when loading features.txt according to the readme file. I downloaded the latest version, but it fails in python 2.7.

Viewer Bug

I've been having some problems with the viewer since the last update. Specifically, for the decoding results, selecting a neurosynth term will (slowly) add a new layer, but then only the axial view works. Removing the offending layer ends up removing the entire layer table. Unfortunately, this doesn't happen every single time and I haven't been able to figure out the circumstances, but it has happened multiple times on different computers

Add ability to filter IDs by abstract

Per a suggestion from @cjhammond in the comments to this blog post, it would be nice to have something like a filter_ids_by_abstract() method that takes a list of PMIDs as input, retrieves abstracts from PubMed, and allows a Y/N response as to whether to keep them in the list (based on whatever criteria the user wants).

Some decoding pages point to wrong NeuroVault pages

This page for image 9629 http://neurosynth.org/decode/?neurovault=9629 links back to 8947 (which does not exist) causing a broken link: http://neurovault.org/images/8947/

Copyright/License are missing for shipped neurosynth/resources/MNI152_T1_2mm_brain.nii.gz

probably should be added somewhere, e.g. to LICENSE ;)