Use the Read Subjects SDK Method (Tutorial)

Last updated 2026-05-14

At a Glance

This document explains how to use read_subjects()(Python) | readSubjects (R) to retrieve subject-level metadata you can filter or join with other analysis results.

You must specify either the subject ID or the query parameter. If you have questions or need help, contact Support.

When to Use This Method

Use read_subjects | readSubjects to retrieve detailed subject records associated with EMR data:

Get subject-level attributes for cohorts you’ve identified in Advanced Search using the EMR tab 
Pull rows for one or more subject_ids known to have associated EMR data. 
Export subject information as a table so you can join it with other EMR‑derived datasets or use it in downstream analysis.

SDK Method

The read_subjects() signature is shown in the box below, and the method parameters follow. Click the tabs to toggle from Python to R.

Signature

Python signature

read_subjects(
    subject_ids: str = None,
    query_dict: dict = None,
    to_df: bool = True,
)

R signature

readSubjects(
    subjectIds = NULL,
    query = NULL,
    toDF = TRUE, ...
)

Parameters

Python parameters

Parameter	Data type	Required or optional	Description
`subject_ids`	`str`	required	A list of subject `UUID` values to retrieve.
`query_dict`	`dict`	required	A dictionary object containing search parameters using Mongo query language.
`to_df`	`bool`	required	If `True`, returns a DataFrame. Default is `True`.

R parameters

Parameter	Data type	Required or optional	Description
`subjectIds`	`list`	required	A list of subject `UUID`s or a single `queryId`.
`query`	`list`	required	A list of query params to search on. The format is similar to that passed to `getFileDescriptors`, but the fields correspond to fields in the `Subject` materialized view.
`toDF`	`bool`	required	Boolean indicating whether the output should be reformatted to a `data.frame`. Default is `True`.

Get Help

If you get stuck during a read_subjects() | readSubjects call, refer to the steps of this tutorial (examples are in Python unless otherwise specified). To use the baked-in help in your IDE, try one of the following commands. Still not working? To file a ticket, click Collaboration Space. Doing so lets you share your insights with others. The read_subjects() | readSubjects signature is shown in the box below, and the method parameters follow. If you have questions, contact Support.

Python	R	Output
`help(hp.read_subjects)`	`help(readSubjects)`	Function signature, list of parameters, class, and a brief description of the method in a compact plain-text format
`hp.read_subjects?`	`?readSubjects`	Method signature, docstring (description), file location, and file type in more readable format
`hp.read_subjects??`	`hise::readSubjects`	Signature, docstring, file path, a verbose set of metadata, and the source code for the method

Import libraries

To get started, set up your environment to interact with HISE programmatically and access all available SDK functions. For details, see Use HISE SDK Methods and Get Help in the IDE .

Navigate to HISE, and use your organizational email address to sign in .
Open an IDE. For instructions, see Create Your First HISE IDE (Tutorial) .

To import hisepy, enter the following code into a new cell in your IDE:

# Import the Python SDK to enable programmatic access to HISE functions
import hisepy as hp

# For downstream analysis (optional)
import pandas as pd

Get subject IDs from Advanced Search

Use Advanced Search to identify which subjects to read before you call read_subjects().

In HISE, go to Research > Advanced Search, and select the EMR tab.
Apply filters to find the subjects you’re interested in (for example, by cohort or visit characteristics), and copy the subject_ids for those subjects.

Paste those IDs into your IDE and pass them as the subject_ids argument when you call hp.read_subjects().

# Copy subject_ids from the EMR tab in Advanced Search
subject_ids = [ "e2753c71-076a-49ec-b2c2-5e48a7b54aec", 
"866427ab-b60d-4426-8b08-6c31e6b6e854" ]

Define a query dictionary

If you prefer, you can define a query dictionary instead of passing subject IDs:
```
# Query subjects by cohort
query_dict = {"cohortGuid": ["FH1"]}
```

Call read_subjects()

You must provide either a list of subject IDs or a query dictionary, but not both.

1. Call read_subjects with subject_ids:

subjects_df = hp.read_subjects(
    subject_ids=subject_ids,
    query_dict=None,
    to_df=True,
)

2. Or call read_subjects with a query_dict:

subjects_df = hp.read-subjects(
    subject_ids=None,
    query_dict=query,
    to_df=True,
)

NOTE

If to_df is False, read_subjects() returns a JSON payload instead of a DataFrame.

Work with the results

After you retrieve the subject metadata, you can inspect and filter it like any other Pandas DataFrame.

# Preview columns and a few rows
subjects_df.head()

# Example: Filter by cohort
fh1_subjects = 
subjects_df[subjects_df["cohortGuid"] == 
"FH1"]

Related Resources

Use Fast Mode (Tutorial)

Work with Studies (Tutorial)

Best Practices for IDE Users

Attach an IDE to a Study (Tutorial)

Use HISE SDK Methods and Get Help