{ "info": { "author": "Denis A. Engemann", "author_email": "denis.engemann@gmail.com", "bugtrack_url": null, "classifiers": [ "Intended Audience :: Developers", "Intended Audience :: Science/Research", "License :: OSI Approved", "Operating System :: MacOS", "Operating System :: Microsoft :: Windows", "Operating System :: POSIX", "Operating System :: Unix", "Programming Language :: Python", "Topic :: Scientific/Engineering", "Topic :: Software Development" ], "description": ".. -*- mode: rst -*-\n\n|Travis|_ |Zenodo|_ |Codecov|_\n\n.. |Travis| image:: https://api.travis-ci.org/mne-tools/mne-hcp.png?branch=master\n.. _Travis: https://travis-ci.org/mne-tools/mne-hcp\n\n.. |Zenodo| image:: https://zenodo.org/badge/53261823.svg\n.. _Zenodo: https://zenodo.org/badge/latestdoi/53261823\n\n.. |Codecov| image:: http://codecov.io/github/mne-tools/mne-hcp/coverage.svg?branch=master\n.. _Codecov: http://codecov.io/github/mne-tools/mne-hcp?branch=master\n\nMNE-HCP\n=======\n\nWe provide Python tools for seamless integration of MEG data from the `Human Connectome Project `_ into the Python ecosystem.\nIn only a few lines of code, complex data retrieval requests can be readily executed on the resources from this neuroimaging reference dataset. Raw HCP data are translated into actionable MNE objects that we know and love. MNE-HCP abstracts away difficulties due to diverging coordinate systems, distributed information, and file format conventions. Providing a simple and consistent access to HCP MEG data will facilitate emergence of standardized data analysis practices.\nBy building on the `MNE software package `_, MNE-HCP naturally supplements a fast growing stack of Python data science toolkits.\n\nFast interface to MEG data\n--------------------------\nAllow us to give you a flavor by a few example queries of MEG HCP data from subject 1003007:\n\n\n.. code-block:: python\n\n # Get all entries from the MEG data header\n info = hcp.read_info('1003007', 'task_motor')\n\n # Get continuous MEG time series\n raw = hcp.read_raw('1003007', 'task_motor')\n\n # Get segmented MEG time series\n epochs = hcp.read_epochs('1003007', 'task_motor')\n\n # Get all MEG time series averaged across events\n list_of_evoked = hcp.read_evokeds('1003007', 'task_motor')\n\n # Get details on contamination and noise sources\n annotations_dict = hcp.read_annot('1003007', 'task_motor')\n\n # Get precomputed independent components that compose the signal time series\n ica_mat = hcp.read_ica('1003007', 'task_motor')\n\nScope and Disclaimer\n--------------------\nThis code is under active research-driven development. The API is still changing,\nbut is getting closer to a stable release.\n\n.. note::\n\n For now please consider the following caveats:\n\n - We only intend to support a subset of the files shipped with HCP.\n - Specifically, for now it is not planned to support io and processing for any outputs of the HCP source space pipelines.\n - This library breaks with some of MNE conventions in order to make the HCP outputs compatible with MNE.\n\nInstallation\n============\n\nWe recommend the `Anaconda Python distribution `_, which comes with the necessary dependencies. Alternatively, to install ``mne-hcp``, you first need to install its dependencies::\n\n\t$ pip install numpy matplotlib scipy scikit-learn mne joblib pandas\n\nThen clone the repository::\n\n\t$ git clone http://github.com/mne-tools/mne-hcp\n\nand finally run `setup.py` to install the package::\n\n\t$ cd mne-hcp/\n\t$ python setup.py install\n\nIf you do not have admin privileges on the computer, use the ``--user`` flag\nwith `setup.py`.\n\nAlternatively, for a devoloper install based on symbolic links (which simplifies keeping up with code changes), do::\n\n\t$ cd mne-hcp/\n\t$ python setup.py develop\n\nTo check if everything worked fine, you can do::\n\n\t$ python -c 'import hcp'\n\nand it should not give any error messages.\n\nDependencies\n------------\n\nThe following main and additional dependencies are required to use MNE-HCP:\n\n - MNE-Python master branch\n - the MNE-Python dependencies, specifically\n - scipy\n - numpy\n - matplotlib\n - scikit-learn (optional)\n\nQuickstart\n==========\n\nThe following data layout is expected: a folder that contains the HCP data\nas they are unpacked by a zip, subject wise.\nWhen data were downloaded via the Aspera connect client, the following\ncommand should produce the expected layout:\n\n.. code-block:: bash\n\n $ for fname in $(ls *zip); do\n $ echo unpacking $fname;\n $ unzip -o $fname; rm $fname;\n $ done\n\nWhen files are downloaded using the `Amazon webservice tools `_, e.g. `s3rcmd`,\nall should be fine.\n\nThe code is organized by different modules.\nThe `io` module includes readers for sensor space data at different processing\nstages and annotations for bad data.\n\n\nTypes of Data\n-------------\n\nMNE-HCP uses custom names for values that are more MNE-pythonic, the following\ntable gives an overview:\n\n+-----------------------+-------------------------------------+----------------+\n| **name** | **readers** | **HCP jargon** |\n+-----------------------+-------------------------------------+----------------+\n| 'rest' | raw, epochs, info, annotations, ica | 'Restin' |\n+-----------------------+-------------------------------------+----------------+\n| 'task_working_memory' | raw, epochs, info, annotations, ica | 'Wrkmem' |\n+-----------------------+-------------------------------------+----------------+\n| 'task_story_math' | raw, epochs, info, annotations, ica | 'StoryM' |\n+-----------------------+-------------------------------------+----------------+\n| 'task_motor' | raw, epochs, info, annotations, ica | 'Motor' |\n+-----------------------+-------------------------------------+----------------+\n| 'noise_subject' | raw, info | 'Pnoise' |\n+-----------------------+-------------------------------------+----------------+\n| 'noise_empty_room' | raw, info | 'Rnoise' |\n+-----------------------+-------------------------------------+----------------+\n\nFunctionality to make the HCP datasets compatible with MNE\n----------------------------------------------------------\n\nMNE HCP comes with convenience functions such as `hcp.make_mne_anatomy`. This one will create an\nMNE friendly anatomy directories and extracts the head model and\ncoregistration MEG to MRI coregistration.\n(Yes, it maps to MRI, not to the helmet -- a peculiarity of the HCP data.)\nIt can be used as follows:\n\n.. code-block:: python\n\n >>> import os.path as op\n >>> import hcp\n >>> storage_dir = op.expanduser('~/data/MNE-HCP')\n >>> hcp.make_mne_anatomy(\n >>> '100307', subjects_dir=storage_dir + '/subjects',\n >>> hcp_path=storage_dir + '/HCP',\n >>> recordings_path=storage_dir + '/hcp-meg')\n reading extended structural processing ...\n reading RAS freesurfer transform\n Combining RAS transform and coregistration\n extracting head model\n coregistring head model to MNE-HCP coordinates\n extracting coregistration\n\n\nFile Mapping\n------------\n\nMNE-HCP supports a low level file mapping that allows for quick compilations\nof sets of files for a given subejct and data context.\nThis is done in :func:`hcp.io.file_mapping.get_file_paths`, think of it as a\nfile name synthesizer that takes certain data description parameters as inputs\nand lists all corresponding files.\n\nExample usage:\n\n.. code-block:: python\n\n >>> import hcp\n >>> files = hcp.file_mapping.et_file_paths(\n >>> subject='123455', data_type='task_motor', output='raw',\n >>> hcp_path='/media/storage/HCP')\n ['/media/storage/HCP/123455/unprocessed/MEG/10-Motor/4D/c,rfDC',\n '/media/storage/HCP/123455/unprocessed/MEG/10-Motor/4D/config']\n\nWhy we are not globbing files? Because the HCP-MEG data are fixed, all file\npatterns are known and access via Amazon web services easier if the files\nto be accessed are known in advance.\n\nGotchas\n=======\n\nNative coordinates and resulting plotting and processing peculartities\n----------------------------------------------------------------------\n\nThe HCP for MEG provides coregistration information for native BTI/4D\nsetting. MNE-Python expects coordinates in meters and the Neuromag\nright anterior superior (RAS) coordinates. However, essential information is\nmissing to compute all transforms needed to easily perform the conversions.\n\nFor now, the way things work, all processing is performed in native BTI/4D\ncoordinates with the device-to-head transform skipped (set to identity matrix),\nsuch that the coregistration directly maps from the native 4D sensors,\nrepresented in head coordinates, to the freesurfer space. This has a few minor\nconsequences that may be confusing to MNE-Python users.\n\n1. In the reader code you will see many flags set to ```convert=False```, etc.\nThis is not a bug.\n\n2. All channel names and positions are native. Topographic plotting might not\nwork as as expected. First of all, the layout file is not recognized. Second,\nthe coordinates are not regonized as native ones, eventually rotating and\ndistorting the graphical display. To fix this, either a proper layout can be\ncomputed with :func:`hcp.viz.make_hcp_bti_layout`.\nOr the conversion to MNE can also be\nperformed using :func:`hcp.preprocessing.map_ch_coords_to_mne`.\nBut note that source localization will be wrong when computed on data in\nNeuromag coordinates. As things are, coordinates have to be kept in the native\nspace to be aligned with the HCP outputs.\n\nReproducing HCP sensor space outputs\n------------------------------------\n\nA couple of steps are necessary to reproduce the original sensor space outputs.\n\n1. Reference channels should be regressed out. Checkout :func:`hcp.preprocessing.apply_ref_correction`.\n\n2. The trial info structure gives the correct latencies of the events\n The latencies in the trigger channel are shifted by around 18 ms.\n For now we'd recommend using the events from the function :func:`hcp.read_trial_info`.\n\n3. The default filters in MNE and FieldTrip are different.\n FieldTrip uses a 4th order butterworth filter. In MNE you might need\n to adjust the `*_trans_bandwidth` parameter to avoid numerical errors.\n In the HCP outputs, evoked responses were filtered between 0.5 and 30Hz prior\n to baseline correction.\n\n4. Annotations need to be loaded and registered. The HCP consortium ships annotations of bad segments and bad channels.\n These have to be read and used. Check out `hcp.read_annot` and add bad\n channel names to `raw.info['bads']` and create and set an `mne.Annotations`\n object as attribute to `raw`, see below.\n\n .. code-block:: python\n\n annots = hcp.read_annot(subject, data_type, hcp_path=hcp_path,\n run_index=run_index)\n bad_segments = annots['segments']['all'] / raw.info['sfreq']\n raw.annotations = mne.Annotations(\n bad_segments[:, 0], (bad_segments[:, 1] - bad_segments[:, 0]),\n description='bad')\n\n5. ICA components related to eye blinks and heart beats need to be removed\n from the data. Checkout the ICA slot in the output of\n `hcp.read_annot` to get the HCP ICA components.\n\n\nConvenience functions\n---------------------\n\nNNE-HCP includes convenience functions that help setting up directory and file layouts\nexpected by MNE-Python.\n\n:func:`hcp.make_mne_anatomy` will produce an MNE and Freesurfer compatible directory layout and will create the following outputs by default, mostly using sympbolic links:\n\n.. code-block:: bash\n\n $subjects_dir/$subject/bem/inner_skull.surf\n $subjects_dir/$subject/label/*\n $subjects_dir/$subject/mri/*\n $subjects_dir/$subject/surf/*\n $recordings_path/$subject/$subject-head_mri-trans.fif\n\nThese can then be set as $SUBJECTS_DIR and as MEG directory, consistent\nwith MNE examples.\nHere, `inner_skull.surf` and `$subject-head_mri-trans.fif` are written by the function such that they can be used by MNE. The latter is the coregistration matrix.\n\nPython Indexing\n^^^^^^^^^^^^^^^\n\nMNE-HCP corrects on reading the indices it finds for data segments, events, or\ncomponents. The indices it reads from the files will already be mapped to\nPython conventions by subtracting 1.\n\nContributions\n-------------\n- currently `@dengemann` is pushing frequently to master, if you plan to contribute, open issues and pull requests, or contact `@dengemann` directly. Discussions are welcomed.\n\nAcknowledgements\n================\n\nThis project is supported by the Amazon Webservices Research grant issued to Denis A. Engemann and\nby the ERC starting grant ERC StG 263584 issued to Virginie van Wassenhove.\n\nI acknowledge support by Alex Gramfort, Mainak Jas, Jona Sassenhagen, Giorgos Michalareas,\nEric Larson, Danilo Bzdok, and Jan-Mathijs Schoffelen for discussions,\ninputs and help with finding the best way to map\nHCP data to the MNE world.", "description_content_type": null, "docs_url": null, "download_url": "http://github.com/mne-tools/mne-hcp", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "http://github.com/mne-tools/mne-hcp", "keywords": null, "license": "BSD (3-clause)", "maintainer": null, "maintainer_email": null, "name": "mne-hcp", "package_url": "https://pypi.org/project/mne-hcp/", "platform": "any", "project_url": "https://pypi.org/project/mne-hcp/", "project_urls": { "Download": "http://github.com/mne-tools/mne-hcp", "Homepage": "http://github.com/mne-tools/mne-hcp" }, "release_url": "https://pypi.org/project/mne-hcp/0.1.dev12/", "requires_dist": null, "requires_python": null, "summary": "MNE HCP project for accessing the human connectome MEG data in Python.", "version": "0.1.dev12" }, "last_serial": 2375364, "releases": { "0.1.dev1": [ { "comment_text": "", "digests": { "md5": "5d664a9de85a7212ccd4081517813650", "sha256": "bdfd45566286665f63a36c19f54709b10f7009f38e2af29857191edf75f5da82" }, "downloads": -1, "filename": "mne-hcp-0.1.dev1.tar.gz", "has_sig": false, "md5_digest": "5d664a9de85a7212ccd4081517813650", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 20014, "upload_time": "2016-09-15T16:33:10", "url": "https://files.pythonhosted.org/packages/3f/5e/f6940b651235e7842aeb8350b9a6590b6526a89901b590e99e61b0a9ac0f/mne-hcp-0.1.dev1.tar.gz" } ], "0.1.dev11": [ { "comment_text": "", "digests": { "md5": "48e9d472ddc843826cf0c7b35e459e22", "sha256": "89fb5d8db711ff270f07428b867326437a2f1cb04d38b8fcf0a2a3353264c79d" }, "downloads": -1, "filename": "mne-hcp-0.1.dev11.tar.gz", "has_sig": false, "md5_digest": "48e9d472ddc843826cf0c7b35e459e22", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 25594, "upload_time": "2016-10-01T22:11:46", "url": "https://files.pythonhosted.org/packages/91/59/6ba8abd9acefa1673be0e82e9094f3fe7158c19dd81ba0b78db62ab2a193/mne-hcp-0.1.dev11.tar.gz" } ], "0.1.dev12": [ { "comment_text": "", "digests": { "md5": "cae0e391a5b0aec5055e98475eec1e78", "sha256": "f5d72963cd0df9a56085812bb14fe545fce01dc46b6c925fa238afc85c406141" }, "downloads": -1, "filename": "mne-hcp-0.1.dev12.tar.gz", "has_sig": false, "md5_digest": "cae0e391a5b0aec5055e98475eec1e78", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 25601, "upload_time": "2016-10-01T22:16:55", "url": "https://files.pythonhosted.org/packages/00/55/05d82a97aea9c689e51e4bbd8ae5195b7a5720150339b99439880ffc489e/mne-hcp-0.1.dev12.tar.gz" } ], "0.1.dev6": [ { "comment_text": "", "digests": { "md5": "95cd532e77b35abc626e8c7cb45bd336", "sha256": "af2aecaf157dae3846a08e5ce4a7fbee21eab316799fe1387dce6198cf748ae4" }, "downloads": -1, "filename": "mne-hcp-0.1.dev6.tar.gz", "has_sig": false, "md5_digest": "95cd532e77b35abc626e8c7cb45bd336", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 20348, "upload_time": "2016-09-16T16:41:26", "url": "https://files.pythonhosted.org/packages/88/75/e6a956fe13c38892051b33e8d14f348b4d0fc286bbf0ed9235c230457b12/mne-hcp-0.1.dev6.tar.gz" } ], "0.1.dev8": [ { "comment_text": "", "digests": { "md5": "95a0c000a0049f796b9247a82af31ab4", "sha256": "54492452f2afedcaf63172073cdaf3ec28432341b1ff661c10fd580fdc33d463" }, "downloads": -1, "filename": "mne-hcp-0.1.dev8.tar.gz", "has_sig": false, "md5_digest": "95a0c000a0049f796b9247a82af31ab4", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 25598, "upload_time": "2016-10-01T22:09:25", "url": "https://files.pythonhosted.org/packages/a6/82/7b4cb6d75dbe28580fade41b9c3457b40596bfcfb06592423f8b9d1077f2/mne-hcp-0.1.dev8.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "cae0e391a5b0aec5055e98475eec1e78", "sha256": "f5d72963cd0df9a56085812bb14fe545fce01dc46b6c925fa238afc85c406141" }, "downloads": -1, "filename": "mne-hcp-0.1.dev12.tar.gz", "has_sig": false, "md5_digest": "cae0e391a5b0aec5055e98475eec1e78", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 25601, "upload_time": "2016-10-01T22:16:55", "url": "https://files.pythonhosted.org/packages/00/55/05d82a97aea9c689e51e4bbd8ae5195b7a5720150339b99439880ffc489e/mne-hcp-0.1.dev12.tar.gz" } ] }