README.rst 5.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118
  1. freesurfer-stats
  2. ================
  3. .. image:: https://travis-ci.org/fphammerle/freesurfer-stats.svg?branch=master
  4. :target: https://travis-ci.org/fphammerle/freesurfer-stats
  5. .. image:: https://coveralls.io/repos/github/fphammerle/freesurfer-stats/badge.svg?branch=master
  6. :target: https://coveralls.io/github/fphammerle/freesurfer-stats?branch=master
  7. .. image:: https://img.shields.io/pypi/v/freesurfer-stats.svg
  8. :target: https://pypi.org/project/freesurfer-stats/#history
  9. .. image:: https://img.shields.io/pypi/pyversions/freesurfer-stats.svg
  10. :target: https://pypi.org/project/freesurfer-stats/
  11. .. image:: https://zenodo.org/badge/194054168.svg
  12. :target: https://zenodo.org/badge/latestdoi/194054168
  13. Python Library to Read FreeSurfer's Cortical Parcellation Anatomical Statistics
  14. `subject/stats/[rl]h.aparc.*.stats`
  15. Freesurfer https://surfer.nmr.mgh.harvard.edu/
  16. Install
  17. -------
  18. .. code:: sh
  19. pip3 install --user freesurfer-stats
  20. Releases follow the `semantic versioning <https://semver.org/>` scheme.
  21. Usage
  22. -----
  23. .. code:: python
  24. >>> from freesurfer_stats import CorticalParcellationStats
  25. >>> stats = CorticalParcellationStats.read('tests/subjects/fabian/stats/lh.aparc.DKTatlas.stats')
  26. >>> stats.headers['subjectname']
  27. 'fabian'
  28. >>> stats.headers['CreationTime'].isoformat()
  29. '2019-05-09T21:05:54+00:00'
  30. >>> stats.headers['cvs_version']
  31. 'Id: mris_anatomical_stats.c,v 1.79 2016/03/14 15:15:34 greve Exp'
  32. >>> stats.headers['cmdline'][:64]
  33. 'mris_anatomical_stats -th3 -mgz -cortex ../label/lh.cortex.label'
  34. >>> stats.hemisphere
  35. 'left'
  36. >>> stats.whole_brain_measurements['estimated_total_intracranial_volume_mm^3']
  37. 0 1.670487e+06
  38. Name: estimated_total_intracranial_volume_mm^3, dtype: float64
  39. >>> stats.whole_brain_measurements['white_surface_total_area_mm^2']
  40. 0 98553
  41. Name: white_surface_total_area_mm^2, dtype: int64
  42. >>> stats.structural_measurements[['structure_name', 'surface_area_mm^2',
  43. ... 'gray_matter_volume_mm^3']].head()
  44. structure_name surface_area_mm^2 gray_matter_volume_mm^3
  45. 0 caudalanteriorcingulate 1472 4258
  46. 1 caudalmiddlefrontal 3039 8239
  47. 2 cuneus 2597 6722
  48. 3 entorhinal 499 2379
  49. 4 fusiform 3079 9064
  50. Load Multiple Stats Files
  51. ~~~~~~~~~~~~~~~~~~~~~~~~~
  52. .. code:: python
  53. >>> import glob, pandas
  54. >>> from freesurfer_stats import CorticalParcellationStats
  55. >>> def load_whole_brain_measurements(stats_path) -> pandas.DataFrame:
  56. ... stats = CorticalParcellationStats.read(stats_path)
  57. ... stats.whole_brain_measurements['subject'] = stats.headers['subjectname']
  58. ... stats.whole_brain_measurements['source_basename'] = os.path.basename(stats_path)
  59. ... stats.whole_brain_measurements['hemisphere'] = stats.hemisphere
  60. ... return stats.whole_brain_measurements
  61. ...
  62. >>> whole_brain_measurements = pandas.concat(
  63. ... map(load_whole_brain_measurements, glob.glob('tests/subjects/fabian/stats/*h.aparc*.stats')),
  64. ... sort=False)
  65. >>> whole_brain_measurements.reset_index(drop=True, inplace=True)
  66. >>> whole_brain_measurements[['subject', 'source_basename', 'hemisphere',
  67. ... 'white_surface_total_area_mm^2', 'pial_surface_total_area_mm^2']]
  68. subject source_basename hemisphere white_surface_total_area_mm^2 pial_surface_total_area_mm^2
  69. 0 fabian lh.aparc.DKTatlas.stats left 98553.0 NaN
  70. 1 fabian rh.aparc.stats right 99468.9 NaN
  71. 2 fabian rh.aparc.a2009s.stats right 99494.9 NaN
  72. 3 fabian rh.aparc.DKTatlas.stats right 99494.9 NaN
  73. 4 fabian lh.aparc.stats left 98536.5 NaN
  74. 5 fabian lh.aparc.pial.stats left NaN 118601.0
  75. 6 fabian rh.aparc.pial.stats right NaN 121260.0
  76. 7 fabian lh.aparc.a2009s.stats left 98553.0 NaN
  77. Load Stats File From Webserver, Amazon S3 or Google Cloud Storage
  78. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  79. .. code:: python
  80. >>> from freesurfer_stats import CorticalParcellationStats
  81. >>> freesurfer_stats.CorticalParcellationStats('https://[...]/stats/rh.aparc.stats').read()
  82. >>> stats.whole_brain_measurements['total_cortical_gray_matter_volume_mm^3']
  83. 0 553998.311189
  84. Name: total_cortical_gray_matter_volume_mm^3, dtype: float64
  85. Replace `https://` with `s3://` or `gcs://`.
  86. Credentials for S3 may be provided in `~/.aws/credentials`
  87. or via environment variables.
  88. See [S3Fs docs](https://s3fs.readthedocs.io/en/latest/#credentials).
  89. Tests
  90. -----
  91. .. code:: sh
  92. pip3 install --user pipenv
  93. git clone https://github.com/fphammerle/freesurfer-stats.git
  94. cd freesurfer-stats
  95. pipenv sync --dev
  96. pipenv run pylint freesurfer_stats
  97. pipenv run pytest