Merge pull request #199 from rmarkello/add_preprint

[DOC] Adds reference to preprint + updates citation

Author: rmarkello

README.rst

@@ -38,9 +38,12 @@ parcels or networks), and (2) combined across donors. While this may
 potentially seem trivial, there are a number of analytic choices in these steps
 that can dramatically influence the resulting data and any downstream analyses.
 Arnatkevičiūte et al., 2019 provided a thorough treatment of this in a `recent
-manuscript <https://www.sciencedirect.com/science/article/pii/
+publication <https://www.sciencedirect.com/science/article/pii/
 S1053811919300114>`__, demonstrating how the techniques and code used to
-prepare the raw AHBA data have varied widely across published reports.
+prepare the raw AHBA data have varied widely across published reports. We
+extended this work in a `recent preprint <https://doi.org/10.1101/
+2021.07.08.451635>`__ (Markello et al., 2021) to quantify how different
+processing choices can impact statistical analyses of the AHBA.
 
 The current Python package, ``abagen``, aims to provide reproducible workflows
 for processing and preparing the AHBA microarray expression data for analysis.

abagen/reporting.py

@@ -40,6 +40,9 @@
             'Dolbeare, T., Guillozet-Bongaarts, A. L., ... & Lein, E. '
             '(2015). Canonical genetic signatures of the adult human '
             'brain. Nature Neuroscience, 18(12), 1832.'),
+    M2021B=('Markello, R.D., Arnatkevic̆iūtė, A., Poline, J-B., Fulcher, B. '
+            'D., Fornito, A., & Misic, B. (2021). Standardizing workflows in '
+            'imaging transcriptomics with the abagen toolbox. Biorxiv.'),
     P2017G=('Parkes, L., Fulcher, B. D., Yücel, M., & Fornito, A. '
             '(2017). Transcriptional signatures of connectomic '
             'subregions of the human striatum. Genes, Brain and '
@@ -109,7 +112,8 @@ def gen_report(self):
         post-mortem brains ({n_female} female, ages {min}--{max}, {mean:.2f}
         +/- {std:.2f}) provided by the Allen Human Brain Atlas (AHBA,
         https://human.brain-map.org; [H2012N]). Data were processed with the
-        abagen toolbox (version {vers}; https://github.com/rmarkello/abagen)
+        abagen toolbox (version {vers}; https://github.com/rmarkello/abagen;
+        [M2021B])
         """.format(**_get_donor_demographics(self.donors), vers=__version__)
 
         if self.atlas.volumetric and self.group_atlas:

docs/citing.rst

@@ -4,44 +4,64 @@
 Citing abagen
 -------------
 
+.. note::
+
+    We strongly encourage you to use the :ref:`automatically-generated methods
+    reports <usage_reporting>` built into ``abagen``, which will provide a list
+    of citations based on your selected processing options!
+
 We're thrilled you've found ``abagen`` useful in your work! Please cite the
-following when referring to your use of the toolbox:
+following manuscripts when referencing your use of the toolbox:
+
+1. Markello, RD, Arnatkevic̆iūtė, A, Poline, J-B, Fulcher, BD, Fornito, A, &
+   Misic, B. (2021). Standardizing workflows in imaging transcriptomics with
+   the abagen toolbox. Biorxiv. doi:`10.1101/2021.07.08.451635 <https://doi.org/
+   10.1101/2021.07.08.451635>`__
+2. Arnatkevic̆iūtė, A, Fulcher, BD, & Fornito, A. (2019). A practical guide to
+   linking brain-wide gene expression and neuroimaging data. NeuroImage, 189,
+   353-367. doi:`10.1016/j.neuroimage.2019.01.011 <https://doi.org/10.1016/
+   j.neuroimage.2019.01.011>`__
+3. Hawrylycz, MJ, Lein, ES, Guillozet-Bongaarts, AL, Shen, EH, Ng, L, Miller,
+   JA, …, & Jones, AR. (2012). An anatomically comprehensive atlas of the adult
+   human brain transcriptome. Nature, 489(7416), 391–399.
+   doi:`10.1038/nature11405 <https://doi.org/10.1038/nature11405>`__
+
+Additionally, to cite the specific version of the toolbox used in your analyses
+you can use the following Zenodo reference:
 
 .. raw:: html
 
-   <script language="javascript">
-   var version = 'latest';
-   function fillCitation(){
-      $('#abagen_version').text(version);
-
-      function cb(err, zenodoID) {
-         getCitation(zenodoID, 'vancouver-brackets-no-et-al', function(err, citation) {
-            $('#abagen_citation').text(citation);
-         });
-         getDOI(zenodoID, function(err, DOI) {
-            $('#abagen_doi_url').text('https://doi.org/' + DOI);
-            $('#abagen_doi_url').attr('href', 'https://doi.org/' + DOI);
-         });
-      }
-
-      if(version == 'latest') {
-         getLatestIDFromconceptID("3451463", cb);
-      } else {
-         getZenodoIDFromTag("3451463", version, cb);
-      }
-   }
-   </script>
-
-   <p style="margin-left: 30px">
-     <span id="abagen_citation">abagen</span> Available from: <a id="abagen_doi_url" href="https://doi.org/10.5281/zenodo.3451463">10.5281/zenodo.3451463</a>.
-     <img src onerror='fillCitation()' alt="" />
-   </p>
-   <p style="margin-left: 30px">
-     2. Arnatkevic̆iūtė, Aurina, Fulcher, Ben D., Fornito, Alex (2019). A practical guide to linking brain-wide gene expression and neuroimaging data. NeuroImage, 189, 353-367. doi:10.1016/j.neuroimage.2019.01.011
-   </p>
-   <p style="margin-left: 30px">
-     3. Hawrylycz, Michael J., Lein, Ed S., Guillozet-Bongaarts, Angela L., Shen, Elaine H., Ng, Lydia, Miller, Jeremy A., … Jones, Allan R. (2012). An anatomically comprehensive atlas of the adult human brain transcriptome. Nature, 489(7416), 391–399. doi:10.1038/nature11405
-   </p>
+    <script language="javascript">
+    var version = 'latest';
+    function fillCitation(){
+       $('#abagen_version').text(version);
+
+       function cb(err, zenodoID) {
+          getCitation(zenodoID, 'vancouver-brackets-no-et-al', function(err, citation) {
+             $('#abagen_citation').text(citation);
+          });
+          getDOI(zenodoID, function(err, DOI) {
+             $('#abagen_doi_url').text('https://doi.org/' + DOI);
+             $('#abagen_doi_url').attr('href', 'https://doi.org/' + DOI);
+          });
+       }
+
+       if(version == 'latest') {
+          getLatestIDFromconceptID("3451463", cb);
+       } else {
+          getZenodoIDFromTag("3451463", version, cb);
+       }
+    }
+    </script>
+
+    <p style="margin-left: 30px">
+      <span id="abagen_citation">abagen</span> Available from: <a id="abagen_doi_url" href="https://doi.org/10.5281/zenodo.3451463">10.5281/zenodo.3451463</a>.
+      <img src onerror='fillCitation()' alt="" />
+    </p>
+
+Note that this will always point to the most recent ``abagen`` release; for
+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>`__.
 
 For more information about why citing software is important please refer to
 `this article <https://www.software.ac.uk/how-cite-software>`_ from the