subjectdb 1.0.0__tar.gz

subjectdb-1.0.0/.gitignore

@@ -0,0 +1,25 @@
+# Private files that live next to the code: never commit or package them.
+subject_database.db
+insert_subject_template.xlsx
+project_template.docx
+*.db
+*.db-journal
+*.sqlite
+*.xlsx
+*.xls
+*.docx
+*.csv
+backups/
+
+# Python and tooling
+.venv
+__pycache__/
+*.py[cod]
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+
+# OS files
+.DS_Store

subjectdb-1.0.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 1.0.0 (2026-10-21)
+
+First release of SubjectDB, a rewrite of the subject database of the lab's former `bids_software`
+(Tkinter) project.
+
+- One PySide6 app with two modes: `subjectdb` (researchers) and `subjectdb-pi` (PI).
+- Pages: Add subject, Subjects (search; project, disease and age filters; edit, delete;
+  export without names), Import from Excel, Projects
+  (metadata, diseases, sessions, tasks and acquisitions), and a disease-list manager.
+- One set of rules for every value (diseases, sex, handedness, names, dates, IDs).
+- Every page shows what others saved meanwhile (it reloads when shown; F5 reloads by hand).
+- The de-identified copy (`subject_database_general.db`) is rebuilt after every save, so
+  deletions and changes now reach it too; it stores birth and diagnosis years only.
+- One-time, reviewed upgrade of the existing databases in place, after an automatic backup.
+- Automatic safety copies before the upgrade and before every Excel import.
+- `subjectdb --check` explains installation problems (display, missing libraries, permissions).
+- Illustrated tutorial, also offline in the app (Help → Tutorial).

subjectdb-1.0.0/LICENSE

@@ -0,0 +1,29 @@
+MIT License
+
+Copyright (c) 2026 Fayed Rassoulou
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---------------------------------------------------------------------------
+Bundled third-party files (see the license files next to them):
+
+* src/subjectdb/gui/assets/fonts/Inter-*.ttf - Inter typeface,
+  SIL Open Font License 1.1 (fonts/OFL.txt).
+* src/subjectdb/gui/assets/icons/*.svg - Lucide icons,
+  ISC License, partly derived from Feather (MIT) (icons/LICENSE).

subjectdb-1.0.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.5
+Name: subjectdb
+Version: 1.0.0
+Summary: Desktop app to register study participants across research projects (SQLite + Qt).
+Project-URL: Homepage, https://github.com/Fayed-Rsl/subjectdb
+Project-URL: Documentation, https://github.com/Fayed-Rsl/subjectdb/blob/main/src/subjectdb/docs/tutorial.md
+Project-URL: Issues, https://github.com/Fayed-Rsl/subjectdb/issues
+Project-URL: Changelog, https://github.com/Fayed-Rsl/subjectdb/blob/main/CHANGELOG.md
+Author: Fayed Rassoulou
+License-Expression: MIT AND OFL-1.1 AND ISC
+License-File: LICENSE
+License-File: src/subjectdb/gui/assets/fonts/OFL.txt
+License-File: src/subjectdb/gui/assets/icons/LICENSE
+Keywords: bids,participants,pyside6,research,sqlite,subjects
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: X11 Applications :: Qt
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Database :: Front-Ends
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.10
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: pyside6-essentials>=6.8
+Description-Content-Type: text/markdown
+
+# SubjectDB
+
+**A small desktop app to register the people who take part in your studies, across all your
+research projects.** Every person gets an ID per project (`rhm007`, which is also the BIDS folder
+`sub-rhm007`); names and birthdates stay in one protected file, and a copy without names is kept
+up to date for analyses.
+
+![SubjectDB: the Subjects page](https://raw.githubusercontent.com/Fayed-Rsl/subjectdb/main/src/subjectdb/docs/images/hero.png)
+
+## Features
+
+- **Two modes.** Researchers add subjects (`subjectdb`) and never see stored personal data. The
+  PI (`subjectdb-pi`) also finds, edits, deletes and imports subjects and manages projects.
+- **IDs done for you.** The next free number is suggested; a number that is taken is refused, also
+  when two people save at the same moment.
+- **The same person in several projects** is recognised by name and birthdate (case and accents
+  ignored, so `Müller` = `MUELLER`) and simply joins the new project.
+- **Clean values everywhere.** `PD`, `parkinson's` and `Morbus Parkinson` are all stored as
+  *Parkinson Disease*; sex, handedness and dates follow one set of rules in the form, the Excel
+  import and the upgrade.
+- **Find subjects fast**: an accent-insensitive, ID-aware search (`7`, `rhm7`, `sub-rhm007`),
+  filters by project, disease and age group, and an export of the rows shown (IDs, birthdates and
+  diagnoses, never names).
+- **Excel import** from a template with dropdown lists, with a preview (*New / Add to project /
+  Already in project / Error*) before anything is saved, and a safety copy before every import.
+- **Projects** with their metadata: authors, funding, description, sessions, tasks and
+  acquisitions, and their own list of diseases.
+- **A shared copy without names** (birth and diagnosis years only), rebuilt after every save,
+  for analyses with SQLite or pandas.
+- **Works with the existing databases** of the old lab app: a one-time, reviewed upgrade in place,
+  after an automatic backup.
+- **Illustrated tutorial** built in: **Help → Tutorial**, also offline.
+
+## Install
+
+Python 3.10 or newer, no admin rights needed. SubjectDB gets its own environment (a plain
+`pip install` is refused by many system Pythons):
+
+```
+python3 -m venv ~/subjectdb-env
+~/subjectdb-env/bin/pip install subjectdb
+~/subjectdb-env/bin/subjectdb --check --data-dir /path/to/database   # says what is missing and how to fix it
+```
+
+The environment holds the two commands, `~/subjectdb-env/bin/subjectdb` and
+`~/subjectdb-env/bin/subjectdb-pi`. (`pipx install subjectdb` works too and puts both on the PATH.)
+
+## Quick start
+
+1. Start the PI app: `~/subjectdb-env/bin/subjectdb-pi`.
+2. Choose an empty folder and click **Create new databases here** (or choose the folder that
+   already holds `subject_database.db`).
+3. **Projects → New project**: a name, an ID prefix and the diseases.
+4. **Add subject**: choose the project, type the person, save. The BIDS label (`sub-…`) is shown
+   with a Copy button.
+
+Researchers start `subjectdb` and choose the same folder.
+
+## Documentation
+
+- [Tutorial](https://github.com/Fayed-Rsl/subjectdb/blob/main/src/subjectdb/docs/tutorial.md):
+  every step with pictures, in simple words.
+- [Databases](https://github.com/Fayed-Rsl/subjectdb/blob/main/src/subjectdb/docs/databases.md):
+  the three files, the rules for values, the tables, the upgrade, backups, queries and the
+  server installation.
+- [Changelog](https://github.com/Fayed-Rsl/subjectdb/blob/main/CHANGELOG.md)
+
+From a source checkout, `python run.py` starts researcher mode and `python run_pi.py` PI mode.
+
+## License
+
+MIT © Fayed Rassoulou. Bundled: the [Inter](https://rsms.me/inter/) typeface (SIL Open Font
+License 1.1) and [Lucide](https://lucide.dev) icons (ISC License). The package licence expression
+is `MIT AND OFL-1.1 AND ISC`.

subjectdb-1.0.0/README.md

@@ -0,0 +1,74 @@
+# SubjectDB
+
+**A small desktop app to register the people who take part in your studies, across all your
+research projects.** Every person gets an ID per project (`rhm007`, which is also the BIDS folder
+`sub-rhm007`); names and birthdates stay in one protected file, and a copy without names is kept
+up to date for analyses.
+
+![SubjectDB: the Subjects page](https://raw.githubusercontent.com/Fayed-Rsl/subjectdb/main/src/subjectdb/docs/images/hero.png)
+
+## Features
+
+- **Two modes.** Researchers add subjects (`subjectdb`) and never see stored personal data. The
+  PI (`subjectdb-pi`) also finds, edits, deletes and imports subjects and manages projects.
+- **IDs done for you.** The next free number is suggested; a number that is taken is refused, also
+  when two people save at the same moment.
+- **The same person in several projects** is recognised by name and birthdate (case and accents
+  ignored, so `Müller` = `MUELLER`) and simply joins the new project.
+- **Clean values everywhere.** `PD`, `parkinson's` and `Morbus Parkinson` are all stored as
+  *Parkinson Disease*; sex, handedness and dates follow one set of rules in the form, the Excel
+  import and the upgrade.
+- **Find subjects fast**: an accent-insensitive, ID-aware search (`7`, `rhm7`, `sub-rhm007`),
+  filters by project, disease and age group, and an export of the rows shown (IDs, birthdates and
+  diagnoses, never names).
+- **Excel import** from a template with dropdown lists, with a preview (*New / Add to project /
+  Already in project / Error*) before anything is saved, and a safety copy before every import.
+- **Projects** with their metadata: authors, funding, description, sessions, tasks and
+  acquisitions, and their own list of diseases.
+- **A shared copy without names** (birth and diagnosis years only), rebuilt after every save,
+  for analyses with SQLite or pandas.
+- **Works with the existing databases** of the old lab app: a one-time, reviewed upgrade in place,
+  after an automatic backup.
+- **Illustrated tutorial** built in: **Help → Tutorial**, also offline.
+
+## Install
+
+Python 3.10 or newer, no admin rights needed. SubjectDB gets its own environment (a plain
+`pip install` is refused by many system Pythons):
+
+```
+python3 -m venv ~/subjectdb-env
+~/subjectdb-env/bin/pip install subjectdb
+~/subjectdb-env/bin/subjectdb --check --data-dir /path/to/database   # says what is missing and how to fix it
+```
+
+The environment holds the two commands, `~/subjectdb-env/bin/subjectdb` and
+`~/subjectdb-env/bin/subjectdb-pi`. (`pipx install subjectdb` works too and puts both on the PATH.)
+
+## Quick start
+
+1. Start the PI app: `~/subjectdb-env/bin/subjectdb-pi`.
+2. Choose an empty folder and click **Create new databases here** (or choose the folder that
+   already holds `subject_database.db`).
+3. **Projects → New project**: a name, an ID prefix and the diseases.
+4. **Add subject**: choose the project, type the person, save. The BIDS label (`sub-…`) is shown
+   with a Copy button.
+
+Researchers start `subjectdb` and choose the same folder.
+
+## Documentation
+
+- [Tutorial](https://github.com/Fayed-Rsl/subjectdb/blob/main/src/subjectdb/docs/tutorial.md):
+  every step with pictures, in simple words.
+- [Databases](https://github.com/Fayed-Rsl/subjectdb/blob/main/src/subjectdb/docs/databases.md):
+  the three files, the rules for values, the tables, the upgrade, backups, queries and the
+  server installation.
+- [Changelog](https://github.com/Fayed-Rsl/subjectdb/blob/main/CHANGELOG.md)
+
+From a source checkout, `python run.py` starts researcher mode and `python run_pi.py` PI mode.
+
+## License
+
+MIT © Fayed Rassoulou. Bundled: the [Inter](https://rsms.me/inter/) typeface (SIL Open Font
+License 1.1) and [Lucide](https://lucide.dev) icons (ISC License). The package licence expression
+is `MIT AND OFL-1.1 AND ISC`.

subjectdb-1.0.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "subjectdb"
+dynamic = ["version"]
+description = "Desktop app to register study participants across research projects (SQLite + Qt)."
+readme = "README.md"
+requires-python = ">=3.10"
+# Our code is MIT; the bundled Inter font is OFL-1.1 and the Lucide icons are ISC.
+license = "MIT AND OFL-1.1 AND ISC"
+license-files = [
+    "LICENSE",
+    "src/subjectdb/gui/assets/fonts/OFL.txt",
+    "src/subjectdb/gui/assets/icons/LICENSE",
+]
+authors = [{ name = "Fayed Rassoulou" }]
+keywords = ["research", "participants", "subjects", "sqlite", "bids", "pyside6"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: X11 Applications :: Qt",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Database :: Front-Ends",
+    "Topic :: Scientific/Engineering :: Medical Science Apps.",
+]
+dependencies = [
+    "PySide6-Essentials>=6.8",
+    "openpyxl>=3.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/Fayed-Rsl/subjectdb"
+Documentation = "https://github.com/Fayed-Rsl/subjectdb/blob/main/src/subjectdb/docs/tutorial.md"
+Issues = "https://github.com/Fayed-Rsl/subjectdb/issues"
+Changelog = "https://github.com/Fayed-Rsl/subjectdb/blob/main/CHANGELOG.md"
+
+[project.scripts]
+subjectdb = "subjectdb.app:main"
+subjectdb-pi = "subjectdb.app:main_pi"
+
+[tool.hatch.version]
+path = "src/subjectdb/__init__.py"
+
+# The project folder also holds private files (databases, Excel, Word). Only the
+# paths listed here can ever reach the sdist; the wheel only gets the package.
+[tool.hatch.build.targets.sdist]
+only-include = ["src", "run.py", "run_pi.py", "README.md", "CHANGELOG.md", "LICENSE"]
+exclude = ["**/__pycache__", "*.db", "*.db-journal", "*.xlsx", "*.xls", "*.docx", "*.csv"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/subjectdb"]
+exclude = ["**/__pycache__", "*.db", "*.db-journal", "*.xlsx", "*.xls", "*.docx", "*.csv"]

subjectdb-1.0.0/run.py

@@ -0,0 +1,14 @@
+"""Start SubjectDB in researcher mode from a source checkout: ``python run.py``.
+
+Installed users run ``subjectdb`` instead. Extra options are passed through,
+for example ``python run.py --data-dir /path/to/database``.
+"""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent / "src"))
+
+from subjectdb.app import main
+
+sys.exit(main())

subjectdb-1.0.0/run_pi.py

@@ -0,0 +1,14 @@
+"""Start SubjectDB in PI mode from a source checkout: ``python run_pi.py``.
+
+Installed users run ``subjectdb-pi`` instead. Extra options are passed through,
+for example ``python run_pi.py --data-dir /path/to/database``.
+"""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent / "src"))
+
+from subjectdb.app import main_pi
+
+sys.exit(main_pi())

subjectdb-1.0.0/src/subjectdb/__init__.py

@@ -0,0 +1,13 @@
+"""SubjectDB: register study participants across research projects.
+
+The package is split in two layers:
+
+* ``vocabulary``, ``db``, ``upgrade`` and ``excel`` hold all rules and all
+  database work. They never import Qt, so they can be tested and scripted alone.
+* ``gui`` is the PySide6 interface. It never talks to SQLite directly; every
+  read and write goes through :class:`subjectdb.db.Registry`.
+
+``app`` glues both together (command line, start-up checks, main window).
+"""
+
+__version__ = "1.0.0"

subjectdb-1.0.0/src/subjectdb/__main__.py

@@ -0,0 +1,7 @@
+"""Allow ``python -m subjectdb`` (researcher) and ``python -m subjectdb --pi`` (PI)."""
+
+import sys
+
+from subjectdb.app import main
+
+sys.exit(main())