Merge pull request #65 from UCLH-Foundry/steve/minor-fixes

submission-rewrite and formatting

.gitignore

@@ -5,5 +5,8 @@ _site
 vendor
 *.pyc
 
+# OS specific files
+.DS_Store
+
 # Environment files
 .env

Gemfile.lock

@@ -17,6 +17,7 @@ GEM
     execjs (2.7.0)
     ffi (1.16.3)
     forwardable-extended (2.6.0)
+    google-protobuf (3.25.3-arm64-darwin)
     google-protobuf (3.25.3-x86_64-linux)
     http_parser.rb (0.8.0)
     i18n (1.14.1)
@@ -65,6 +66,8 @@ GEM
     rexml (3.2.6)
     rouge (4.2.0)
     safe_yaml (1.0.5)
+    sass-embedded (1.71.0-arm64-darwin)
+      google-protobuf (~> 3.25)
     sass-embedded (1.71.0-x86_64-linux-gnu)
       google-protobuf (~> 3.25)
     sass-embedded (1.71.0-x86_64-linux-musl)
@@ -75,6 +78,7 @@ GEM
     webrick (1.8.1)
 
 PLATFORMS
+  arm64-darwin-23
   x86_64-linux
   x86_64-linux-musl
 

README.md

@@ -1,4 +1,5 @@
 # Project Info Site
+
 This is the main repository for Project Info Site.
 
 ## Contributing
@@ -7,16 +8,16 @@ Please read our [contributors' guide](contribute/project_submission.md) for deta
 
 ## Building Locally
 
-This site is built Jekyll: a static site generator written in Ruby. See the [Jekyll quick start guide](https://jekyllrb.com/docs/) for instructions on how to install Jekyll and it's dependencies on your device.
+This site is built Jekyll: a static site generator written in Ruby. See the [Jekyll quick start guide](https://jekyllrb.com/docs/) for instructions on how to install Jekyll and it's dependencies on your device. You might also need to install [node.js](https://nodejs.org/en/learn/getting-started/how-to-install-nodejs).
 
 Then clone this repository:
 
-```
-git clone https://github.com/tcouch/project-info-site.git
+```sh
+git clone https://github.com/UCLH-Foundry/uclh-research-discovery.git
 ```
 
 And build and serve the site with:
 
-```
+```sh
 bundle exec jekyll serve
 ```

_config.yml

@@ -33,6 +33,7 @@ email: [email protected]
 plugins:
   - jekyll-feed
   - jekyll-autoprefixer
+  - jekyll-seo-tag
 
 autoprefixer:
   browsers:

_includes/head.html

@@ -11,6 +11,8 @@
 
     <script src="https://unpkg.com/[email protected]"></script>
 
+    <link rel="shortcut icon" type="image/png" href="{{ "/assets/images/favicon.png" | prepend: site.baseurl }}" >
+
     {%- feed_meta -%}
     {%- if jekyll.environment == 'production' and site.google_analytics -%}
       {%- include google-analytics.html -%}

contribute/index.md

@@ -4,5 +4,31 @@ title: Contribute
 permalink: /contribute/
 ---
 
-# Contribute to {{site.title}}
-UCLH research teams can add their own projects to this site by making a [pull request](https://docs.github.com/articles/about-pull-requests) to our [GitHub repository](https://github.com/tcouch/project-info-site). For detailed instructions, please see our [project submission process](./project_submission).
+## Contribute to {{site.title}}
+
+We believe that all research using patient data should be visible to the public and the scientific community. We encourage all research teams to share the following
+
+1. a lay summary of the research proposal
+2. a synthetic example of the data
+3. a simple vignette of their findings
+
+### The lay summary
+
+This can be submitted as soon as the project is approved.
+
+### Synthetic data
+
+Sharing data is important to meet the demands of scientific reproducibility, and the more open the share, the better we can hold ourselves to this standard. But even when working with anonymised data, there is a always a residual risk of re-identification. We manage this risk by providing support for generating synthetic data. We do this in two layers.
+
+1. Data that is structurally identical but has never 'seen' the real data
+2. Data that learns from the real data but only at the aggregate level 
+
+We share layer 1 synthetic data publicly, and provide access to layer 2 data on request.
+
+### Your findings
+
+We recommend that teams share vignettes of key findings from their work here. This enables patients and the public to understand the impact health data science is having at UCLH.
+
+## How to contribute
+
+UCLH research teams can add their own projects to this site by making a [pull request](https://docs.github.com/articles/about-pull-requests) to our [GitHub repository](https://github.com/UCLH-Foundry/uclh-research-discovery). For detailed instructions, please see our [project submission process](./project_submission).

contribute/project_submission.md

@@ -2,110 +2,143 @@
 layout: page
 ---
 
-# Submitting a project for inclusion on this site
-If you are a UCLH researcher, you can submit details about your own research project(s) and have them added to this site.
+# Submitting a project
 
-Whilst some experience of version control with git and GitHub would be beneficial, the guidance below tries to assume as little prior knowledge as possible and sticks to making changes via the GitHub user interface. Contributors with more experience may want to take a different approach.
+You can submit your own research project for sharing here.
 
-**Step 1**: [Upload datasets and code to a research data repository](#step-1-upload-datasets-and-code-to-a-research-data-repository)
+This is a brief over guide, but a more complete version for those less familiar with GitHub and pull requests is also [available](./project_submission_lowcode)
 
-**Step 2**: [Clone our repository on GitHub](#step-2-clone-our-repository-on-github)
+The simplest approach is to clone this repository locally.
 
-**Step 3**: [Complete the project template](#step-3-complete-the-project-template)
+## Preparing your submission
 
-**Step 4**: [Make a pull request](#step-4-make-a-pull-request)
+```sh
+git clone https://github.com/UCLH-Foundry/uclh-research-discovery.git
+cd uclh-research-discovery
+```
 
-## Step 1: Upload datasets and code to a research data repository
+Now create a *new* directory under `./projects`, and add a file called `index.md`. 
 
-To help people who are interested in your research to better understand what data you have used and how you process it, it can be helpful to generate a synthetic dataset which you can share together with any relevant computer code in an open-access repository. We recommend using UCL's institutional [research data respository](https://rdr.ucl.ac.uk/) service as it is free for all UCL researchers to use and provides an embed link which can be used to include your data alongside details about your project on this site. Please read the guidance on the [UCL Library Researd Data Repository](https://www.ucl.ac.uk/library/open-science-research-support/research-data-management/ucl-research-data-repository) page for details on how to prepare and upload your data.
+```sh
+cd ./projects
+mkdir my_new_project
+cd my_new_project
+touch index.md
+```
 
-Once your submission has been approved, you can find the embed URL by navigating to your deposit's page and selecting 'Embed' from the menu. Copy the iframe tag and include this in one of the html or markdown files you create in Step 3.
+An example is available for you in `./projects/_project_template`. You could simple duplicate and rename this directory.
 
-## Step 2: Fork our repository on GitHub
+```sh
+cd ./projects
+cp -R ./projects/* ./my_new_project
+```
 
-To complete the next steps you will need a GitHub account, which will enable you to take a copy of the site's code and later merge your changes back in. If you don't have one you can [sign up for free](https://github.com/join).
+### The `index.md` file
 
-The source code for this site can be found on GitHub: [{{site.data.github.url}}](https://{{site.data.github.url}}). To make a copy you can make changes to, you can fork the repository. You can do whatever you want with the forked copy once you've made it, and then create a pull request (see below) to have your changes merged back into the original code base.
+Now edit the `index.md` file. It will need a YAML header as below. The additional data and results tabs are optional. If you choose to use them then each is a simple markdown file.
 
-To start, make sure you're logged into your account, and then find the fork button on this site's GitHub repository and click "Create a new fork":
+```yaml
+---
+layout: project
+title: My New Project
+status: ongoing
+authors:
+  - Jeremy Bentham
+  - Charles Darwin
+  - John Snow
+tabs:
+- {
+  name: my_data_tab,
+  source: data.md,
+  label: Data
+  }
+- {
+  name: my_results_tab,
+  source: results.md,
+  label: Results
+  }
+---
 
-![UCLH Research Discovery GitHub repository (fork)]({{'assets/images/fork_1.png' | relative_url}})
+Here is the text introducing my study. The YAML frontmatter above will not be displayed to the user.
 
-In the form that follows, select your username from the Owner dropdown menu, then click "Create fork". A copy of the repository should then appear under your own username with a note beneath the title saying "forked from {{site.data.github.url}}".
+We recommend including your lay summary here.
+```
 
-## Step 3: Complete the project template
+#### YAML frontmatter
 
-Once you have forked the repository, you can start adding your project. The pages for each project are kept in separate folders under `/_projects`. Start by creating a new folder for your project containing an `index.md` file.
+title
+: By default the title for your project will be derived from the folder name by replacing any dash or hyphen characters with spaces, and converting the result to title case. Add a title here to override this
 
-### index.md
-Whilst you might be used to making a new folder before creating the files that go in it, GitHub doesn't actually let you create an empty folder, so you need to create both the folder and your first file at the same time. Every project folder must include a file called index.md, which serves as the landing page for your project, so that's probably the best place to start:
+status
+: Each project page displays the current status of the project on a label displayed next to the title. This can be one of two options: ongoing or completed. If not included here, the default will be ongoing.
 
-1. From the main page of the forked repository, select the `_projects` folder from the file explorer table. ![Select _projects]({{'assets/images/new_project_1.png' | relative_url}})
-2. From within this folder, click *Add file > Create new file* ![Add file > Create new file]({{'assets/images/new_project_2.png' | relative_url}})
-3. At the top of the page you'll see an empty box with the placeholder text "Name your file...". Enter the name of the new folder you'd like to create:<br>**The name of the folder will be used to generate the title for your project (see below for how to override this)**<br>![Enter a folder name]({{'assets/images/new_project_3.png' | relative_url}})<br> followed by a forward slash `/`, and then the name of the file `index.md`:<br>![Enter file name]({{'assets/images/new_project_4.png' | relative_url}})
-4. You can now start writing a lay summary of your project written in [markdown](https://en.wikipedia.org/wiki/Markdown) format in the text box below. You can include as much detail as you like, but you also have the option to add additional pages if you'd like to split things up into separate sections (see *Extra content* below).
-5. When you'd like to save your progress, click "Commit changes...". In the pop-up enter whatever short message you think is appropriate to describe the changes you've made, then click "Commit changes".
-6. To edit an existing file, locate and click on it in the GitHub repository's file explorer, then select the pencil icon from the right of the toolbar:![Edit file icon]({{'assets/images/edit_file.png' | relative_url}})
+authors
+: This file must contain a list of authors added in the format shown in the example above
 
+The tab section is optional.
 
-If you're new to markdown:
-* Whilst editing a mardown file you can switch between the *Preview* and *Edit* views to get a sense of how your markdown content is going to appear on the page.
-* This [markdown cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) to help you get started.
+### Sharing data
 
+If you wish to share data, then we encourage the use of the UCL [Research Data Discovery](https://rdr.ucl.ac.uk/) service. You can embed a link to your data directly.
 
-### metadata.yml
-Your project folder must also include a `metadata.yml` file which adds information about your project. The file, written in [yaml format](https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html), can include a list of project authors (required), the title, and its status.
+For example, the `data.md` file might be look like this.
+
+```md
+## My data
+
+Here are the data that I used for my study
+
+<iframe src="https://widgets.figshare.com/articles/18692549/embed?show_title=1" width="568" height="351" allowfullscreen frameborder="0"></iframe>
 
-An example metadata.yml file might look like this:
-```yaml
-title: Nature vs Nurture the UCLH Perspective
-status: ongoing
-authors:
-- Charles Darwin
-- Gregor Mendel
-- Rosalind Franklin
 ```
-<dl>
-<dt>title</dt>
-<dd>By default the title for your project will be derived from the folder name by replacing any dash or hyphen characters with spaces, and converting the result to title case. Add a title here to override this</dd>
-<dt>status</dt>
-<dd>Each project page displays the current status of the project on a label displayed next to the title. This can be one of two options: ongoing or completed. If not included here, the default will be ongoing.</dd>
-<dt>authors</dt>
-<dd>This file must contain a list of authors added in the format shown in the example above</dd>
-</dl>
-
-### Extra content
-If you'd like to split content across several pages, or include an embed link for your data, you can add extra content by including additional markdown or html files in your project folder. This content will appear in separate tabs across the top of the page. 
+
+### Sharing results
+
+Similarly, you can embed results and images in the `results.md` file. We would recommend considering the Quarto publishing system. In which case, replace `results.md` with `results.html` and include the Quarto assets folder in the project folderinclude the Quarto assets folder in the project folder. Relative links should be preserved.
+
+### Ready to submit
+
+Your folder structure might look like
+
+```txt
+|-my_new_project
+  |-index.md
+  |-data.md
+  |-results.html
+  |-assets/
+    |-figure-html
+    |-libs
+```
+
+
+### Tips
+
+If you'd like to split content across several pages, or include an embed link for your data, you can add extra content by including additional markdown or html files in your project folder. This content will appear in separate tabs across the top of the page.
 
 The name of the file is used to generate the tab label for the extra content as follows:
 
-* The filename suffix (.md/.html is removed)
-* Any underscore(_) or hyphen (-) characters are replaced with spaces
-* Digits at the start of the filename are removed
-* Any whitespace remaining at the start or end of the name is removed
-* The name is converted to title case
+- The filename suffix (.md/.html is removed)
+- Any underscore(_) or hyphen (-) characters are replaced with spaces
+- Digits at the start of the filename are removed
+- Any whitespace remaining at the start or end of the name is removed
+- The name is converted to title case
 
 As an example, the tab label for `03_code-and_data.md` would be "Code And Data".
 
 Tab order is alphabetical (except index.md which always appears first). To determine the order in which tabs appear, use numbers at the start of your filenames (e.g. `01_methods.md`, `02_privacy.md`, `03_data.html`).
 
-### Assets
+#### Assets
+
 The site builder only picks up files with .html or .md suffixes as extra content to be included as tabs on the project page, anything else is ignored. However, you can use relative links to include other types of assets in your pages such as images, javascript, css etc. For example, you could create a folder inside your project folder called images, where you can upload all of the images you'd like to include in your pages. To upload a file, select "Upload files" from the "Add files" dropdown menu.
 
-### Quarto
+#### Quarto
+
 If you use Quarto to generate an html page, you will find it generates a whole folder of assets that need to be included. No problem, just include the Quarto assets folder in your project folder alongside the html file, and the relative links to those assets should still work.
 
-## Step 4: Make a pull request
+## Make a pull request
 
 To publish your project, you will need to merge your new files back into the original GitHub repository. To do this you will need to submit a [Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests). The pull request process allows us to review submissions before they are added to ensure they comply with our standards.
 
-To open a pull request:
-1. Select Pull requests from the top navigation menu<br> ![Pull requests in the top nav menu]({{'assets/images/pull_request_1.png' | relative_url}})
-2. Click the green 'New pull request' button
-3. On the next page title "Comparing changes" you should see the base repository on the left (the original repository) with an arrow pointing to it from the head repository (your fork) on the right. Make sure the pull request is targeting the staging branch on the base repository (this should already be selected as the default option)<br> ![Original repository on the left, fork on the right]({{'assets/images/pull_request_2.png' | relative_url}})
-4. Click 'Create pull request'
-5. Add a title and description, including any details you think may be relevant for somebody reviewing your changes
-6. Then click 'Create pull request'
 
 Your pull request will then need to be approved by two reviewers who are chosen automatically from a pool of volunteer editors. Reviewers might sometimes make comments or request changes before approving your submission so please make sure you are able to receive notifications from GitHub in order to respond to their requests.