README.rst 5.5 KB

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