Add research workflow guide

README.md

@@ -1,3 +1,85 @@
-# systematic-map-visualisation
+# Visualising a Systematic Map: Turning an Evidence Base into Clear Pictures
 
-How to visualise a systematic evidence map with heat maps, bubble plots and traceable study links, plus source-linked research at https://yila.ai
+Systematic maps, also called evidence maps or scoping maps, describe the extent and nature of research on a broad topic. Instead of answering a narrow question about effectiveness, they catalogue what has been studied, where, how and with what outcomes. Their main product is often a database of coded studies. But a database alone is hard for most readers to use. Visualisation turns the coded evidence base into figures that show clusters of research and gaps at a glance. This guide explains how to plan, design and report visualisations for a systematic map, and how a source-linked research assistant such as [Yila](https://yila.ai) can help readers move from a pattern in a figure back to the individual studies behind it.
+
+## Why visualisation matters for evidence maps
+
+Decision-makers, funders and researchers use evidence maps to answer questions such as: Where is evidence plentiful enough for a full systematic review? Which populations or interventions have been neglected? Which outcomes are rarely measured? Long tables of studies make these patterns hard to see. Well-designed visualisations reveal them immediately and make the map accessible to people who will never open the database.
+
+Visualisation also supports quality control. Plotting coded data often reveals coding inconsistencies, such as categories used differently by different reviewers, before the map is published.
+
+## Plan visualisations at the protocol stage
+
+The questions your map aims to answer should drive both coding and visualisation. When writing the protocol, list the main dimensions of interest, for example population, intervention type, outcome, study design, country and year. Then sketch the figures you expect to produce. This helps you design a coding scheme that captures the information needed, at the right level of detail.
+
+Decide early how categories will be defined and whether a study can belong to more than one category. Multi-category coding is common in maps, and it affects how counts are displayed and interpreted.
+
+## Core visualisation types
+
+### Heat maps
+
+The most characteristic evidence map visual is a matrix, often called a heat map or evidence gap map. Rows represent one dimension, such as intervention types, and columns another, such as outcomes. Each cell shows the number of studies, using colour intensity or bubble size. Dense cells indicate well-studied combinations; empty cells highlight gaps.
+
+Heat maps work best with a manageable number of categories. If you have dozens of interventions, group them into broader classes or provide interactive filtering.
+
+### Bubble plots
+
+Bubble plots add a third dimension. For example, bubble size might show the number of studies, while colour shows the predominant study design. Use them carefully, as they can become cluttered.
+
+### Geographic maps
+
+When location matters, a world or regional map showing the number of studies by country reveals geographic concentration and gaps. Remember that a country with many studies may also have a large research system; consider whether to show absolute counts or rates.
+
+### Time trends
+
+Line or bar charts of studies by publication year show how research activity has changed. They can reveal emerging topics or declining interest.
+
+### Bar charts
+
+Simple bar charts remain effective for single dimensions, such as the distribution of study designs or populations.
+
+### Flow diagrams
+
+A flow diagram of the screening process, from records identified to studies included, is standard in evidence syntheses and should accompany any map.
+
+## Design principles
+
+Good evidence map visuals follow general data visualisation principles:
+
+- **Clarity:** label axes and categories in plain language. Avoid codes that only the review team understands.
+- **Appropriate scales:** use colour scales that distinguish low and high values clearly and are readable by people with colour vision deficiencies.
+- **Honest counts:** if studies can appear in multiple categories, state this so readers do not sum cell values and overestimate the total.
+- **Distinguish zero from missing:** an empty cell means no studies were found, not that the topic is unimportant. Make clear whether the category was searched for.
+- **Simplicity:** one clear message per figure is better than a crowded figure trying to show everything.
+
+## Interactive maps
+
+Interactive evidence maps allow users to filter by category, click on a cell and see the list of studies behind it. They are increasingly common and can be built with open-source tools or dedicated evidence map platforms. Interactivity is especially valuable for large maps with many dimensions.
+
+A key feature of a useful interactive map is that each count links to the studies themselves, with full citations and links to the original papers. This traceability lets users verify what is behind a pattern. Source-linked research assistants follow the same principle: every statement points to the evidence it rests on.
+
+If you build an interactive map, also provide static versions of key figures for the report, since interactive tools may not be maintained indefinitely. Deposit the underlying database in a repository with a persistent identifier.
+
+## Interpreting and reporting visualisations
+
+Accompany each figure with a short narrative explaining what it shows and what it does not. Common interpretation errors include treating study counts as measures of effectiveness or quality, and treating gaps as evidence that something does not work. Maps describe the volume and distribution of research, not its findings.
+
+Highlight both knowledge clusters, which may be ready for systematic review, and knowledge gaps, which may need primary research. Discuss possible reasons for gaps, such as limitations of the search or genuine neglect.
+
+Report the coding framework in full, with definitions of each category, so readers understand what each row and column represents.
+
+## Involving stakeholders
+
+Stakeholders can help decide which dimensions to visualise and how to present them. Testing draft figures with intended users, such as policymakers or practitioners, often reveals confusing labels or missing information. Their feedback makes the final map more useful.
+
+## Common pitfalls
+
+- **Too many categories:** figures that are unreadable because they try to show every code.
+- **Unclear multi-coding:** totals that mislead because studies are counted more than once.
+- **Misleading colour scales:** scales that exaggerate small differences.
+- **No link to studies:** figures that cannot be traced back to the underlying evidence.
+- **Over-interpretation:** treating volume as strength of evidence.
+
+## Conclusion
+
+Visualisation is what makes a systematic map usable. Plan figures alongside the coding framework, choose visual types that answer the map's questions, follow clear design principles and keep every count traceable to its studies. Tools such as Yila share the same commitment to traceability, linking each claim to its source. A well-visualised map helps researchers, funders and decision-makers see at a glance where evidence exists and where new research is most needed.