- Understand how to set up a centralized location for project storage/management
- Understand the purpose and use of the wiki
- Understand how the different ways folders and components can be used to organize a project
Hopefully you all had a chance to skim over some of the files I emailed to you yesterday. The files are a small subsection of materials from the 2012 Annual National Election Survey in the US, which we will be using for today's workshop. Don’t worry, you don't need to know anything about US politics or elections; it is simply a dataset that can be easily understood no matter your background.
I emailed you the materials this morning. If you open up the filed called, ‘Questionnaire’, you’ll notice a sample of 12 questions that respondents answered in the survey. Each group will decide amongst themselves, from the available materials, what their research question will be, variables they want to use, analyses they want to perform, how they want to build and structure their project, and how open to make the project.
We talked before about problems when we don’t document our work along the way. Documenting after a study is accepted for publication is difficult, and this is even more challenging for collaborative projects with the workflow involving passing materials back and forth by email and otherwise. A common result is a distributed, unstructured network of materials, with some documents on your computer, others in Dropbox, and multiple versions of the same files in various email threads. Often, you may not be able to find the correct files for your own use, let alone others trying to figure out what you did. To avoid these problems, we will use the OSF as a collaborative space. Our study will be organized and documented in a centralized location with support for managing file versions and changes over time.
Now that you are all signed in, you should see the project dashboard. This is where you will start each new project. A project on OSF can be anything: a lab group, an organization, a grant, a line of research, an individual experiment, etc. Think of your project as the top level of a nested structure. You’ll be able to nest as many things under it as you like.
Since we don’t have any projects yet will be only working on one research project, let's create a project for our study. If you are the PI in your group, please click on the ‘create project’ button and give the project whatever title you choose. If you would like to give the project a short description you may. Later you can add a longer description in the project wiki. Go ahead and create the project:
Activity: PIs create new project
If you are a PI, you should now see something that looks similar to my screen. If you aren’t a PI, you can follow along on my screen for the moment. This is the project overview page. Any project you create on the site will start out looking similar to this. You can then customize it to fit the needs of your particular project or workflow. The system was built to be agnostic to discipline, which is why projects start out so bare.
The project overview page has a few different sections. The wiki is a collaborative editing space that you can use to include important overview information about the project, including things like READMEs, abstracts, research questions, outlines, etc. The file tree is how you upload and navigate to files in the system; most file types are accepted such as CSVs, Word documents, PowerPoint slides, PDFs, and image or video files. The component section is how you add additional structure and nesting to your project (we will talk more about this later). You will also see the citation widget, which displays the automatically generated citation for the project:
In your browser's search bar, you will notice a 5 letter string at the end of the osf.io url. This entire web address is a GUID, or a 'Globally Unique Identifier.' This permanent, unique identifier has been assigned to this project page and will always point back to it unless the project is deleted.
If you are the graduate student or RA in your group, go ahead and type in the GUID of the project your PI created.
Activity(Question): What are GS & RAs seeing after typing in GUID?
If you aren’t a PI, you should see a screen that says you don’t have access to the project. This occurs because all projects on the OSF are set to private by default. As such, only people who have been added as contributors to the project have access to see and/or edit it. On our example project, the PI is the only contributor because he/she created it. Since we want this to be a collaborative project, we need to give the other two members of your team access to the project. Add your team members as contributors by going to the sharing tab and clicking.
Here, I can search for people who I want to add as collaborators, then click the + icon to add them to the project.
You will notice that each person is given a specific permission setting for access to the project. There are three possible settings, admin, read + write, and read. Read access means the contributor can see into the project and download files, but they will not be able to add files or modify content. Contributors with Read + Write access can add and modify files, but they cannot change any of the settings on the project. For example, they cannot add new contributors or change the privacy settings. Administrator access allows a contributor to do anything with the project and files. I can assign different permission settings to different contributors.
PIs, go ahead and add your graduate student and RA collaborators to your project. You can decide what level of access you want to give them, but keep in mind that everyone will need the ability to upload files.
Activity: PIs add other groups members as contributors
Grad students and RAs, if you try the GUID again, you should now be able to see the project page. Does everyone see their project page? If you check your email, you will also notice that you have received an alert that you have been added to this project. This way, no one can secretly add you to projects without your knowledge. And, if you do not want to be on that project, you can easily remove yourself.
If we now go back to the project overview page, you’ll notice that all three people are listed as contributors on the project and they are also listed in the auto generated citation for the project.
If you wanted to give someone access to your project but did not want to give them authorship credit, you can do this via the 'sharing' tab as well. Perhaps your RA needs access to your project but you typically give your RAs acknowledgements rather than authorship; you can uncheck the ‘bibliographic contributor’ box next to that person’s name on the 'sharing' page.
Now that you have created a project you and your group members can access, the next thing to do is to write down some information about the project - such as the purpose of the project, our initial research question, etc. As the project evolves over the course of the research lifecycle, documenting this information as you go will make it easy for us to retrace the project history. This section can start out pretty loose or very detailed depending on whether it is, for example, exploratory versus confirmatory research. On the OSF, a good place to put this type of information is in the wiki. The wiki is a real-time, collaborative editor, meaning your whole group can work on it at once. It can also be formatted using markdown if you want to get fancy. Access the wiki by clicking on the widget and then clicking on the ‘edit’ button in the upper right corner. This will open up the text editor.
Let's have you take a minute to set up a wiki for your project. Take a few minutes to discuss amongst your group what you are interested in looking at with regards to the ANES dataset I gave you. Then, collaboratively enter in your research question and hypotheses (if you have them).
Activity: Create wiki with RQ and hypothesis
Right now our project is pretty flat. It is basically one big folder with some content entered in the wiki. For many projects, we will want structure by adding sections to organize related files. For example, we might want to organize all our data files together and keep those files separate from protocols or study materials. If we had set up a project for a lab group or an institution, you might have separate sections for each person in the lab, or each line of research. On the OSF, you can do this in two ways. The first way to add structure to a project is to add components. You do this by clicking the add component button on the right of your screen. You can name the component whatever you want (materials, data, protocol, IRB, etc.) and you can also choose a category.
Once the component is created, we see that its structure is the same as the higher level project we created earlier. Components have their own file trees, wikis, contributor lists, and privacy settings. We can also nest components within components. Components are a way to organize different types of files in a project, while also allowing you to set up areas that have different privacy settings or contributor lists from other sections in the project. This can be important for having fine grained control over access to different parts of a project.
Folders are another organization option that function differently than components. A folder is simply a way to group files. If we click on the OSF storage icon you’ll notice that a create folder button will appear.
We can name this folder what ever we like.
If you click on the folder, it will only expand - you won’t be taken into the folder and it doesn’t have a wiki or it’s own access settings. Access settings are the same as the project/component it is nested under. Therefore, folders help organize files, while components help set up large sections of a project.
Now that I’ve explained the difference between components and folders, we can work on giving our projects some structure. There are no right or wrong way to set up your project, and you can always rearrange things later. Think through the major categories of file types you might have (i.e. hypotheses, methods, data), and whether you might want to toggle the public/private settings (i.e. perhaps you only want to make your hypotheses and methods public). You can also change your contributors' access (i.e. you may want your RA to have only read access to your data). Finally, determine whether you want to set them up as folders or components.
Activity: Create project structure using folders/components
The last thing we’re going to do is to add some background literature to the project. However, instead of upload the PDFs I sent you directly to the OSF, we’re going to take advantage of the OSFs add-on capabilities. Add-ons allow you to connect third party services to the OSF so you can continue to use the tools that you like, but connect them so that you, your collaborators, and readers of your work, only have to go to one place to find all aspects of your project. If you go to the settings page of your project you can see the different add-ons that are available.
For the background literature, we’re going to use one of the storage add-ons. I’m going to show it with Dropbox, but if you don’t have a dropbox account you can use Box or Googledrive. RAs, if you would go into your Dropbox account and create a folder called ‘demo project’ and then upload the PDFs to that folder. Now, go to your OSF project and create a new component for the ‘background literature’. We don’t have to put the add-on in it’s own component, but this will allow us to keep these PDFs private if we decide we want to make the rest of the project public.
When you’re inside the ‘background literature’ component, go to the settings tab and check the Dropbox add-on, or whichever one you are going to use. This will bring up some information on exactly how this add-on will function.
Click confirm, and then click apply below the list of add-ons. You will then be asked to connect your account.
You’ll be taken to dropbox where you will have to input your username and password, and will then be asked to allow OSF access to your dropbox.
Back at the OSF, you’ll now see a list of all your dropbox folders in your project. RAs, you are the only people that can see this. Select whichever folder you want to connect to your project and click save.
If we now go back to our project we’ll see that the PDFs appear within the background literature section of our demo project.
What this has done is create a two-way door between the OSF and Dropbox. Any changes we make to that Dropbox folder will show up in our project, and any changes we make to the materials from the OSF will show up in Dropbox.