Commandline Usage

PACSIFIER is a commandline tool that can be run in a variety of ways, providing a set of command-line interface (CLI) commands, which can be run directly in a shell or via a Docker container, for interacting with a PACS server and manipulating DICOM files.

It consists of the following commands:

pacsifier: The main command, which can be used to interact with a PACS server and manipulate DICOM files.
pacsifier-anonymize: Anonymize DICOM files.
pacsifier-create-dicomdir: Create a DICOMDIR file.
pacsifier-get-pseudonyms: Get pseudonyms for a list of DICOM files.
pacsifier-move-csv: Move CSV info dumps to a separate folder.
pacsifier-add-karnak-tags: Add Karnak tags to DICOM files.
pacsifier-extract-carestream-report: Extract Carestream reports from DICOM files.

In the following sections, we will describe the configuration files, how to run these commands in a shell, and how to run them in a Docker container.

Configuration File

PACSIFIER requires a JSON configuration file that specifies the PACS server connection parameters. The file must contain exactly these keys:

{
    "server_address": "PACS server IP or hostname",
    "port": 104,
    "server_AET": "SERVER_AET",
    "AET": "YOUR_AET",
    "move_AET": "MOVE_DESTINATION_AET",
    "move_port": 11112,
    "batch_size": 30,
    "batch_wait_time": 10
}

Configuration keys
Key	Type	Description
`server_address`	string	PACS server IP address or hostname
`port`	integer	PACS server port number for incoming requests
`server_AET`	string	PACS server Application Entity Title (max 16 characters)
`AET`	string	Your local station Application Entity Title (max 16 characters)
`move_AET`	string	AET of the remote move destination
`move_port`	integer	Port on the move destination to receive images (C-MOVE)
`batch_size`	integer	Number of series to download before pausing
`batch_wait_time`	number	Sleep time (in seconds) after each batch

Note

The AET and corresponding IP of the workstation should be declared on the PACS server, including the storeable attribute.

Tip

Migrating from PACSMAN? Update the following key names and types:

server_ip → server_address
port: string → integer
move_port: string → integer
batch_size: string → integer
batch_wait_time: string → integer

Query File

The query file is a .csv file that specifies which DICOM data to query from the PACS server. It can include one or many of the following columns:

Supported query columns
Column Name	Description
`StudyDate`	Study date in `YYYYMMDD` format. Date ranges are supported (e.g., `20150201-20160201`).
`StudyTime`	Study time in `HHMMSS` format (e.g., `140500` for 14:05:00).
`PatientID`	The patient ID.
`PatientName`	The patient name. Not recommended as there is no clear standard for how names are stored.
`PatientBirthDate`	Patient birth date in `YYYYMMDD` format. Date ranges are not supported.
`SeriesDescription`	The series description.
`ProtocolName`	The protocol name.
`StudyInstanceUID`	The Study Instance UID.
`SeriesInstanceUID`	The Series Instance UID.
`Modality`	The modality (e.g., `CT`, `MR`).
`AcquisitionDate`	The acquisition date.
`DeviceSerialNumber`	The device serial number.
`SeriesNumber`	The series number.
`StudyDescription`	The study description.
`AccessionNumber`	The accession number.
`SequenceName`	The sequence name.
`ImageType`	The image type. Note: Using this filter significantly slows down queries. Use only if absolutely necessary.

The query file can be built in Excel and exported to .csv format.

Important notes:

If a cell in a row is empty, that attribute is omitted from the query for that row.
The wildcard * alone is not accepted. However, it can be used with other characters (e.g., BEAT_SelfNav*).
Series folders are named after their Series Description. If a DICOM image has no Series Description, it is stored in a folder called No_series_description.

Query File Examples

Example 1 — Query by date and patient ID:

StudyDate,PatientID
20150512,123421
,45322
20180102,

This retrieves: images for patient 123421 from 12/05/2015, all images for patient 45322, and all images from 02/01/2018.

Example 2 — Date range with patient ID:

StudyDate,PatientID
20150512-20150612,124588

Retrieves images for patient 124588 with study dates between 12/05/2015 and 12/06/2015.

Example 3 — Wildcard protocol name:

ProtocolName,Modality,PatientBirthDate
BEAT_SelfNav*,CT,19920611

Retrieves all CT images with protocol names starting with BEAT_SelfNav for patients born on 11/06/1992.

Running `PACSIFIER` commands in a shell

`pacsifier` command

Query, move and retrieve DICOM images from a PACS server.

usage: pacsifier [-h] --config CONFIG [--save] [--info] [--move]
                 [--queryfile QUERYFILE] [--out_directory OUT_DIRECTORY]
                 [--upload] [--upload_directory UPLOAD_DIRECTORY] [--version]
                 [--resume] [--verbose]

Named Arguments

--config, -c

Configuration file path

--save, -s

Store images resulting from query (cannot be used together with ‘–move’)

Default: False

--info, -i

Store parsed version of findscu output (DICOM header subset)

Default: False

--move, -m

Move images resulting from query (cannot be used together with ‘–save’)

Default: False

--queryfile, -q

Path to query file (mandatory if ‘–save’ or ‘–move’ is used)

--out_directory, -d

Output directory where images will be saved (used only with ‘–save’ or ‘–move’ options)

Default: “./data”

--upload, -u

Upload DICOM images to PACS server

Default: False

--upload_directory, -ud

Directory containing the DICOM images to upload (only used with ‘–upload’ option)

Default: “./data”

--version

show program’s version number and exit

--resume

Resume extraction by skipping already downloaded series

Default: False

--verbose, -v

Print verbose progress information during retrieval

Default: False

`pacsifier-anonymize` command

usage: pacsifier-anonymize [-h] --in_folder IN_FOLDER --out_folder OUT_FOLDER
                           [--delete_identifiable] [--remove_private_tags]
                           [--fuzz_acq_dates] [--new_ids NEW_IDS]
                           [--keep_patient_dir_names]

Named Arguments

--in_folder, -d

Directory to the dicom files to be anonymized

Default: “./data”

--out_folder, -o

Output directory where the anonymized dicoms will be saved

Default: “./data”

--delete_identifiable, -i

Delete identifiable files like Dose reports

Default: False

--remove_private_tags, -p

Remove private tags

Default: False

--fuzz_acq_dates, -a

Fuzz acquisition dates

Default: False

--new_ids, -n

List of new ids.

--keep_patient_dir_names, -k

Do not rename patient directories, keep original IDs

Default: False

`pacsifier-create-dicomdir` command

Create a DICOMDIR of all dicoms within a folder.

usage: pacsifier-create-dicomdir [-h] [--in_folder IN_FOLDER]
                                 [--out_folder OUT_FOLDER]

Named Arguments

--in_folder, -d

Directory to the dicom files

Default: “./data”

--out_folder, -o

Output directory where the dicoms and DICOMDIR will be saved

Default: “./data”

`pacsifier-get-pseudonyms` command

Create new pseudonyms for a list of PatientIDs.

usage: pacsifier-get-pseudonyms [-h] [--mode {de-id,custom}] [--config CONFIG]
                                [--queryfile QUERYFILE]
                                [--mappingfile MAPPINGFILE] [--shift-days]
                                --project_name PROJECT_NAME --out_directory
                                OUT_DIRECTORY [--verbose]

Named Arguments

--mode, -m

Possible choices: de-id, custom

Mode of operation: use de-ID API to get new pseudonyms and day shifts (“de-id”) or use a custom mapping file in CSV format that specifies the new pseudonyms (“custom”)

Default: “de-id”

--config, -c

Deidentification configuration file path (required for –mode de-id)

--queryfile, -q

Path to PACSIFIER query file (used to find PatientIDs, required for –mode de-id)

--mappingfile, -mf

Path to custom mapping file in CSV format (required for –mode custom). The file is expected to have no header and two columns: the first column is the old pseudonym, the second column is the new pseudonym. The file should not contain any empty cells.

--shift-days

Generate random day shifts for all pseudonyms in the +- 30 days range (employed for –mode custom). If not specified, day shifts are set to 0.

Default: False

--project_name, -a

Name of the project in GPCR (may or may not correspond to Kheops album)

--out_directory, -d

Output directory where the pseudonyms will be saved as a json

--verbose, -v

Print verbose output

Default: False

`pacsifier-move-csv` command

Move all csv files within a dicom folder into a new folder.

usage: pacsifier-move-csv [-h] [--data_folder DATA_FOLDER]
                          [--info_folder INFO_FOLDER]

Named Arguments

--data_folder, -d: Path to the dicom folder
--info_folder, -o: Path to the folder where all csv files will be moved

`pacsifier-add-karnak-tags` command

Add private DICOM tags to several studies so that Karnak can de-identify them using provided patient codes and route them to the appropriate Kheops album.

usage: pacsifier-add-karnak-tags [-h] --in_folder IN_FOLDER --new_ids NEW_IDS
                                 [--day_shift DAY_SHIFT] --album_name
                                 ALBUM_NAME

Named Arguments

--in_folder, -d

Directory to the dicom files

Default: “./data”

--new_ids, -n

List of new patient IDentifiers

--day_shift, -s

List of day shift per patient

--album_name, -a

Name of destination Kheops album to route the tagged study

`pacsifier-extract-carestream-report` command

Extract plain text from Carestream radiology reports in SR.

usage: pacsifier-extract-carestream-report [-h] --data_folder DATA_FOLDER

Named Arguments

--data_folder, -d: Path to the folder containing the reports

Running `PACSIFIER` commands in Docker

The Docker image entrypoint runs the provided command in the pacsifier_minimal conda environment. You can use the Docker wrapper scripts (recommended) or call the CLI commands directly.

Recommended (wrapper scripts)

docker_pacsifier -c config.json -q query.csv -d /output --save

See Docker Wrappers for the full list of wrapper scripts and examples.

Direct Docker invocation

docker run --rm --net=host -v /path/to/my_dir:/base \
        quay.io/translationalml/pacsifier:latest \
        pacsifier --save --info --queryfile /base/my_query.csv \
        --config /base/my_config.json --out_directory /base/my_output_dir

Commandline Usage

Configuration File

Query File

Query File Examples

Running PACSIFIER commands in a shell

pacsifier command

Named Arguments

pacsifier-anonymize command

Named Arguments

pacsifier-create-dicomdir command

Named Arguments

pacsifier-get-pseudonyms command

Named Arguments

pacsifier-move-csv command

Named Arguments

pacsifier-add-karnak-tags command

Named Arguments

pacsifier-extract-carestream-report command

Named Arguments

Running PACSIFIER commands in Docker

Recommended (wrapper scripts)

Direct Docker invocation

Running `PACSIFIER` commands in a shell

`pacsifier` command

`pacsifier-anonymize` command

`pacsifier-create-dicomdir` command

`pacsifier-get-pseudonyms` command

`pacsifier-move-csv` command

`pacsifier-add-karnak-tags` command

`pacsifier-extract-carestream-report` command

Running `PACSIFIER` commands in Docker