Merge pull request #108 from justinehansen/docs

[ENH] Update docs and readme to highlight citations

README.rst

@@ -2,6 +2,7 @@
 
 The ``neuromaps`` toolbox is designed to help researchers make easy,
 statistically-rigorous comparisons between brain maps (or brain annotations).
+Documentation can be found `here <https://netneurolab.github.io/neuromaps/>`_.
 
 The accompanying paper is published in `Nature Methods <https://www.nature.com/articles/s41592-022-01625-w>`_.
 
@@ -41,8 +42,13 @@ Citation
 --------
 
 If you use the ``neuromaps`` toolbox, please cite our `paper <https://www.nature.com/articles/s41592-022-01625-w>`_.
+**Importantly**, ``neuromaps`` implements and builds on tools that have been previously developed, and we redistribute data that was acquired elsewhere.
+Please be sure to cite the appropriate literature when using ``neuromaps``, which we detail below.
 
-**Importantly**, ``neuromaps`` redistributes original work performed by other groups. Therefore, if you use data included in the ``neuromaps`` repository, please make sure to cite the original papers that published this data. A table with references for each brain map can be found at this link: https://docs.google.com/spreadsheets/d/1oZecOsvtQEh5pQkIf8cB6CyhPKVrQuko.
+- If you use volume-to-surface transformations (registration fusion), please cite `Buckner et al 2011 <https://journals.physiology.org/doi/full/10.1152/jn.00339.2011>`_ (original proposition) and `Wu et al 2018 <https://onlinelibrary.wiley.com/doi/10.1002/hbm.24213>`_ (first implementation of MNI152 to fsaverage transformation).
+- If you use surface-to-surface transformations (multimodal surface matching), please cite `Robinson et al 2014 <https://www.sciencedirect.com/science/article/pii/S1053811914004546?via%3Dihub>`_ and `Robinson et al 2018 <https://www.sciencedirect.com/science/article/pii/S1053811917308649?via%3Dihub>`_.
+- If you use data included in ``neuromaps``, please cite the the original papers that publish the data. A table with references for each brain annotation can be found in our `wiki <https://github.com/netneurolab/neuromaps/wiki>`_, or more specifically, at `this <https://docs.google.com/spreadsheets/d/1oZecOsvtQEh5pQkIf8cB6CyhPKVrQuko/edit?rtpof=true&sd=true#gid=1162991686>`_ link.
+- If you use the spatial null models, there is an associated citation with each type of null model. They can be found in the docstring of the function, and also `here <https://netneurolab.github.io/neuromaps/api.html#module-neuromaps.nulls>`_. 
 
 License information
 -------------------

docs/citing.rst

@@ -11,6 +11,13 @@ following manuscripts when referencing your use of the toolbox:
    Blostein, N, Seidlitz, J, Baillet, S, Satterthwaite, TD, Chakravarty, MM, Raznahan, A, Misic, B. 
    (2022). neuromaps: structural and functional interpretation of brain maps. 
    Nature Methods. doi:`10.1038/s41592-022-01625-w <https://doi.org/10.1038/s41592-022-01625-w>`__
+2. If you use volume-to-surface transformations (registration fusion), please cite `Buckner et al 2011    <https://journals.physiology.org/doi/full/10.1152/jn.00339.2011>`_ (original proposition) and `Wu et al 2018 <https://onlinelibrary.wiley.com/doi/10.1002/hbm.24213>`_ (first implementation of MNI152 to fsaverage transformation).
+3. If you use surface-to-surface transformations (multimodal surface matching), please cite `Robinson et  al 2014 <https://www.sciencedirect.com/science/article/pii/S1053811914004546?via%3Dihub>`_ and `Robinson et al 2018 <https://www.sciencedirect.com/science/article/pii/S1053811917308649?via%3Dihub>`_.
+4. If you use data included in ``neuromaps``, please cite the the original papers that publish the data.
+A table with references for each brain map can be found in our `wiki <https://github.com/netneurolab/neuromaps/wiki>`_, or more specifically, at `this <https://docs.google.com/spreadsheets/d/1oZecOsvtQEh5pQkIf8cB6CyhPKVrQuko/edit?rtpof=true&sd=true#gid=1162991686>`_ link.
+5. If you use the spatial null models, there is an associated citation with each type of null model.
+They can be found in the docstring of the function, and also `here <https://netneurolab.github.io/neuromaps/api.html#module-neuromaps.nulls>`_. 
+
 
 Additionally, to cite the specific version of the toolbox used in your analyses
 you can use the following Zenodo reference:
@@ -50,10 +57,6 @@ you can use the following Zenodo reference:
 .. older releases please refer to the `Zenodo listing <https://zenodo.org/search?
 .. page=1&size=20&q=conceptrecid:%223451463%22&sort=-version&all_versions=True>`__.
 
-If you use data included in the ``neuromaps`` repository, be sure to cite the original 
-paper that published this data.
-A table with references for each brain map can be found in the `Wiki <https://github.com/netneurolab/neuromaps/wiki/Annotation-information>`_.
-
 For more information about why citing software is important please refer to
 `this article <https://www.software.ac.uk/how-cite-software>`_ from the
 Software Sustainability Institute.

docs/user_guide/annotations.rst

@@ -9,7 +9,18 @@ These annotations are spatial maps representing some feature of interest and
 are available in at least one of the four standard coordinate systems.
 
 We have curated a set of brain annotations that we make available through a
-standard interface. You can search for available annotations using the
+standard interface.
+More details about each annotation can be found in our `Wiki 
+<https://github.com/netneurolab/neuromaps/wiki/Annotation-information>`_.
+
+.. important::
+
+    ``neuromaps`` curates data that was acquired by other groups.
+    If you fetch data from ``neuromaps``, please cite the accompanying
+    papers listed for each annotation in the `Wiki
+    <https://github.com/netneurolab/neuromaps/wiki/Annotation-information>`_.
+
+You can search for available annotations using the
 :func:`neuromaps.datasets.available_annotations` function:
 
 .. code-block::
@@ -39,9 +50,7 @@ second entry in the tuple provides a brief description of what the map
 represents. (Because these descriptors are encoded directly in the filenames of
 the relevant maps we are somewhat limited in terms of space.) The last two
 entries in the tuple correspond to the coordinate system and density/resolution
-in which the annotations are provided. More details on each annotation, as well
-as papers to cite if you use the data, exist on our `Wiki 
-<https://github.com/netneurolab/neuromaps/wiki/Annotation-information>`_.
+in which the annotations are provided.
 
 This function also accepts keyword arguments in case we want to narrow down the
 list of returned annotations: