add protocols db user guide

docs/protocols.md

@@ -22,40 +22,21 @@ The Open MR Protocols working group have developed a database for scanner protoc
 
 Each deposited protocol contains all information necessary to reproduce that sequence on an appropriately licensed scanner, allowing yourself and others to have a permanent and full record of your data acquisition methodology.
 
-Coming soon
-{: .label .label-yellow }
-
-**THIS TOOL IS CURRENTLY IN DEVELOPMENT. PLEASE REFER TO THE INFORMATION BELOW TO UNDERSTAND THE AIM AND AMBITION OF THIS PROJECT. THE "HOW TO" GUIDE WILL BE BUILT BY THE COMMUNITY AND TOOL DEVELOPERS IN THE COMING MONTHS.**
-
-<br>
-
-[![For WIN members](../../img/btn-win.png)](https://open.win.ox.ac.uk/pages/open-science/community/Open-WIN-Community/docs/tools/protocols/#for-win-members)      [![For external researchers](../../img/btn-external.png)](https://open.win.ox.ac.uk/pages/open-science/community/Open-WIN-Community/docs/tools/protocols/#for-external-researchers)
-
-## For WIN members
-### Benefits
-#### Version control ![version-control](../../img/icon-version-control.png)
-The MR Protocols database is version controlled, so WIN members are invited to upload their protocols during pilotting to keep track of optimisation and final versions. Comments and notes can be added to each entry to you can keep well structured documentation about why certain decisions were made. You can also link database entries with acquired data held on the [Open Data](../data) server
+[![For WIN members](../../img/btn-win.png)](https://open.win.ox.ac.uk/pages/open-science/community/Open-WIN-Community/docs/protocols/protocols_guide_internal/)      [![For external researchers](../../img/btn-external.png)](https://open.win.ox.ac.uk/pages/open-science/community/Open-WIN-Community/docs/protocols/protocols_guide_external/)
 
-#### Citable research output ![doi](../../img/icon-doi.png)
-Versions (with minor and major edits) can be assigned a digital object identified (DOI) using the [Oxford Research Archive (ORA) Data repository](https://deposit.ora.ox.ac.uk) using the stable link provided by the MR Protocols database. Once a DOI has been created, your MR protocol becomes a citable object which you can add to your list of research outputs.
 
-#### Reproducible methods detail ![reproduce](../../img/icon-reproduce.png)
-Depositing your MR protocol in the database is as simple as uploading the sequence pdf available from the scanner console, or alternatively you can upload the .exar file used by our [Siemens scanners](https://www.win.ox.ac.uk/about/facilities). All sequence detail is captured from either document, and parsed into a unified machine readable and searchable format. You can upload a single sequence, or all sequences used in a single imaging session (a protocol) together.
+## Citation
 
-## For external researchers
-External users will be able to search the database for MR protocols which individual research teams have chosen to make openly available. These may be deposited to support publications as supplementary methods material, or they may form the main body of research in sequence development.
+If you use this tool, please cite...
 
-Both internal and external users can search the database using keyword terms based on anatomy, the imaging system, sequence types, or the theoretical application.
-
-## How to use
-### Access
-Access the [Open MR Protocols Database](https://open.win.ox.ac.uk/protocols/)
-
-Detailed guidance on how to use the Open MR Protocols is available for
+Coming soon
+{: .label .label-yellow }
+## License
 
-- [WIN members](../../../docs/tools/protocols_guide_internal)
-- [External researchers](../../../docs/tools/protocols_guide_external)
+This tool has been openly developed and shared using an open source license. You are free to...
 
+Coming soon
+{: .label .label-yellow }
 
 ## Working group members (alphabetically)
 We are grateful to the following WIN members for their contributions to developing the Open MR Protocols database

docs/protocols/protocols_guide_external.md

@@ -8,10 +8,129 @@ nav_order: 2
 ---
 
 
-# User Guide for Non-WIN Researchers
+# User Guide for External Researchers
 {: .fs-9 }
 
-Coming soon
-{: .label .label-yellow }
+A guide for external researchers on how to use the Open WIN MR protocols database
+{: .fs-6 .fw-300 }
 
 ---
+
+## For external researchers
+External are able to search the database for MR protocols which individual research teams have chosen to make openly available. These may be deposited to support publications as supplementary methods material, or they may form the main body of research in sequence development.
+
+Both internal and external users can search the database using keyword terms based on anatomy, the imaging system, sequence types, or the theoretical application.
+
+
+**Contents**
+- [Purpose](#purpose)
+- [Scope](#scope)
+  - [Other resources](#other-resources)
+- [Intended Audience](#intended-audience)
+- [How To Access MR Protocols](#how-to-access-the-open-win-mr-protocols-database)
+- [How To Cite A Protocol](#how-to-cite-a-protocol)
+- [Example](#example)
+- [How To Create Your Own Protocols Database](#how-to-create-your-own-protocols-database)
+- [Contact](#contact)
+  - [Feedback](#feedback)
+
+
+## Purpose
+
+> What is the Open WIN MR Protocols Database?
+
+This doc provides guidance for *external* users. Text will be drafted here and added to the help page of [the database](https://open.win.ox.ac.uk/protocols)
+
+### Other resources
+
+The Open WIN MR Protocols Database is designed and hosted by the [Wellcome Centre for Integrative Neuroimaging (WIN Centre)](https://www.win.ox.ac.uk/) at the [University of Oxford](https://www.ox.ac.uk/). The database is part of [**Open WIN Tools**](https://open.win.ox.ac.uk/pages/open-science/community/Open-WIN-Community/docs/tools/), a collection of software tools and infrastructure to openly and effectively share research outputs, incl. acquisition protocols, experimental tasks for fMRI, FSL analysis pipelines and data.
+
+
+## Intended Audience
+
+An *external user* is anyone without Oxford University Single-Sign-On (SSO) credentials or anyone outside WIN (**?**)
+
+Anyone looking for a specific MR protocol -- for informational, reference, teaching, research or any other purposes -- can download open access protocols.
+Each deposited protocol contains all information necessary to reproduce that sequence on an appropriately licensed scanner. The aim of this database is to speed up translation across groups and institutions by facilitating open and reproducible research.
+
+*Internal users* can also access non-public protocols. For more information, see our [guide for internal users](user-guide-internal.md).
+
+
+## How To Access The Open WIN MR Protocols Database
+
+![gif - external](./figures_external/gif_external.gif)
+
+- Go to start page: https://open.win.ox.ac.uk/protocols/
+- No login required to download open access protocols
+- Enter a keyword or search term in the search box
+- Browse list of available protocols
+- Select individual protocols to view acquisition details
+- Download protocol (includes meta-info and full sequence information)
+
+
+---
+
+## Example
+
+**1. Search** for all open access (i.e. publicly available) protocols that contain the keyword *T1*
+
+![WIN MR Database - Home](./figures_external/screenshot_mr_db_home.png)
+
+**2.** The search returns a **list of open access protocols** containing *T1*, with additional information on species, project name and date of most recent changes to each entry.
+
+![WIN MR Database - Search](./figures_external/screenshot_mr_db_search.png)
+
+**3. Select** the **UK Biobank v4.0_0001** protocol to view details. The first section contains some general information about the protocol, including a stable URL for quick access, version history and scanning info.
+
+![WIN MR Database - Protocol overview](./figures_external/screenshot_protocol_overview.png)
+
+**4.** The section **Protocol Info** provides some additional meta-information (project name, description, usage guidance) and a summary of the sequences used. Below the summary, detailed information is given for each indivdual sequence, incl. keywords, description and the necessary acquisition time.
+
+![WIN MR Database - Protocol info](./figures_external/screenshot_protocol_info1.png)
+![WIN MR Database - Protocol info](./figures_external/screenshot_protocol_info2.png)
+
+**5. Download** protocol: At the top of the page, just below the protocol name is the download button. This will lead to a download link for a zip file that contains the information shown in the protocol overview plus full configuration details for each sequences (not shown online).
+
+![WIN MR Database - Protocol download](./figures_external/screenshot_protocol_download1.png)
+![WIN MR Database - Protocol download](./figures_external/screenshot_protocol_download2.png)
+
+
+Note that the amount of information and detail shown may vary across protocols. For additional information and questions, please refer to information, links and contact information given under "Usage Guidance" in the *Protocol Info* section.
+
+
+ 
+
+## How To Cite A Protocol
+
+Please use the DOI associated with each protocol when citing. The preferred format is *Author(s). Year. Protocol name. DOI. URL. (??)*
+
+
+## How To Create Your Own Protocols Database
+
+The main source code for this database is openly available on [gitlab](https://git.fmrib.ox.ac.uk/acquisition/win-protocols-db).
+
+If you reuse the code to build your own database, please cite it as <mark>Open WIN MR Protocols Database. XX. YY. DOI. ??</mark>
+
+
+## Contact
+
+Information about who to contact about this protocol should be provided in the usage notes (*Protocol Info -> Usage Guidance*). If not and you really need to contact someone, please [get in touch with us](https://open.win.ox.ac.uk/protocols/about).
+
+### Feedback
+
+For feedback on this documentation, please use [gitlab issues](https://git.fmrib.ox.ac.uk/acquisition/win-protocols-db/-/issues).
+
+~
+
+# <mark>Notes for us when writing</mark>
+Things to add:
+- [x] Info for who to contact about this sequence should be written in the usage notes. If it it not and you really need to speak to someone, please [contact us](https://open.win.ox.ac.uk/protocols/about).
+- [x] How to cite
+- [x] Download only access
+- [x] Give link to how to feedback on this documentation (gitlab issues)
+
+# <mark>Open issues</mark>
+- [x] Can the downloaded file be named something more meaningful? (e.g. "WIN_open_protocol_\<Name\>")
+- [x] What is the preferred format for citing a protocol? E.g. something like *Author(s). Year. Protocol name. DOI. URL. (??)* - as specified from the zenodo entry
+- [x] The [gitlab](https://git.fmrib.ox.ac.uk/acquisition/win-protocols-db) repo for the database source code needs a DOI to be included here. - TBC when writing paper for JOSS
+- [x] What should the format be for citing the source code for the database? - as above

docs/protocols/protocols_guide_internal-how-1.md

+---
+layout: default
+title: Add a new protocol
+grand_parent: Open MR Protocols
+parent: WIN Members
+has_children: false
+nav_order: 3
+---
+
+
+# Adding a new protocol entry to the database
+{: .fs-9 }
+
+
+---
+
+![open-protocols](../../../img/img-open-acq-flow.png)
+
+
+## Contents
+- [1. Prepare the required files](#1-prepare-the-required-files])
+- [2. Upload](#2-upload)
+- [3. Top level protocol information](#3-top-level-protocol-information)
+- [4. Attachments](#4-attachments)
+- [5. Sequence level protocol information](#5-sequence-level-protocol-information)
+- [6. Save](#6-save)
+- [7. Set visibility](7-set-visibility)
+- [8. Reference List](8-reference-list)
+
+
+#### 1. Prepare the required files
+
+##### 1.1 Ask your radiographer for your protocol pdf and scanning procedure file.
+Your scanning procedure file (.doc) and scanner protocol (.pdf) will be given to by your radiographer at the start of your project. You will be provided with a new version if there are changes in the protocol. You can request copies of these files by emailing radiographers@win.ox.ac.uk with your calpendo project number.
+
+##### 1.2 Request permission from the radiographer author of the scanning procedure to add them as an author on the public doi record of your protocol.
+The radiographer author of your scanning procedure is listed at the top of the file. Contact this radiographer and ask their permission to be listed as a contributor to this protocol on the public doi record. Request the radiographers ORCID ID for inclusion.
+
+##### 1.3 Redact confidential information from the scanning procedure and convert it to a pdf.
+Any names should be redacted from the scanning procedure unless permission to be listed has been provided by those individuals. Review the complete scanning procedure document (including instructions such as "check voxel location with <NAME>") and redact all identifiable information which you do not have permission to share. These details can be replaced with the word "REDACTED" or covered with a black rectangle.
+
+Review all images and ensure that identifiable information such as participant IDs are redacted (cover with a black rectangle). Ensure identifiable facial features (in sagital views of slice pack positioning) are redacted (cover with a black rectangle).
+
+Currently, only the owner of the project is able to edit the uploaded protocol. If you would like to suggest changes to someone else's protocol you can do so by emailing the admin team who can then contact the project's owner.
+
+You might want to add a statement such as "available for re-use, but I'm unable to assist with implementation" in the usage notes to clarify the extent of assistance you are able to provide.
+
+#### 2. Upload
+
+##### 2.1 Log in to the database.
+
+Only WIN members (as determined by SSO authentication) are able to deposit protocols in the database.
+
+![gif-log in](../../../img/img-protocols/gif_login.gif)
+
+To log in:
+1. Go to [https://open.win.ox.ac.uk/protocols/](https://open.win.ox.ac.uk/protocols/)
+2. Click the "Login" icon on the top right of the screen
+3. Click the "Login via Shibboleth" option and enter your Oxford SSO details when requested.
+
+
+
+##### 2.2 Add a new protocol entry
+
+Protocols are saved to individual user profiles.
+
+![gif - add new protocol](../../../img/img-protocols/gif_add-protocol.gif)
+
+1.  Once you are logged in, you will see the "**Add Protocol**" icon.
+2. Click on "**Add Protocol**", and you will be taken to the "**Add new protocol**"" page.
+3.  Click the "**Browse**" button to open a file explorer.
+4.  Navigate in the file explorer to the scanner protocol (.pdf) you want to upload. Select "open" in your file explorer.
+5. Click on the "**Add new protocol**" button to upload the selected pdf to the database.
+
+
+
+##### 2.3 File type error
+If the uploaded file is recognised as a sequence pdf, you should see the **Register Protocol** page. If the file is not in the right format, you will see an error. Please check the file you have selected is a pdf of your MR protocol.
+
+#### 3. Top level protocol information
+You can enter details about your protocol which are relevant to the study as a whole, or all sequences. These details are entered at the top of your protocol. These details will help future users understand your decisions or implement your protocol.
+
+![gif - top details](../../../img/img-protocols/gif_top-details.gif)
+
+##### 3.1 Project, hardware and species
+Some fields of this section are identified by the database from your pdf. Others have to be selected by you. Complete the following selections by selecting the appropriate item from the dropdown menus.
+1. Project (select from Calpendo registered projects)
+2. Scanner
+3. Species
+4. Post mortem (tick if appropriate)
+
+##### 3.2 Keywords
+Keywords can be used by users to find your protocol. Note that when users are searching for a protocol, their search query will be matched to keywords only, not text in the body of the entry.
+
+Start typing keywords to select from a built in list. Consider adding keywords relating to:
+1. The sequence type (e.g., "T1 structural")
+2. Regions of interest
+3. The participant population or clinical condition
+4. Cognitive or behavioural function
+5. Task or stimulus properties
+
+
+##### 3.3 Description
+This section should identify and highlight important features of the protocol. For example the study design, methods, and procedure. The Radiographers procedure abstract is sufficient.
+
+
+##### 3.4 Usage guidance
+This section should provide high-level instructions for use of this protocol. Where possible, we recommend including the following:
+1. **Contact details** for anyone looking to discuss re-use of the project. Note this information will be publicly available if your protocol is made public. Only include contact details where explicit permission has been granted.
+2. **How to cite** this entry, including any references you would like to be cited in addition to this entry (see [Issuing a doi and licence](#issuing-a-doi-and-license) below)
+3. **Your terms for reuse** (see [Issuing a doi and licence](#issuing-a-doi-and-license) below), including any specific terms around authorship before others reuse this protocol. For example, "We request that future users of this protocol contact the authors of this entry to discuss collaboration and authorship agreements relating to reuse." This may be particularly relevant for experimental protocols or sequences.
+
+You may also like to include some practical guidance, such as the total length of the scanning session, staffing levels, or any peripheral equipment. You may refer the reader to the radiographers procedure file if this is to be attached (see [4. Attachments](#4-attachments)).
+
+You should also highlight non-standard software or sequence requirements, such as custom pulse sequences.
+
+
+#### 4. Attachments
+Browse to and add any attachments to support the implementation of your protocol. This should ideally include the (redacted) radiographers procedure. You may additionally chose to attach analysis of pilot data, for example.
+
+*Note that there is a file size limit of 15MB for each individual file attached*
+
+#### 5. Sequence level protocol information
+You can add details specific to individual sequences. These details may make it easier for users of this protocol to understand the outputs if the protocol is run, information about why these sequences where chosen or refer to decisions made during pilotting. You may reference back to earlier versions of the protocol entry to indicate changes where appropriate.
+
+Each of the sections below should be completed for each sequence.
+
+![gif - sequence details](../../../img/img-protocols/gif_sequence-details.gif)
+
+##### 5.1 Sequence name
+This is identified from the pdf. You can update it or add any additional context where necessary.
+
+##### 5.1 Sequence keywords
+1. Keywords including for example modality, ROIs, clinical conditions, study population, study type.
+
+##### 5.2 Sequence description
+The sequence description provides key features that might help someone choose whether it meets their needs. For example, “A standard T1-weighted structural scan, of 1mm isotropic resolution, suitable for registration to a standard template in an FMRI protocol.".
+
+It may additionally be useful to disambiguate any abbreviations in the name of the sequence, for example "bold_mbep2d_MB4P2_task_faces" could be described as "multiband 2D echoplanar sequence; multiband acceleration factor 4, PAT (GRAPPA) factor 2; for faces task.".
+
+For fieldmap sequences, it may be useful to say which BOLD sequence they will be used to correct.
+
+Where a specific task is mentioned, you could link to where that task is shared, or published analysis of any data using that task.
+
+#### 6. Save
+Once all required fields have been completed, you will be able to save the entry to the protocols database. Press "Save" to progress to return to the list of your protocols
+
+
+#### 7. Set visibility
+By default, your entries will be set to "Internal (University Only)" visible when you add them to the database. This means users will be required to log into the the protocols database with an SSO <mark>confirm WIN SSO?</mark> in order to review or download your entry.
+
+After they have been entered onto the database you can make individual protocols publicly visible ("Open Access") and identify them as "WIN Recommended" protocols as appropriate.
+
+"Open Access Actions"
+If you choose to make a protocol public ("open access") ensure you have added a license note to your entry, reserved a doi for the protocol using zenodo, and added the doi to the usage guidance (see [Issuing a doi and licence](#issuing-a-doi-and-license) below).
+
+#### 8. Reference List
+This field features prominently at the top of the entry when it is accessed by users, so it may be appropriate to repeat any important citation information which is listed in the usage guidance.
+
+Add any references which are relevant to this protocol, for example the paper or pre-print which it accompanies. You can also use this space to draft the author list and track changes in contribution.
+
+We recommend that you consider using the [CRediT](https://casrai.org/credit/) system for identifying individual author contributions. You may wish to order authors alphabetically.
+
+![gif - references](../../../img/img-protocols/gif_references.gif)

docs/protocols/protocols_guide_internal-how-2.md

+---
+layout: default
+title: Issue a doi and license
+grand_parent: Open MR Protocols
+parent: WIN Members
+has_children: false
+nav_order: 4
+---
+
+
+# Issuing a doi and license
+{: .fs-9 }
+
+
+---
+
+![open-protocols](../../../img/img-open-acq-flow.png)
+
+
+We suggest you use the free tool Zenodo for creating a doi for your protocol. This will allow others to cite your protocol independently from other work in the study, and add contributors who may not be named elsewhere.
+
+#### Who to include as an author
+
+This is an opportunity to provide attribution to all individuals who contributed to this project up to the point at which the scanning protocol was finalised and/or published. This may include individuals who contributed to each of the stages below:
+- Gaining ethical approval
+- Registry as a clinical trials or pre-registration
+- Sequence development or pilotting
+- Analysis of pilotted data
+- Authoring of the Radiographer's procedure
+
+##### ORCID
+Where possible, we promote the use of ORCID to consistently identify and attribute authors. Request that your contributors provide their ORCID for inclusion. Alternatively you can look them up on the [ORCID database](https://orcid.org) but make certain that you have found the correct individual.
+
+##### CRediT
+You may wish to consider assigning authorship using the [Contributor Roles Taxonomy (CRediT) notation](https://casrai.org/credit/), which is now formally recognised by major publishing houses. Using this standard, the contributions of each individual are clearly stated against pre-defined contributor roles. This taxonomy is often paired with alphabetical ordering of authors, rather than prioritising "first author" and "last author" positions.  
+
+##### Tenzing
+You can write a CRediT statement by hand, or you can use a tool to curate the required information. The [Tenzing app](https://rollercoaster.shinyapps.io/tenzing/) can use a csv table of author information to generate CRediT statements in multiple different forms.
+
+You can collect the author information (for example ORCID, affiliations, funding acknowledgements) using the google table linked via Tenzing (see [How to use tenzing](https://rollercoaster.shinyapps.io/tenzing/)). Alternatively you are welcome to take a copy of this [MS Form: Authoring information for CRediT statement (Open WIN)](https://forms.office.com/Pages/ShareFormPage.aspx?id=G96VzPWXk0-0uv5ouFLPkYMD50Te0q5HobQjqRFNJmpUM0NHR01CTkxZV0dTMUxLR0hQOTJGTURUTC4u&sharetoken=2cQ8XQ8eqkhqEhTRQT51) to collate your author information. Send the form to each of your intended authors and use the information collected to generate the csv table required by tenzing.
+
+
+#### Using Zenodo
+
+The below basic process outlines how to upload a document to zenodo to generate a doi. We have also provided boilerplate text suggestions for use where relevant.
+
+Note once you publish your protocol with zenodo, it cannot be deleted. If you are doing this for the first time, or are otherwise uncertain of the process, Zenodo provides a practice sandbox website for testing. This can be found at [sandbox.zenodo.org](https://sandbox.zenodo.org/). The website interface is identical to the ‘real’ [zenodo.org](https://zenodo.org/), but DOIs issued on the sandbox aren’t real. Note that you 1) have to make a separate account on the sandbox site; and 2) that there is no way of converting a sandbox listing to a real one, you will have to replicate the steps you took on [zenodo.org](https://zenodo.org/).
+
+1. Create a zenodo account using your ORCID ID or log into an existing zenodo account.
+2. Go to "Upload" and select "new upload".
+3. Set the file type to "other" and **tick the "reserve doi" box**
+4. Enter a title. We suggest you use: `WIN MR Protocol: [your protocol name]`
+5. Add authors as described above, including their ORICD.
+6. Description: Suggested text below
+```
+Protocol for the acquisition of MRI data for the study "[your protocol name]".
+
+Conducted at the Wellcome Centre for Integrative Neuroimaging (WIN), University of Oxford.
+
+Please see the entry of this this protocol in the WIN MR Protocols Database to ensure this is the latest version: [your stable url, provided by the protocols database]
+
+Author list and CRediT roles: [your author list]
+
+Additional papers to be cited: [publications relating to this protocol, including preprints]
+
+Acknowledgements: [acknowledgements, for example funders]
+```
+7. Copy the reserved doi, title and authors into your Usage Guidance section on the protocol database entry. It may be helpful to look at existing zenodo entries to see how this will be formatted, for example the zenodo entry for [2018_114 Seven Day Prucalopride](https://zenodo.org/record/6107725#.YhUSWy2cZBw).
+8. Download your protocol entry from the WIN database in pdf form. If your entry contained attachments, zip it into a single directory.
+9. In the files section at the top, click "choose files" to locate your protocols database entry (pdf or zipped directory). Once located, click "start upload".
+10. Fill in any additional language, keyword or notes information as you wish.
+11. Set your access requirements and choose a license as appropriate. We suggest a [CC-BY-4.0 license](https://creativecommons.org/licenses/by/4.0/)

docs/protocols/protocols_guide_internal-how-3.md

+---
+layout: default
+title: Edit your protocol
+grand_parent: Open MR Protocols
+parent: WIN Members
+has_children: false
+nav_order: 5
+---
+
+
+# Editing your protocol entry
+{: .fs-9 }
+
+
+---
+
+![open-protocols](../../../img/img-open-acq-flow.png)
+
+
+If you are using the protocols datbase to track changes made to your protocol while pilotting, you can amend the entry and create different version which can be reviewed at any point.
+
+![gif - update](../../../img/img-protocols/gif_update.gif)
+
+1. Go to "my protocols" and find the entry you would like to update.
+2. Select whether you are adding a new sequence pdf (`Update with new protocol file`) or making a change to other parts of the entry only (`Update keeping existing protocol file`)
+3. Identify whether you are making a minor amendment to descriptive text, incrementing the "edit" number only, or a more substantial update, incrementing the version number.
+4. Make the required changes.
+5. We recommend adding a "Change Log" section to the `Description` field, to record what changes were made and why.
+6. Save your edits using the `save` button at the bottom of the page.
+7. You can review your edits by clicking on `full history` on any protocol entry.
+
+### Transferring ownership
+If you are unable to log in with an SSO (your Oxford account has expired), you will need to transfer ownership of your protocol to someone else (potentially the Principal Investigator on the project). To arrange this, please contact admin@win.ox.ac.uk and request that the entry is transferred.

docs/protocols/protocols_guide_internal-how-4.md

+---
+layout: default
+title: Track engagement
+grand_parent: Open MR Protocols
+parent: WIN Members
+has_children: false
+nav_order: 6
+---
+
+
+# Tracking engagement
+{: .fs-9 }
+
+
+---
+
+![open-protocols](../../../img/img-open-acq-flow.png)
+
+
+You can track how many times your protocol has been viewed and downloaded from the `Engagement Statistics` panel. Views and downloads are separated into internal to Oxford (where the user has logged in with an SSO) or external. When reporting on the impact of your entry, remember to also include the zenodo download and view statistics, if you used zenodo to create a doi.

docs/protocols/protocols_guide_internal-why-public.md

+---
+layout: default
+title: Why make your MR protocols public
+grand_parent: Open MR Protocols
+parent: WIN Members
+has_children: false
+nav_order: 2
+---
+
+
+# Why should I make my protocol public?
+{: .fs-9 }
+
+
+
+---
+
+![open-protocols](../../../img/img-open-acq-flow.png)
+
+
+
+1. You (and the radiographers) receive the credit for this part of the work (you can include citable DOIs)
+2. Makes it easier to share this information with colleagues and potential collaborators
+3. Keeps a reproducible record for your lab of all details and decisions made (version control)
+4. You contribute to open and reproducible research since other researchers might reuse your MR protocol. This will speed up translation of your research findings and will ultimately increase the impact of your research.

docs/protocols/protocols_guide_internal-why-use.md

+---
+layout: default
+title: Why use the MR Protocols Database
+grand_parent: Open MR Protocols
+parent: WIN Members
+has_children: false
+nav_order: 1
+---
+
+
+# Why use the MR Protocols Database
+{: .fs-9 }
+
+Why you should consider using the WIN MR protocols database to record and share details of your MR data acquisition.
+{: .fs-6 .fw-300 }
+
+---
+
+![open-protocols](../../../img/img-open-acq-flow.png)
+
+
+The MR protocol database has been developed to share MR protocols internally across WIN as well as externally. The database provides access to standard protocols and to the latest experimental protocols uploaded by WIN members. The database facilitates sharing your MR sequence with your and other research groups and helps you to keep track of updates via version control. Each deposited protocol contains all information necessary to reproduce that sequence on an appropriately licensed scanner, allowing yourself and others to have a permanent and full record of your data acquisition methodology.
+
+
+## For WIN members
+### Benefits
+#### Version control ![version-control](../../../img/icon-version-control.png)
+The MR Protocols database is version controlled, so WIN members are invited to upload their protocols during pilotting to keep track of optimisation and final versions. Comments and notes can be added to each entry to you can keep well structured documentation about why certain decisions were made. You can also link database entries with acquired data held on the [Open Data](../data) server
+
+#### Citable research output ![doi](../../../img/icon-doi.png)
+Versions (with minor and major edits) can be assigned a digital object identified (DOI) using the [Oxford Research Archive (ORA) Data repository](https://deposit.ora.ox.ac.uk) using the stable link provided by the MR Protocols database. Once a DOI has been created, your MR protocol becomes a citable object which you can add to your list of research outputs.
+
+#### Reproducible methods detail ![reproduce](../../../img/icon-reproduce.png)
+Depositing your MR protocol in the database is as simple as uploading the sequence pdf available from the scanner console, or alternatively you can upload the .exar file used by our [Siemens scanners](https://www.win.ox.ac.uk/about/facilities). All sequence detail is captured from either document, and parsed into a unified machine readable and searchable format. You can upload a single sequence, or all sequences used in a single imaging session (a protocol) together.
+
+
+## Use cases
+
+### Internal - pilotting
+
+#### Who
+WIN members, most likely the study researcher.
+
+#### Motivation
+Keeping track of changes to the protocol (for example seuqences added, sequences modified in volume or parameters) for best practice in reproducibility and prosterity.
+
+#### Goal
+Maintain an accessible record of what changes were made and why, for own record keeping and communication.
+
+
+### Internal - sharing internally
+
+#### Who
+WIN members, primarily users of MRI systems.
+
+#### Motivation
+Effective sharing complete details of their protocol with another scan user.
+
+#### Goal
+Provide full and reproducible information about the protocol efficiently, along with details of your decision making process (if used during pilotting).
+
+
+### Internal - publishing externally
+
+#### Who
+WIN members, most likely the study researcher or PI.
+
+#### Motivation
+Include the protocol as supplementary materials in a publication, or sharing with a collaborator.
+
+#### Goal
+To share the fully reproducible protocol efficiently and with credit

docs/protocols/protocols_guide_internal.md

@@ -10,7 +10,7 @@ nav_order: 1
 # User Guide for WIN Members
 {: .fs-9 }
 
-Coming soon
-{: .label .label-yellow }
 
 ---
+
+![open-protocols](../../../img/img-open-acq-flow.png)