No Description

Fabian Peter Hammerle f81abee7ff CorticalParcellationStats.read: adapt to get_filepath_or_buffer not returning should_close in pandas v0.21.0 & v0.22.0 4 years ago
freesurfer_stats f81abee7ff CorticalParcellationStats.read: adapt to get_filepath_or_buffer not returning should_close in pandas v0.21.0 & v0.22.0 4 years ago
tests 35c2e51fa8 CorticalParcellationStats.read: support pathlib.Path, http, s3 etc. via pandas.io.common.get_filepath_or_buffer 4 years ago
.gitignore dfe6215926 added changelog 4 years ago
.pylintrc 3a2481c161 CorticalParcellationStats.read: stricter parsing to avoid silent errors; added "BrainVolStatsFixed" header 4 years ago
.style.yapf d8cf13e57b setup yapf (pep8 style) 5 years ago
.travis.yml fb0b0a9a50 pipeline: enable pylint-import-requirements plugin 4 years ago
CHANGELOG.md 35c2e51fa8 CorticalParcellationStats.read: support pathlib.Path, http, s3 etc. via pandas.io.common.get_filepath_or_buffer 4 years ago
COPYING 87d07d3aa5 added GPLv3+ license 4 years ago
Pipfile fb0b0a9a50 pipeline: enable pylint-import-requirements plugin 4 years ago
Pipfile.lock fb0b0a9a50 pipeline: enable pylint-import-requirements plugin 4 years ago
README.rst 904c1be3ee readme: document url loading 4 years ago
setup.py d807824ef0 setup.py: added missing dependency "numpy" 4 years ago

README.rst

freesurfer-stats
================

.. image:: https://travis-ci.org/fphammerle/freesurfer-stats.svg?branch=master
:target: https://travis-ci.org/fphammerle/freesurfer-stats
.. image:: https://coveralls.io/repos/github/fphammerle/freesurfer-stats/badge.svg?branch=master
:target: https://coveralls.io/github/fphammerle/freesurfer-stats?branch=master
.. image:: https://img.shields.io/pypi/v/freesurfer-stats.svg
:target: https://pypi.org/project/freesurfer-stats/#history
.. image:: https://img.shields.io/pypi/pyversions/freesurfer-stats.svg
:target: https://pypi.org/project/freesurfer-stats/
.. image:: https://zenodo.org/badge/194054168.svg
:target: https://zenodo.org/badge/latestdoi/194054168

Python Library to Read FreeSurfer's Cortical Parcellation Anatomical Statistics
`subject/stats/[rl]h.aparc.*.stats`

Freesurfer https://surfer.nmr.mgh.harvard.edu/

Install
-------

.. code:: sh

pip3 install --user freesurfer-stats

Releases follow the `semantic versioning ` scheme.

Usage
-----

.. code:: python

>>> from freesurfer_stats import CorticalParcellationStats
>>> stats = CorticalParcellationStats.read('tests/subjects/fabian/stats/lh.aparc.DKTatlas.stats')
>>> stats.headers['subjectname']
'fabian'
>>> stats.headers['CreationTime'].isoformat()
'2019-05-09T21:05:54+00:00'
>>> stats.headers['cvs_version']
'Id: mris_anatomical_stats.c,v 1.79 2016/03/14 15:15:34 greve Exp'
>>> stats.headers['cmdline'][:64]
'mris_anatomical_stats -th3 -mgz -cortex ../label/lh.cortex.label'
>>> stats.hemisphere
'left'
>>> stats.whole_brain_measurements['estimated_total_intracranial_volume_mm^3']
0 1.670487e+06
Name: estimated_total_intracranial_volume_mm^3, dtype: float64
>>> stats.whole_brain_measurements['white_surface_total_area_mm^2']
0 98553
Name: white_surface_total_area_mm^2, dtype: int64
>>> stats.structural_measurements[['structure_name', 'surface_area_mm^2',
... 'gray_matter_volume_mm^3']].head()
structure_name surface_area_mm^2 gray_matter_volume_mm^3
0 caudalanteriorcingulate 1472 4258
1 caudalmiddlefrontal 3039 8239
2 cuneus 2597 6722
3 entorhinal 499 2379
4 fusiform 3079 9064

Load Multiple Stats Files
~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: python

>>> import glob, pandas
>>> from freesurfer_stats import CorticalParcellationStats
>>> def load_whole_brain_measurements(stats_path) -> pandas.DataFrame:
... stats = CorticalParcellationStats.read(stats_path)
... stats.whole_brain_measurements['subject'] = stats.headers['subjectname']
... stats.whole_brain_measurements['source_basename'] = os.path.basename(stats_path)
... stats.whole_brain_measurements['hemisphere'] = stats.hemisphere
... return stats.whole_brain_measurements
...
>>> whole_brain_measurements = pandas.concat(
... map(load_whole_brain_measurements, glob.glob('tests/subjects/fabian/stats/*h.aparc*.stats')),
... sort=False)
>>> whole_brain_measurements.reset_index(drop=True, inplace=True)
>>> whole_brain_measurements[['subject', 'source_basename', 'hemisphere',
... 'white_surface_total_area_mm^2', 'pial_surface_total_area_mm^2']]
subject source_basename hemisphere white_surface_total_area_mm^2 pial_surface_total_area_mm^2
0 fabian lh.aparc.DKTatlas.stats left 98553.0 NaN
1 fabian rh.aparc.stats right 99468.9 NaN
2 fabian rh.aparc.a2009s.stats right 99494.9 NaN
3 fabian rh.aparc.DKTatlas.stats right 99494.9 NaN
4 fabian lh.aparc.stats left 98536.5 NaN
5 fabian lh.aparc.pial.stats left NaN 118601.0
6 fabian rh.aparc.pial.stats right NaN 121260.0
7 fabian lh.aparc.a2009s.stats left 98553.0 NaN

Load Stats File From Webserver, Amazon S3 or Google Cloud Storage
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: python

>>> from freesurfer_stats import CorticalParcellationStats
>>> freesurfer_stats.CorticalParcellationStats('https://[...]/stats/rh.aparc.stats').read()
>>> stats.whole_brain_measurements['total_cortical_gray_matter_volume_mm^3']
0 553998.311189
Name: total_cortical_gray_matter_volume_mm^3, dtype: float64

Replace `https://` with `s3://` or `gcs://`.

Credentials for S3 may be provided in `~/.aws/credentials`
or via environment variables.
See [S3Fs docs](https://s3fs.readthedocs.io/en/latest/#credentials).

Tests
-----

.. code:: sh

pip3 install --user pipenv
git clone https://github.com/fphammerle/freesurfer-stats.git
cd freesurfer-stats
pipenv sync --dev
pipenv run pylint freesurfer_stats
pipenv run pytest