Merge pull request #338 from RSE-Sheffield/feat/report-summary-text

Add boilerplate text to describe the readiness score

Author: Joe-Heffer-Shef

data/readiness_descriptions/matrix.json

@@ -0,0 +1,37 @@
+[
+  [
+    "there is no consideration of talent development activities, with little awareness of the need to spot talent, provide training, or create an enabling environment for research careers.",
+    "planning is underway to develop talent-spotting and training initiatives, with growing awareness of the need to support research careers and create an enabling environment.",
+    "talent development activities including training and research skill building are beginning to occur in small pockets of the organization.",
+    "talent development, training programs, and research career support are expanding throughout the organization beyond isolated areas.",
+    "comprehensive talent development and research career support systems are fully embedded across the organization with continuous monitoring and improvement processes in place."
+  ],
+  [
+    "the organization has not considered reducing barriers to research activities and shows little awareness of the need to provide time, resources, or legitimacy for research work.",
+    "plans are being developed to reduce research barriers and provide necessary resources, with early evidence of activities based on these plans.",
+    "efforts to provide research time and resources while legitimizing research activities are emerging in small areas of the organization.",
+    "research support through dedicated time and resources is widely adopted across the organization, with growing recognition of research impact and contributions.",
+    "research activities are fully embedded with established resource allocation, widespread recognition of research contributions, and systematic review processes for continuous improvement."
+  ],
+  [
+    "there is no consideration of forming external research partnerships or developing midwifery research leadership to influence broader research agendas.",
+    "planning is underway to establish external research links and develop leadership capacity, with some early activities beginning to emerge.",
+    "research partnerships and leadership development activities are starting to form in small pockets of the organization.",
+    "external research linkages and leadership initiatives are expanding significantly and becoming widely adopted throughout the organization.",
+    "strong research partnerships and leadership programs are fully established across the organization with ongoing monitoring and continuous improvement mechanisms."
+  ],
+  [
+    "the organization has not considered involving patients and the public in research or engaging the wider workforce in research delivery activities.",
+    "plans are being developed to support public involvement in research and engage more staff in research delivery, with early implementation beginning.",
+    "patient and public involvement initiatives along with workforce engagement in research delivery are emerging in small areas of the organization.",
+    "inclusive research practices involving patients, public, and the wider workforce are expanding and becoming widely adopted across the organization.",
+    "comprehensive inclusive research delivery systems are embedded throughout the organization with established monitoring and improvement processes."
+  ],
+  [
+    "there is no consideration of developing digital research capabilities or data science skills for research and service development purposes.",
+    "planning is underway to build digital research leadership and data science skills, with early evidence of training and development activities.",
+    "digital research capabilities and data science skill development are beginning to emerge in small pockets of the organization.",
+    "digital research leadership and data science capabilities are expanding significantly and being widely adopted across the organization.",
+    "advanced digital research capabilities and data science expertise are fully embedded throughout the organization with continuous monitoring and improvement systems."
+  ]
+]

survey/templates/survey/report.html

@@ -5,12 +5,9 @@
 {% block content %}
     <div class="container">
         <h1><i class='bx bxs-report'></i> Report: {{ survey.name }}</h1>
-
         <p>{{ survey.description }}</p>
 
-
         <div class="mb-3">
-
             <h2>Summary Ranking Matrix</h2>
             <div class="sort-response-summary-matrix"
                  data-json-config-id="configData"
@@ -23,21 +20,20 @@ <h3>Report sections</h3>
                         <li><a href="#page-section-{{ forloop.counter0 }}">{{ section.section_config.title }}</a></li>
                     {% endif %}
                 {% endfor %}
-
             </ul>
 
-
             {% for section in sections %}
                 {% if section.section_config.type != "consent" %}
                     <div class="page-break"></div>
                     <div>
-                        <h2 id="page-section-{{ forloop.counter0 }}">{{ section.section_config.title }}</h2>
+                        <h2 id="page-section-{{ forloop.counter0 }}">Section {{ section.section_config.title }}</h2>
                     </div>
                     <div>
                         <div
                                 class="sort-response-section-viewer"
                                 data-json-config-id="configData"
                                 data-json-responses-id="responsesData"
+                                data-json-readiness-descriptions-id="readinessDescriptions"
                                 data-section-index="{{ forloop.counter0 }}"
                         ></div>
 
@@ -46,8 +42,6 @@ <h3>Evidence statement</h3>
                             <div class="sort-richtext-field"
                                  data-update-url="{% url 'survey_evidence_gathering_update' survey.id forloop.counter0 %}"
                                  data-init-contents="{{ section.evidence.text }}" data-view-only="true"></div>
-                            {#            <h5>Evidence files</h5>#}
-                            {#            <div class="sort-file-browser" data-json-id="filesListData"></div>#}
                         {% endif %}
 
                         {% if section.improvement %}
@@ -73,6 +67,7 @@ <h3>Improvement plan</h3>
         {{ files_list | json_script:"filesListData" }}
         {{ survey.survey_config | json_script:"configData" }}
         {{ responses | json_script:"responsesData" }}
+        {{ readiness_descriptions | json_script:"readinessDescriptions" }}
         {% vite_client %}
         {% vite_asset "src/main.ts" %}
 

survey/views.py

@@ -458,6 +458,11 @@ def get(self, request: HttpRequest, pk: int):
         #         "fileUrl": file_url
         #     })
 
+
+        # Response descriptions
+        with open("data/readiness_descriptions/matrix.json") as file:
+            readiness_descriptions: list[list[str]] = list(json.load(file))
+
         context = {
             "survey": survey,
             "responses": [
@@ -467,6 +472,7 @@ def get(self, request: HttpRequest, pk: int):
             "sections": sections,
             "csrf": str(csrf(self.request)["csrf_token"]),
             # "files_list": files_list,
+            "readiness_descriptions": readiness_descriptions,
         }
 
         return render(request, "survey/report.html", context)

ui_components/src/lib/components/SortLikertStats.svelte

@@ -16,9 +16,10 @@
         config: SurveyConfig;
         surveyStats: SurveyStats;
         sectionIndex: number,
-        fieldIndex: number
+        fieldIndex: number,
+        readinessDescriptions: string[],
     }
-    let {config, surveyStats, sectionIndex, fieldIndex}: Props = $props();
+    let {config, surveyStats, sectionIndex, fieldIndex, readinessDescriptions}: Props = $props();
 
     let sectionConfig = $derived(config.sections[sectionIndex]);
     let fieldConfig = $derived(config.sections[sectionIndex].fields[fieldIndex]);
@@ -38,26 +39,50 @@
         strongestList.map(qm => {
             output.push(fieldConfig.sublabels[qm.index]);
         })
-        return output.join(", ");
+        return output;
     })
     let weakestAreas: string = $derived.by(()=>{
         const weakestList = questionMeanSorted.slice(0,2);
         const output: string[] = [];
         weakestList.map(qm => {
             output.push(fieldConfig.sublabels[qm.index]);
         })
-        return output.join(", ");
+        return output;
     })
+    const sectionMeanReadiness: number = surveyStats.sections[sectionIndex].fields[fieldIndex].mean;
+    const sectionMeanReadinessInt: bigint = parseInt(sectionMeanReadiness);
+    const readinessDescription: string = readinessDescriptions[sectionMeanReadinessInt-1];
 
 </script>
+<h3>Summary <span class="badge badge-secondary bg-secondary">{sectionMeanReadiness.toFixed(0)}</span></h3>
 <p>
     Section {sectionConfig.title} demonstrates an overall score <strong>
-    of {formatNumber(surveyStats.sections[sectionIndex].fields[fieldIndex].mean)} out of
+    of {sectionMeanReadiness.toFixed(2)} out of
     {getHighestHistogramValue(surveyStats.sections[sectionIndex].fields[fieldIndex].histograms[0])}</strong> indicating maturity
     ranking of <strong>{getSortMaturityLabel(surveyStats.sections[sectionIndex].fields[fieldIndex].mean)}</strong>.
-    Areas of strength are demonstrated in questions <strong>{strongestAreas}</strong>.
-    Areas of improvements are identified in questions <strong>{weakestAreas}</strong>.
+    The responses suggest that {readinessDescription}
 </p>
+<div class="progress">
+  <div class="progress-bar bg-secondary" role="progressbar" style="width: {0.2*sectionMeanReadiness*100}%" aria-valuenow="{sectionMeanReadiness}" aria-valuemin="0" aria-valuemax="4">
+      {sectionMeanReadiness.toFixed(1)} / 5
+  </div>
+</div>
+<h4>Areas of strength</h4>
+<p>Areas of strength are demonstrated in the following questions:</p>
+<ul>
+{#each strongestAreas as strongArea }
+    <li>{strongArea}</li>
+{/each}
+</ul>
+<h4>Areas for improvement</h4>
+<p>
+    Areas of improvements are identified in the following questions:
+</p>
+<ul>
+{#each weakestAreas as weakArea }
+    <li>{weakArea}</li>
+{/each}
+</ul>
 <LikertHistogram fieldConfig={fieldConfig}
                                  fieldStats={surveyStats.sections[sectionIndex].fields[fieldIndex]}></LikertHistogram>
 <table class="table table-bordered mt-4">

ui_components/src/lib/components/SurveySectionDataView.svelte

@@ -11,10 +11,11 @@
     interface Props {
         config: SurveyConfig,
         surveyStats: SurveyStats | null,
-        sectionIndex: number
+        sectionIndex: number,
+        readinessDescriptions: string[],
     }
 
-    let {config, surveyStats, sectionIndex = 0}: Props = $props();
+    let {config, surveyStats, sectionIndex = 0, readinessDescriptions}: Props = $props();
     let sectionConfig = $derived(config.sections[sectionIndex]);
 
 </script>
@@ -29,7 +30,8 @@
                             config={config}
                             surveyStats={surveyStats}
                             sectionIndex={sectionIndex}
-                            fieldIndex={fi}>
+                            fieldIndex={fi}
+                            readinessDescriptions={readinessDescriptions}>
                     </SortLikertStats>
                 </div>
 

ui_components/src/main.ts

@@ -107,18 +107,24 @@ mapMatchedElement(".sort-response-viewer", (elem) => {
 });
 
 mapMatchedElement(".sort-response-section-viewer", (elem) => {
-    const sectionIndex = elem.dataset.sectionIndex;
+    const sectionIndex = Number(elem.dataset.sectionIndex);
     const configId = elem.dataset.jsonConfigId;
     const responsesId = elem.dataset.jsonResponsesId;
+    // Get readiness-level descriptions for all sections
+    const readinessDescriptionsId = elem.dataset.jsonReadinessDescriptionsId;
+    const readinessDescriptionsAllSections = getDataInElem(readinessDescriptionsId, []);
+    // Readiness descriptions for just this section (levels 0 to 4)
+    const readinessDescriptions = readinessDescriptionsAllSections[sectionIndex-1];
     const config = getDataInElem(configId, {}) as SurveyConfig;
     const responses: SurveyResponseBatch = getDataInElem(responsesId, []) as [];
-    const surveyStats = generateStatsFromSurveyResponses(config, responses)
+    const surveyStats = generateStatsFromSurveyResponses(config, responses);
     mount(SurveySectionDataView, {
         target: elem,
         props: {
             config: config,
             surveyStats: surveyStats,
-            sectionIndex: Number(sectionIndex)
+            sectionIndex: sectionIndex,
+            readinessDescriptions: readinessDescriptions,
         }
     });
 });