QualCoder 3.6

[ccbogel]

Various updates to QualCoder 3.6 are detailed below.

Installation:

Windows

You have two options (see attached files at the end of the release page):

• QualCoder_3_6_setup.exe: a Windows installer
• QualCoder-3.6.exe A portable binary. Double-click to run and wait for 15 seconds.

On first use of the exe, Windows will ask you to allow to run QualCoder. This is because it is from an unknown publisher. It costs a lot of money to get a trusted publisher certificate - so that will not be possible for the foreseeable future.

Mac

Attached to the release page you will find two options:

• QualCoder_3_6_arm64.dmg: App bundle for newer Macs with Apple Silicon (M1 ... M4 processors)
• QualCoder_3_6_x86_64.dmg: App bundle for the older Macs with Intel processor (core i5, i7, etc).

The app bundles are compiled on macOS Sequoia. They might also work on Sonoma and Ventura. If you are on an older version, consider updating your OS or install QualCoder from source as described in the wiki: https://github.com/ccbogel/QualCoder/wiki/2.1.-Installation#macos

Note: We are currently not able to sign the app bundles, so you will get a warning that QualCoder is from an unregistered developer. You have to manually allow the app to be executed, if your Gatekeeper is active. Follow these steps:

• Double-click the downloaded dmg-file.
• Drag QualCoder into the link to your applications.
• Start QualCoder by double-clicking the app within your applications folder. You will get an error that QualCoder is from an unregistered developer. The app will not start.
• Go to Settings -> Privacy and Security -> Scroll down until you see a message stating QualCoder was prevented from starting. Click on "open anyway".
• From now on, QualCoder should start without issues.

Linux

A binary (double click to run) is available for Ubuntu 24.

Run from source

For install from source code, download the zip file below and use the instructions on the main GitHub QualCoder page, or the wiki to install on your operating system.

License changes

The license for QualCoder has been changed to the GNU Lesser General Public License (LGPL) version 3 license.

General changes

Throughout QualCoder all the icons have been replace with material design icons.

Thanks to Kai:
A lock out for the SQLite database to prevent multiple access.
Improved error messaging with an error dialog class.
Default to native style on Windows.
Applied UTF-8 to config file.

Kai Droege - Artificial intelligence features

Many thanks to Kai for testing and developing these features over the last several months.

• An AI based search function to explore the data, look for a particular phenomenon or concept in the whole corpus and interpret the data interactively with the AI. This is part of the text coding workspace.
• An AI Chat: Here, the AI analyzes data, summarizes the results (with exact sources, linked to the original documents), and allows to discuss them. I have implemented three types of chats:
  ** A “code chat” that works on already coded data,
  ** a “topic chat” that explores a certain phenomenon in the data, even if it has not been coded yet (this is internally using the ‘AI search’ described above), and
  ** a “general chat” that allows to discuss any question not directly related to the data (basically a build in ChatGPT).
• Prompt Editing: All the functions described above can be modified by varying the underlying prompts that instruct the AI what to do (in plain English). QualCoder already comes with a predefined set of prompts. These allow, for instance, to modify the AI search to be either very open, interpretative and inclusive or to be more focused, adhering to predefined coding rules outlined in the code’s memo (as it is common practice in content or thematic analysis).
• Methodological control and transparency: The user can also rewrite these prompts or define their own, targeted at their particular methods and research questions. This is a major advantage over commercial QDA software packages that do not offer the same level of transparency and control since they keep the underlying prompts confidential. Not so with QualCoder, which offers an easy to use interface to view, modify, and share such prompts.
• Different AI models: QualCoder uses a combination of a local AI model, specialized on multilingual sematic search in a large corpus of data (an E5 sentence encoder) and a Large Language Model (LLM) like GPT-4, usually hosted online. QualCoder can now also use other LLMs, in particular the open-source models offered by the German academic research agency Helmholtz Society (project “Blablador”, free academic access available). The available models are defined in QualCoders config.yml

Implementation details:

By default, the AI features are disabled. The user is asked at the first startup whether they want to enable it. If so, a wizard will guide through the setup process. This wizard can also be started later via the new AI menu.

Startup: Even with the AI turned off, the startup time will be a little longer. Some of the heavy AI-related libraries (especially “sentence-encoder”) will be loaded in a background thread to prevent the app from becoming unresponsive. A new status message at the bottom of the app indicates when the AI is ready.

Vector store: For the semantic search to operate, all text based empirical documents in a project must be converted into semantic embeddings using the local AI model (sentence encoder) mentioned above. These embeddings are then stored in a special database called a “vector store”, based on chroma_db. This happens only once (and when a document is edited, renamed or newly added). Since the analysis of a large document can take up to a minute or longer, this is done in a background thread (status bar: "AI: reading data"). The AI features cannot be used until this process is finished.

Data Structure: Additional AI-related data will be stored in a newly created subfolder within the project called "ai_data". This contains the vector store, a yaml-file with project specific prompts (if there are any) and an SQLite database storing the AI-chats.
UI integration: A new tab for the AI chat and a new menu for the AI features. All AI-related settings are incorporated in the normal settings dialog.

Manage files

Context menu. Added a show all rows EXCEPT value.
Added button to rename all visible rows. Select visible rows by using show value like, show this value and/or show Except value. The rename take a user created prefix and the _001, _002 et cetera.

Editing text files. Uses a different module to speed up identifying changes. A big improvement with large text files.

Manage files - audio video

The option to automatically transcribe audio to text using AI has been removed.
Some

Import survey

The default process is now for each qualitative data column, will be imported as an individual file into the database.
On import each qualitative column name will be added as a code, and the relevant row text will be auto-coded to that code.

Manage references

Improved several functions.
Can view the file via right-click on the file in the files table.
File linked ris_id now has a tooltip that shows the reference title, year and reference type.
New button to automatically link a reference to a file. This works by matching words in the reference title to words in the file name. Needs at least a 70% match between the words to automatically link.
Check the linking after it is applied to ensure it is correct.

Fixed error that kept reference attributes for a file, that remained after a reference was unlinked.

Codes

Code organiser menu option.

Useful for grounded theory development to help develop and organise the coding concepts and their hierarchy.
BACK UP PROJECT before applying changes to the codes tree.
Select a code branch or All, then right click to:
Add categories, rename codes and categories, update memos, merge codes, merge categories, delete categories.

Code images

Can export image grayed-out/blurred/solarised with coded sections highlighted, using key press Ctrl G
Can export image grayed-out/blurred/solarised with selected coded area highlighted - using right-click context menu in a selected coded area
Can export image grayed-out/blurred/solarised with selected code highlighted - using right-click context menu in a selected coded area
L keypress to 'Show codes like' when coding area is in focus

Code text

Line numbers added to show position in text.
A button added to set a default colour for all newly added codes while coding, instead of a random colour.
L keypress to 'Show codes like' when coding area is in focus

Code audio video

Added a button to open the context menu for options with coded segments. Select the segment then the option.
This is a hack to fix an issue in the Windows Exe where right-click on a segment does not open the context menu.
L keypress to 'Show codes like' when coding area is in focus

Reports

Report codes

Checkbox added to allow of export file and case attributes. This is only for exporting codes results as Excel (XLSX) or CSV file formats.
Each file variable will be prepended with FileVar_
Each case variable will be prepended with CaseVar_

HTML export with media links.
The export links contained some errors. This has been fixed.

Codes by text segments

This report creates a table where each text segment is one row. The columns are of all selected codes. A 1 represents that the segment is coded by that code, a 0 - it is not coded by that code.
This function is useful for those researchers who code the same segments of text with multiple codes, such as in the legal field or organisational psychology.

Code co-occurrence

This report shows a table of code names along the x and y axes. The table cells show the count of coding co-occurrences. This is where two codes overlap or are directly abutting. Click on the cell to show the text coding details.

Options include: selecting specific text files or selecting specific codes. There is an export to Excel option.

Errors in this release

CSV import error.
Note, the Windows exe has fixed this error.
line 561 in import_survey.py
Please delete the word "True"
self.ui.comboBox_quote.setFocus(True)

Making QualCoder run more easily on different operating systems

There are now an installer for Windows and app bundles for MacOS available, se installation instructions at the beginning of this page.
There may be an Ubuntu 24 executable. However, it is 3.3GB in size.

[menelic]

Thank you @ccbogel and @kaixxx for this long awaited release with many key improvements and a welcome refresh. Please let us know which mac architectures and/or MacOS versions you are referring to in the Readme as not able to run the tarball install of QualCoder - and when we can expect the MacOS app? Am planning to onboard a team, so this info would save us a lot of potential trial and error.

Also, please do not let the 3.3 GB installer size for the Ubuntu version keep you from releasing it! Better a 3GB executable than none ;-)

[kaixxx]

Hi @menelic
I'm going to compile a macOS dmg app bundle for Apple Silicon (M1...M4 processors) as well as for the older Intel Macs. If everything goes well, the apps will be available later today.

[menelic]

thanks @kaixxx - unfortunately the arm installer does not work on Apple silicone #1007

[kaixxx]

DMG files for macOS are now added to the release, as well as a Windows installer. I have also updated the installation instructions above and on the release page.

[kaixxx]

@menelic: Follow my updated installation instructions above

[vansorat]

Thanks for the Mac installer!
QualCoder_3_6_x86_64.dmg worked on 2017 MacBook Pro. Intel core i5. MacOS Ventura 13.72.

Did not work on 2013 MacBook Pro Mac OS Big Sur 11.7.10 intel i7. The QC jumped up and down and I got the security noticed and clicked on "open anyway". But it did not run. I even changed preferences to run app from anywhere. I was able to run 3.2 and 3.5 on this but recently 3.5 did not work.

[kaixxx]

Thanks for testing. I'm happy to hear that it works on your 2017 Intel Mac.
In case of your second machine, the operating system (Big Sur) is too old. I've compiled QualCoder on a current macOS Sequoia, and the backward compatibility has limits.
If you really want to get QualCoder running on the old machine, the only chance would be to install it from source.

[vansorat]

Would it be possible to relabel the download assets files so that the two exe files are grouped together and the two files for Mac OS together? Also, could a tool tip be added so that we know the two exe files are for Windows and the other 2 or for Mac and that one is for intel and the other for M1 processor.

I also successfully ran both exe files on a Windows 11 computer. My understanding of the differences is that if I "install" using the set.up than I have to uninstall. Where as with the other exe file I just delete the folder. I noticed with exe I get more "not responding" while it is processing.

[kaixxx]

Good point, I have renamed the file-labels and also added a list at the end of the release page: https://github.com/ccbogel/QualCoder/releases/tag/3.6

Regarding the difference between the two Windows options: The installer will set up QualCoder like any other application, with entries in the start menu, etc. The executable is just a binary that you can store anywhere and run from there. It will also start up a little slower.

[vansorat]

Thanks and it is very clear now! Although the new file names will need to replace filenames at the top of this page and other pages.

Also for OS, do you need to include "older" and "newer"? It confused me because I was thinking that there are newer and older intel (I have a 2013 and 2017 mac). Is the only difference whether intel or M processor rather than how old they are?

[kaixxx]

Although the new file names will need to replace filenames at the top of this page and other pages.

I cannot change the actual file names. I've just added the prefix "Windows"/"Mac" to the download links. The downloaded file will still have the old name.

Mac: Yes, Intel vs. Apple Silicon (M) is the only difference that matters. But not everybody understands that, so adding 'old' vs. 'new' might help here, especially for younger people that never had an Intel mac.

[ccbogel]

Should there be a minimum version that works suggestion. e.g. the Big Sur macOS 11 did not work?

[vansorat]

suggest structuring sentence like you did for silicon processor, by replacing
bundle for the older Intel-based Macs
with
bundle for the older Macs with Intel processor (core i5, i7, etc)

[kaixxx]

bundle for the older Macs with Intel processor (core i5, i7, etc)

OK, I've done that above, in the release page, readme and wiki

I've also added the following info regarding macOS versions:

"The app bundles are compiled on macOS Sequoia. They might also work on Sonoma and Ventura. If you are on an older version, consider updating your OS or install QualCoder from source as described in the wiki: https://github.com/ccbogel/QualCoder/wiki/2.1.-Installation#macos"

[ChinchuC]

Hi,
Reporting an error that I encountered. (Not sure if this thread is the right place for that. Apologies if no)

I received the above error message while trying to download additional AI components needed to integrate the Blablador AI to Qualcoder 3.6

File "qualcoder\ai_async_worker.py", line 108, in run
File "qualcoder\ai_vectorstore.py", line 236, in downloadembedding_model
TypeError: int() argument must be a string, a bytes-like object or a real number, not 'NoneType'

I have already got the API key for the integration and inserted it.

Could this be some general bug, or specific to me.

Attaching a screenshot of the add AI components dialogue box and the error screen

[ccbogel]

Thank you . Yes this is a recent error. see here :

Kai -who develops the AI parts of QualCoder has written: "huggingface has changed some internal settings on their servers, which affects the download routine in QualCoder for some of the files "

Im not sure of a fix or this for now. But keep an eye on the Issues thread below.

#1072

To use QualCoder without AI, you can delete the .qualcoder folder which is in your Home folder. All setting changes that you made will be deleted, but you can reset those in Settings, apart from the AI part.

[ChinchuC]

Thanks for the response. I will follow the thread that discusses this issue.

…

On Tue, Jul 1, 2025 at 1:04 PM QualCoder Developer ***@***.***> wrote: Thank you . Yes this is a recent error. see here : Kai -who develops the AI parts of QualCoder has written: "huggingface has changed some internal settings on their servers, which affects the download routine in QualCoder for some of the files " Im not sure of a fix or this for now. But keep an eye on the Issues thread below. #1072 <#1072> To use QualCoder without AI, you can delete the .qualcoder folder which is in your Home folder. All setting changes that you made will be deleted, but you can reset those in Settings, apart from the AI part. — Reply to this email directly, view it on GitHub <#1006 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/APTSAIZ3A7UBD4T5KAJRDPT3GI22DAVCNFSM6AAAAABWZJBTFKVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTGNRSGU4TANY> . You are receiving this because you commented.Message ID: ***@***.***>

-- Regards, Dr. Chinchu C. <https://www.mhinnovation.net/profile/dr-chinchu-c>, Psychologist Assistant Professor, Centre for Women's Studies, Pondicherry University. https://www.pondiuni.edu.in/faculy_profiles/dr-chinchu-c/ https://books.apple.com/us/book/x/id1591674573 Psychologist and Research Consultant, Association for Social Change, Evolution and Transformation (ASCENT)

[kaixxx]

I have added a workaround here: #1072 (comment)

Please report back if it works for you.

[ChinchuC]

Many thanks. I have tried the workaround, and it seems to be working fine now. AI is loading and there are no errors or download prompts shown. Will try out the AI features soon. Thanks again.

…

On Tue, Jul 1, 2025 at 2:37 PM kaixxx ***@***.***> wrote: I have added a workaround here: #1072 (comment) <#1072 (comment)> Please report back if it works for you. — Reply to this email directly, view it on GitHub <#1006 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/APTSAI3SGSDOPIT4NYTOHGD3GJFUBAVCNFSM6AAAAABWZJBTFKVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTGNRSGY4DIMI> . You are receiving this because you commented.Message ID: ***@***.***>

-- Regards, Dr. Chinchu C. <https://www.mhinnovation.net/profile/dr-chinchu-c>, Psychologist Assistant Professor, Centre for Women's Studies, Pondicherry University. https://www.pondiuni.edu.in/faculy_profiles/dr-chinchu-c/ https://books.apple.com/us/book/x/id1591674573 Psychologist and Research Consultant, Association for Social Change, Evolution and Transformation (ASCENT)

[kaixxx]

That's good to know, thank you.