Merge commit

.github/workflows/DNA build.yml → .github/workflows/build-check-test.yml

@@ -1,4 +1,4 @@
-name: build
+name: build-check-test
 
 on: [push, pull_request, workflow_dispatch]
 
@@ -67,31 +67,38 @@ jobs:
         name: DNA
         path: build/*.jar
 
+
   rDNA:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v3
 
     - uses: r-lib/actions/setup-r@v2
 
+    - name: Restore R Packages
+      uses: actions/cache@v3
+      with:
+        path: ~/.cache/R
+        key: ${{ runner.os }}-r-rDNA-${{ hashFiles('**/DESCRIPTION') }}-v1
+
     - uses: r-lib/actions/setup-r-dependencies@v2
       with:
         cache-version: 2
         working-directory: rDNA/rDNA
         extra-packages: |
-          any::ggplot2
           any::roxygen2
-          any::igraph
-          any::ggraph
-          any::askpass
-          any::cluster
-          any::sna
 
     - uses: gradle/wrapper-validation-action@v1
 
     - name: Setup Gradle
       uses: gradle/[email protected]
 
+    - name: Restore Gradle Cache
+      uses: actions/cache@v3
+      with:
+        path: ~/.gradle/caches
+        key: ${{ runner.os }}-gradle-${{ hashFiles('**/build.gradle') }}-v1
+
     - name: Execute Gradle build for rDNA
       run: ./gradlew :rDNA:build
 
@@ -123,21 +130,26 @@ jobs:
     steps:
       - uses: actions/checkout@v3
 
-      - uses: r-lib/actions/setup-pandoc@v2
-
       - uses: r-lib/actions/setup-r@v2
         with:
           r-version: ${{ matrix.config.r }}
           http-user-agent: ${{ matrix.config.http-user-agent }}
           use-public-rspm: true
 
+      - name: Restore R Packages
+        uses: actions/cache@v3
+        with:
+          path: ~/.cache/R
+          key: ${{ runner.os }}-r-rDNA-check-${{ hashFiles('**/DESCRIPTION') }}-v1
+
       - uses: r-lib/actions/setup-r-dependencies@v2
         with:
-          extra-packages: any::rcmdcheck
-          needs: check
+          cache-version: 2
           working-directory: rDNA/rDNA
+          extra-packages: |
+            any::rcmdcheck
 
       - uses: r-lib/actions/check-r-package@v2
         with:
           working-directory: rDNA/rDNA
-          upload-snapshots: true
+          upload-snapshots: true

README.md

@@ -14,15 +14,45 @@ The Java software Discourse Network Analyzer (DNA) is a qualitative content anal
 
 [DNA 3.0](https://github.com/leifeld/dna/releases) was first released on 12 June 2022. It constitutes a major rewrite from the previous version DNA 2.0 beta 25. DNA 3 comes with many new features and improvements. The [release](https://github.com/leifeld/dna/releases) page contains all the details (scroll to version 3.0.7 for the first DNA 3 release).
 
-If you require the latest (non-release) version of the DNA jar file from GitHub, you can clone the git repository to your computer and execute `./gradlew build` on your terminal or command line. This will build the jar file and store it in the `build/` directory of the cloned repository. Alternatively, you can try to download the latest artifact from the build process under [GitHub Actions](https://github.com/leifeld/dna/actions) by clicking on the latest build and scrolling down to "Artifacts". However, it is usually recommended to use the most recent [release](https://github.com/leifeld/dna/releases/) version.
+[![build-check-test](https://github.com/leifeld/dna/actions/workflows/build-check-test.yml/badge.svg)](https://github.com/leifeld/dna/actions/workflows/build-check-test.yml)
 
-[![DNA/rDNA build](https://github.com/leifeld/dna/actions/workflows/DNA%20build.yml/badge.svg)](https://github.com/leifeld/dna/actions/workflows/DNA%20build.yml)
+## Installation of DNA
+
+DNA was written in Java and requires Java 11 or higher on your system. You can check if you have Java >= 11 on your system by opening the terminal of your operating system (e.g., typing `cmd` in your Windows start menu or using the terminal app on MacOS) and typing:
+
+``` shell
+java --version
+```
+
+If this indicates a version below 11 (or 1.11), installing the latest version of [Adoptium Temurin OpenJDK](https://adoptium.net) or any other Java >= 11 is recommended before you proceed. Once installed, restart your system and check the version again.
+
+To use DNA, simply download the latest `.jar` file under "[Releases](https://github.com/leifeld/dna/releases)" on the right along with the `sample.dna` file, a toy database you can load in DNA (password: `sample`) to play with the software. You can double-click on the `.jar` file to open DNA. No installation is required.
+
+MacOS users may need to give the program authorization to be executed. Some MacOS users reported issues with opening files. These issues should have been fixed in version 3.0.11. You can also browse the [issue tracker](https://github.com/leifeld/issues) (including closed issues) and the [commit messages](https://github.com/leifeld/dna/commits/master/) for more information on MacOS issues. Get in touch via the issue tracker or Matrix (infos below) if you are unable to solve these issues.
+
+If your system does not want to start DNA with a double-click on the `.jar` file, you can also open it from the terminal. To do so, navigate to the directory where the `.jar` file is stored on your computer using the `cd` command, for example `cd ~/Documents/`. Once there, type in something like this, with the `.jar` file corresponding to the file version you downloaded:
+
+``` shell
+java -jar dna-3.0.11.jar
+```
+
+If you require the latest (non-release) version of the DNA jar file from GitHub, you can clone the git repository to your computer and execute `./gradlew build` on your terminal or command line. This will build the jar file, the rDNA R package, and the bibliography, and store them in the `build/` directory of the cloned repository. If you only want to build the jar file, you can also execute `./gradlew :dna:build` (omit `./` on Windows). Alternatively, you can try to download the latest artifact from the build process under [GitHub Actions](https://github.com/leifeld/dna/actions) by clicking on the latest build and scrolling down to "Artifacts". However, it is usually recommended to use the most recent [release](https://github.com/leifeld/dna/releases/) version.
+
+Along with DNA, it is recommended to download [visone](https://visone.ethz.ch/), which can be opened in the same way as DNA. You can open `.graphml` files from DNA's network export in visone.
 
 ## rDNA 3.0: Connecting DNA to R
 
 The R package rDNA connects DNA to R for data exchange and analysis.
 
-Please note that the current version 3.0 does not have the full functionality of the old 2.0 version yet. It can create networks, but please use the old version for now if you require more complex data management and analysis functionality in R. It is possible to import DNA 2 data into DNA 3 at any point (but not the other way around). New R functions will be added in the future.
+rDNA offers functionality such as:
+- plotting networks with different layouts,
+- applying many kinds of cluster analysis/community detection/subgroup analysis and selecting the best solution automatically to identify coalitions,
+- detection of phase transitions,
+- partitioning of concepts into backbones and redundant sets,
+- ideological scaling via item response theory,
+- barplots etc.
+
+The old 2.0 version additionally supported data exchange between DNA databases and rDNA by adding or retrieving documents, statements, attributes, statement types, coders etc. The 3.0 version does not support most of this data exchange functionality yet, so if you need to batch-import documents, for example, use DNA 2.0 first and then import everything into a DNA 3.0 database for further analysis (note that you cannot import from 3.0 into 2.0). More functions for data exchange and analysis will be added in the future.
 
 To install the new rDNA 3 directly from GitHub, try the following code in R:
 
@@ -53,7 +83,7 @@ download.file(url = u, destfile = dest, mode = "wb")
 
 ## Documentation and community
 
-- This **tutorial on YouTube** describes installation of DNA, basic data coding, network export, and network analysis using visone. The video clip is 18 minutes long.
+- This **tutorial on YouTube** describes installation of DNA, basic data coding, network export, and network analysis using visone. The video clip is 18 minutes long and based on DNA 3.0.10.
 
   [![DNA tutorial](https://img.youtube.com/vi/u3hc86Tcs9A/0.jpg)](https://www.youtube.com/watch?v=u3hc86Tcs9A)