├── Computing └── README.md ├── LICENSE ├── LICENSE_other ├── NewMembers ├── GradsAndPostdocs.md ├── GroupPoliciesProcedures │ ├── TimeOff.md │ └── TravelReimbursement.md ├── IntroToSlack.md ├── README.md ├── Undergrads.md └── WorkingInTheMobleyLab.md ├── README.md ├── SciBiz ├── DealingWithPeerReview.md └── README.md └── Writing ├── README.md ├── StyleGuide.md └── WritingTips.md /Computing/README.md: -------------------------------------------------------------------------------- 1 | # Computing and coding 2 | 3 | ## Helpful resources 4 | 5 | ### Linux, command-line, Python etc.: 6 | - For very helpful material on Linux and Python relevant to our area, refer to [Oliver Beckstein's Computational Methods in Physics course](https://asu-compmethodsphysics-phy494.github.io/ASU-PHY494/overview/), which has sectionns on Linux/Unix, Python, git, etc. 7 | - For additional background information on Linux, check out [Code Academy's course](https://www.codecademy.com/learn/learn-the-command-line). 8 | - MIT has a nice course, [The Missing Semester of Your CS Education](https://missing.csail.mit.edu/) which covers the shell, shell tools/scripting, editors, data, command-line, version control, debugging and profiling, security and cryptography, and a variety of other topics. 9 | - [explainshell](https://explainshell.com/explain?cmd=ssh++-Fc+-N+-f+hs) provides a place where you can type in Linux shell commands and it will explain them to you 10 | 11 | ### Trainings relating to computer-aided drug design with Python 12 | - [My course in Computing Techniques in Drug Discovery](https://github.com/MobleyLab/drug-computing) 13 | 14 | ### Numerical methods and error analysis 15 | - [Andrew White's Numerical Methods and Statistics](https://whitead.github.io/numerical_stats/) 16 | - [Best Practices for Quantification of Uncertainty and Sampling Quality in Molecular Simulations](https://www.livecomsjournal.org/index.php/livecoms/article/view/v1i1e5067) 17 | 18 | ### Deep learning/machine learning 19 | - Andrew White's [Deep Learning for Molecules and Materials](https://dmol.pub/intro.html) 20 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2021 Mobley Lab at UC Irvine 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /LICENSE_other: -------------------------------------------------------------------------------- 1 | Attribution 4.0 International 2 | 3 | ======================================================================= 4 | 5 | Creative Commons Corporation ("Creative Commons") is not a law firm and 6 | does not provide legal services or legal advice. Distribution of 7 | Creative Commons public licenses does not create a lawyer-client or 8 | other relationship. Creative Commons makes its licenses and related 9 | information available on an "as-is" basis. Creative Commons gives no 10 | warranties regarding its licenses, any material licensed under their 11 | terms and conditions, or any related information. Creative Commons 12 | disclaims all liability for damages resulting from their use to the 13 | fullest extent possible. 14 | 15 | Using Creative Commons Public Licenses 16 | 17 | Creative Commons public licenses provide a standard set of terms and 18 | conditions that creators and other rights holders may use to share 19 | original works of authorship and other material subject to copyright 20 | and certain other rights specified in the public license below. The 21 | following considerations are for informational purposes only, are not 22 | exhaustive, and do not form part of our licenses. 23 | 24 | Considerations for licensors: Our public licenses are 25 | intended for use by those authorized to give the public 26 | permission to use material in ways otherwise restricted by 27 | copyright and certain other rights. Our licenses are 28 | irrevocable. Licensors should read and understand the terms 29 | and conditions of the license they choose before applying it. 30 | Licensors should also secure all rights necessary before 31 | applying our licenses so that the public can reuse the 32 | material as expected. Licensors should clearly mark any 33 | material not subject to the license. This includes other CC- 34 | licensed material, or material used under an exception or 35 | limitation to copyright. More considerations for licensors: 36 | wiki.creativecommons.org/Considerations_for_licensors 37 | 38 | Considerations for the public: By using one of our public 39 | licenses, a licensor grants the public permission to use the 40 | licensed material under specified terms and conditions. If 41 | the licensor's permission is not necessary for any reason--for 42 | example, because of any applicable exception or limitation to 43 | copyright--then that use is not regulated by the license. Our 44 | licenses grant only permissions under copyright and certain 45 | other rights that a licensor has authority to grant. Use of 46 | the licensed material may still be restricted for other 47 | reasons, including because others have copyright or other 48 | rights in the material. A licensor may make special requests, 49 | such as asking that all changes be marked or described. 50 | Although not required by our licenses, you are encouraged to 51 | respect those requests where reasonable. More_considerations 52 | for the public: 53 | wiki.creativecommons.org/Considerations_for_licensees 54 | 55 | ======================================================================= 56 | 57 | Creative Commons Attribution 4.0 International Public License 58 | 59 | By exercising the Licensed Rights (defined below), You accept and agree 60 | to be bound by the terms and conditions of this Creative Commons 61 | Attribution 4.0 International Public License ("Public License"). To the 62 | extent this Public License may be interpreted as a contract, You are 63 | granted the Licensed Rights in consideration of Your acceptance of 64 | these terms and conditions, and the Licensor grants You such rights in 65 | consideration of benefits the Licensor receives from making the 66 | Licensed Material available under these terms and conditions. 67 | 68 | 69 | Section 1 -- Definitions. 70 | 71 | a. Adapted Material means material subject to Copyright and Similar 72 | Rights that is derived from or based upon the Licensed Material 73 | and in which the Licensed Material is translated, altered, 74 | arranged, transformed, or otherwise modified in a manner requiring 75 | permission under the Copyright and Similar Rights held by the 76 | Licensor. For purposes of this Public License, where the Licensed 77 | Material is a musical work, performance, or sound recording, 78 | Adapted Material is always produced where the Licensed Material is 79 | synched in timed relation with a moving image. 80 | 81 | b. Adapter's License means the license You apply to Your Copyright 82 | and Similar Rights in Your contributions to Adapted Material in 83 | accordance with the terms and conditions of this Public License. 84 | 85 | c. Copyright and Similar Rights means copyright and/or similar rights 86 | closely related to copyright including, without limitation, 87 | performance, broadcast, sound recording, and Sui Generis Database 88 | Rights, without regard to how the rights are labeled or 89 | categorized. For purposes of this Public License, the rights 90 | specified in Section 2(b)(1)-(2) are not Copyright and Similar 91 | Rights. 92 | 93 | d. Effective Technological Measures means those measures that, in the 94 | absence of proper authority, may not be circumvented under laws 95 | fulfilling obligations under Article 11 of the WIPO Copyright 96 | Treaty adopted on December 20, 1996, and/or similar international 97 | agreements. 98 | 99 | e. Exceptions and Limitations means fair use, fair dealing, and/or 100 | any other exception or limitation to Copyright and Similar Rights 101 | that applies to Your use of the Licensed Material. 102 | 103 | f. Licensed Material means the artistic or literary work, database, 104 | or other material to which the Licensor applied this Public 105 | License. 106 | 107 | g. Licensed Rights means the rights granted to You subject to the 108 | terms and conditions of this Public License, which are limited to 109 | all Copyright and Similar Rights that apply to Your use of the 110 | Licensed Material and that the Licensor has authority to license. 111 | 112 | h. Licensor means the individual(s) or entity(ies) granting rights 113 | under this Public License. 114 | 115 | i. Share means to provide material to the public by any means or 116 | process that requires permission under the Licensed Rights, such 117 | as reproduction, public display, public performance, distribution, 118 | dissemination, communication, or importation, and to make material 119 | available to the public including in ways that members of the 120 | public may access the material from a place and at a time 121 | individually chosen by them. 122 | 123 | j. Sui Generis Database Rights means rights other than copyright 124 | resulting from Directive 96/9/EC of the European Parliament and of 125 | the Council of 11 March 1996 on the legal protection of databases, 126 | as amended and/or succeeded, as well as other essentially 127 | equivalent rights anywhere in the world. 128 | 129 | k. You means the individual or entity exercising the Licensed Rights 130 | under this Public License. Your has a corresponding meaning. 131 | 132 | 133 | Section 2 -- Scope. 134 | 135 | a. License grant. 136 | 137 | 1. Subject to the terms and conditions of this Public License, 138 | the Licensor hereby grants You a worldwide, royalty-free, 139 | non-sublicensable, non-exclusive, irrevocable license to 140 | exercise the Licensed Rights in the Licensed Material to: 141 | 142 | a. reproduce and Share the Licensed Material, in whole or 143 | in part; and 144 | 145 | b. produce, reproduce, and Share Adapted Material. 146 | 147 | 2. Exceptions and Limitations. For the avoidance of doubt, where 148 | Exceptions and Limitations apply to Your use, this Public 149 | License does not apply, and You do not need to comply with 150 | its terms and conditions. 151 | 152 | 3. Term. The term of this Public License is specified in Section 153 | 6(a). 154 | 155 | 4. Media and formats; technical modifications allowed. The 156 | Licensor authorizes You to exercise the Licensed Rights in 157 | all media and formats whether now known or hereafter created, 158 | and to make technical modifications necessary to do so. The 159 | Licensor waives and/or agrees not to assert any right or 160 | authority to forbid You from making technical modifications 161 | necessary to exercise the Licensed Rights, including 162 | technical modifications necessary to circumvent Effective 163 | Technological Measures. For purposes of this Public License, 164 | simply making modifications authorized by this Section 2(a) 165 | (4) never produces Adapted Material. 166 | 167 | 5. Downstream recipients. 168 | 169 | a. Offer from the Licensor -- Licensed Material. Every 170 | recipient of the Licensed Material automatically 171 | receives an offer from the Licensor to exercise the 172 | Licensed Rights under the terms and conditions of this 173 | Public License. 174 | 175 | b. No downstream restrictions. You may not offer or impose 176 | any additional or different terms or conditions on, or 177 | apply any Effective Technological Measures to, the 178 | Licensed Material if doing so restricts exercise of the 179 | Licensed Rights by any recipient of the Licensed 180 | Material. 181 | 182 | 6. No endorsement. Nothing in this Public License constitutes or 183 | may be construed as permission to assert or imply that You 184 | are, or that Your use of the Licensed Material is, connected 185 | with, or sponsored, endorsed, or granted official status by, 186 | the Licensor or others designated to receive attribution as 187 | provided in Section 3(a)(1)(A)(i). 188 | 189 | b. Other rights. 190 | 191 | 1. Moral rights, such as the right of integrity, are not 192 | licensed under this Public License, nor are publicity, 193 | privacy, and/or other similar personality rights; however, to 194 | the extent possible, the Licensor waives and/or agrees not to 195 | assert any such rights held by the Licensor to the limited 196 | extent necessary to allow You to exercise the Licensed 197 | Rights, but not otherwise. 198 | 199 | 2. Patent and trademark rights are not licensed under this 200 | Public License. 201 | 202 | 3. To the extent possible, the Licensor waives any right to 203 | collect royalties from You for the exercise of the Licensed 204 | Rights, whether directly or through a collecting society 205 | under any voluntary or waivable statutory or compulsory 206 | licensing scheme. In all other cases the Licensor expressly 207 | reserves any right to collect such royalties. 208 | 209 | 210 | Section 3 -- License Conditions. 211 | 212 | Your exercise of the Licensed Rights is expressly made subject to the 213 | following conditions. 214 | 215 | a. Attribution. 216 | 217 | 1. If You Share the Licensed Material (including in modified 218 | form), You must: 219 | 220 | a. retain the following if it is supplied by the Licensor 221 | with the Licensed Material: 222 | 223 | i. identification of the creator(s) of the Licensed 224 | Material and any others designated to receive 225 | attribution, in any reasonable manner requested by 226 | the Licensor (including by pseudonym if 227 | designated); 228 | 229 | ii. a copyright notice; 230 | 231 | iii. a notice that refers to this Public License; 232 | 233 | iv. a notice that refers to the disclaimer of 234 | warranties; 235 | 236 | v. a URI or hyperlink to the Licensed Material to the 237 | extent reasonably practicable; 238 | 239 | b. indicate if You modified the Licensed Material and 240 | retain an indication of any previous modifications; and 241 | 242 | c. indicate the Licensed Material is licensed under this 243 | Public License, and include the text of, or the URI or 244 | hyperlink to, this Public License. 245 | 246 | 2. You may satisfy the conditions in Section 3(a)(1) in any 247 | reasonable manner based on the medium, means, and context in 248 | which You Share the Licensed Material. For example, it may be 249 | reasonable to satisfy the conditions by providing a URI or 250 | hyperlink to a resource that includes the required 251 | information. 252 | 253 | 3. If requested by the Licensor, You must remove any of the 254 | information required by Section 3(a)(1)(A) to the extent 255 | reasonably practicable. 256 | 257 | 4. If You Share Adapted Material You produce, the Adapter's 258 | License You apply must not prevent recipients of the Adapted 259 | Material from complying with this Public License. 260 | 261 | 262 | Section 4 -- Sui Generis Database Rights. 263 | 264 | Where the Licensed Rights include Sui Generis Database Rights that 265 | apply to Your use of the Licensed Material: 266 | 267 | a. for the avoidance of doubt, Section 2(a)(1) grants You the right 268 | to extract, reuse, reproduce, and Share all or a substantial 269 | portion of the contents of the database; 270 | 271 | b. if You include all or a substantial portion of the database 272 | contents in a database in which You have Sui Generis Database 273 | Rights, then the database in which You have Sui Generis Database 274 | Rights (but not its individual contents) is Adapted Material; and 275 | 276 | c. You must comply with the conditions in Section 3(a) if You Share 277 | all or a substantial portion of the contents of the database. 278 | 279 | For the avoidance of doubt, this Section 4 supplements and does not 280 | replace Your obligations under this Public License where the Licensed 281 | Rights include other Copyright and Similar Rights. 282 | 283 | 284 | Section 5 -- Disclaimer of Warranties and Limitation of Liability. 285 | 286 | a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE 287 | EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS 288 | AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF 289 | ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, 290 | IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, 291 | WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR 292 | PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, 293 | ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT 294 | KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT 295 | ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. 296 | 297 | b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE 298 | TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, 299 | NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, 300 | INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, 301 | COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR 302 | USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN 303 | ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR 304 | DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR 305 | IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. 306 | 307 | c. The disclaimer of warranties and limitation of liability provided 308 | above shall be interpreted in a manner that, to the extent 309 | possible, most closely approximates an absolute disclaimer and 310 | waiver of all liability. 311 | 312 | 313 | Section 6 -- Term and Termination. 314 | 315 | a. This Public License applies for the term of the Copyright and 316 | Similar Rights licensed here. However, if You fail to comply with 317 | this Public License, then Your rights under this Public License 318 | terminate automatically. 319 | 320 | b. Where Your right to use the Licensed Material has terminated under 321 | Section 6(a), it reinstates: 322 | 323 | 1. automatically as of the date the violation is cured, provided 324 | it is cured within 30 days of Your discovery of the 325 | violation; or 326 | 327 | 2. upon express reinstatement by the Licensor. 328 | 329 | For the avoidance of doubt, this Section 6(b) does not affect any 330 | right the Licensor may have to seek remedies for Your violations 331 | of this Public License. 332 | 333 | c. For the avoidance of doubt, the Licensor may also offer the 334 | Licensed Material under separate terms or conditions or stop 335 | distributing the Licensed Material at any time; however, doing so 336 | will not terminate this Public License. 337 | 338 | d. Sections 1, 5, 6, 7, and 8 survive termination of this Public 339 | License. 340 | 341 | 342 | Section 7 -- Other Terms and Conditions. 343 | 344 | a. The Licensor shall not be bound by any additional or different 345 | terms or conditions communicated by You unless expressly agreed. 346 | 347 | b. Any arrangements, understandings, or agreements regarding the 348 | Licensed Material not stated herein are separate from and 349 | independent of the terms and conditions of this Public License. 350 | 351 | 352 | Section 8 -- Interpretation. 353 | 354 | a. For the avoidance of doubt, this Public License does not, and 355 | shall not be interpreted to, reduce, limit, restrict, or impose 356 | conditions on any use of the Licensed Material that could lawfully 357 | be made without permission under this Public License. 358 | 359 | b. To the extent possible, if any provision of this Public License is 360 | deemed unenforceable, it shall be automatically reformed to the 361 | minimum extent necessary to make it enforceable. If the provision 362 | cannot be reformed, it shall be severed from this Public License 363 | without affecting the enforceability of the remaining terms and 364 | conditions. 365 | 366 | c. No term or condition of this Public License will be waived and no 367 | failure to comply consented to unless expressly agreed to by the 368 | Licensor. 369 | 370 | d. Nothing in this Public License constitutes or may be interpreted 371 | as a limitation upon, or waiver of, any privileges and immunities 372 | that apply to the Licensor or You, including from the legal 373 | processes of any jurisdiction or authority. 374 | 375 | 376 | ======================================================================= 377 | 378 | Creative Commons is not a party to its public 379 | licenses. Notwithstanding, Creative Commons may elect to apply one of 380 | its public licenses to material it publishes and in those instances 381 | will be considered the “Licensor.” The text of the Creative Commons 382 | public licenses is dedicated to the public domain under the CC0 Public 383 | Domain Dedication. Except for the limited purpose of indicating that 384 | material is shared under a Creative Commons public license or as 385 | otherwise permitted by the Creative Commons policies published at 386 | creativecommons.org/policies, Creative Commons does not authorize the 387 | use of the trademark "Creative Commons" or any other trademark or logo 388 | of Creative Commons without its prior written consent including, 389 | without limitation, in connection with any unauthorized modifications 390 | to any of its public licenses or any other arrangements, 391 | understandings, or agreements concerning use of licensed material. For 392 | the avoidance of doubt, this paragraph does not form part of the 393 | public licenses. 394 | 395 | Creative Commons may be contacted at creativecommons.org. 396 | 397 | -------------------------------------------------------------------------------- /NewMembers/GradsAndPostdocs.md: -------------------------------------------------------------------------------- 1 | # Specific Advice for Graduate Students and Postdocs in the Lab 2 | 3 | ## For graduate students specifically 4 | 5 | ### A bit on how our relationship will change over time 6 | 7 | As a graduate student in the lab, you begin a great progression. At the beginning, the adviser has most of the knowledge and does the teaching, but ideally, by the end of the Ph.D., you have the most knowledge about your project and do the teaching. That is, our relationship should hopefully develop from one where I explain to you what I think should be done and why and you normally agree, to one where you explain to me what you think should be done and why, and I normally agree.  As far as I know, this progression is not one that you can deliberately work at -- but you can work at educating yourself, pouring yourself into knowing everything about your project(s) and how they connect to research being done elsewhere, and making sure you understand everything about what you are doing. As your knowledge and abilities grow, you will begin to have your own ideas and bring them to the table, and eventually, we will find that your ideas are right as often or more often than mine. Our goal together it to help you get to this point. 8 | 9 | ### Starting projects versus later projects 10 | 11 | I often like to give graduate students starting in the lab one or two "warm-up" projects -- projects where I know how to do all or almost all of the work already, and I know the outcome will be interesting. In the process, you will get to learn how to use our technology (simulation packages, toolkits, etc.) and how to do the types of calculations we do, while at the same time achieving something interesting and publishable. As you do so, however, you should be engaged in the literature and we should be thinking about ideas for larger projects which will ultimately form the bulk of your dissertation. 12 | 13 | ### Internships 14 | If you think you might be interested in doing a summer industry internship, either with a company working on drug discovery software, or in a drug company itself, keep me informed as I may become aware of opportunities. Several students have done internships at Schrodinger and OpenEye, but others, including Genentech, are also possible. 15 | 16 | ### What it Takes to Graduate 17 | People often ask me how quickly they can finish graduate school, and what it takes to graduate. It's hard to give a firm answer to this since it depends to a large extent on things I don't control, including: 18 | - You and how hard you work/how quickly you solve problems 19 | - How well our science works out and how many problems we run into 20 | Typically, people finish graduate school in our area in 4-6 years. UCI imposes a 9 quarter (3 year) clock for graduation after advancement to Ph.D. candidacy, though I understand exceptions are made. Beyond that, it's hard to be more specific. We're talking about research, and graduating involves completing one or more new research projects. If they had already been done, we could better predict how long it would take, but that also would mean they wouldn't amount to a Ph.D., which involves novelty. Often, though, most of the time in graduate school is taken up doing things that aren't exactly right or don't quite work out, which means that when things go well, it's possible to finish fairly quickly. For example, I graduated in four years, and in fact if I had to repeat all of my Ph.D. research after I knew what would work, I could probably have done it all in just six months, including writing my dissertation. Most of my time was spent doing things that didn't quite work out, or figuring out how to solve specific problems.  21 | 22 | Some advisers have firm guidelines as to what their students need to accomplish to get a Ph.D., such as a quota of first-author publications (three or five, for example). I don't have an absolute rule here, but I would expect that every graduating student will have at least one first-author publication on a project where they have been the primary driving force/taken ownership, and probably more (typically three or more). I don't want to rule out the possibility that a student might tackle one very large project which would be best suited for a single publication, but more often I expect students will either tackle three or more smaller projects, or one large project which also involves several innovations which are themselves suitable for separate publications. So, again, I have no firm rule here but you should normally plan on three or more first-author publications before you'll be able to graduate, unless there are special circumstances (e.g. we decide to put more work into a single larger publication, prioritizing doing new science over writing papers). When in doubt, talk to me about your specific situation. 23 | 24 | 25 | ## For both graduate students and postdocs 26 | 27 | ### Presence in the lab 28 | 29 | Pre-COVID, I would expect you to normally be physically present in the lab during normal working hours (i.e. roughly 8-9 hour days beginning sometime between 8-10 a.m. or so), unless you have arranged with me otherwise.  (There are obvious exceptions for classes, etc.) Post-COVID, this is still evolving and I am more receptive to remote work; at present, you should plan to have at least two days a week in the lab unless you've arranged with me otherwise, and one of those should be group meeting day. If you expect to be absent outside normal in-lab times, I would expect to hear in advance -- i.e., an e-mail in the morning when you wake up if you'll be out sick, etc. As noted previously ([Working in the Mobley Lab](WorkingInTheMobleyLab.md)) I expect you to treat graduate school as at least a full-time job. While I'm not particularly concerned about you clocking a specific number of hours, in general I find that people in the lab spend less time being stuck (because they can interact with me or lab mates), are able to help one another more, and make more rapid progress.  30 | 31 | Really, my major concern is with research progress -- if I know what you're doing, and you're working hard and making progress, and I can interact with you frequently, I'll not be particularly concerned about where you are. But if you never seem to be here and don't seem to be making any headway, I'll start to be concerned the two are linked and you're not putting in the time. 32 | 33 | For postdocs, physical presence in the lab is particularly important, as postdocs are expected to be able to help other lab members, especially when my time is limited.  34 | 35 | ### Having your own project ideas 36 | 37 | It's good to have independent ideas for projects, digressions, or papers. You ultimately should end up doing some projects of your own conception and design. But you also have to be prepared for me to ask you to drop things. To do a new project, you need to be able to sell me on it; if you can't, you'll have to make it a lower priority or drop it. 38 | 39 | Project selection can be really tough. An ideal project would test an interesting hypothesis, and yield results which are important, interesting, and high-impact regardless of the outcome. Indeed, it's always working thinking through a project and figuring out what your next step would be if the outcome is A vs B. But sometimes, projects are interesting enough that it's worth doing them even if only one outcome is interesting. For example, with Chris Vanderwaal, I spent some time looking through known drugs to see if a new scaffold he had come up with had substantial shape similarity to the core of a known drug. If it did, he could potentially build a new drug targeting the same receptor based on his novel scaffold, which could potentially have very high impact. So we proceeded, though so far it looks like the outcome is that there are no such drugs. But if we found anything, it could have been tremendously important, so we were willing to tolerate the potential "uninteresting" outcome. 40 | 41 | ### Funding as it relates to project selection 42 | If you have, or obtain, your own funding, this provides you with the most freedom in terms of selecting a research project, as it only needs to be something of mutual interest. In contrast, however, if you are supported by lab research funds, you will have to work on a project which those funds support, so this gives you considerably less freedom.  43 | 44 | ### Funding and career advancement 45 | 46 | Even if you are being supported in the laboratory by my research funds, you are strongly encouraged to seek your own funding. One reason for this is that in the sciences, success at obtaining funding is often taken as a mark of a successful researcher. So, whether or not you need the funding, future employers will notice that you have obtained it. Additionally, many graduate and postdoctoral fellowships are fairly prestigious and/or known to be competitive, so these are taken as a further mark of success. It is a low-pressure, high-reward position: If you don't get it, it only cost you time and postage, but if you do get it, it's potentially a big boost to your career. 47 | 48 | ### Travel, conferences, and presentations 49 | If you have work to present, or anticipate having work to present, consider presenting it either locally or at a conference. Look for opportunities which interest you, or talk to me about suitable opportunities. Don't let funding stop you from investigating. I may be able to fund your travel from my research funding, or you may obtain your own funding which provides for travel. Also, many conferences have special travel awards for students or postdocs. Becoming known in the scientific community is an important part of advancing your career (it is a remarkably small community), as is improving your presentation skills, which only happens with practice.   50 | 51 | ### Plan for your future -- and have a backup plan 52 | 53 | Think about what you want to do after you leave the lab, and investigate options as time goes on (for postdocs this is more urgent). Talk to me about what you think -- for example, if you're thinking academia, I want to talk with you about what it takes to get positions. If you're thinking industry, we should discuss steps to take so you know some potential employers. But do also think about backup plans -- what would you do if you can't do your first-choice? This should interface with our work on periodic Individual Development Plans (IDPs).  54 | -------------------------------------------------------------------------------- /NewMembers/GroupPoliciesProcedures/TimeOff.md: -------------------------------------------------------------------------------- 1 | # Mobley Lab Policy on Time Off 2 | 3 | Folks working in the lab are expected to take time off/away from work in order to be healthy (in body and mind), sharp, connected with their families and communities, and therefore productive in the lab. Too much time focused on research can result in you getting burned out, discouraged, and disconnected from the people around you. 4 | 5 | Please plan on taking a minimum of two weeks off each year (if you are not in a position which accumulates leave; if you are, then use your leave), not counting holidays, weekends, etc. Deadlines, or your own priorities, may at times result in you deciding to put in time on holidays, weekends or similar, but if you do, you should as a general rule plan to be off at some other time to make up for it. This 10 days does not count time off for being sick or out for medical appointments, etc., and represents a minimum. (As a postdoc, I worked with someone whose policy was "Take as much time off as you want, whenever you want." That's not quite my policy, and in that position I found I worked rather a lot -- but I do encourage people to **be where you are**: When you're working, do it 100%, and then disconnect when you're not working. I find this results in far better productivity than if you're "always working" while trying to keep the rest of your life going at the same time.) 6 | 7 | ## Approval and tracking: 8 | - I only ask that, if you want to plan to be away from lab and off work for more than a few hours during normal work days/hours, you contact me (David Mobley) before making concrete plans, just as you would any normal employer, to get approval. Normal employers expect folks to be available/reachable during working hours unless notice is given, and I have the same expectation. Of course this does not apply to time off when the university is closed — though if you plan to be away over, say, Christmas it’s nice to know about your plans so I’m not asking you for things during that time. 9 | - Once approved, please post in Slack #status when you will be away (and pin your post), as that’s where I’ll check for it. 10 | - Please keep track of how much time you do take, to ensure you take adequate time off. 11 | 12 | This is of course separate from any reporting you have to do for the university in connection with your position (e.g. postdocs have to handle timesheets, etc.) 13 | -------------------------------------------------------------------------------- /NewMembers/GroupPoliciesProcedures/TravelReimbursement.md: -------------------------------------------------------------------------------- 1 | # Mobley Lab Travel and Travel Reimbursement 2 | 3 | Before planning travel, **check with and get pre-approval from David Mobley** regarding your travel plans. For reimbursement related forms, see the following: 4 | 5 | - *Getting Reimbursed for Travel Expenses at UCI*: http://www.accounting.uci.edu/travel/reimbursement/getting-reimbursed.html 6 | - *Travel Reimbursement Request Form* : http://pharmsci.uci.edu/wp-content/uploads/2017/10/Travel-Reimbursement-Form-2017.pdf 7 | 8 | Note, you won't generally get reimbursed for gas unless it is for a rental car, however you *can* claim mileage, see [Using a Personal Vehicle for Travel or University-Related Business](http://www.accounting.uci.edu/travel/reimbursement/personal-vehicles.html) 9 | 10 | 11 | ## How to get reimbursement? 12 | - Get appropriate form from PharmSci website under “faculty resources” - Form link http://pharmsci.uci.edu/faculty/faculty-and-staff-resources/ (as of 1-21-20) 13 | - Fill out form 14 | - contact David Mobley for fund source 15 | - get signature from David Mobley 16 | - submit to pharmsci (pharmpur@uci.edu will take it). 17 | - **There is a 30 day deadline for reimbursements!** 18 | 19 | Philosophy: In general we try and act like a business, meaning that work-related travel should be reimbursed as long as you get permission in advance and expenses are reasonable. 20 | 21 | Note also that our funding is typically not in separate buckets of "travel" vs "other stuff" so money which is not spent on travel can often be spent on paying people, or computer time, or whatever else, so we try and travel reasonably frugally. 22 | -------------------------------------------------------------------------------- /NewMembers/IntroToSlack.md: -------------------------------------------------------------------------------- 1 | # Introduction to Slack in the Mobley Lab 2 | 3 | ## What is Slack? 4 | 5 | Slack is essentially a group messaging application which can be accessed from multiple platforms: desktop application, web browser, and/or mobile application. 6 | 7 | ## Why do we use Slack? 8 | 9 | - It cuts down on email a lot in a way which helps productivity: 10 | - Files / images / code snippets / hyperlinks are easily shared. 11 | - Communication is dynamic within channels or individual conversations or groups of conversations. 12 | - Conversations can be threaded, so multiple ideas can be concurrently discussed in an organized fashion. 13 | - People coming in to a conversation late (or joining an old project) can easily see the history 14 | - It organizes communication / information that is project specific. 15 | - Channels can be created as desired for each project. 16 | - Individual names, or entire groups, can be tagged (e.g. `@channel`, `@dmobley`, `@gradstudents` etc.). 17 | - Past conversations (individual or inside channels) can be easily searched. 18 | - Important facts/data can be “pinned” in a channel or conversation for easy access. 19 | - Items can also be “starred” for personal reference. 20 | - There are a number of useful features: setting reminders, integrating with calendars (e.g., Google Calendar) or task managers (e.g. Todoist), keeping up with journals (RSS feeds), keeping notes (by messaging yourself or Slackbot), etc. 21 | 22 | ## How to get started on Slack: 23 | 24 | 1. Dr. Mobley or another administrator will invite you to join team “MobleyLab”. The web interface can be accessed at mobleylab.slack.com. 25 | 2. Get the desktop application (mobile too, if you like; see below) 26 | 3. Browse through the available channels and join ones that pertain to you or that are interesting to you. Some channels all Mobley group members should take part in: 27 | - `#general`: Group-wide announcements/stuff everyone should know 28 | - `#groupmeetings`: Group event scheduling/discussion/reminders. Synchronized with group Google Calendar so it also issues event reminders, etc. 29 | - `#status`: This is for letting people know when you are/aren't available/where you are, etc. If you’re planning a trip/vacation, note it here and pin it. (Also update your status description when you're leaving!) 30 | - `#journalclub`: Perpetual Journal Club - post links to interesting articles here, or comments on articles you are reading, etc. If you have an upcoming group meeting and it’s not good timing to do a research update, pick a hot paper from this (or elsewhere) to present on! 31 | - `#announcements`: Announcements which are e-mailed in (this channel has an e-mail address); seminar announcements, etc. If you get an email that you would like to share with the group (e.g., funding opportunities, upcoming seminars), forward that email to the e-mail address listed in the channel details (click the down arrow from the channel name in the desktop app) and it’ll come straight to Slack. 32 | 33 | - Some optional channels you might be interested in: 34 | - `#computing`: Computing environment, high performance computing, cluster operations, etc. 35 | - `#coding`: General coding and software (i.e. GitHub) questions/comments/info 36 | - `#purchasing`: Purchasing of things for the lab/otherwise. 37 | - `#refrigerator`: Group fridge management/notices. 38 | - `#random`: Non-work banter and water cooler conversation. Or puns. Definitely puns. 39 | - `#outreach`: Volunteer activities with UCI and the local community. 40 | - `#writing`: Tips/info on writing scientific papers, etc. 41 | - `#funding`: Funding opportunities 42 | - `#journal_(whatever)`: Journal RSS feeds. Subscribe to these if you want to see what’s in that journal. 43 | - `#website`: Group website maintenance/discussion 44 | - `#mobleylabevents`: Channel for event planning (ie lab trips, holiday celebrations, etc.) 45 | 46 | 4. Add a distinct logo/avatar for yourself. This will make group conversations easier to follow. Some find these especially helpful. 47 | 48 | 5. Plan check-ins. Pick a channel to do regular (daily or weekly, depending on how research active you are) check-ins on what you're doing. Answer these three questions; even single-sentence or single-phrase answers will work: 49 | 1. What did you do yesterday/last? 50 | 2. What are you doing next? 51 | 3. Is anything blocking your progress/what would help you make better progress? 52 | 53 | 54 | ## Slack etiquette: 55 | 56 | - **Mind what notifications you send:** A message usually triggers a notification, especially if you @ mention the person. Don’t send notifications except to get attention. For example: 57 | - If someone asks you to do something but doesn’t ask for a response, just use :eyes: to show you saw it (see “emojis”, below) 58 | - Make sure anyone you @ mention really needs a notification 59 | - **Keep science open**: Keep as much as possible in open channels rather than direct messages or Howdy check-ins 60 | - If someone joins a project later, you want the things they should know to be in a channel they can join 61 | - Save direct messages for things which should be private 62 | - **Set your status**: If you’re away (e.g., in a meeting, at lunch), you can set your status (with emoji optionally!) to let others know replies may be delayed. 63 | - **Know when NOT to use Slack**: Verbal communication (including with drawings!) can be much faster/higher bandwidth. Know when to switch technologies. 64 | - Ask to switch to voice/video 65 | - Ask to schedule a meeting 66 | - Slack is good for short/brief updates, asynchronous communication, etc. Don’t stretch it to cover what it shouldn’t. 67 | 68 | ##Bonus points for Slack:## 69 | 70 | - **Lots of emojis!** You can "react" to any message. E.g. a common reaction is "thumbs up". 71 | - Tip: If someone asks you to do something, use the "eyes on" ( :eyes:) emoji to show that you saw it. Then when you've done it, use the :white_check_mark: to show it’s done and taken care of. Note that you can also search for these emoji's, so you can use them to flag things you're supposed to do/have done and search for them... 72 | - **Different levels of notifications!** You get a direct (!) notification for individual messages and for @ mentions. For channels that people are updating, it shows up as bold. If you don't belong to a channel, you don't get those notifications. 73 | - **Be sure to adjust your notification settings** -- many people will find it too distracting to have Slack “ding” at you for everything. If you have the app on your computer, click on “Slack” in the upper left corner and click “Preferences” to change things like notifications or sidebar settings. You will also see an option for uploading emails to slack under “Messages & media”. 74 | - Fine-grained notification control allows you to make certain channels be low priority or silent, others make noise, and others (such as direct messages or mentions of your name or key words) be especially obvious. 75 | - **Apps!** You can check Slack on your phone and get notifications and respond rapidly. 76 | - **Permalinks!** Every post has a permanent link (URL, effectively) that you can copy and re-use, such as to refer back to it in a later post, or to embed in your task manager (Todoist, for example) to pull it up when you need 77 | - **Starred items!** When you want to easily be able to find something again, star it to make it easier to search for it or to pull it up when you toggle “show channel details” at the top 78 | - **Pinned items!** The equivalent of starred items but for EVERYONE, not just for you. Attach a key document, note, or image to a channel long-term to make it easy to find until it’s un-pinned. Take responsibility for your project channel to pin key info there. 79 | Examples of things that commonly get pinned: link to the code associated with some project, reference guides/etiquette on some computing cluster 80 | If you will be away from the lab for sometime (e.g., going home for Christmas), note the dates you’ll be out and pin it to the #status channel. 81 | - **Reminders!** Use /reminder to set reminders to yourself, everyone, or combinations of people. 82 | Integrations! There are tons of integrations with other services you might want to use, such as Dropbox, Google Drive, Todoist, etc. 83 | - **Bots!** There are a variety of bots to perform simple tasks for you, i.e. run a simple poll by typing “/poll” and collect responses right in Slack. 84 | 85 | 86 | ## Other random info: 87 | - Dr. Mobley tries to prioritize communication in Slack over e-mail, but adjusts notifications so not everything grabs his attention immediately. If you need to call his attention to something, direct message him, use `@dmobley`, or use the words “urgent” or “immediate” or similar. 88 | - If you tell him something and he doesn’t respond or put :eyes: on it, remind him; on occasion he misses notifications, especially when in threads. 89 | -------------------------------------------------------------------------------- /NewMembers/README.md: -------------------------------------------------------------------------------- 1 | # Information for new Mobley Lab members 2 | 3 | This contains information for new Mobley Lab members, but it may be useful to people more broadly. 4 | 5 | ## Manifest 6 | 7 | - [WorkingInTheMobleyLab.md](WorkingInTheMobleyLab.md): General introduction to the lab/research in the lab. 8 | - [Undergrads.md](Undergrads.md): Additional undergraduate-specific advice for working in the lab 9 | - [GradsAndPostdocs.md](GradsAndPostdocs.md): Additional graduate/postdoctoral scholar advice relating to working in the lab 10 | - [IntroToSlack.md](IntroToSlack.md): Discusses Slack and how we use it in the lab. 11 | - [GroupPoliciesProcedures](GroupPoliciesProcedures): More minor group policies and procedures, such as travel procedures, vacation, etc.. 12 | -------------------------------------------------------------------------------- /NewMembers/Undergrads.md: -------------------------------------------------------------------------------- 1 | # Specific Advice for Undergraduates in the Lab 2 | 3 | As an undergraduate in my lab, I know you have lots of other responsibilities and need to do well in your classes. So I understand the amount of time and effort you can commit will have fluctuations, and I just expect that you keep me informed about that.  4 | 5 | Do block out specific times for research, especially getting started, because there's a lot to learn at the beginning and it can be tough. You need to push ahead, learning as much as you can, and get through the tough part to get to the fun and interesting part where you begin to accomplish new and exciting things. Remember it's coming and don't give up before you get there! Normally undergrads joining the lab spend some time just learning linux, Python, and vi, before moving to a real research project. This typically takes a substantial amount of time, so stick with it.  6 | 7 | I normally try to pick undergraduate projects where I already know very well what procedure needs to be followed, and the outcome is interesting. This is for a couple reasons. First, it means that you can definitely complete them, since the procedure is known and the outcome will be interesting. This is good for helping you have some publications, and helps me make sure your effort achieves something which helps the group. However, other projects are also possible. If there's a project you have in mind which particularly interests you and which you think we can accomplish with the tools we have, I'm certainly open to discuss it. 8 | 9 | Do remember that Google is your friend, and that for things like Python, linux, and vi, or even for info on how to use various software tools, you can easily Google for most of the information you might need. But also remember that others in the lab can help a great deal. Remember that people in the lab have their own projects and are busy, but often they will also be glad to help you get started or give you advice on solving your specific problem.  10 | -------------------------------------------------------------------------------- /NewMembers/WorkingInTheMobleyLab.md: -------------------------------------------------------------------------------- 1 | # Working in the Mobley Lab 2 | 3 | I'm delighted you want to work in the lab. Research is exciting, and I take great pleasure from being able to learn new things, develop new tools, and help advance science. I'm glad you want to join us in this endeavor!  4 | 5 | Because working in a research lab is in some ways different from many other jobs, and because your relationship with me as an adviser is different from many other types of relationships, I want to provide some information on what you I expect from people in the lab, what you can expect from me, and how you can help me get you what you need to succeed.  6 | 7 | ## A brief intro to research 8 | 9 | Research, by its definition, is the process of discovering something new. Sometimes, this is a new discovery about nature, but it also may be a new way of doing something, a new way of thinking about things, or creation of a new tool to do something old better/differently/more efficiently. The point is, research involves the new. This makes it uniquely exciting and challenging.  10 | 11 | One way in which the "newness" of research is exciting and challenging is that it means that you're typically doing something that no one has done before, so no one can tell you exactly how to do it or what you will find. Sometimes, you may be following a well-established procedure and the novelty is in what you apply this procedure to and in your results. But other times, you're doing something entirely unique -- you're tackling your own unique problem, one which has not been yet solved by anyone else. If it had, you could just use their solution, rather than solving it yourself. This can involve lots of trial and error, backtracking and starting over, etc. I like to say that we put the "re" in research -- we search and then we search again. 12 | 13 | It's important to realize this right away, because it means that you can't necessarily look up the right way to solve your problem, or how other people have solved it. Other people may have solved pieces of it, or related problems, but if someone else has already solved your problem, you normally shouldn't be doing it.  14 | 15 | Here, I strongly encourage you to read, "The Importance of Stupidity in Scientific Research," by Schwartz. This does a great job highlighting how research is fundamentally different from most other things we do. While not everything in this article applies to everything we do, you should definitely read it. You can get a PDF here: http://jcs.biologists.org/content/121/11/1771.long 16 | 17 | To quote Brian Shoichet, "Sometimes we learn the most from failure." Unexpected and/or wrong results often point the way forwards, once we understand them. 18 | 19 | ## My role as an adviser 20 | 21 | If you're in my lab, I'm your research adviser. This is distinct from being your boss. It's important to dwell on the word "adviser" for a moment. At minimum, it means I provide advice. This fits within the context of research, as discussed above. Working in the group on a research project, you're working on a problem I have not already solved. If I had solved it, there would be no point in you also solving it (except perhaps as training or preparation to solve a harder problem). Thus, since I have not yet solved your problem, I can't tell you exactly how to solve it. I can offer advice -- I can explain how I would go about trying to solve it if I were doing so; I can point you to relevant literature or to other people to ask; I can tell you how I've handled similar problems, or pass on experience or conventional wisdom from myself or others. But fundamentally, I primarily provide advice.  22 | 23 | Sometimes, my advice may be very specific. If you're a new graduate student, or an undergraduate in the lab, I may tell you to try a specific approach first, perhaps applying a well-established technique to a new problem, and possibly I might even provide written instructions. You should do as I suggest. But you should still recognize that you're doing research, and so you need to understand the problem you're trying to solve, and see how my approach provides a route to solve that problem. If you just try to do exactly what I say without understanding it, problems and delays will almost inevitably result. (You will also grow frustrated when I ask you "Why are you doing that?" when you're just doing what I told you to do -- but I forgot WHY I told you to do it.) As you grow in your abilities and knowledge, you'll progress to more challenging projects where my guidance starts to sound a lot more like advice. And, if you're a graduate student or postdoc, I'm expecting you ultimately to develop to the point where you will occasionally (or often) think my advice is wrong, and be able to convince me that the way I suggest approaching a problem is in fact not the right way. This is a good thing -- our goal is to help you develop into an independent scientist, rather than an extension of my brain. 24 | 25 | My role as an adviser is also to help you get where you want to go. You should make sure I know your career goals (see also the Individual Development Plans I'm now asking you to do), and talk with me about how your work in the lab can best help you accomplish those. If you're an undergraduate thinking of pursuing a professional degree in pharmacy, what you need from your time in the lab is going to look quite different than if you're a graduate student thinking of pursuing a faculty position, and so on. We should work through these issues together. 26 | 27 | This also impacts what you need to learn in the lab. Depending on your goals and background, it may make sense for us to invest a good deal of time improving your presentation or writing skills, or giving you more opportunities to work as part of a team, or making sure you spend significant time teaching. My job includes working to help you develop in the areas you need to grow in. But to do so, I need to know your goals, and I need to know you want the help. For example, graduate students often need to improve their scientific writing abilities. You'll get some practice as you begin to write research papers. But if you feel particularly weak, or your native language isn't English, you may benefit from additional practice, so for some students in the past I've had them submit weekly written reports which I edit for English usage and return to them. But this is not normally something I impose on students -- I'll do it to help, if you want to develop in your writing abilities.  28 | 29 | Since I am your advisor, I need to know a good deal about what you're doing so I can offer good advice. But it also means that you have to be the expert about your project.  30 | 31 | ### Let’s avoid a few misunderstandings about working in the group: 32 | 33 | - Don’t treat me like your boss: 34 | - I’m not expecting you to blindly do whatever I say or whatever you think I want 35 | - If you blindly follow instructions, you’ll get into trouble because I’ll change my mind, or I won’t remember what I told you or why I told you to do it. 36 | - I want you to take ownership of what you’re doing; you should never find yourself telling me, "I did it because you told me to!" If you’re only doing it because I told you to, you haven’t taken ownership. You either need to get me to convince you it’s worth trying, or convince me that it’s not worth trying. 37 | - It’s your job to know your project, area, and field; the goal is that you get to know it better than me. 38 | - Do treat me like your boss: 39 | - If you go off and ignore all instructions/suggestions/advice you receive from me, we won’t accomplish much together 40 | - If you’re not going to do what I suggest, then I need to know it and know why, so I can plan accordingly. 41 | - I’m not your problem-solver or tutor 42 | 43 | Next, I want to address what I expect from people in the lab, which is mostly geared towards ensuring: 44 | 1. I have what I need to give you good advice and make sure we use our time productively 45 | 2. You know what you need to invest in order to succeed 46 | 3. You help me give you what you need to succeed 47 | 48 | *Note: I said above I'm not your boss. But, I may also be your boss, if I am your formal supervisor (i.e. you're a paid researcher in the lab), but more of our interaction will come in the context of the advisor/advisee relationship.*  49 | 50 | ## What I expect from you 51 | 52 | - Meet with me when you need to talk - by coming by or (if it's a longer conversation) scheduling a time.  53 | - Formerly I scheduled weekly meetings with each person in the lab, but this tended to result in times when I had too many meetings which were of the "nothing new to report" nature and not enough meetings with some people when things are busy. 54 | - Then I canceled all meetings and had everyone check-in electronically with me daily and met only when it was needed. This was bad for some people who needed meetings in order to feel like they had deadlines. 55 | - Currently we take sort of a hybrid approach: 56 | - Everyone is encouraged to check in daily on Slack (see `#check-ins` channel) and answer, briefly (a sentence or less can suffice, unless more is needed): 57 | - "What did you do yesterday/last?" 58 | - "What are you going to do next?" 59 | - "Is anything blocking your progress/what would help you progress faster?" 60 | - We work to identify whether you do better with deadlines (regularly scheduled meetings with me, e.g. weekly) or more independence 61 | - We schedule meetings accordingly 62 | - You know how to get my availability via Calendly so you can get me in the interim if needed (or drop into my office/office hours) 63 | - **Take initiative to set regular meetings with me on whatever frequency is needed** 64 | - Come prepared when we meet, including bringing materials for:  65 | - Updates on what you've done/ what challenges you're facing 66 | - Any new data/plots/ideas 67 | - Questions you need to ask; graphical aids to help with the discussion 68 | - Specific requests for any action you need from me 69 | - Come on time, or notify me in advance you will be late.  70 | - Give regular updates in your project’s Slack channel and via dailies and potentially also by keeping and sharing a detailed log of your progress. I want to be involved and know how you’re doing/how it’s progressing. 71 | - I can't help you if I don't know 72 | - If I don't hear from you, I often find it is a bad sign — I tend to assume you aren't doing anything, or you are stuck. If you're stuck, I need to know. And if you're not doing anything, I need to know it and know why.  73 | - If you're working productively but independently on something, make sure I'm aware of it and why it's time-consuming; I can sometimes get impatient if I don't see progress unless I know what it is you ARE doing.  74 | - Take ownership. It's your project, and your future depends on it (see footnote below). You need to understand where we are, the goals, and how we propose to get there.   75 | - If you don't understand why we're doing something, make it your business to understand 76 | - Don't wait for me to make it work.   77 | - Press me for help when you need it 78 | - Get help from elsewhere 79 | - Often a project will tend to grow as time goes on. Part of your job is to fight against this so that you can finish it.  80 | - Work to define clear objectives and endpoints 81 | - If the objectives expand, make sure they are still clear 82 | - You have responsibility to keep your project moving, focused, and organized. 83 | - You have responsibility to ensure it gets finished 84 | - You may need Dr. Mobley to nag other people to help you 85 | - You may need to nag Dr. Mobley to help you 86 | - You will likely need to set deadlines, milestones, etc., or work with Dr. Mobley to do so. 87 | - "Finished" means it turns into a paper or papers (or at least preprints) and a thesis chapter, usually 88 | - **Know which projects are yours to own (see “take ownership”)**:  89 | - Normally each project will have several people involved, but it “belongs” to one who will end up being the first author (though in some cases there may be co-first authors) 90 | - If the project is yours, you must take ownership of it, including nagging/setting deadlines 91 | - This is what earns your slot as first author and means you can use it in your thesis 92 | - If you don’t take ownership, someone else will have to, and they’ll get the first author slot 93 | - **Be resourceful**, and don't reinvent the wheel:  94 | - Read the manual 95 | - Use Google 96 | - Ask other people in the lab, or other nearby computational labs (Tobias, Luo, Andricioaei) 97 | - Find other people on campus with the expertise you need and ask them   98 | - There are experts here on a huge variety of experimental and computational techniques 99 | - Ask users' lists for the software in question 100 | - If you're tackling a problem that surely, someone somewhere has solved before, decide whether it would be faster to find that person or to solve it yourself. Research is in the novel, not in reinventing the wheel. Ingenuity should be rewarded, but not wasted effort. 101 | - **Keep track of what you've done**, using Evernote or Google Docs or similar 102 | - Record enough detail that if you find out something went wrong, you can see what you did 103 | - Record enough detail that if you need to do it again later (or show someone else), you'll know how 104 | - Record enough detail you can explain it in a paper 105 | - Keep files and other important information organized to deposit with your paper/thesis/etc. and for posterity (I need to update here with a link to recommended details to store) 106 | - Usually this means that you might spend as much as 1/4 of your time on a given project organizing data, taking notes, etc. This ongoing organization will save you a lot of time when you go to write a paper and organize your data. 107 | - **Make good use of my time**: Recognize I don't have infinite time, so make good use of the time I can give you 108 | - Make every effort to remember what we discuss, even if it means taking notes or asking me to slow down or repeat something 109 | - Understand what I tell you, even if it means making me clarify 110 | - Slack is great. But know when NOT to use it; other technologies (such as in-person conversation) can have much better bandwidth. 111 | - **Treat research as a job or more** (see footnote):  112 | - Set aside time to be focused on research and do it; if you're a full-time researcher, invest full-time (at least 40 hrs a week) in research. (Many people are excited about it and do more than that -- but at minimum you should give it your full attention for at least that amount of time). 113 | - Give it your absolute best effort and brainpower 114 | - In general, be physically present in the lab much of the time 115 | - You may need to ask questions of others or they may need to ask you 116 | - These may be relationships you have the rest of your career 117 | - If you’re more productive elsewhere, make sure I know that. 118 | - The “10,000 hour rule” says that it takes roughly 10,000 hours of practice on average to become an expert at something. Your goal in graduate school is to become an expert in your area. 10,000 hours works out to roughly 50 hours a week, 50 weeks a year, for four years, or 40 hours a week, 50 weeks a year, for five years. (I am not recommending 50 hour weeks, just doing math.) This is not a firm guide; the point is to recognize it takes a significant investment of time and energy. 119 | - **Ask for help when you need it**, and let me know when you're stuck 120 | - **Know the relevant literature**, keep up with new innovations in the area as well as background information and historical context. Use the group `#journalclub` Slack channel to help with this. 121 | - **Meet due dates**; if I ask for something specific and don't tell you when I need it, ask. 122 | - **Be an adult** 123 | - Have a calendar. Use it. Don’t miss meetings or scheduled events without advance notice or because you forgot to calendar them. 124 | - Block out time on your calendar to do your most important work at your best times 125 | - Don’t set your priorities based on what happened most recently or what seems most urgent; make sure to get to your most important work 126 | - Have a to-do list (whatever technology works best for you; many of us like Todoist). Use it. 127 | - Block out time to do the most important things 128 | - Back up your data. Assume you will have multiple critical hard drive failures during your graduate career. Plan for it. 129 | - Use secure passwords, and probably a password manager (LastPass and 1Password are good options, but there are others). Check out http://correcthorsebatterystaple.net and the XKCD linked there. 130 | - Plan reasonable vacations. You’ll need to recharge once in a while. Perhaps 2-4 weeks a year of time off is reasonable; run it by me first before making plans. 131 | - **Develop your writing skills**. Many scientists are weak in this area, but you’ll have to do a lot of it. Work at it. 132 | - Read Plaxco’s “The art of writing science” 133 | - Read the [lab style guide](https://github.com/MobleyLab/Training/blob/main/Writing/StyleGuide.md) 134 | - Plan your writing time. Writing a paper draft should take no more than a month. 135 | - Scott Shell points out that a typical paper is about 7000 words; if you write four hours a day for two weeks that’s an average of 150 words per hour or 2.3 words per minute, which is nothing compared to writing a paper in a night for a college class. So it should never take multiple months to write a draft, unless you’re wasting a ton of time somewhere. I’m happy to help if you find that’s the case. 136 | - **Remember how to do things when shown** 137 | - If I show you how to do something, I probably will expect you to be able to do it again (or to teach someone else how). Take notes as needed to make this happen, or ask me to watch while you do it yourself, or both. 138 | - **Use group funds wisely, with permission** 139 | - Don’t book travel for the group without discussing it with me 140 | - Usual rule of thumb: You can go to some workshops/conferences/major meetings once you have work for publication/presentation; usually this will involve sharing an inexpensive hotel with another group member 141 | - Find out about travel reimbursement policies first 142 | - **Seek funding** 143 | - Note #funding Slack channel, with corresponding Google Doc 144 | - Usual rule of thumb: Even if I have adequate grants, you will TA at least once a year unless you have your own funding 145 | - **Back up your data** 146 | - Be familiar with, and occasionally recap, the material on the New Member Checklist 147 | 148 | Footnotes: 149 | - *The degree to which this is true progresses as your career does; it's much more true for postdocs than graduate students, and more true for graduate students than undergraduates.* 150 | - *Undergraduates or students taking a heavy class load are a bit of an exception with respect to treating research as more than a job.* 151 | 152 | ## What to expect from me 153 | 154 | - Available to you on a regular basis  155 | - I should be available to meet at least weekly or more when needed (except when traveling); I'll also be reading your daily check-ins via Slack 156 | - If you need regularly scheduled meetings we can meet at the frequency we decide makes the most sense 157 | - Help with project selection and planning 158 | - Help figuring out how to do your project, advice on how to proceed, suggestions on how to get un-stuck, evaluations of your results 159 | - Pointers on where to get help or additional information 160 | - Mentoring as you want or need it -- for example, on presentation skills, writing, collaboration, etc. Ask. 161 | - Assistance preparing, editing, and submitting papers  162 | - If you have trouble writing, I'm also happy to block out a big block of time and sit down and work through a rough first draft together (i.e. on a Saturday afternoon, …)  163 | - But you also need to plan ahead (see “How to help me help you…”); you have to book time if you need me to edit a draft or similar.  164 | - Training in what you need to know  165 | - From me, the group, or somewhere/someone else 166 | - Help with networking and connections 167 | - Help getting funding if applicable 168 | - I will have things done when I say I will (or if not, I may need a reminder) 169 | - Caveat: Paper-editing. If I book time to edit your paper but find it is full of grammar errors, I may exhaust my editing time trying to fix your grammar errors. You don’t want this. Get other eyes on it first. 170 | - I’ll assign you a chore of some kind; usually everyone gets one (website duties, watching funding opportunities, coordinating group meeting, etc.). This is partly to make sure I have time to do things like edit your papers and meet with you, rather than spending all my time doing logistics. 171 | 172 | If you're in the lab, feel free to drop by my office unscheduled, but do ask if I have time.  173 | 174 | ## How to help me help you 175 | 176 | I juggle a lot of responsibilities, and so as a result am normally a bit backlogged on things. I try to prioritize the things you can expect from me (above), with research coming near the top of the list. (If you want to understand a bit more about the demands on faculty’s time, this [document from colleague Scott Shell is a useful read](https://shellresearchgroup.files.wordpress.com/2020/10/grad_student_lowdown.pdf).  177 | 178 | In any case, given that I have limited time, there are a number of ways you can help me do a better job getting you what you need: 179 | 180 | - Remember I'm your adviser, and you're the expert on your project. This means I can't remember every detail, so you need to remind me. A good starting point is to assume that I don’t remember what you’re doing and why you’re doing it any time you give an update, so to provide a bit of context (or a link to a log!). 181 | - I may not remember the advice I gave you, or why I gave it to you -- so remember it or keep track of it.  182 | - Understand what I recommend and why: (a) If you think of a better way, you'll know it's better. (b) You can explain it to me when I forget.  183 | - I normally won't remember to do anything unless I have it written down  184 | - If you don't see me write it down, remind me 185 | - If you think I might have forgotten about it or lost it, ask 186 | - If you have a list of things you need from me, make a checklist for me on GitHub, in Todoist, or in Evernote. 187 | - If you need something and it takes me more than a week (unless I'm on travel/vacation) and I haven't mentioned it, ask. Normally if I'm going to be slow about something, I'll tell you (and apologize). 188 | - If you have a deadline for something you need from me, make sure I know it. And I’ll tell you when I’ve done things, so if the deadline is approaching and you haven’t heard, remind me. (Note: I tend to never complete tasks without deadlines.) 189 | - You can help me by writing things down for me (i.e. if you need something, mention it in Slack and in a project document) 190 | - Keep good project notes showing your progress and what you're doing next, and share them with me  191 | - When you need help, make sure I have what I need to help you right in front of me by providing it all at once, such as:  192 | - A brief reminder of what you are trying to do and why (and perhaps also link to a project document) 193 | - Exactly what went wrong, at what stage 194 | - All commands, input files, paths, etc., to reproduce your problem  195 | - What I need to know to repeat your exact procedure to troubleshoot  196 | - If it will expedite, ask to sit down together to look at it  197 | - I am forgetful and will contradict myself, giving you opposite advice at times. I apologize for this. On the plus side, it means you'll have to think through things from both sides. 198 | - If you are unable to make progress on something without something from me, make sure I know (and remind me) 199 | - I don't like to keep people waiting, especially if there is nothing else they can do in the meantime 200 | - But I may not always know/remember you're in that situation, so if you are, let me know. 201 | - I try to use e-mail sparingly and Slack more, but if you need something urgently, call me or text me. I deliberately check e-mail infrequently. Assume e-mail response times will be at least a day, often longer. (If something in e-mail is urgent, tell me about it in another way.)  202 | - Don’t e-mail me stuff when it could go in Slack. But if you need to e-mail, use e-mail subject lines that describe the content and action needed, as well as the timeline 203 | - Don't embed an important new e-mail topic in an old thread unless you want me to miss it. I tend to archive e-mails perhaps excessively, especially if I think they’re about an issue I’ve already dealt with. 204 | - Book time for what you need. 205 | - My schedule can become completely booked. If you are planning to have me a paper draft to edit, or code to review, let me know as far in advance as possible in terms of your timeframe so I can actually get it on the calendar. Especially for things requiring good chunks of time, like paper editing, it can take me a couple weeks to get to it if you don’t give me advance notice. Make sure you have things ready so I can make the most of my time — you don’t want me to spend it fixing grammar errors or trying to find your input files to try out your code. Make it easy for me so you get the feedback you want. 206 | 207 | ## For specific groups: 208 | - [Specific advice for undergraduate students is here](Undergrads.md)  209 | - [Specific advice for graduate students and postdocs is here](GradsAndPostdocs.md) 210 | 211 | 212 | ## Useful reading on aspects of "doing science": 213 | - Kevin Plaxco on ["The Art of Writing Science"](http://doi.wiley.com/10.1002/pro.514) 214 | - [Fraser lab philosophy](https://fraserlab.com/philosophy/): Jamie Fraser's lab at UCSF has a lot of great background material relating to being in a research group, what the advisor-advisee relationship should look like, etc. Not all is directly relevant to us but most of it is. Worth reading. 215 | - Uri Alon on ["How to Give a Good Talk"](https://pubmed.ncbi.nlm.nih.gov/19854123/) 216 | - My talk on "Giving Good Talks" (link to be added later) 217 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Training 2 | 3 | This repository is currently under construction. It will eventually contain various Mobley Lab training materials, policies, procedures, etc. 4 | 5 | ## Manifest 6 | - `NewMembers`: Info for new members in the Mobley Lab, which may be useful more broadly. 7 | - `SciBiz`: To contain various information on what my old PI would call "the science business", such as navigating peer review, networking, etc. Currently contains information on navigating papers through peer review. 8 | - `Writing`: Information and tips on writing, including a style guide and info on our paper-writing process. 9 | - `Computing`: Background relating to scientific computing, Python, coding, etc., both generally and in the lab in specific 10 | 11 | 12 | 13 | ## License 14 | 15 | This material here is made available under CC-BY and MIT licenses, as appropriate: 16 | 17 | MIT for all software/code 18 | [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/) for all other materials 19 | -------------------------------------------------------------------------------- /SciBiz/DealingWithPeerReview.md: -------------------------------------------------------------------------------- 1 | # Navigating the Peer Review System 2 | 3 | *By David Mobley* 4 | 5 | The authoring/peer review process tends to seem opaque and stressful, especially for early-career scientists. It doesn't have to be, however. Here I'll give a very brief overview of how I like to see the paper preparation, submission, and review process working, then focus especially on my strategy for dealing with and responding to peer reviews. 6 | 7 | ## The life cycle of a paper 8 | 9 | In the lab, I typically like to see papers proceed through several stages: 10 | 1. **Early concept and outline**: When starting a project, ideally one would develop the concept and begin an initial outline which deals with the purpose of the study and what its objectives are, as well as what exactly needs to be done to accomplish that. 11 | 2. **Mid-stage outline**: As the study goes on, the outline gets updated to reflect what is actually being done and how the study is developing, as well as information on critical graphics/figures/tables/analysis. 12 | 3. **Late-stage outline**: Eventually, as the study concludes, the outline reaches a point where it is detailed enough that it shows the major structure of the paper, drafts/sketches of the figures and tables which will be made (these don't have to be publication quality; the point here is to plan out what they will be like before you waste time making publication-quality ones), and goes over all the main points without worrying about proper English and grammar. The points can be made in bullet-point form, but at a detailed enough level that they could easily be turned into prose. The outline will likely include info on most sources to be cited. At this point, we also edit the *structure* of the paper before doing the actual drafting, so that the process of organizing the paper can occur before we write it -- saving much editing in the later stages. 13 | 4. **First (rough) draft**: The outline is then turned into a first draft, usually by the first author (though see below), essentially by converting the outline into prose and inserting figures, tables, and data. Depending on the paper, the next step(s) will vary; it may be be circulated to all authors, or it may go through one or more rounds of editing with group members/the PI before it is circulated further, or the author may edit more individually before that. 14 | 5. **Later draft(s)**: The author may then proceed to polish this draft further before circulating it, or it may be circulated at the rough draft stage. Eventually, though, the PI and all authors will then edit this first draft, providing feedback, edits, etc. How many drafts this goes through will depend on many factors. One piece of practical advice is to always provide (or ask for) a timeline when asking for feedback. 15 | 6. **Final draft**: When the paper is finalized, it should be circulated to all authors for final approval, again with a set timeline. 16 | 7. **Preprint**: Once the paper is finalized and prior to submission, it should be submitted to a preprint server like bioRxiv, chemRxiv, arXiv, etc. (If it is a review or other content which cannot be posted to a traditional preprint server, consider Zenodo.) Choose permissive licensing, like CC-BY 4.0 (as discussed in the work of [Stodden](http://aip.scitation.org/doi/abs/10.1109/MCSE.2009.19)) to allow broad reuse of the content and to ensure at least SOME version of your paper is freely available. **Preprint submission is the stage we celebrate in the group** because it means you completed the paper we wanted to write, and submission is the step we control, whereas the peer review process can be more unpredictable. 17 | 8. **Peer review**: Once preprinted, we submit the paper to a journal for peer review. First, an editor will decide whether the paper appears of interest to that journal's audience and *potentially* of high enough quality to be appropriate for the journal. If so, the editor will send it out for review to usually two or more scientists in the field (though on occasion I've received as many as six peer reviews, or as few as one). These scientists will provide feedback/suggestions/criticism, usually one to two months after initial submission, and then the editor will make a decision. Decisions range from "reject" to "accept with no revisions", though rejections are rare if one is submitting solid work to an appropriate journal (and are more common the "higher impact" the journal is). Typically, solid work submitted to an appropriate journal will have a decision of "minor revisions" or "major revisions", the details of which vary widely. The end result can range from having to clarify a few points, to needing to substantially extend the whole study or re-do almost all of it. Ideally, one would have received enough feedback from colleagues early in the study design to avoid scenarios which involve re-doing substantial work. Once feedback is dealt with (more on this below) the changes and responses go back to the editor, who makes a decision on whether the changes are adequate, or whether another round of peer-review is needed. This process iterates until the editor reaches a final decision, though authors who manage the initial peer reviews well can usually reach acceptance after a single round of revisions. 18 | 9. **Publication**: Once the editor is happy with the results of the peer review process, the paper is accepted, then goes off for the journal's editing and typesetting process. If there are issues at this point, the journal may ask for minor adjustments (figure size changes, etc.), otherwise the authors will eventually get back a set of proofs to check for errors/problems before final publication. The intent is that the authors check for errors introduced in the editing/typesetting process, but this also provides an opportunity to do a last check for typos/unclear points, though extensive editing cannot be done. 19 | 10. **Post-publication**: Obviously, post-publication, one can promote the work, but there isn't much else to be done. Any changes would require an erratum (except with "special" journals like F1000 Research, or LiveCoMS). For this reason, I highly encourage authors to provide supporting data in a GitHub repository or similar, since any corrections needed to supporting data would otherwise require an erratum, even if they did not affect the paper itself. 20 | 21 | ### The process varies paper-to-paper 22 | 23 | It is important to note that the first stage above, "early concept and outline", is highly variable from project-to-project. Some projects can be planned well from start-to-finish even before they are begun; others are more of an exploration and the destination is unclear until well after the study is underway. Thus the degree of planning which can be done is highly variable depending on the nature of the project. 24 | 25 | ### Help with paper writing 26 | 27 | Many of us encounter writer's block, where we reach some stage of the process where it is difficult to proceed or where we are prone to procrastinate. You'll know you've hit this stage if you suddenly find you have a desperate desire to clean your house, cook, or do something else you normally don't like to do, when you otherwise had planned to be writing your paper. If that's the case, you either need some accountability or some help to continue onwards. 28 | 29 | One thing that sometimes works well, especially for first-time authors, is to schedule a collaborative writing block -- either to finalize an outline, or to write a first draft. In this scenario, the author schedules a substantial block of time with the PI (or, possibly, another author). For example, I've blocked out six hours before to sit down together and write a first draft with a student or postdoc. Usually, one would dictate and the other would write, with questions going back and forth, etc. This can lead to a really great feeling -- you enter in the morning with nothing but a roadblock in your way, and you leave the session in the afternoon with most of a rough draft, along with notes on how to proceed from there. 30 | 31 | That's a relatively extreme intervention, but accountability can also be helpful. Maybe you're able to make progress, but those procrastination reflexes keep getting in your way and you just aren't progressing as fast as you would like. Well, get a partner to hold you accountable to put in solid blocks of work on the paper (e.g. touch bases with a lab-mate once an hour or once a day on what you accomplished). There are even sites which can provide a virtual partner for you if non one is available. 32 | 33 | ### Don't overly stress about typesetting and formatting 34 | 35 | You don't need to stress too much about how well your final draft conforms to what papers look like in the journal you're targeting. Yes, you need to adhere to the journal's guidelines regarding font sizes, and any rules it sets about section titles, etc. (so be sure to consult the author guidelines). But first and foremost, you're writing a paper. Ideally, you should produce a draft which looks nice, since you will post a preprint of it for everyone to read. Get help from the lab in choosing a nice LaTeX template for this purpose. 36 | 37 | Given that you have a nice template, though, don't stress too much about formatting, typesetting, or the placement of your figures. LaTeX is famously bad at putting figures exactly where you want them, and the journal will ultimately change all of this when it prepares your paper for publication. Indeed, it takes your submitted material and completely reformats the entire article, placing the figures where it wants them, etc. None of your formatting will persist. So the important things for you to worry about are (a) making sure your preprint looks good and is easy to read and understand, and (b) making sure your peer reviewers can easily read, understand, and review the paper. You don't have to worry about making it match the way it should look in the journal. 38 | 39 | **DO work hard to make your compiled paper readable and user-friendly**. You plan to send your paper to actual humans to read, both to a broad audience via a preprint server and to peers via a journal, you want to make sure it is easy to read, looks decent, and is user friendly. Journals will sometimes ask you to place your figures and tables at the end of the paper (and, worse, separate the captions from the figures and tables)! Don't do this, or don't do it unless the journal forces you, and even then we may want to fight them about it. Peer reviewers hate it; they have to flip back and forth between the content to the figures and captions. I'm not sure why journals sometimes ask for it, and I think fewer are doing it now. But we're writing first for our readers, not first for the journal. So place your figures and captions sensibly. 40 | 41 | ## Practical writing tips 42 | 43 | I have a few practical tips for writing to ensure productivity: 44 | 1. **Do one task at a time**: Whenever you are seriously writing, focus on one part of the writing process. Write, find references, do background reading, or compile data or figures. Don't jump around between tasks. Resist the temptation to write a couple of sentences, then realize you need a citation on a particular topic, then go off to investigate the literature to find the best citations on that. By the time you return, potentially a couple of hours later, you will have lost your train of thought and the ability to follow the logical flow of your writing. Instead, when you're writing, **just write**. As you go, make notes on the other things you think of that you need to do, so you can come back to them later. I like to put these in square brackets, with whatever I'm thinking of, like `[insert reference to Boresch paper here]` or `[add Figure of binding site here]` and then keep going. Later, come back and take action on any notes you've left for yourself. I'll take action on references in one time slot, work on figures in another, etc. 45 | 2. **Don't multitask**: Writing well requires focus. Resist the temptation to do other things or allow interruptions while you are writing. Set periods of time for writing during which you turn off all non-emergency notifications (or maybe even your internet and phone). Build in times to emerge and check if there's anything you need to deal with. Often, a time-based technique works well for this, though if you're working from an outline you could also do it by sections, e.g. "I'll write the first half of the bullet points in the Introduction and then take a break." I typically will work in something like 50 minute blocks with 10-minute procrastination/notifications breaks, something like a modified [pomodoro technique](https://todoist.com/productivity-methods/pomodoro-technique). Find what works for you -- but most importantly, don't let notifications keep interrupting you. When it's time to write, write. 46 | 47 | ## Writing style guide 48 | 49 | I plan to update this later to link to the lab style guide once I have it available on this repository. 50 | 51 | ## Dealing with peer reviews 52 | 53 | When peer reviews come back, it's necessary to think through how to respond to them. Reviewers are often rushed, so it's not uncommon that they misunderstand parts of your paper, or even misunderstand the purpose entirely. It's easy to end up seeing the process, then, as a battle between you and the reviewers -- one where you have to fight them to ensure your paper gets a fair treatment. 54 | 55 | I prefer, instead, to try and see peer reviewers as representative readers. If a peer reviewer has a question or misunderstands a point, it usually means that other readers will also misunderstand the same point, or have the same question -- even if the reviewer was completely incorrect. 56 | 57 | To help understand the process, let's take a quick look at what the peer-review process looks like from the editor's side. As an author, you'll be able to navigate the process better if you understand what it looks like for the one making the decisions. 58 | 59 | ### Make the editor's job easy while improving your paper 60 | 61 | When I'm serving as the editor of a paper, I may not be reading it as carefully as the peer reviewers. Often, I'll send it to several people who are more expert on the subject matter than I am, and whose judgment I trust. When I get the reviews back, I look at them carefully and then pass the decision on to the authors. When I get revisions back, I then look over the response letter to see how well the authors have addressed the reviewers' concerns. Particularly, I'm looking to see: 62 | - Did they make the recommended changes? 63 | - Are they getting into an argument with the reviewers or saying the reviewers are wrong? 64 | - Did the reviewers raise any concerns about fundamental flaws and have those been fixed? 65 | - Have the authors added any necessarily disclaimers on potential pitfalls, limitations, etc.? 66 | 67 | If the authors have clearly taken seriously all of the concerns raised by reviewers, even if some of those resulted from a misunderstanding of certain points, they often can make my decision easy. If they've clearly made all of the recommended changes, it may not be necessary for me to send it back to the reviewers again. In contrast, if they're arguing with the reviewers or there's back-and-forth on issues that go deeper than my understanding, it will need to go back to the reviewers so I can get expert judgment on the topic. 68 | 69 | Given that, authors can make the editor's job easy by making all the recommended changes that they possibly can, with the obvious exception of those which would hurt the paper or which are clearly misguided. Making these changes -- or clarifying any misunderstandings which led to them -- should make your paper stronger. This is particularly true if your reviewers are representative readers; you want to ensure that everyone else reading the paper doesn't have the same concerns as the reviewers, either by answering those concerns adequately in your paper, or clarifying any misunderstandings which led to them. 70 | 71 | If your response, then, makes clear that you've taken seriously all of the reviewer comments and made appropriate changes to deal with them, you will normally tend to have a relatively easy time navigating the peer-review process, and your papers will get sent out for fewer cycles of re-review. 72 | 73 | ### Here's the procedure I prefer 74 | 75 | Given the above, here's how I normally want peer reviews dealt with in the lab: 76 | 1. When reviews come in, create a Google Doc with the content of the peer reviews. 77 | 2. Below each major point of feedback, draft a response to the point (using a different font style). Explain (in past tense) what changes you want to say you made to the paper to address the concerns raised. For example, you could say, "We addressed this deficiency by performing the recommended calculations. The new data is shown in Table X and Figure Y..." or, "We apologize that we did not explain this point adequately; the reviewer thought we meant that X, but instead we were saying Y. We now make this point more clear in the revised manuscript." DO NOT YET MAKE ANY OF THESE CHANGES. Just make sure you understand the reviewer's concerns, and begin thinking through how they can be dealt with. Insert marginal comments in your Google Doc to note any concerns that you don't understand, or any points you aren't sure how to answer. 78 | 3. Take particular note of any points that would require new calculations or experiments, and prioritize those for decisions. 79 | 4. Make an effort to say "no" as little as possible; in the vast majority of cases, if the reviewer asks for something, you should either be revising the paper to provide that, or addressing *in the paper* why you don't need to do that. Then, your response to the reviewer can be something like, "We apologize for being unclear on this point; we have now added a section to the manuscript discussing this," or "We have updated the paper to more thoroughly discuss the prior data that indicates that X is a potentially viable approach, though we now note in the paper that Y may be a good follow-up experiment for future work." Again, your goal is to be able to show the reviewers and editor that you did the best job you possibly could to deal with every concern, even if you didn't do exactly what was recommended. 80 | 5. Iterate on the Google Doc with your PI and any co-authors to finalize your approach to dealing with the reviews. 81 | 6. Before making any changes to your paper, save a version 82 | 7. Do any necessary calculations and revisions 83 | 8. Add a small cover letter at the top of your Google Doc that explains that you believe you've adequately dealt with the concerns of the reviewers, and that detailed changes are given in the list of responses shown below. 84 | 9. (Optional/journal-dependent) Use `latexdiff` to prepare a version of your paper that shows all changes/edits highlighted. Submit this along with your paper. 85 | 86 | ## Data archival 87 | 88 | More on this later, but briefly, you should try to ensure that your paper has everything needed to reproduce your work. This means providing a good description of what you actually did in the paper itself, as well as in associated Supporting Information. But you'll also want to provide code and input files, as well as potentially output data. Here's what I suggest: 89 | - Small datasets and code should live in a GitHub repository. For paper-specific content, use a paper-specific GitHub repo; for general/multipurpose software, you may have a more general/sustainable repository. Make sure your paper clearly indicates what version of the software was used. 90 | - Large datasets should be archived somewhere permanent, not dependent on your particular lab. Zenodo and Figshare can be good options, but other options can also be good; often, consulting your institutions library can provide good leads. At UCI, eScholarship can be a good option. Dryad can also be interesting. 91 | - Consider multiple archival strategies for longevity: 92 | - Libraries and journals are probably best for long-term archival (e.g. in the long-term, GitHub may no longer exist) 93 | - For files that you might need to update or correct, make sure you use something version controlled like GitHub 94 | - Usually I recommend making your content available on GitHub (except datasets which are too large and need to live elsewhere), and then linking to that GitHub repository in your paper, as well as archiving a *copy* of it with the journal. Note in your paper that any updates to the supporting materials will be made *on the GitHub repository*. Otherwise, any changes to your datasets will require an erratum to the paper, even if your changes don't affect the analysis/statistics/etc. in the paper. Obviously, that can rapidly become a nightmare -- for example, suppose your supporting data includes a list of molecules and some of the molecule names are incorrect. You don't want to do a new erratum anytime you someone points out an error in a molecule name. 95 | 96 | 97 | 98 | ## Other resources 99 | - A colleague highly recommends [this Coursera course from Stanford](https://www.coursera.org/learn/sciwrite#syllabus) on scientific writing. 100 | -------------------------------------------------------------------------------- /SciBiz/README.md: -------------------------------------------------------------------------------- 1 | # Information on "The Science Business" 2 | 3 | Training/background materials on how I/we think about the science business. 4 | 5 | ## Manifest 6 | - [DealingWithPeerReview.md](DealingWithPeerReview.md): Information on navigating the peer review system, from the perspective of an author. 7 | -------------------------------------------------------------------------------- /Writing/README.md: -------------------------------------------------------------------------------- 1 | # Information and tips on academic writing 2 | 3 | This will contain various materials on writing 4 | 5 | ## Manifest 6 | - [StyleGuide.md](StyleGuide.md): A relatively minimal style guide that expands over time 7 | - [WritingTips.md](WritingTips.md): A set of tips on how to effectively write papers 8 | -------------------------------------------------------------------------------- /Writing/StyleGuide.md: -------------------------------------------------------------------------------- 1 | # Style Guide 2 | 3 | (See also the group document on paper-writing tips to be linked here at a later date.) 4 | 5 | ## We generally follow the style of: 6 | [ACS Style Guide](https://pubs.acs.org/doi/full/10.1021/acsguide.50101) (which unfortunately lives behind a paywall; at a later date we should port summaries of key insights here), see especially: 7 | - *Effective writing* (Section 5.1) (use direct, declarative sentences, often in active voice!) 8 | - *General style conventions* (Section 5.3) -- Editorial style (hyphenation, capitalization, modifiers, etc.) 9 | - *Grammar, spelling, and punctuation* (Section 5.2) 10 | - [Strunk & White, “Elements of Style”](https://www.amazon.com/Elements-Style-Fourth-William-Strunk/dp/020530902X/ref=sr_1_1?ie=UTF8&qid=1493395544&sr=8-1&keywords=elements+of+style) 11 | - [Plaxco, “The art of writing science”](https://onlinelibrary.wiley.com/doi/full/10.1002/pro.514) 12 | - Especially note his rule about how the first sentence of every paragraph should tell the reader what you expect them to get out of the paragraph. 13 | 14 | But some issues are worth addressing specifically within the group because they come up particularly often in our work. 15 | 16 | 17 | ## Terms and terminology, word choices (alphabetical order): 18 | - “Atom type”, not “atomtype” 19 | - “Dataset”, not “data set”, when used as a description of a particular entity, such as “we collected this dataset to allow validation of…” 20 | - “Force field”, not “forcefield” 21 | - "Parametrize", not "parameterize" 22 | - "Small molecule", not "small-molecule" (in the context of a "small molecule force field") 23 | - “Predicting”, resist the temptation to use when calculating values which you know. Sometimes acceptable to use for values which have already been measured but are blind to you (e.g. in the context of a blind challenge), but best used for values which have not yet been measured. Use “calculating”, “estimating”, or “computing” if comparing to literature values. 24 | - “Side chain” not “side-chain” 25 | - “Underestimate”/”Overestimate”: Only use for quantities where this has a clear and obvious meaning. Don’t use it for binding free energies, where “underestimate” can refer to the magnitude (so “underestimated” means “binds too weakly”) or the value (so “underestimated” means “binds too strongly”). A similar concern applies to Kd values. Just say something direct, like “the computed binding free energy was too favorable”. 26 | - "Van der Waals": Describes the physical interaction/behavior, in contrast to Lennard-Jones, a particular potential function which can be used to describe this interaction. 27 | - "Pose": Usually used to discuss a static placement of a ligand/small molecule in a receptor. Refers primarily to the placement of the small molecule, NOT to the structure of the receptor. 28 | - "Binding mode": Refers to the overall placement/orientation/conformation of a small molecule bound to a receptor, and gives a less static picture than the word "pose". With care, the idea of "binding mode" can be generalized to include the relevant receptor conformation(s), bound waters, etc. It can also include a group of relevant microstates that correspond to a metastable state. 29 | - OpenFF-specific terms: 30 | - Capitalize the first letter of each word in a compound word software name released by OpenFF: 31 | - "BespokeFit" is the name of the package for fitting custom torsions 32 | - "TorsionDrive" scans torsions 33 | 34 | ## General style: 35 | - **Words**: 36 | - Technical words: Never use a complex, technical word if there is a simple, ordinary word which says the same thing more directly. Technical words are best reserved for use when they differ in meaning or are more precise. We’re not out to demonstrate our vocabulary but to be clear. 37 | - “Fancy” words when a simpler will do. Example: Normally prefer “use” to “utilize” (unless you need the slightly different nuance of utilize). Or “elucidate” when you mean show/demonstrate. 38 | - Active voice: See ACS guidance on direct, declarative sentences, often in active voice. 39 | - Know the rules before you break them, and only break them for good reasons. Example: Don’t use “And” or “But” at the start of a sentence. But do so when you make a deliberate decision to do so for readability. 40 | - Throwaway words and other words to avoid: 41 | - Don’t say “Several X exist…” What are we going to do, talk about nonexistent methods? In general avoid the word “exist” 42 | - “Obviously”. If it were truly obvious it either wouldn’t be necessary to say it or it would risk insulting your readers. Avoid the word, rephrase, or don’t say it. 43 | - Usually avoid "we want to highlight that", "importantly", "it is important to note that", etc. Just make your point. Use emphasis words sparingly and only if essential. 44 | - Throwaway words -- general principles: It’s not necessary/helpful to say something is a certain way unless the opposite would also make sense. So usually don’t use: 45 | - “Data-driven” -- what’s the alternative? Completely made up? Usually writers insert this as a type of buzzword; it sounds good but doesn’t convey information. 46 | - Avoid contractions because science papers should be modestly more formal than normal writing 47 | - Tense: For papers, usually past tense for what we did, present tense for results, and past tense for conclusions except when describing implications. Relatedly, things shown in a figure or table can be referred to in present tense, as the data in the figure or table still shows any observed effect. 48 | - **Phrases, complexity and hedging** -- see https://cgi.duke.edu/web/sciwriting/index.php?action=lesson3 49 | - Avoid meaningless phrases/excessive wordiness 50 | - Avoid excessive hedging/caveats 51 | - Ensure your sentences have simple subjects 52 | - **Sentences:** 53 | - Prefer concise, direct, clear sentences. If you find yourself having lots of clauses, simplify. 54 | - Opening material gets the most emphasis. So, try to start with the “what”, not the “how”, for example, not “By running MD simulations looking at …., we found…” but rather, “We examined X using MD simulations. We found…” 55 | - Prefer simple subjects and verbs for easy reading. While a sentence like "The entry of other water molecules into the binding site in EQ runs of a FXa system (PDB: 1EZQ) when the alchemical water was fully decoupled led to sudden changes in work values in transition simulations." might be grammatically correct, it's hard to follow because the subject is too complex. 56 | - Transitions: Often use transition words to make clear how subsequent sentences follow from prior sentences. 57 | - **Paragraphs**: 58 | - Length: Journal articles are typically two column, which means you need to err in the direction of short paragraphs (to avoid having paragraphs which fill entire columns and are hard to parse) 59 | - Opening sentence: See Plaxco rule above 60 | - **Clarity and correctness**: 61 | - Strive for clarity and correctness 62 | - Write as simply as you can while still being correct and precise 63 | - Being overly precise and technical will cost you clarity 64 | - Writing in an overly simplified way will cost technical precision 65 | - Simplify to the point of oversimplification then back off slightly to achieve the simplest explanation which is still correct and complete 66 | - **Structure**: 67 | - **Section/subsection headers**: Apply the “titles should be statements” rule as much as the journal guidelines will allow for section/subsection headers. Don’t make subsection headers just generic headers (like “MD simulation details”) unless journal guidelines REQUIRE it. 68 | - **Section/subsection divisions and numbering**: Use as many subsections/divisions as you need to break things up for good readability and easy cross-referencing. If you find you have a five page section, for example, it probably needs division into subsections. However, don’t use an additional level of division unless there will be more than one item at that level. For example, if you decide to break Section 5.1 into subsections so that you have Section 5.1.1, you must also have Section 5.1.2. If Section 5.1 doesn’t need multiple subsections, don’t break it up. 69 | - **Lists**: Items in a list must be the same *kind of thing*. Imagine a grocery shopping list reading "Apples, lettuce, crackers, puppies, cheese". One of these would likely be shocking. More typically in academic writing one will be tempted to mix questions with statements, or mix tenses, or other variations. Don't. Ensure items in a list have a consistent kind. 70 | - **Methods**: If describing methods used in a project (such as in a paper) and your work closely follows the methods from a previous study, it's appropriate to cite the prior study and describe your methods more concisely, referring to that study for more details. However: 71 | - Your study should always at least concisely summarize your methods 72 | - Your work must make clear how to find full details and reproduce your work 73 | - Never send your readers on a chase; while you can cite a prior study for details, if THAT study cites a prior study for details you're wasting the reader's time. No "Russian doll" methods sections. 74 | - **References**: 75 | - Don’t refer to authors by name in the text unless it helps your discussion to do so or is important to your narrative. 76 | - Ensure your sentences flow naturally and grammatically even without the reference. So DO write "Previous work discussed this extensively [39-47]," but not "For additional discussion, we refer the reader to [37-47]." 77 | - **Acknowledgments**: Be generous. If someone gave you an idea which was helpful, or helped with scripts, code, queuing system, whatever, acknowledge them. It costs you nothing. 78 | - **Authorship**: If someone helped the project significantly, even in terms of providing key ideas, consider asking if they would like to be a co-author (discussing with your PI too). It costs almost nothing. 79 | - **Figure captions**: Try to make them self-contained so they provide a concise summary of the figure, including its main point(s). Figures+captions should be stand-alone enough that someone can understand what it’s showing without reading the text. The main take-away of the figure should be clearly stated in the caption. 80 | - **Figure subtitles**: If journal style allows, the caption should ideally start with a single-phrase header/subtitle in boldface which is not a complete sentence, then the rest of the caption should use complete sentences. 81 | - **Table captions**: Generally the same considerations apply as for figure captions. 82 | - **Other practical tips for clarity and correctness**: 83 | - Be very careful of the use of "its" in sentences with multiple nouns; [this choice of word often dramatically reduces clarity](https://reason.com/volokh/2022/06/15/its-a-problem/). 84 | - Exercise considerable care when using negatives. Avoid constructions like "failed to X all the Y" ("failed to sample all of the relevant states" -- did it sample none of the relevant states? Or it sampled some but not all?), or "not X in both of of the Y" ("not sampled in both of the trials" -- was it sampled in one, or neither?) 85 | - **Figure, table and section numbering/naming** (except when journal style dictates otherwise): 86 | - In text, use "Sec. 1", "Fig. 1", "Table 1" for sections, figures and tables 87 | - In figures, use lowercase letters for panel numbers, e.g. "(a)" not "(A)" 88 | - Section titles should use title case, rather than capitalizing only the first letter 89 | 90 | ## Tips if using LaTeX for writing 91 | 92 | We often use LaTeX (e.g. Overleaf) for writing papers. Some LaTeX-specific tips are helpful: 93 | - Figures and floating objects should usually use LaTeX to do the work of placement; don't be overly insistent on where they go, with lots of `[h!]` and `[H]` position instructions in your placements of figures and tables; this can result in odd appearances 94 | - If you are making a final manuscript with LaTeX that needs to be publication quality (e.g. for LiveCoMS) pay careful attention to figure placement in the final version. 95 | - Abbreviate journal titles in bibliographies; if using a citation manager like Zotero, check the "use journal abbreviations" box on export to ensure this happens. 96 | 97 | ## Graphics and Figures 98 | - Always use clear axis labels, with large enough fonts for the display size 99 | - Consider colorblindness (e.g. see this post for [some considerations](https://www.tableau.com/about/blog/examining-data-viz-rules-dont-use-red-green-together), though Google for many more) and pick colorblind-friendly palettes and ensure that you use more than color to distinguish key aspects of your data 100 | 101 | ## Writing documentation for software 102 | 103 | - **Tone**: Aim for a friendly, conversational, clear tone. 104 | + Software documentation does not need to be as formal in tone as a paper 105 | * You can end sentences in prepositions if you want to. 106 | * It's OK to freely split infinitives. 107 | * Prefer active voice to passive voice. 108 | + Avoid slang - documentation should be accessible to as wide a readership as possible 109 | - **Living document**: Unlike a paper, documentation is easy to update if we find readers are commonly making the same misinterpretations. This means we can err on the side of clarity in the clarity/correctness trade-off. 110 | - **Links**: Use hyperlinks liberally. 111 | + Use links to... 112 | * Provide detail on technical terms for unfamiliar readers 113 | * Acknowledge other writing or software projects 114 | * Connect related parts of documentation that are separated by the flow of prose 115 | + Make a link out of your natural prose where possible, rather than saying "click here" 116 | + *Always* link to the API reference of a method or object the first time you introduce it in a page's prose. 117 | - **Check output**: Always do a final proof read on the rendered output, not on the markup. This will let you spot syntax errors and other incorrectly rendered documentation 118 | - **The software does things**: When describing a behavior or principle of the software, write as though the software is an agent that does things rather than a product produced by the developers. Prefer making the software the subject of a sentence rather than the developers 119 | + "When input is ambiguous, the toolkit should raise an error rather than guess" rather than "When input is ambiguous, we always try to raise an error rather than guess" 120 | * It's nice/polite to include the reader whenever we use the word "we". If "we" is the dev team, this excludes the reader. 121 | + "The `rmsd()` function computes the root mean square deviation" rather than "Use the `rmsd()` function to compute the root mean square deviation" 122 | - **Write code examples**: Lots of people find programming easier to learn by example than by theory, and it's convenient to be able to copy-paste the most common usages of a library. 123 | - **Write docstrings**: At minimum, every function or type in a public API should have a docstring. 124 | + Function docstrings should at minimum describe every argument and what output is produced. 125 | + Class docstrings should at minimum describe the purpose of the class. 126 | + Great docstrings include examples of common use; errors, exceptions, and panics that the code can cause; any side effects or argument mutation; background information needed to understand what the code does; and the purpose and intended use of the code. 127 | + Whenever you change the source of an object, check to make sure that the docstring is still correct and complete. 128 | - **Types**: Code examples and notebooks are much easier to read when the reader knows or can discern the types of each variable 129 | + When you introduce a function, describe its type signature, especially its return type 130 | + Talk explicitly in prose about the types of variables - what they're for, what data they hold, and what methods/behaviors they have 131 | + Link to the API docs for types as you introduce them 132 | - **Code in prose**: Render names taken verbatim from code in `monospaced font` to signal that it is code, but don't overdo it 133 | + Code used to invoke software often has a similar name to the software itself, but this doesn't mean that they're interchangeable. In prose, call things by their (correctly capitalized) name, not their invoking command. 134 | * "Python", not "`python`", "`python3`", or "python" 135 | * "GROMACS", not "`gmx`" or "Gromacs" 136 | * "Conda", not "`conda`" or "conda". 137 | * "Amber", not "AMBER" 138 | + Don't pluralize or otherwise conjugate names from code when they're monospaced. "`ForceField` objects", not "`ForceField`s" or "`ForceFields`". "Run `python`" or "Run Python", not "Run `Python`" 139 | + Feel free to come up with English names for the objects you're describing. This can make reading easier, as the prose is not constantly changing font, but also makes writing easier 140 | * "The `np.array()` function returns an array, which stores its contents in contiguous memory. Arrays are instances of the `ndarray` class." 141 | 142 | 143 | ## Git Friendliness 144 | 145 | Git's line-based diffing algorithm is great for code, but doesn't play very nicely with prose. There are three strategies for dealing with this: 146 | 147 | - **Use hard-wrapping; break at <= 80 characters**: This strategy introduces 148 | hard line breaks at word boundaries if a word would run over 80 149 | characters line width. This can be a bit of a pain to write in editors 150 | that don't automate hard wrapping, but it looks great to read in any 151 | editor. Paragraph breaks involve a double line break. Diffs usually 152 | include the remainder of the paragraph after the spot where a change 153 | occurred, but small changes can be isolated to a single line. 154 | - **Use soft-wrapping and break at paragraph boundaries.**: This strategy uses your text editor's line wrap functionality to wrap text. It's easy to write and doesn't require any post-processing, but can be problematic when viewed without soft-wrapping. With this strategy, git diffs include the entire paragraph surrounding any changes, and multiple changes to a paragraph will be rendered as a single diff. 155 | - **Break at sentence boundaries**: This strategy introduces a line break at the end of every sentence, and a double break at the end of paragraphs. 156 | This establishes an analogy between sentences and lines of code, but usually doesn't look great. 157 | It does, however, produce very clean diffs, as changes to a sentence only include that sentence in the diff, and not the following sentences. 158 | 159 | ## Other Reminders: 160 | - **Report uncertainties with one significant digit of precision**. Round the associated value to the correct precision based on the uncertainty. For example, “3.247 +/- 0.134” becomes “3.2+/-0.1”, and “0.3247 +/- 0.0134” becomes “0.32+/-0.01”, etc. Deal with the uncertainty first, then round the value accordingly. 161 | - **Render values as number-space-unit** 7.8 mm, not 7.8mm. Prefer SI units over non-SI alternatives. Uncertainties go before units: 31.4±0.9 kJ/mol. 162 | - **Use dashes correctly** 163 | - hyphen `-` "-": Separates compound words and words broken over a line-break 164 | - en dash `--` "–": Separates ranges of numbers: 1–5 165 | - em dash `---` "—": Separates distinct clauses — or parentheticals — within a sentence 166 | - **Use spell check** It makes life easier. All major text editors should either have spell check built in, or have a plugin available for it, so writing in LaTeX or Markdown is not an excuse. 167 | -------------------------------------------------------------------------------- /Writing/WritingTips.md: -------------------------------------------------------------------------------- 1 | # Writing Tips 2 | 3 | This document provides some tips on how to go about writing a paper and using the "outline first" strategy we usually prefer. 4 | 5 | **Disclaimer**: This is not nearly complete and needs much expansion. 6 | 7 | Please: Get an ORCID (unique researcher identifier) and include it in your work: https://orcid.org/ (free) 8 | 9 | ## Other related content in our lab materials 10 | See the [group style guide](https://github.com/MobleyLab/Training/blob/main/Writing/StyleGuide.md) for language and word issues. 11 | 12 | ## Potentially helpful tips: 13 | - Start by writing an outline 14 | - Use the group outline template, to be made available here at a later date 15 | - Begin by identifying the objective(s) of your paper -- what will it attempt to do/show/communicate and why? This dictates a lot about the outline 16 | - Identify a target journal or journals as this also affects the structure significantly 17 | - Then write a high level outline of the major sections -- what are the section titles and what major points will you make in each? 18 | - Usually save outlining -- and writing! -- the introduction and conclusions until the end, as these are often hardest 19 | - Eventually get down to a detailed outline, with at least a bullet point per paragraph and probably a bullet point per sentence before it is done 20 | - You will also want to (ultimately) identify all of the figures you’ll have, what data they’ll show, etc. Sketch your figures if needed and get feedback (or do quick draft figures), so you don’t waste time making and refining figures no one will want 21 | - Your outline can also list many of the references you’ll have 22 | - **Why write an outline first?**: 23 | - Separate the process of “picking the right words” from the process of “deciding how the paper should be organized”, and make it so that once you start to write, you only have to pick the right words 24 | - Deal with organizational issues (such as “this part belongs in the introduction") with your PI and other authors before you write the paper, to minimize the amount of rewriting you have to do 25 | - Writing an outline first helps you separate the hard process of thinking about what to say from the hard part of thinking about what words to use. Separating these parts makes it easier. (Scott Shell points out that a typical paper is about 7000 words; if you write for four hours a day for two weeks that's an average of 150 words per hour or 2.3 words per minute, which is nothing compared to writing a paper in a night for a college class. Thus it should never take multiple months to write a draft, unless you're wasting a lot of time somewhere -- and if you are, let's figure out where and why.) 26 | - Make sure you’ve read Plaxco’s work on “the art of writing science”, and if you follow just one rule from it, make it be the “the first sentence of every paragraph states the point of the paragraph” rule (see here https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3009394/) 27 | - Know who is taking the lead role on the paper, and, if it’s you, know what that involves (e.g. see https://journals.plos.org/ploscompbiol/article/file?id=10.1371/journal.pcbi.1006508&type=printable ) 28 | - Follow Credit Taxonomy for tracking people’s contributions: http://www.cell.com/pb/assets/raw/shared/guidelines/CRediT-taxonomy.pdf 29 | 30 | ## Tips for the writing process 31 | - Identify what task you are working on at present and do **only that task** 32 | - If you're writing, don't get derailed by needing to fill in references. I like to write `[ref]` or `[ref Boresch paper]` or similar as I'm going to leave notes to myself that are easy to return to later. 33 | - Focus on **getting your ideas down** when it is time to write 34 | - Not on editing 35 | - You want to keep your train of thought going as you write, remembering where you came from and where you're going. So don't let anything interrupt that 36 | - **Turn off notifications**. Write for designated blocks of time interruption free. 37 | - If you're filling in references, focus on filling in references; don't go off onto a deep dive into the literature 38 | - Do a deep dive into the literature when it's time for that 39 | - Build in procrastination breaks. 40 | - Likely you will only be able to maintain focus for a certain amount of time 41 | - Learn how long that is and then build in breaks for a designated amount of time to refresh/recover 42 | - Something like the Pomodoro technique can work well for this 43 | - Unless you are superhuman, you likely will not be able to stay deeply focused exlusively on writing for hours at a time; if you try to, you'll end up surfing the web or cleaning your house or... 44 | - Plan for this; learn what your limits are and make your work blocks smaller than those limits 45 | - Identify if you have writers block and get help. 46 | - If it's hard to get going -- either on an outline or through a paper itself -- get help 47 | - I (Mobley) find that it sometimes helps first-time paper-writers if we block out an extended period of time sit down together and collaboratively write a first draft, either of an outline or a paper 48 | - If you need this, or think it might help, let's talk 49 | - It can be very satisfying to enter the room for an extended writing session, sit down together for a few hours, and leave with a draft that is complete enough to be able to continue fleshing it out on your own 50 | - This can require significant advance planning (e.g. I might not have a big block of time except on a weekend or if we plan far ahead) 51 | - Others could also help 52 | 53 | ## LaTeX tips 54 | - Usually we use Overleaf for shared editing/writing in LaTeX 55 | - Many journals ask revisions to be accompanied by something highlighting the changes which were made in revision. Be sure to save a version of your Overleaf before making these edits, then use `latexdiff` on the before-and-after versions to prepare a nice PDF with changes highlighted. This can also integrate with Git, e.g. [`git-latexdiff`](https://gitlab.com/git-latexdiff/git-latexdiff). 56 | 57 | ## Other recommended materials elsewhere: 58 | - [Helmut Grubmuller's writing guidelines](https://www.mpinat.mpg.de/631838/guidelines_english.pdf): These give a variety of useful and important tips on one of the key parts of writing and editing -- how to think about what the READER is thinking based on what you wrote. It's not just an issue of checking whether our words accurately represent what is in our heads -- but whether they get the reader to understand what we want them to understand. This also gives a variety of very concrete ways to improve scientific writing. 59 | --------------------------------------------------------------------------------