Description

'cogmapr' is an R-package that aims (i) to generated cognitive maps based on the coding of qualitative documents and (ii) to help researchers to analyse these cognitive maps. This approach was firstly developed for analysing systems of pratices in social-ecological systems (CMASOP1), but can be useful for qualitative analyses.

'cogmapr' is the core of a series of three R-packages that works together :

  • 'qcoder', particularilly, the forked version developped for cognitive mapping
  • 'cogmapr', all r-base functions for building and analysing cognitive maps (exporting, plots, quotes, documents, …)
  • 'cogmapvisualizr', a shiny app that makes the usage of 'cogmapr' easier

This user’s manual covers the usage of these three tools. A first section is devoted to the installation of them and the second section to their usage.

Installation

The coding tool : qcoder

We developped a fork of the project ‘ropenscilabs/qcoder’ that aims to code qualitative documents (interviews, …) using the CMASOP approach.2

The package is hosted on Github and can be installed using the 'devtools'.

devtools::install_github('FrdVnW/qcoder', ref = "cogmap-dev", upgrade = 'never')

cogmapr

Special dependencies

‘cogmapr’ depend on 'graph' and 'Rgraphviz', two packages that are not available on CRAN but hosted on ‘Bioconductor’.

install.packages("BiocManager")
BiocManager::install(c("graph", "Rgraphviz"), update = FALSE)

The cogmapr package

The cogmapr package is available on CRAN.

install.packages("cogmapr")

The development branches and previous releases are hosted on Gitlab and can be installed in R using ‘devtools’. These can be installed as follow.

devtools::install_git("https://gitlab.com/FrdVnW/cogmapr", branch = "dev", upgrade = 'never')
devtools::install_git("https://gitlab.com/FrdVnW/cogmapr", branch = "RELEASE_0.9.1", upgrade = 'never')

cogmapvisualizr

'cogmapvisualizr' is an R-package that contains a shiny app for an easy way of using the main functions of 'cogmapr'. It is hosted on gitlab and can be installed using ‘devtools’.

devtools::install_git("https://gitlab.com/FrdVnW/cogmapvisualizr", ref = "master", upgrade = 'never')

Usage

qcoder

Load package

library(qcoder)

Creation and parametrization of a new project

  1. Creation of a new project

    create_qcoder_cogmap_project("PROJECT_NAME", sample = TRUE)

    This command will set up a new repository, which is a folder ‘PROJECTNAME’ and a series of important subfolders. If sample = TRUE=, basic examples files are copied in the subfolders (4 documents, a small concepts list and some units informations).

  2. Import

    Before the import, optionnally :

    • edit the 'concepts.csv' file in the folder ‘concepts’ 3
    • add more documents in the folder ‘documents’,
    • edit the units (class of documents).

    Importing the main parameters will initiate the data frames, in the data frames subfolders.

    import_project_data("PROJECT_NAME")

    BE CAREFUL ! Do not import project data if you have already coded your documents or a part of them !

  3. Some project variables

    Three variables have to be defined before launching the application. These variables can be adapted/changed each time the project is launched (but this is not recommanded).

    project_document_part <- c(
        "Subject A",
        "Subject B",
        "Subject C"
    )
    project_coding_class <- c(
        "Relationship Class x",
        "Relationship Class y",
        "Relationship Class z"
    )
    project_concept_class <- c(
        "Concept Class i",
        "Concept Class j",
        "Concept Class k"
    )

The qcoder application

  1. Launch the application

    If you already started your projects and coded your documents, you can start here.

    This will serve a shiny application reachable locally (127.0.0.1).

  2. Coding the documents

    For coding your documents using qcoder, we proposed a small screencast.

cogmapr

The ‘cogmapr’ package contains functions that can be used for plotting cognitive maps using scripts and terminal. Both base plot and ggplot2 outputs are proposed.

Load packages cogmapr and others dependencies

library("cogmapr")
library("dplyr")
library("pander")
library("ggplot2")
library("Rgraphviz")

Project configuration

'PROJECT_NAME' is a project made by the 'qcoder' package, using the 'cogmap' way, as descibed here above. The main path is the path in your computer where this project is stored, (terminating by “/”). By default, it is assumed to be in the working directory of your R session.

project_name <- "PROJECT_NAME"
main_path <- paste0(getwd(),'/')
my.cogmap.project <- ProjectCMap(main_path,project_name)

Some basic functions (see help on functions of cogmapr for more possibilities)

The following commands or group of commands generate, in this order :

  • a plot, the individual cognitive map (ICM) of the first document,
  • the list of relationships and quotes of the first document,
  • a plot, the social cognitive map (SCM) of all documents, but selecting the relationship with a minimum weight of 2.

    plot(IndCMap(my.cogmap.project, doc.id = ‘1’))

    QuotesIndCMap(my.cogmap.project,1)

    plot( SocCMap( EdgSocCMap(my.cogmap.project, min.weight = 2 ), my.cogmap.project, label=“name” ) )

These functions may need a LaTeX installation on your computer (to be enhanced, maybe adding other formats).

SheetCoding(my.cogmap.project)
## ReportICM(my.cogmap.project) ## bug
## ReportSCM(my.cogmap.project) ## bug

cogmapvisualizr

The 'cogmapvisualizr' application can be launch with these commands. (!! still need 'cogmapr' and the 3.2.2, here above).

library(cogmapvisualizr)
cogmapvisualizr()

References

Frédéric M Vanwindekens, Didier Stilmant, and Philippe V Baret. Development of a broadened cognitive mapping approach for analysing systems of practices in social–ecological systems. Ecological modelling, 250:352–362, 2013.

Frédéric M Vanwindekens, Philippe V Baret, and Didier Stilmant. A new approach for comparing and categorizing farmers’ systems of practice based on cognitive mapping and graph theory indicators. Ecological Modelling, 274:1–11, 2014.

Frédéric M Vanwindekens, Didier Stilmant, and Philippe V Baret. Using R in transdisciplinary approches for visualiazing and analysing people’s perceptions, knowledge and practices in complex social-ecological systems. In The R User Conference, useR! 2017 July 4-7 2017 Brussels, Belgium, page 251, 2017.

Footnotes

1 Vanwindekens et al., 2013

2 The CMASOP approach was initially developped using RQDA. This package is no longer maintained and not supported on newer systems (R, linux…). It depends on linux packages GTK+3.0, and gWidgetsRGtk2. If you really want to use RQDA again, we developped a docker image that can be used at this usage : https://gitlab.com/FrdVnW/dockerqda (info in the readme file).

3 You can use the spreadsheet in <./inst/concepts_builder.xlsx>, screencast for that part here https://youtu.be/aun75Y-uI6Q