Get a Hub account and log in

An account is required for working with the TRR379 collaboration platform on Forgejo. You can sign in using “GitLab Aachen” Single Sign-On (SSO) (preferred) or request an account manually.

Single sign-on using GitLab Aachen

1. Visit the TRR379 collaboration hub and click Sign in with Gitlab-Aachen on the login page.

2. Log in using your preferred identity provider (i.e., GitHub or your affiliated organization via DFN-AAI SSO) and follow the on-screen instructions to activate your account.
3. Visit the confirmation link that will be sent to the email address associated with the account.

Manual request

In order to obtain an account manually, email trr379@lists.fz-juelich.de. Please email from an institutional email, and CC the respective TRR379 project lead. In the email, mention any projects and/or organizations you require read or write access to.

Set up your Hub account permissions

To access and report records using the knowledge pooling tool, you must have read and write access to the protected collection on the TRR379 collaboration platform. You must be a member of both:

• metadata-pool-read-protected, and
• metadata-pool-write-protected.

1. To confirm your team memberships, sign into the Hub (see also Get a Hub account and log in).
2. Navigate to both of the following links to view the team members:

• metadata-pool-read-protected
• metadata-pool-write-protected

3. If you are unable to see a repository or team member list, or if your user name is not listed, please proceed to request access.
4. Request access to protected team(s)

   • Please email trr379@lists.fz-juelich.de from an institutional email and with the respective TRR379 project lead in CC to request access to the metadata-pool-read-protected and/or metadata-pool-write-protected team(s).

Create your contributor profile

TRR379 contributor profiles are automatically updated on the main website based on the knowledge pool. Follow these steps to create and/or edit your own profile, including uploading a portrait photo.

1. Navigate to the knowledge pooling tool.

2. Log in using your associated TRR379 hub account.

   • Click the “Login” (human silhouette) button.
   • Select the “Login with TRR379 hub” option.
   • Read the disclaimer, and if you agree, select “Authorize Application”.
   • A checkmark will appear on to the “Login” (human silhouette) button if you were successfully logged in.

3. Select the “Person” Data Type on the left side of the page.

4. Create a new record by clicking the + (plus) button, or edit an existing record by clicking the pencil icon.

5. To add a portrait photo, click the “Upload a depiction” Wizard button (person silhouette icon). Click the file attachment button (paperclip icon), and select the portrait image with your file browser. Wait for the green checkmark confirmation of a successful upload, and then click “SAVE”.

6. Proceed to add relevant information to complete your contributor profile as follows:

7. Once all relevant information has been entered, click “SAVE” in the top-right corner to save the Person record.
8. Click the “Submit” button (cloud icon, top-right), which should show a green notification dot to indicate changes are ready to be submitted.

9. The interface will list all records you are about to submit. For a contributor profile with a profile photo, you should see three records: a File, a Depiction, and a Person.
10. Click “Submit”. A confirmation message will appear when submission is successful. If an error occurs, note the message and retry. If it persists, you may wish to review common error messages or reach out for help via the resources on the Support page.

Report publications

1. Navigate to the knowledge pooling tool.

2. Log in using your associated TRR379 hub account.

   • Click the “Login” (human silhouette) button.
   • Select the “Login with TRR379 hub” option.
   • Read the disclaimer, and if you agree, select “Authorize Application”.
   • A checkmark will appear on to the “Login” (human silhouette) button if you were successfully logged in.

3. Select the “Publication” Data Type on the left side of the page.

4. Select the “Import a publication via DOI” button (square icon with right-facing arrow, just to the right of the + plus button).

5. Enter the DOI, and select “IMPORT”. A new section should appear showing the imported metadata. If you receive an error message that the record already exists, follow the instructions to edit the existing record instead of importing a new one.

6. Confirm, add, or edit the Title, Abstract, and Authors as necessary. For authors that are not automatically linked upon import to Person records in the pool, you can click and search directly in the “Linked Record” column to find a corresponding Person record in the pool; if no linked record is selected, a new Person record will be created for that author. Click “SAVE” when everything looks correct.

7. Navigate to your new Publication record in the pool’s Publication records list, and click the pencil icon to edit it.

8. For publications to make the best impressions and live up to their fullest metadata potential, proceed to add relevant information to complete the Publication record as follows:

9. Once all relevant information has been entered, click “SAVE” in the top-right corner to save the Publication record. After saving, a well-curated publication record links to its authors, topics, and projects.
10. Click the “Submit” button (cloud icon, top-right), which should show a green notification dot to indicate changes are ready to be submitted.

9. The interface will list all records you are about to submit. You should see your Publication record here.
10. Click “Submit”. A confirmation message will appear when submission is successful. If an error occurs, note the message and retry. If it persists, you may wish to review common error messages or reach out for help via the resources on the Support page.

Document instruments and questionnaires

TRR379 uses the knowledge pool to document research instruments and questionnaires, and to provide standardized identifiers that can be used when harmonizing data across sites.

You can document an instrument at different levels. In particular, questionnaires can be documented as:

• the original instrument or questionnaire,
• a TRR379-specific version or variant,
• individual questionnaire items, and
• where useful, site-specific versions of an instrument or item.

These records can be linked to one another to expose the relationships between the original instrument, TRR379 versions, and individual questionnaire items.

You do not need to complete every level or every metadata field at once. Instrument documentation is an iterative process. A basic record with a clear identifier and name is already useful and can be expanded later.

Document an instrument

If you have an instrument that is used in TRR379, start by creating an Instrument record in the knowledge pool. At a minimum, give the instrument a meaningful name and a persistent identifier.

If you know the description, instrument type, source publication, or relationships to other records, add those as well. You can always add additional information later.

1. Navigate to the knowledge pooling tool.

2. Log in using your associated TRR379 hub account.

   • Click the “Login” (human silhouette) button.
   • Select the “Login with TRR379 hub” option.
   • Read the disclaimer, and if you agree, select “Authorize Application”.
   • A checkmark will appear on to the “Login” (human silhouette) button if you were successfully logged in.

3. Select the “Instrument” Data Type on the left side of the page.

4. Create a new record by clicking the + (plus) button, or edit an existing record by clicking the pencil icon.

5. Click the “Edit PID manually” button (pencil icon to the right of “Persistent identifier”) and edit the random identifer according to the following naming convention:

trr379:instruments/<original_instrument>-<trr379_variant_and_version>-<item_or_subscale_name>

Click the “Persistent identifer” pencil icon again to lock the PID editor.

6. Within the “Name” box, enter a human-readable name for the content in your Instrument record. As is relevant, this might take the format: <original_instrument_name>, <subscale_name> (<trr379_variant>), or for a specific questionnaire item it would simply be the text for that question.
7. Add whatever metadata you have available (see also Relationships and Additional metadata).

8. Once all relevant information has been entered, click “SAVE” in the top-right corner to save the Instrument record.
9. Click the “Submit” button (cloud icon, top-right), which should show a green notification dot to indicate changes are ready to be submitted.

10. The interface will list all records you are about to submit. You should see your Instrument record here.
11. Click “Submit”. A confirmation message will appear when submission is successful. If an error occurs, note the message and retry. If it persists, you may wish to review common error messages or reach out for help via the resources in the Support page.

Document a questionnaire

Questionnaires can be represented at several levels.

Original instrument
    │
    └─ TRR379 variant
          │
          ├─ Item 1
          ├─ Item 2
          ├─ Item 3
          └─ ...

Original questionnaire

If the original instrument/questionnaire is known, create a record for it, give it a PID in the format, trr379:instruments/<original_instrument> (e.g., trr379:instruments/lha) and, where possible, link it to its source publication or other canonical documentation.

TRR379 questionnaire variant

TRR379-specific versions take on the PID format, trr379:instruments/<original_instrument>-<trr379_variant_and_version> (e.g., trr379:instruments/lha-trr379-q01). This is where you should document meaninful differences from the original questionnaire, including:

• translation
• modified wording
• different item selection
• coding differences
• particular TRR379 projects using the variant

Questionnaire items

If the individual questionnaire subscales and/or items (i.e., questions) are known, create a separate Instrument record for each item. For LHA, for example:

trr379:instruments/lha-trr379-q01-subscale-aggression
trr379:instruments/lha-trr379-q01-subscale-consequences
trr379:instruments/lha-trr379-q01-subscale-selfdirected
trr379:instruments/lha-trr379-q01-item1
trr379:instruments/lha-trr379-q01-item2
...

Item-level identifiers allow sites to refer to the same questionnaire items consistently when preparing standardized datasets.

For each item, be sure to include:

• Name: the actual question/item text
• part of: the questionnaire/variant it belongs to

When available, this also where value encodings for answer options may be recorded.

Relationships

Relationships are useful when you know how the record relates to another instrument or questionnaire.

Additional metadata

For instruments to live up to their fullest metadata potential, proceed to add relevant information as you are able. For example:

BIDS conversion

Converting the heterogeneous, site-specific raw MRI data acquisitions into a standardized dataset is an essential precondition for the collaborative work in TRR379. It readies the data for processing with established pipelines, and applies a pseudonymization as a safeguard for responsible use of this personal data.

TRR379 uses the Brain Imaging Data Structure (BIDS) as the standard for its datasets.

Conversion to BIDS

The conversion of raw MRI data in DICOM format to a BIDS-compliant dataset is a largely automated process. The recommended software to be used for conversion is heudiconv. Heudiconv uses dcm2niix as the actual DICOM→NIfTI converter. Heudiconv tutorials further illustrate how the software works.

Heudiconv performs the task of mapping DICOM series to BIDS entities (ie. determining BIDS-compliant file names). A key heudiconv concept is a heuristic: a Python program (function) which receives the DICOM series properties and matches them with a file naming pattern. A heuristic typically relies on DICOM series naming (set at the scanner console), but it can also use other properties such as number of images or acquisition parameters.

Heudiconv workflows have been implemented at each MRI acquisition site, and reuse shared components.

Shared Resources

• q02/heudiconv-container is a DataLad dataset providing a heudiconv container.
• q02/rdmtools contains Python scripts which further automate BIDS conversion, pushing created datasets to dedicated locations, and other data curation tasks.
• q01/phantom-mri-dicoms is a superdataset grouping phantom MRI scans from all sites, used to develop and test the conversion workflow; it also contains the reference TRR379 heudiconv heuristic.

Details

Modular datasets

A DataLad dataset containing a BIDS dataset will typically have these subdatasets. Subdatasets help in recording provenance while enabling different access scopes for different components:

• code/heudiconv: heudiconv container (q02/heudiconv-container)
• code/rdmtools: optional, shared scripts for data curation tasks (q02/rdmtools)
• sourcedata/dicoms: a site-specific DICOM dataset, itself containing one subdataset per session
• .heudiconv: heudiconv cache / intermediate outputs are stored in a separate dataset to avoid including DICOM information in the BIDS dataset

Dump-things API

The metadata service is a small application built on FastAPI that can be deployed running in a virtual environment, managed by Hatch – running under an unprivileged user account. This scenario is described here. However, any other deployment approaches suitable for Python-based applications may work just as fine.

Required software

The only software that is required outside the virtual environment (and the web server) is pipx, which is used to deploy hatch for a user – no need for administrator privileges otherwise.

sudo apt install pipx --no-install-recommends

User account setup

Here we set up a dedicated user dumpthing to run the service. However, the service could also run under any other (existing) user account.

# new user, prohibit login, disable password
sudo adduser dumpthing --disabled-password --disabled-login

# allow this user to run process while not logged in
sudo loginctl enable-linger dumpthing

# allow this user to execute systemd commands interactively.
# this needs XDG_RUNTIME_DIR define.
# the demo below is for ZSH
sudo -u dumpthing -s
cd
echo 'export XDG_RUNTIME_DIR="/run/user/$UID"' >> ~/.zshrc
# put `hatch` in the PATH for convenience
echo 'export PATH="/home/dumpthing/.local/bin:$PATH"' >> ~/.zshrc

Service environment setup

Everything in this section is done under the target user account. Use something like sudo -u dumpthing -s to enter it.

The following commands perform the initial setup, which provides an installation of the dump-things-service to query and encrich the TRR379 knowledge base.

# install `hatch` to run the service in a virtual environment
pipx install hatch

# obtain the source code for the service
git clone https://hub.trr379.de/q02/dump-things-service.git

# obtain the dataset with the (curated) metadata to be served
# by the service
git clone https://hub.trr379.de/q02/trr379-knowledge.git curated_metadata

# set up a directory for receiving metadata submissions
# each subdirectory in it must match a "token" the needs to be
# presented to the service to make it accept a record posting.
mkdir token_realms

# the service expects a particular data organization.
# we opt to create a dedicated root directory for it,
# and symlink all necessary components into it
mkdir server_root
ln -s ../curated_metadata/metadata server_root/global_store
ln -s ../token_realms server_root/token_stores

# now we can test-launch the service
hatch run fastapi:run --port 17345 /home/dumpthing/server_root

If the service comes up with no error, we can ctrl-c it.

Service management with systemd

We use systemd for managing the service process, the launch, and logging. This makes it largely unnecessary to interact with hatch directly, and allows for treating the user-space service like any other system service on the system.

The following service unit specification is all that is needed.

mkdir -p .config/systemd/user/
cat << EOT > .config/systemd/user/dumpthing.service
[Unit]
Description=DumpThing service (hatch environment)
Wants=network-online.target
After=network-online.target


[Service]
Type=simple
WorkingDirectory=/home/dumpthing/dump-things-service
ExecStart=/home/dumpthing/.local/bin/hatch run fastapi:run --port 17345 /home/dumpthing/server_root

[Install]
WantedBy=default.target
EOT

With this setup in place, we can control the service via systemd.

# launch the service
systemctl --user start dumpthing

# configure systemd to auto-launch the service in case of a
# system reboot
systemctl --user enable dumpthing.service

Web server setup

Here we use caddy as a reverse proxy to expose the services via https at metadata.trr379.de.

# append the following configuration to the caddy config
cat << EOT >> /etc/caddy/Caddyfile
# dumpthings service endpoints
metadata.trr379.de {
    reverse_proxy localhost:17345
}
EOT

A matching DNS setup must be configured separately.

Afterwards we can reload the web server configuration and have it expose the service.

# reload the webserver config to enable the reverse proxy setup
# (only necessary once)
sudo systemctl reload caddy

Updates and curation

Whenever there are updates to the to-be-served curated metadata, the setup described here only required the equivalent of a git pull to fetch these updates from the “knowledge” repository.

When records are submitted, they end up in the directory matching the token that was used for submission. Until such records are integrated with the curated metadata in global_store, they are only available for service requests that use that particular token.

An independent workflow must be used to perform this curation (acceptance, correction, rejection) of submitted records.

Neurobagel

NeuroBagel is a collection of containerized services that can be deployed in a variety of way. This page describes a deployment using podman and podman-compose that is confirmed to be working on machine with a basic Debian 12 installation.

For other installation methods, please refer to the NeuroBagel documentation.

The following instruction set up a “full-stack” NeuroBagel deployment. The contains all relevant components

• query front-end
• federation API
• node API
• graph database

This setup is suitable for a self-contained deployment, such as the central TRR379 node. Other deployments may only need a subset of these services.

On the target machine, NeuroBagel services will run “rootless”. This means they operate under a dedicated user account with minimal privileges.

Required software

Only podman, and its compose feature are needed. They can be installed via the system package manager.

sudo apt install podman podman-compose

User setup

We create a dedicated user neurobagel on the target machine. NeuroBagel will be deployed under this user account, and all software and data will be stored in its HOME directory.

# new user, prohibit login, disable password
sudo adduser neurobagel --disabled-password --disabled-login

# allow this user to run process while not logged in
sudo loginctl enable-linger neurobagel

# allow this user to execute systemd commands interactively.
# this needs XDG_RUNTIME_DIR define.
# the demo below is for ZSH
sudo -u neurobagel -s
cd
echo 'export XDG_RUNTIME_DIR="/run/user/$UID"' >> ~/.zshrc
exit

Configure NeuroBagel

In the HOME directory of the neurobagel user we create the complete runtime environment for the service. All configuration is obtained from a Git repository.

# become the `neurobagel` user
sudo -u neurobagel -s
cd

# fetch the setup
git clone https://hub.trr379.de/q02/neurobagel-recipes recipes

# create the runtime directory
mkdir -p run/data/
mkdir -p run/secrets/

# copy over the demo data for testing (can be removed later)
cp recipes/data/* run/data

# generate passwords (using `pwgen` here, but could be any)
pwgen 20 1 > run/secrets/NB_GRAPH_ADMIN_PASSWORD.txt
pwgen 20 1 > run/secrets/NB_GRAPH_PASSWORD.txt

# configure the the address of the "local" NeuroBagel
# node to query
cat << EOT > recipes/local_nb_nodes.json
[
    {
        "NodeName": "TRR379 central node",
        "ApiURL": "https://nb-cnode.trr379.de" 
    }
]
EOT

Web server setup

NeuroBagel comprises a set of services that run on local ports that are routed to the respective containers. Here we use caddy as a reverse proxy to expose the necessary services via https at their canonical locations.

# append the following configuration to the caddy config
cat << EOT >> /etc/caddy/Caddyfile
# neurobagel query tool
nb-query.trr379.de {
    reverse_proxy localhost:13700
}
# neurobagel apis
# graph db api not exposed at 13701
nb-cnode.trr379.de {
    reverse_proxy localhost:13702
}
nb-federation.trr379.de {
    reverse_proxy localhost:13703
}
EOT

A matching DNS setup must be configured separately.

Manage NeuroBagel with systemd

We use systemd for managing the NeuroBagel service processes, the launch, and logging. This makes it largely unnecessary to interact with podman directly, and allows for treating the containerized NeuroBagel like any other system service.

The following service unit specification is all that is needed. With more recent versions of podman and podman-compose better setups are possible. using podman version. However, this one is working with the stock versions that come with Debian 12 (podman 4.3.1 and podman-composer 1.0.3) and requires no custom installations.

mkdir -p .config/systemd/user/
cat << EOT > .config/systemd/user/neurobagel.service
[Unit]
Description=NeuroBagel rootless pod (podman-compose)
Wants=network-online.target
After=network-online.target


[Service]
Type=simple
WorkingDirectory=/home/neurobagel/recipes
EnvironmentFile=/home/neurobagel/recipes/trr379.env
ExecStart=/usr/bin/podman-compose -f ./docker-compose.yml up
ExecStop=/usr/bin/podman-compose -f ./docker-compose.yml down

[Install]
WantedBy=default.target
EOT

Launch

With this setup in place, we can launch NeuroBagel

# reload the webserver config to enable the reverse proxy setup
# (only necessary once)
sudo systemctl reload caddy

# launch the service (pulls all images, loads data, etc).
# after a minutes the service should be up
systemctl --user start neurobagel

# configure systemd to auto-launch NeuroBagel in case of a
# system reboot
systemctl --user enable neurobagel.service

RDM Infrastructure

[This is a draft under discussion]

The planned RDM infrastructure is a federation of interoperable site infrastructures. The key design principle is that no primary data are aggregated to a central infrastructure.

We aim to establish an infrastructure that is suitable for use within the TRR379, but not limited to this scope. Once deployed, the associated services are usable beyond the scope of TRR379.

The following schema sketches the planned infrastructure. Components that hold (primary) data are depicted in yellow. Components that hold (mostly or exclusively) metadata are shown in blue. The direction of information flow is indicated by arrows, exchange of data by solid arrows, and metadata-only exchange by dotted arrows. Infrastructures that are only accessible to authorized agents are labeled with a “lock” symbol. Further details on individual components are provided below.

graph TB;
    subgraph Central services
        C1[("Collaboration portal<br>hub.trr379.de<br> 🔐")]:::meta
        C2{{"Data search<br>query.trr379.de<br> 🔐"}}:::meta
        C3(Main website<br>www.trr379.de):::meta
        C4("Data catalog<br>data.trr379.de"):::meta
    end
    subgraph "Aachen 🔐"
        A1[(hub)]:::data
        A1a[(lab1)]:::data
        A1b[(lab2)]:::data
        A2{{query}}:::meta
    end
    subgraph "Frankfurt 🔐"
        F1[(hub)]:::data
        F2{{query}}:::meta
    end
    subgraph "Heidelberg 🔐"
        H1[(hub)]:::data
        H1a[(ZI-hub)]:::data
        H1b[(lab1)]:::data
        H2{{query}}:::meta
    end
    A1 -.-> C1
    A1a -.-> A1
    A1b <---> A1
    A1 -.-> A2
    A2 <-.-> C2
    F1 -.-> C1
    F2 <-.-> C2
    F1 -.-> F2
    C3 <-.-> C1
    C3 -.-> C2
    H1 -.-> C1
    H1a <-.-> C1
    H1a <-.-> H1
    H1b <---> H1
    H1 -.-> H2
    H2 <-.-> C2
    C1 -.-> C2
    C1 -.-> C4
    C3 -.-> C4
    H1b <---> A1a
    %% node links to actual services
    click C1 href "https://hub.trr379.de"
    click C3 href "https://www.trr379.de"
    %% classes to distinguish data and metadata nodes
    classDef data fill:#ffa200,color:#000
    classDef meta fill:#5C99C8,color:#000
    %% invisible link purely for manipulating the grouping
    C2 ~~~ A1b
    C4 ~~~ A1b
    C2 ~~~ F1
    C2 ~~~ H1b

Central services

All central services a metadata-focused. No primary data acquired at participating sites are aggregated into central databases/storage.

Collaboration portal (hub.trr379.de)

This is the main hub for collecting actionable links to all TRR379 resources and information. The software solution for this hub is Forgejo-ankesajo. It is a free and open-source software package, and the direct service counterpart of DataLad, the main tool proposed for implementing reproducible research workflows in TRR379 labs.

The hub will store DataLad datasets, referencing all TRR379 data resources without hosting any actual data. Instead the DataLad dataset point to the individual institutional data stores, or to community data repositories when and where data have been published.

The hub is also a place to deposit (shared) computational environments, and implementations of (shared) data processing pipelines, software publications, and source code repositories under a uniform TRR379 umbrella.

A test site is deployed at https://hub.trr379.de and is being evaluated.

Main website

See this page for a description of the main website. Importantly, the website renders essential metadata for the TRR379 (contributors, roles, publications, projects, research topics, etc.) It provides a unique URI for any such entity, to be used as identifiers in all TRR379 (meta)data resources.

The website is programmatically generated from a repository hosted on the TRR379 hub, to enable contributions by all TRR379 members.

Data catalog

The TRR379 data catalog is a website dedicated to providing a uniform (read-only) view on the TRR’s data resources. It is rendered programmatically by DataLad Catalog from metadata on TRR379 data resources hosts in the TRR379 hub.

This site is indexed by specialized search engines like Google’s dataset search and a key enabler for general findability of TRR379 resources.

Data search

This is a federated data discovery service that is tailored to the cohort dataset acquired by TRR379 as a whole. It will enable the discovery of individual data records matching a given set of criteria, regardless of the contributing TRR379 site.

The service is federated. Each sites runs their own instance, and has the sole authority on deciding what metadata are shared with other TRR379 sites. Only these metadata property will be accessible by TRR379 at large, while more detailed metadata records can be use for in-house queries.

The proposed solution for the query service is a version of NeuroBagel adapted to the data nature and needs of TRR379.

Site infrastructure

Sites are free to implement any RDM solutions, as long as that infrastructure provides

• (programmatically) queryable metadata of a previously agreed upon nature
• (programmatically) accessible data to any authorized members of TRR379

with the aim to enable reproducible research from primary data to published results within and across TRR379.

Q02 supports sites with software solution that facilitate interoperability within TRR379. This includes the local deployment of the software systems used to run the central services.

We aim at individual sites running their own data hubs (using the same software solution) as the central https://hub.trr379.de. In contrast to the central hub, these institutional sites can directly use the storage features of Forgejo-ankesajo, and host arbitrary amounts of data. TRR379 can communicate data availability using a federation protocol.

Matrix Space

The TRR379 has a dedicated space at https://app.element.io/#/room/!YTyCzxGsutdlGNxjGj:matrix.org on Matrix, an open, free, and encrypted messaging platform with unlimited history. It is intended as an informal place to exchange information, get faster feedback, and connect with people working on the same topics across sites. Joining is entirely voluntary.

To join the space, you need a Matrix account. Many institutions provide their own homeservers for setting up institutional accounts. If not, anyone can create a free account at https://app.element.io/.

The TRR379 Matrix space is only for TRR379 consortium members. To get access, email trr379@lists.fz-juelich.de with your Matrix account name included, or contact @mih:matrix.org directly on matrix.

Calendars

TRR379 uses a dedicated CalDAV server at https://cal.trr379.de. This service can be used to host any number of online calendars. Individual calendars can be configured to be publicly accessible, or only for internal (authenticated) consumption.

Internal calendars

Any number of non-public calendars can be created and shared with specific audiences. This can be useful to coordinate data acquisition sessions, organize room bookings, or schedule slots for internal meetings and events.

Contact the management team to request a dedicated calendar.

Public calendars

All public calendars are available via CalDAV URL and can be included in any calendar solution, such as Google calendar.

The URLs follow the pattern https://cal.trr379.de/public/<name>, where <name> is the calendar name, as stated in the list below. For the events calendar this is https://cal.trr379.de/public/events.

For use with Google calendar, replace https:// with webcal://. For example, the events calendar can be added to Google calendar with the URL webcal://cal.trr379.de/public/events.

Available public calendars:

• events: General TRR379 events [preview]

Collaboration Platform

https://hub.trr379.de is the central (data) collaboration site of the consortium. It runs an enhanced variant of the Forgejo software that is designed for maximum interoperability with the RDM solution DataLad.

The main difference to the Gitlab solution – that is also employed by TRR379 for internal purposes – is the ability to also host arbitrarily large data on the same site. The integration with the git-annex software makes it ideal for the federated, multi-site nature of TRR379. The full software-stack is free and open source software, and can be deployed at any collaborating site with minimal effort. This aspect is essential for supporting the decentralized RDM approach of the TRR.

Any contributor can have an account on the central hub. Please contact the Q02 team to get set up.

Knowledge Pooling Tool

The knowledge pooling tool is a system used for aggregating information on research progress and outputs across TRR379 partner sites and projects.

It comprises:

• A web UI for submitting, editing, and browsing records such as people, projects, and publications
• A backend API allowing scripts and applications to contribute or retrieve metadata
• OAuth 2.0 and token-based authentication that integrates with Forgejo teams on the collaboration platform to manage read and write permissions

The current (generation v0) tool can be accessed at:

• UI: https://pool.v0.trr379.de/ui/
• API: https://pool.v0.trr379.de/api/docs

For technical information on the knowledge pooling tool and its data and privacy policy, visit:

• https://pool.v0.trr379.de/

For information on using the knowledge pooling tool, see:

• Accounts & Access for getting set up, including creating a linked Hub account
• Submit to the Knowledge Pool for submitting, editing, and browsing records in the web UI
• Generate an Access Token on the Hub for generating a personal access token for authentication purposes, particularly when working with the programmatic API
• shacl-vue Documentation (external link) for the documentation for the knowledge pool’s web UI.
• Dump Things Service Documentation (external link) for the documentation for the knowledge pool’s backend API.

Main Website

This is the main website of the TRR379.

This website is not just a public-facing view on the consortium. It is specifically built to be the core component of the metadata concept of TRR379. It provides a collection of canonical definitions of entities essential for the function of TRR379. Such entities include

• projects of the TRR
• contributors to the TRR
• publication from the TRR membership
• site of the consortium
• …

Sources

The website sources are hosted on the TRR379 collaboration hub in a repository under the Q04 project organization. This repository is a DataLad dataset, the same technology that is used for research data management in the TRR379. The repository README contains instruction on how to obtain a clone of the website for working on it, and testing it locally.

Semantics

Any such entity has a dedicated page on the website, with a stable URL that serves as a URI for that entity. As such, these URLs can be used in any TRR379-related metadata to declare relationships to TRR379 entities, for example, the authorship of a publication, the origin project of a data release, etc.

The website is built with the static site generator Hugo. It capitalized on its taxonomy feature. Any page on the site is built from a metadata record. For Hugo, this metadata is presented in the form of a page’s front matter. However, these metadata may themselves be generated from the result of a database query.

Here is an example record for TRR379 spokesperson Ute Habel:

title: Ute Habel
projects:
- a02
- a04
- q01
- q04
sites:
- Aachen
- Juelich
roles:
- pi
- spokesperson
layout: contributor
params:
  orcid:  0000-0003-0703-7722
  name-title: Prof. Dr. rer. soc.
  affiliation: Department of Psychiatry, Psychotherapy and Psychosomatics, Faculty of Medicine, RWTH Aachen University
  sortkey: "Habel, Ute"

<additional content on the page's subject>

From this information, the page that identifies and describes Ute Habel as a spokesperson is generated. It also links and references her record on the respective pages for projects, sites, and roles she is associated with. Consequently, the URL https://www.trr379.de/contributors/ute-habel/ can serve as a URI for Ute Habel within the TRR379 metadata. Moreover, ute-habel is a unique identifier for her as a contributor to TRR379.

While other special-purpose identification systems exist (e.g., https://orcid.org for academics), this approach is automatically applicable to any concept and entity relevant to TRR379. Including roles, data acquisition methods, instruments, etc. The domain root trr379.de represents a unique namespace to define and reference any required entities. This enables a timely and unencumbered development of a metadata concept for TRR379, without hindering alignment with and mapping to more global efforts and initiatives.

Look

Structured metadata is rendered to an HTML website with Hugo using a template. This approach separates the information from its presentation.

The look of the website can be altered by adjusting the template, or switching to a different template entirely. This requires familiarity with Hugo and its templating mechanism.

At present, the congo template is used.

Data Catalog

https://data.trr379.de hosts the data catalog of the TTR379. This site is currently work in progress, and will be published once the project has started to accumulate data.

A data catalog is a website that displays and organises information that you provide about your collected datasets.

The purpose of a catalog is to make data more FAIR, specifcally more findable, even if they are access restricted. The catalog further encourages collaboration between partner sites. If all partners share a common data catalog which showcases their respective collected datasets, partners can more easily engage in potential collaborations with each other as they can see what data has already been collected at each site.

The data catalog only makes metadata (i.e. descriptive fields about your dataset) openly available, there is no need to make the actual data file content publicly accessible. In other words, you do not need to upload sensitive data (or publicly available data, for that matter) anywhere in order for the dataset to be part of the catalog, just metadata. Providing full access to a dataset, or merely to a limited description about a dataset is entirely within your control. If a partner wishes to pursue a collaboration regarding a certain dataset, that partner will still need to follow the existing institutional routes of requesting access to your dataset. You have FULL control over what information is displayed in the catalog, and if you want the data files to be publicly accessible or not.

Catalog sources follow a specific design and structure.

The main source of metadata for the data catalog is the DataLad dataset at ./data, also referred to as the catalog superdataset or the catalog homepage dataset.

The idea is that this superdataset acts as a container for the metadata of all new datasets that should be represented in the catalog.

In a typical catalog source repository, you will find the following structure:

./catalog - this is where the data catalog sources live - the live catalog site serves this directory

./code - this directory contains scripts that are used for catalog updates

./data - this is a DataLad subdataset of the current data-catalog dataset/repo - its origin is at: abcd-j/data - it functions as the superdataset for all datasets rendered in the catalog, i.e. it is the homepage of the catalog

./docs - documentation sources - contains documentation for catalog users and contributors

./inputs - input files used during catalog creation, updates, and testing

Cohort Data Discovery

https://nb-query.trr379.de hosts the central NeuroBagel query interface of the TRR379. With this solution, data availability can be queried dynamically, to facilitate data access requests.

NeuroBagel supports federated queries and is therefore ideally suited for the decentralized research data management approach of TRR379.

Data Models

https://concepts.trr379.de hosts resources and documentation on the metadata models driving the research data management procedures of TRR379.

Documentation

https://docs.trr379.de (this site) is the main documentation source for the TRR379. It offers information on facilities and procedures.

It sources live on the collaboration platform at https://hub.trr379.de/q04/docs.trr379.de and are stored as a DataLad dataset. The documentation website is built with the Hugo static website generator. Content of the pages is written in Markdown.

For information on contributing to the docs, see:

• Contribute to the docs

Service Status Monitor

The website status.trr379.de provides a central monitor for TRR379 services. In case of an outage (or a suspected outage), this site can be used to look for already known issues, or to report new ones.

Service outages and recoveries are also available as push notifications. Contact trr379@lists.fz-juelich.de to get access. A notification is pushed when a service failure is detected for more than two consecutive tests (typically a 10min interval).

Participants

This page is a more in-depth description of the rationale behind the SOP for participant identifiers used by TRR379.

Q1 participant identifiers

Q01 is the central recruitment project. Any participant included in the core TRR379 dataset is registered with Q01 and receives an identifier. This identifier is unique within TRR379 and stable across the entire lifespan of TRR379.

The dataset acquired by TRR379 is longitudinal in nature. Therefore participants need to be reliably identified and re-identified for follow-up visits. Because participants are not expected to remember their TRR379 identifier, it is necessary to store personal data on a participant for the time of their participation in data acquisition activities.

In order to avoid needlessly wide-spread distribution of this personal data, participant registration and personal data retention is done only at the site where a person participates in TRR379 data acquisitions. Each site:

• issues TRR379-specific participant identifiers that are unique and valid throughout the runtime of TRR379
• uses secure systems for this purpose, for example, existing patient information systems
• is responsible for linking all relevant information that is required for reporting and data analysis within TRR379 to the issued Q01 identifier, so that all data can be identified and delivered upon request (e.g., link to brain imaging facility subject ID).

The site-issued identifiers have a unique, site-specific prefix (e.g., a letter like A for Aachen), such that each site can self-organize their own identifier namespace without having to synchronize with all other sites to avoid duplication.

The identifiers must not have any other information encoded in them.

Responsible use and anonymization of identifiers

The TRR379 participant identifiers, as described above, are pseudonymous. Using these TRR379-specific identifiers only, for any TRR379-specific communication and implementations, is advised for compliance with the GDPR principles of necessity and proportionality of personal data handling. This includes, for example, data analysis scripts that can be expected to become part of a more widely accessible documentation or publication.

Any TRR379 site that issues identifiers is responsible for strictly separating personal data used for (re-)identifying a participant, such as health insurance ID, government ID card numbers, or name and date of birth. This information is linked to TRR379-specific identifiers in a dedicated mapping table. Access to this table is limited to specifically authorized personnel.

When a participant withdraws, or when a study’s data acquisition is completed, the mapping of the TRR379 identifier to personal identifying information (1) is destroyed, by removing the associated record (row) from the mapping table. At this point, the TRR379 identifier itself can be considered anonymous. Consequently, occurrences of such identifiers in any published or otherwise shared records, or computer scripts need not be redacted.

The validity of the statement above critically depends on the identifier-issuing sites to maintain a strictly separate, confidential mapping of identifier to personal identifying information, and to not encode participant-specific information into the identifier itself.

Participant identifiers in A/B/C projects

For each project or study that is covered by its own ethics documentation and approval, separate and dedicated participant identifiers are used that are different from a Q01-identifier for a person. This is done to enable such projects to fulfill their individual requirements regarding responsible use of personal data. In particular, it enables any individual project to share and publish data without enabling trivial, undesired, and unauthorized cross-referencing of data on an individual person, acquired in different studies.

These project-specific identifiers are managed and issued in the same way as described above.

1. A project requests a project-specific identifier from the local site representative of Q01, by presenting personal identifying information.
2. This information is matched to any existing Q01-identifier, and a project-specific identifier is created and/or reported.
3. Any created project-specific identifier is linked to the Q01-identifier, using the same technical systems and procedures that also link other identifiers (e.g., patient information system record identifier).

Importantly, the mapping of the Q01-identifier and a project-specific identifier is typically not shared with the requesting project. This is done to prevent accidental and undesired co-occurrence of the two different identifiers in a way that enables unauthorized agents to reconstruct an identifier mapping that violates the boundaries of specific research ethics.

Special-purpose identifiers

Sometimes it is necessary to generate participant identifiers that are not compliant with the procedures and properties described above. For example, an external service provide may require particular information to be encoded in an identifier (e.g., sex, age, date of acquisition).

If this is the case, an additional identifier must be generated for that specific purpose. Its use must be limited in time and it must not be reused for other purposes.

Identifier generation and linkage to the standard Q01-participant identifiers is done using the procedure described for project-specific identifiers above.

Service Projects

• Q01
• Q02
• Q03
• Q04

CRC

A Collaborative Research Centre (CRC) is a DFG (Deutsche Forschungsgemeinschaft) funded long-term university-based research institution, established for up to 12 years, in which researchers work together within a multidisciplinary research programme. Collaborative Research Centres consist of a large number of projects; the number and scope of these projects depend on the research programme. Individual projects are led by one researcher or jointly by several researchers.

DFG

The German Research Foundation (Deutsche Forschungsgemeinschaft, DFG) is a German research funding organization.

OAuth 2.0

OAuth 2.0 is an open standard protocol for authorization that allows applications to access data on another service without directly handling passwords themselves.

RDM

Research data management (RDM) is the set of practices around handling research data throughout its lifecycle.

SOP

A standard operating procedure, mostly referred to as SOP, is a set of step-by-step instructions compiled to help carry out routine operations.

TRR

A Transregio (TRR) is a variant of a DFG (Deutsche Forschungsgemeinschaft) funded Collaborative Research Centre (CRC). Whereas traditional collaborative research centres are proposed and carried out by one university, a CRC is proposed and carried out jointly by two or three universities. It allows close cooperation between these institutions and the researchers based there, including the shared use of resources. The contributions of the partner applicants are essential to the joint research goal, complementary and synergistic.