Commit 5bac2ef2 authored by Cassandra Gould van Praag's avatar Cassandra Gould van Praag
Browse files

update copy

parent 2c1d3144
Pipeline #13390 passed with stages
in 2 minutes and 33 seconds
......@@ -18,9 +18,19 @@ How to share your magnetic resonance imaging protocols
## Purpose
The Open MR Protocols working group have developed a database for scanner protocols with a web interface to enable protocols to be shared both across WIN and externally. The database provides access to standard protocols and to the latest experimental protocols and where these have been uploaded by WIN members.
The MR Protocols database is a repository for scanner protocols and associated information (for example radiographic procedures). Each entry in the database should contain sufficient information to enable to replication of data collection for a study, where appropriate hardware and licenses are available. Entries to the database are version controlled, so users can effectively map how and why changes were implmented.
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.
The database is accessible via a web interface to enable frictionless sharing of materials both internally and externally.
Users are guided through the process of generating a digital object identifier (doi) and licence for their deposited material so they can receive appropriate attribution for reuse.
The database provides access to standard protocols and to the latest experimental protocols and where these have been uploaded by WIN members.
## Access the MR Protocols database
Available here: [http://open.win.ox.ac.uk/protocols/](http://open.win.ox.ac.uk/protocols/)
## How to use the MR Protocols database
Training guides are available for WIN members and external users. Please select the appropriate option from the buttons below, or the navigation menu.
[![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/)
......
......@@ -17,120 +17,66 @@ A guide for external researchers on how to use the Open WIN MR protocols databas
---
## 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.
External researchers are able to search the database for MR protocols which 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.
## How To Access WIN MR Protocols Database
![gif - external](../../../img/img-protocols/gif_external.gif)
**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)
### 1. Access the MR Protocols database
Available here: [http://open.win.ox.ac.uk/protocols/](http://open.win.ox.ac.uk/protocols/)
### 2. Search
## Purpose
Search the database using keyword terms based on anatomy, the imaging system, sequence types, or the theoretical application.
> What is the Open WIN MR Protocols Database?
The search returns a **list of open access protocols** containing your search term, with additional information on the species of participant in the study, the project name as it appears on our resource booking system (Calpendo) and date of most recent changes to each entry.
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
### 3. Top level details
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.
Select the protocol you are interested in to view more details. The name of the protocol you are viewing will be shown at the top, along with a button to download all the materials for the current version of this entry. Further top-level details are as below:
`Open Access Status` (this will only be `Open Access` for protocols visible to external researchers) and a stable URL for reference.
## Intended Audience
`Version Info` will contain the date the protocol was first entered, the current version, and a link to access the full version history.
An *external user* is anyone without Oxford University Single-Sign-On (SSO) credentials or anyone outside WIN (**?**)
`Reference list` will describe how the author would like to be cited in reuse of this material, and any other published materials (such as journal papers or software) which should be considered alongside this material. This may contain a weblink out to where the DOI was issued.
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.
`Scanning Info` will give basic details about the hardware and application, including the total duration of acquisition time.
*Internal users* can also access non-public protocols. For more information, see our [guide for internal users](user-guide-internal.md).
### 4. Protocol Info
Authors are advised to include the following information in the `Protocol Info` section:
- `Description`: This section should identify and highlight important features of the protocol. For example the study design, methods, and procedure.
- `Change log`: Brief details of changes to the protocol with each version update on the database
- `Usage guidance`: Including contact details for someone to discuss the protocol or its reuse (optional), how to cite the protocol and terms for reuse.
- `File Attachments`: The names of any files additionally attached to this entry (for example radiographer's procedure) will be listed to the top of this section.
## How To Access The Open WIN MR Protocols Database
### 5. Individual sequence details
![gif - external](./figures_external/gif_external.gif)
The following sections give the name, keyword and researcher description and acquisition run time of each sequence in the protocol.
- 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)
### 5. Download
---
## 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)
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, all attached files, plus full configuration details for each sequence (not shown online).
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.
 
Please review the `Disclaimer and Usage` guidance at the top of the download.
## 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>
Please refer to the authors citation guide contained within the `Reference List` section of each entry to appropriately acknowledge re-use of material.
## 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).
Information about who to contact regarding re-use of a specific protocol should be provided in the usage guidance. If not contact information is provided, please [contact 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).
## 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).
# <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)
If you reuse the code to build your own database, please cite it as...
# <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
Coming soon
{: .label .label-yellow }
......@@ -147,13 +147,15 @@ Once all required fields have been completed, you will be able to save the entry
## 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.
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.
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"
### 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).
If you identify a protocol as open access, this will trigger a review by database administrators. <mark>Further detail of the review process coming soon. </mark>
## 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.
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment