Welcome to OpenREM’s documentation!

OpenREM logo

OpenREM is an opensource framework created for the purpose of radiation exposure monitoring. The software is capable of importing and displaying data from a wide variety of x-ray dose related sources, and then enables easy export of the data in a form that is suitable for further analysis by suitably qualified medical physics personnel.

Please see openrem.org for more details.

Contents:

Installation instructions

Basic guide

Non-operating system specific path names are represented using the linux convention of a / separator. If you are installing in a Windows environment you will need to use the Windows \ separator.

Installation prerequisites

Install python 2.7

Install setuptools and pip

Note

Before continuing, consider virtualenv

Install OpenREM

  • pip install openrem (Needs internet connection)

Configure OpenREM

Locate install location

  • Linux: /usr/lib/python2.7/dist-packages/openrem/ or /usr/lib/python2.7/site-packages/openrem/
  • Windows: C:\Python27\Lib\site-packages\openrem\

There are two files that need renaming: (changed for 0.4.0)

  • openrem/local_settings.py.example to openrem/local_settings.py
  • openrem/wsgi.py.example to openrem/wsgi.py

In the local_settings.py file, set the database details.

For testing you can use the SQLite3 database:

'ENGINE': 'django.db.backends.sqlite3',
'NAME': '/ENTER/PATH/WHERE/DB/FILE/CAN/GO',
  • Linux example: 'NAME': '/var/openrem/openrem.db',
  • Windows example: 'NAME': 'C:\Documents\User\OpenREM\openrem.db',

For production use, see Database options below

Generate a new secret key and replace the one in the local_settings.py file. You can use http://www.miniwebtool.com/django-secret-key-generator/ for this.

Create the database

  • Linux: python /usr/lib/python2.7/dist-packages/openrem/manage.py syncdb
  • Windows: python C:\Python27\Lib\site-packages\openrem\manage.py syncdb

Answer each question as it is asked, do setup a superuser. This username and password wil be used to log into the admin interface to create the usernames for using the web interface. See the Start using it! section below.

Help! I get a value too long for type character varying(50) error!
This error with part of the Django auth_permissions system that we are not using, and can safely be ignored. This is being tracked as Issue 62

For production installs, convert to South (What is south?)

  • Linux: python /usr/lib/python2.7/dist-packages/openrem/manage.py convert_to_south remapp
  • Windows: python C:\Python27\Lib\site-packages\openrem\manage.py convert_to_south remapp

Start test web server

  • Linux: python /usr/lib/python2.7/dist-packages/openrem/manage.py runserver
  • Windows: python C:\Python27\Lib\site-packages\openrem\manage.py runserver

If you are using a headless server and need to be able to see the web interface from another machine, use python /usr/lib/python2.7/dist-packages/openrem/manage.py runserver x.x.x.x:8000 (or Windows equivalent) replacing the x with the IP address of the server and 8000 with the port you wish to use.

Open the web addesss given, appending /openrem (http://localhost:8000/openrem)

Start using it!

Add some data! (See the Importing data to OpenREM for adding the scripts to the path if this doesn’t work)

  • openrem_rdsr.py rdsrfile.dcm

Add some users (New in version 0.4.0)

  • Go to the admin interface (eg http://localhost:8000/admin) and log in with the user created when you created the database (syncdb)

  • Create some users and add them to the appropriate groups (if there are no groups, go to the OpenREM homepage and they should be created).

    • viewgroup can browse the data only
    • exportgroup can do as view group plus export data to a spreadsheet, and will be able to import height and weight data in due course (See Issue #21)
    • admingroup can delete studies in addition to anything the export group can do

Further instructions

Database options

SQLite is great for getting things running quickly and testing if the setup works, but is really not recommended for production use on any scale. Therefore it is recommended to use a different database such as PostgreSQL or MySQL.

Here are instructions for installing PostgreSQL on linux and on Windows:

Installing PostgreSQL for OpenREM on Ubuntu linux
Install PostgreSQL and the python connector
  • sudo apt-get install postgresql
  • sudo apt-get build-dep python-psycopg2

The second command installed a lot of things, at least some of which are necessary for this to work!

If you are using a virtualenv, make sure you are in it and it is active (source bin/activate)

  • pip install psycopg2
Create a user for the database
  • sudo passwd postgres
  • Enter password, twice
  • sudo -u postgres createuser -P openrem_user
  • Enter password, twice
  • Superuser, No
  • Create databases, No
  • Create new roles, No
Optional: Specify the location for the database

You might like to do this if you want to put the database on an encrypted location

For this example, I’m going to assume all the OpenREM programs and data are in the folder /var/openrem/:

  • sudo /etc/init.d/postgresql stop
  • mkdir /var/openrem/database
  • sudo cp -aRv /var/lib/postgresql/9.1/main /var/openrem/database/
  • sudo nano /etc/postgresql/9.1/main/postgresql.conf
Change the line
  • data_directory = '/var/lib/postgresql/9.1/main' to
  • data_directory = '/var/openrem/database/main'
  • sudo /etc/init.d/postgresql start
Create the database
  • su postgres
  • psql template1
  • CREATE DATABASE openrem_db OWNER openrem_user ENCODING 'UTF8';
  • \q
  • exit
Change the security configuration

The default security settings are too restrictive to allow access to the database.

  • sudo nano /etc/postgresql/9.1/main/pg_hba.conf

  • Add the following line:
    • local openrem_db openrem_user md5
  • sudo /etc/init.d/postgresql restart

Configure OpenREM to use the database
Find and edit the settings file, eg
  • nano local/lib/python2.7/site-packages/openrem/openrem/settings.py
Set the following (changing name, user and password as appropriate):
  • 'ENGINE': 'django.db.backends.postgresql_psycopg2',
  • 'NAME': 'openrem_db',
  • 'USER': 'openremuser',
  • 'PASSWORD': 'openrem_pw',
Fire it up with OpenREM
  • python path/to/openrem/manage.py syncdb
  • python path/to/openrem/manage.py convert_to_south remapp
Installing PostgreSQL for OpenREM on Windows

Note

Author JA Cole

Get PostgreSQL and the python connector
Install PostgreSQL

Run the the postgresql installer. It will ask for a location. Ensure the “data” directory is not under “Program Files” as this can cause permissions errors. Enter a superuser password when prompted. Make sure you keep this safe as you will need it.

Create a user and database

Open pgAdmin III

  • Click on servers to expand
  • Double click on PostgreSQL 9.3
  • Enter your superuser password
  • Right click on “login roles” and choose “New login role”
  • Create the openremuser (or whatever you want your user to be called) and under definition add a password.
  • Click OK
  • Right click on databases and choose “New database”
  • Name the database (openremdb is fine) and assign the the owner to the user you just created.
Install psycopg2

Run the installer you downloaded for psycopg2 earlier.

Configure OpenREM to use the database
Find and edit the settings file (notepad works fine). The path depends on your python install, but could be something like:
  • C:\lib\python2.7\site-packages\openrem\openrem\settings.py
Set the following (changing name, user and password as appropriate):
  • 'ENGINE': 'django.db.backends.postgresql_psycopg2',
  • 'NAME': 'openrem_db',
  • 'USER': 'openremuser',
  • 'PASSWORD': 'openrem_pw',
Fire it up with OpenREM
  • python path/to/openrem/manage.py syncdb
  • python path/to/openrem/manage.py convert_to_south remapp
Fix ‘’ value too long for type character varying(50)’’ error

This error is caused by the django auth_permissions system not being able to cope with long names in the models.

  • Open pgAdmin III
  • Open Servers
  • Open databases
  • Open the openrem database
  • Open schemas
  • Open public
  • Open tables
  • right click on auth_permission
  • Select properties
  • Change ‘’name’’ to ‘’varying(100)’’ from ‘’varying(50)’‘

Then run python path/to/openrem/manage.py syncdb again.

Database migrations

South is a django application to manage database migrations. Using South means that future changes to the database model can be calculated and executed automatically with simple commands when OpenREM is upgraded.

Production webservers

Unlike the database, the production webserver can be left till later and can be changed again at any time.

For performance it is recommended that a production webserver is used instead of the inbuilt ‘runserver’. Popular choices would be either Apache or you can do as the cool kids do and use Gunicorn with nginx.

The django website has instructions and links to get you set up with Apache.

Virtualenv and virtualenvwrapper

If the server is to be used for more than one python application, or you wish to be able to test different versions of OpenREM or do any development, it is highly recommended that you use virtualenv or maybe virtualenvwrapper

Virtualenv sets up an isolated python environment and is relatively easy to use.

If you do use virtualenv, all the paths referred to in the documentation will be changed to:

  • Linux: lib/python2.7/site-packages/openrem/
  • Windows: Lib\site-packages\openrem

OpenREM Release Notes

Version history change log

OpenREM version history

0.4.2
  • #83 Fix for #73 introduced bug that prevents the import scripts from working. Fixed.
0.4.1
  • #82 Added instructions for adding users to the release notes
0.4.0

Note

  • #80 Added docs for installing Apache with auto-start on Windows Server 2012. Contributed by JA Cole
  • #79 Updated README.rst instructions
  • #78 Moved upgrade documentation into the release notes page
  • #77 Removed docs builds from repository
  • #76 Fixed crash if exporting from development environment
  • #75 Fixed bug where requested procedure wasn’t being captured on one modality
  • #73 Made launch scripts and ptsizecsv2db more robust
  • #72 Moved the secret key into the local documentation and added instructions to change it to release notes and install instructions
  • #71 Added information about configuring users to the install documentation
  • #69 Added documentation about the new delete study function
  • #68 Now checks sequence code meaning and value exists before assigning them. Thanks to JA Cole
  • #67 Added ‘Contributing authors’ section of documentation
  • #66 Added ‘Release notes’ section of documentation, incuding this file
  • #65 Added new local_settings.py file for database settings and other local settings
  • #64 Fixed imports failing due to non-conforming strings that were too long
  • #63 The mammography import code stored the date of birth unnecessarily. Also now gets decimal_age from age field if necessary
  • #60 Removed extraneous colon from interface data field
  • #18 Studies can now be deleted from the web interface with the correct login
  • #16 Added user authentication with different levels of access
  • #9 Enable import of *.dcm
0.3.9

Note

#51 includes changes to the database schema – make sure South is in use before upgrading. See http://docs.openrem.org/page/upgrade.html

  • #59 CSS stylesheet referenced particular fonts that are not in the distribution – references removed
  • #58 Export to xlsx more robust - limitation of 31 characters for sheet names now enforced
  • #57 Modified the docs slightly to include notice to convert to South before upgrading
  • #56 Corrected the mammography target and filter options added for issue #44
  • #53 Dates can now be selected from a date picker widget for filtering studies
  • #52 Split the date field into two so either, both or neither can be specified
  • #51 Remove import modifications from issue #28 and #43 now that exports are filtered in a better way after #48 and #49 changes.
  • #50 No longer necessary to apply a filter before exporting – docs changed to reflect this
  • #49 CSV exports changed to use the same filtering routine introduced for #48 to better handle missing attributes
  • #48 New feature – can now filter by patient age. Improved export to xlsx to better handle missing attributes
  • #47 Install was failing on pydicom – fixed upstream
0.3.8
  • – File layout modified to conform to norms
  • #46 Updated documentation to reflect limited testing of mammo import on additional modalities
  • #45 mam.py was missing the licence header - fixed
  • #44 Added Tungsten, Silver and Aluminum to mammo target/filter strings to match – thanks to DJ Platten for strings
  • #43 Mammography and Philips CT import and export now more robust for images with missing information such as accession number and collimated field size
  • #42 Documentation updated to reflect #37
  • #37 Studies now sort by time and date
0.3.7
  • #40 Restyled the filter section in the web interface and added a title to that section
  • #38 Column titles tidied up in Excel exports
  • #36 openrem_ptsizecsv output of log now depends on verbose flag
  • #35 Numbers no longer stored as text in Excel exports
0.3.6
  • #34 Localised scripts that were on remote web servers in default Bootstrap code
  • #33 Documentation now exists for adding data via csv file
  • #24 Web interface has been upgraded to Bootstrap v3
  • #5 Web interface and export function now have some documentation with screenshots
0.3.5-rc2
  • #32 Missing sys import bug prevented new patient size import from working
0.3.5
  • – Prettified this document!
  • #31 Promoted patient size import from csv function to the scripts folder so it will install and can be called from the path
  • #30 Improved patient size import from csv to allow for arbitary column titles and study instance UID in addition to accession number.
  • #29 Corrected the docs URL in the readme
0.3.4-rc2
  • #28 XLSX export crashed if any of the filter fields were missing. Now fills on import with ‘None’
  • #27 Use requested procedure description if requested procedure code description is missing
0.3.4
  • – General improvements and addition of logo to docs
  • #23 Added Windows XP MySQL backup guide to docs
  • #22 Added running Conquest as a Windows XP service to docs
  • #15 Added version number and copyright information to xlsx exports
  • #14 Added version number to the web interface
  • #13 Improve the docs with respect to South database migrations
0.3.3-r2
0.3.3

Note

Installs of OpenREM earlier than 0.3.3 will break on upgrade if the scripts are called from other programs. For example openrem_rdsr is now called openrem_rdsr.py

  • – Added warning of upgrade breaking existing installs to docs
  • #10 Added .py suffix to the scripts to allow them to be executed on Windows (thanks to DJ Platten)
  • #8 Removed superfluous ‘/’ in base html file, harmless on linux, prevented Windows loading stylesheets (thanks to DJ Platten)
  • #7 Added windows and linux path examples for test SQLite database creation
  • #6 Corrected renaming of example files installation instruction (thanks to DJ Platten)
  • #4 Added some text to the documentation relating to importing files to OpenREM
  • #3 Corrected copyright notice in documentation
0.3.2
  • Initial version uploaded to bitbucket.org

Release notes and upgrade instructions

Version specific information

OpenREM Release Notes version 0.4.2
Headline changes
  • This release fixes a major bug introduced in 0.4.0 regarding the import scripts.
Specific upgrade instructions
Upgrading from 0.4.1 or 0.4.0

Follow the Generic upgrade instructions

Upgrading from 0.3.9 or earlier

Follow the instructions in OpenREM Release Notes version 0.4.0

OpenREM Release Notes version 0.4.1
Headline changes
  • This release is exacly the same as 0.4.1 bar some documentation corrections
Specific upgrade instructions

Please use the 0.4.0 release notes for upgrades from 0.3.9

OpenREM Release Notes version 0.4.0

OpenREM Release Notes version 0.4.0
Headline changes
  • User authentication has been added
  • Studies can be deleted from the web interface
  • Import scripts can now be passed a list of files, eg python openrem_rdsr.py *.dcm
  • Date of birth no longer retained for mammography (bug fix - correct behaviour already existed for other imports)
  • General bug fixes to enable import from wider range of sources
  • Improved user documentation
Specific upgrade instructions
  • pip install openrem -U Note - this will upgrade openrem and all its dependencies.

  • Migrate the database

    Warning

    A database migration is required that will need a choice to be made

    • Linux: python /usr/lib/python2.7/dist-packages/openrem/manage.py schemamigration --auto remapp
    • Windows: C:\Python27\Lib\site-packages\openrem\manage.py schemamigration --auto remapp

    When South has considered the changes to the schema, you will see the following message:

    ? The field 'Observer_context.device_observer_name' does not have a default specified, yet is NOT NULL.
    ? Since you are making this field nullable, you MUST specify a default
    ? value to use for existing rows. Would you like to:
    ?  1. Quit now.
    ?  2. Specify a one-off value to use for existing columns now
    ?  3. Disable the backwards migration by raising an exception; you can edit the migration to fix it later
    ? Please select a choice: 3
    

    As per the final line above, the correct choice is 3. The fields that are now nullable previously weren’t. Existing data in those fields will have a value, or those tables don’t exist in the current database. The problem scenario is if after the migration these tables are used and one of the new nullable fields is left as null, you will not be able to migrate back to the old database schema without error. This is not something that you will want to do, so this is ok.

    Do the migration:

    • Linux: python /usr/lib/python2.7/dist-packages/openrem/manage.py migrate remapp
    • Windows: C:\Python27\Lib\site-packages\openrem\manage.py migrate remapp
  • Update the settings files

    Warning

    The settings file has changed and will need to be manually edited.

    Changes need to be made to the settings.py file where the database details are stored. Normally upgrades don’t touch this file and the copy in the upgrade has a .example suffix. This upgrade and potentially future ones will need to change this file, so the format has been changed. The settings.py file will now be replaced each time the code is upgraded. In addition, there is a new local_settings.py file that contains things that are specific to your installation, such as the database settings.

    This upgrade will include a file called settings.py.new and the local_settings.py.example file. You will need to do the following:

    • Copy the database settings from your current settings.py file to the local_settings.py.example file and rename it to remove the .example. Both of these files are in the openrem/openrem directory, which will be somewhere like
      • Linux: /usr/lib/python2.7/dist-packages/openrem/openrem/
      • Windows: C:\Python27\Lib\site-packages\openrem\openrem\
    • Move the existing settings.py out of the python directories
    • Rename the settings.py.new to settings.py
  • Create a new secret key

    All versions of openrem ship with the same secret key. This key is used for web security checks, and should be unique (and secret) for each installation.

  • Restart your webserver

  • Add some users

    • Go to the admin interface (eg http://localhost:8000/admin) and log in with the user created when you originally created the database (manage.py syncdb)

    • Create some users and add them to the appropriate groups (if there are no groups, go to the OpenREM homepage and they should be created).

      • viewgroup can browse the data only
      • exportgroup can do as view group plus export data to a spreadsheet, and will be able to import height and weight data in due course (See Issue #21)
      • admingroup can delete studies in addition to anything the export group can do

Generic upgrade instructions

  • Make sure you have setup South before you upgrade – see Database migrations for details.
  • Always consult the specific version release notes linked above before upgrading.
Code upgrade

pip install openrem -U

Note - this will upgrade OpenREM and all the programs it depends on (e.g. Django)

Database migration

Always do a database migration using South after an upgrade in case any of the database models have changed. This will normally not be the case.

  • Linux: python /usr/lib/python2.7/dist-packages/openrem/manage.py schemamigration --auto remapp
  • Windows: C:\Python27\Lib\site-packages\openrem\manage.py schemamigration --auto remapp

If response to the last command is ‘Nothing seems to have changed’, no migration is required. Else, follow the instructions to migrate:

  • Linux: python /usr/lib/python2.7/dist-packages/openrem/manage.py migrate remapp
  • Windows: C:\Python27\Lib\site-packages\openrem\manage.py migrate remapp
Restart the web server

Restart the web server to enable any changes that have been made to the web interface.

Contributing authors

The following people have contributed to OpenREM - either with code, documentation or ideas.

Importing data to OpenREM

Using the OpenREM interface and export function

Filtering for specific studies

This image shows the CT studies view, available to any logged in user, filtered by entering terms in the boxes on the right hand side to show just the studies where the modality model name includes the term ‘soma’:

Filtering CT studies

The search fields can all be used on their own or together, and they are all case insensitive ‘contains’ searches. The exception is the date field, where both from and to have to be filled in (if either are), and the format must be yyyy-mm-dd. There currently isn’t any more complex filtering available, but it does exist as issue 17 for a future release.

The last box below the filtering search boxes is the ordering preference.

Viewing study details

By clicking on the study description link (in blue), you can see more details for an individual study:

Individual CT study

Not all the details stored for any one study are displayed, just those thought to be most useful. If there are others you’d like to see, add an issue to the tracker.

The final field in the summary at the top is called ‘Test patient indicators?’ When studies are imported the ID and patient name fields are both ignored, but they are parsed to check if they have ‘phy’, ‘test’ or ‘qa’ in them to help exclude them from the data analysis. If they do, then this information is added to the field and is displayed both in the web interface as a Test patient indicator and in the Excel export. The name and ID themselves are not reproduced, simply the presence of one of the key words. Therefore a patient named ‘Phyliss’ would trigger this, but only ‘Phy’ would be reproduced in this field. Other fields will also help to confirm whether a study is for a real patient such as the lack of an Accession Number and an unusual patient age.

Exporting to csv and xlsx sheets

From any of the modality pages in the OpenREM interface, you can export the displayed studies to a csv spreadsheet by clicking on the link near the top. In the CT interface, you can also export to an enhanced XLSX spreadsheet.

New in 0.4.0: These links only appear if you are logged in as a user in the exportgroup or the admingroup.

For CT, the XLSX export has multiple sheets. The first sheet contains a summary of all the study descriptions, requested procedures and series protocol names contained in the export:

CT export front sheet

This information is useful for seeing what data is in the spreadsheet, and can also be used to prioritise which studies or protocols to analyse based on frequency.

The second sheet of the exported file lists all the studies, with each study taking one line and each series in the study displayed in the columns to the right.

CT export all data sheet

The remainder of the file has one sheet per series protocol name. Each series is listed one per line. If a single study has more than one series with the same protocol name, then the same study will appear on more than one line.

Deleting studies

New in 0.4.0

If you log in as a user that is in the admingroup, then an extra column is appended in the filtered view tables to allow studies to be deleted:

Deleting studies

Clicking on delete takes you to a confirmation page before the delete takes place.

Documentation for the OpenREM code

Contents:

DICOM import modules

RDSR module

Ultimately this should be the only module required as it deals with all Radiation Dose Structured Reports. Currently this has only been tested on CT and fluoroscopy structured reports, but it also has the logic for mammography structured reports if they start to appear.

remapp.extractors.rdsr.rdsr(rdsr_file)

Extract radiation dose related data from DICOM Radiation SR objects.

Parameters:filename (str.) – relative or absolute path to Radiation Dose Structured Report.
Tested with:
  • CT: Siemens, Philips and GE RDSR, GE Enhanced SR.
  • Fluoro: Siemens Artis Zee RDSR

Mammography module

Mammography is interesting in that all the information required for dose audit is contained in the image header, including patient ‘size’, ie thickness. However the disadvantage over an RSDR is the requirement to process each individual image rather than a single report for the study, which would also capture any rejected images.

remapp.extractors.mam.mam(mg_file)

Extract radiation dose structured report related data from mammography images

Parameters:filename (str.) – relative or absolute path to mammography DICOM image file.
Tested with:
  • GE Senographe DS software versions ADS_43.10.1 and ADS_53.10.10 only.
  • Limited testing: GE Senographe Essential
  • Limited testing: Hologic Selenia
  • Limited testing: Siemens Inspiration

CT non-standard modules

Initially only Philips CT dose report images are catered for. These have all the information that could be derived from the images also held in the DICOM header information, making harvesting relatively easy.

remapp.extractors.ct_philips.ct_philips(philips_file)

Extract radiation dose structured report related data from Philips CT dose report images

Parameters:filename (str.) – relative or absolute path to Philips CT dose report DICOM image file.
Tested with:
  • Philips Gemini TF PET-CT v2.3.0
  • Brilliance BigBore v3.5.4.17001.

Non-DICOM import modules

Patient height and weight csv import module

This module enables a csv file to be parsed and the height and weight information extracted and added to existing studies in the OpenREM database. An example may be a csv extract from a RIS or EPR system.

There needs to be a common unique identifier for the exam - currently this is limited to accession number or study instance UID.

remapp.extractors.ptsizecsv2db.csv2db(*args, **kwargs)

Import patient height and weight data from csv RIS exports. Can be called from openrem_ptsizecsv.py script

Parameters:
  • –si-uid (bool) – Use Study Instance UID instead of Accession Number. Short form -s.
  • csvfile (str) – relative or absolute path to csv file
  • id (str) – Accession number column header or header if -u or –si-uid is set. Quote if necessary.
  • height (str) – Patient height column header. Create if necessary, quote if necessary.
  • weight (str) – Patient weight column header. Create if necessary, quote if necessary.

Example:

openrem_ptsizecsv.py -s MyRISExport.csv StudyInstanceUID HEIGHT weight

Export from database

Multi-sheet Microsoft Excel XLSX exports

This export has a summary sheet of all the requested and performed protocols and the series protocols. The next sheet has all studies on, one study per line, with the series stretching off to the right. The remaining sheets are specific to each series protocol, in alphabetical order, with one series per line. If one study has three series with the same protocol name, each one has a line of its own.

remapp.exports.xlsx.ctxlsx(request)

Export filtered CT database data to multi-sheet Microsoft XSLX files.

Parameters:request (HTTP get) – Query parameters from the CT filtered page URL.

Single sheet CSV exports

remapp.exports.exportcsv.exportFL2excel(request)

Export filtered fluoro database data to a single-sheet CSV file.

Parameters:request (HTTP get) – Query parameters from the fluoro filtered page URL.
remapp.exports.exportcsv.exportCT2excel(request)

Export filtered CT database data to a single-sheet CSV file.

Parameters:request (HTTP get) – Query parameters from the CT filtered page URL.
remapp.exports.exportcsv.exportMG2excel(request)

Export filtered mammography database data to a single-sheet CSV file.

Parameters:request (HTTP get) – Query parameters from the mammo filtered page URL.

Tools and helper modules

OpenREM settings

Administrative module to define the name of the project and to add it to the Python path

remapp.extractors.openrem_settings.name_of_project()

Returns the name of the project. Default OpenREM

remapp.extractors.openrem_settings.add_project_to_path()

Add project to path, assuming this file is within project

Get values

Tiny modules to reduce repetition in the main code when extracting information from DICOM headers using pydicom.

remapp.tools.get_values.get_value_kw(tag, dataset)

Get DICOM value by keyword reference.

Parameters:
  • keyword (str.) – DICOM keyword, no spaces or plural as per dictionary.
  • dataset (dataset) – The DICOM dataset containing the tag.
Returns:

str. – value

remapp.tools.get_values.get_value_num(tag, dataset)

Get DICOM value by tag group and element number.

Always use get_value_kw by preference for readability. This module can be required when reading private elements.

Parameters:
  • tag (hex) – DICOM group and element number as a single hexadecimal number (prefix 0x).
  • dataset (dataset) – The DICOM dataset containing the tag.
Returns:

str. – value

remapp.tools.get_values.get_seq_code_value(sequence, dataset)

From a DICOM sequence, get the code value.

Parameters:
  • sequence (DICOM keyword, no spaces or plural as per dictionary.) – DICOM sequence name.
  • dataset (DICOM dataset) – The DICOM dataset containing the sequence.
Returns:

int. – code value

remapp.tools.get_values.get_seq_code_meaning(sequence, dataset)

From a DICOM sequence, get the code meaning.

Parameters:
  • sequence (DICOM keyword, no spaces or plural as per dictionary.) – DICOM sequence name.
  • dataset (DICOM dataset) – The DICOM dataset containing the sequence.
Returns:

str. – code meaning

remapp.tools.get_values.get_or_create_cid(codevalue, codemeaning)

Create a code_value code_meaning pair entry in the Content_item_descriptions table if it doesn’t already exist.

Parameters:
  • codevalue (int.) – Code value as defined in the DICOM standard part 16
  • codemeaning – Code meaning as defined in the DICOM standard part 16
Returns:

Content_item_descriptions entry for code value passed

Check if UID exists

Small module to check if UID already exists in the database.

remapp.tools.check_uid.check_uid(uid, level='Study')

Check if UID already exists in database.

Parameters:uid (str.) – Study UID.
Returns:1 if it does exist, 0 otherwise

DICOM time and date values

Module to convert betweeen DICOM and Python dates and times.

remapp.tools.dcmdatetime.get_date(tag, dataset)

Get DICOM date string and return Python date.

Parameters:
  • tag (str.) – DICOM keyword, no spaces or plural as per dictionary.
  • dataset (dataset) – The DICOM dataset containing the tag.
Returns:

Python date value

remapp.tools.dcmdatetime.get_time(tag, dataset)

Get DICOM time string and return Python time.

Parameters:
  • tag (str.) – DICOM keyword, no spaces or plural as per dictionary.
  • dataset (dataset) – The DICOM dataset containing the tag.
Returns:

python time value

remapp.tools.dcmdatetime.get_date_time(tag, dataset)

Get DICOM date time string and return Python date time.

Parameters:
  • tag (str.) – DICOM keyword, no spaces or plural as per dictionary.
  • dataset (dataset) – The DICOM dataset containing the tag.
Returns:

Python date time value

remapp.tools.dcmdatetime.make_date(dicomdate)

Given a DICOM date, return a Python date.

Parameters:dicomdate (str.) – DICOM style date.
Returns:Python date value
remapp.tools.dcmdatetime.make_time(dicomtime)

Given a DICOM time, return a Python time.

Parameters:dicomdate (str.) – DICOM style time.
Returns:Python time value
remapp.tools.dcmdatetime.make_date_time(dicomdatetime)

Given a DICOM date time, return a Python date time.

Parameters:dicomdate (str.) – DICOM style date time.
Returns:Python date time value

Test for QA or other non-patient related studies

remapp.tools.not_patient_indicators.get_not_pt(dataset)

Looks for indications that a study might be a test or QA study.

Some values that might indicate a study was for QA or similar purposes are not recorded in the database, for example patient name. Therefore this module attempts to find such indications and creates an xml style string that can be recorded in the database.

Parameters:dataset (dataset) – The DICOM dataset.
Returns:str. – xml style string if any trigger values are found.

Models

class remapp.models.Content_item_descriptions(*args, **kwargs)

Table to hold all the context ID code values and code meanings.

  • Should be renamed Context_identifiers. If it does, I think it would only need to be edited in tools.get_values.get_or_set_cid and admin, then a South migration.
  • Could be prefilled from the tables in DICOM 3.16, but is actually populated as the codes occur. This assumes they are used correctly.
class remapp.models.General_study_module_attributes(*args, **kwargs)

General Study Module C.7.2.1

Specifies the Attributes that describe and identify the Study performed upon the Patient.

From DICOM Part 3: Information Object Definitions Table C.7-3

Additional to the module definition:
  • performing_physician_name
  • operator_name
  • modality_type
  • procedure_code_value_and_meaning
  • requested_procedure_code_value_and_meaning
class remapp.models.Projection_xray_radiation_dose(*args, **kwargs)

Projection X-Ray Radiation Dose template TID 10001

From DICOM Part 16:
This template defines a container (the root) with subsidiary content items, each of which represents a single projection X-Ray irradiation event entry or plane-specific dose accumulations. There is a defined recording observer (the system or person responsible for recording the log, generally the system). A Biplane irradiation event will be recorded as two individual events, one for each plane. Accumulated values will be kept separate for each plane.
class remapp.models.Accumulated_xray_dose(*args, **kwargs)

Accumulated X-Ray Dose TID 10002

From DICOM Part 16:
This general template provides detailed information on projection X-Ray dose value accumulations over several irradiation events from the same equipment (typically a study or a performed procedure step).
class remapp.models.Calibration(*args, **kwargs)

Table to hold the calibration information

  • Container in TID 10002 Accumulated X-ray dose
class remapp.models.Irradiation_event_xray_data(*args, **kwargs)

Irradiation Event X-Ray Data TID 10003

From DICOM part 16:
This template conveys the dose and equipment parameters of a single irradiation event.
class remapp.models.Image_view_modifier(*args, **kwargs)

Table to hold image view modifiers for the irradiation event xray data table

From DICOM Part 16 Annex D DICOM controlled Terminology Definitions
  • Code Value 111032
  • Code Meaning Image View Modifier
  • Code Definition Modifier for image view
class remapp.models.Irradiation_event_xray_detector_data(*args, **kwargs)

Irradiation Event X-Ray Detector Data TID 10003a

From DICOM Part 16 Correction Proposal CP-1077:
This template contains data which is expected to be available to the X-ray detector or plate reader component of the equipment.
class remapp.models.Irradiation_event_xray_source_data(*args, **kwargs)

Irradiation Event X-Ray Source Data TID 10003b

From DICOM Part 16 Correction Proposal CP-1077:
This template contains data which is expected to be available to the X-ray source component of the equipment.
Additional to the template:
  • ii_field_size
  • exposure_control_mode
class remapp.models.Xray_grid(*args, **kwargs)

Content ID 10017 X-Ray Grid

From DICOM Part 16

class remapp.models.Pulse_width(*args, **kwargs)

In TID 10003b. Code value 113793 (ms)

class remapp.models.Kvp(*args, **kwargs)

In TID 10003b. Code value 113733 (kV)

class remapp.models.Xray_tube_current(*args, **kwargs)

In TID 10003b. Code value 113734 (mA)

class remapp.models.Exposure(*args, **kwargs)

In TID 10003b. Code value 113736 (uAs)

class remapp.models.Xray_filters(*args, **kwargs)

Container in TID 10003b. Code value 113771

class remapp.models.Irradiation_event_xray_mechanical_data(*args, **kwargs)

Irradiation Event X-Ray Mechanical Data TID 10003c

From DICOM Part 16 Correction Proposal CP-1077:
This template contains data which is expected to be available to the gantry or mechanical component of the equipment.
Additional to the template:
  • compression_force
  • magnification_factor

Dose Related Distance Measurements Context ID 10008

Called from TID 10003c

class remapp.models.Accumulated_projection_xray_dose(*args, **kwargs)

Accumulated Projection X-Ray Dose TID 10004

From DICOM Part 16:
This general template provides detailed information on projection X-Ray dose value accumulations over several irradiation events from the same equipment (typically a study or a performed procedure step).
convert_gym2_to_cgycm2()

Converts Gy.m2 to cGy.cm2 for display in web interface

class remapp.models.Accumulated_mammography_xray_dose(*args, **kwargs)

Accumulated Mammography X-Ray Dose TID 10005

From DICOM Part 16:
This modality specific template provides detailed information on mammography X-Ray dose value accumulations over several irradiation events from the same equipment (typically a study or a performed procedure step).
class remapp.models.Accumulated_cassette_based_projection_radiography_dose(*args, **kwargs)

Accumulated Cassette-based Projection Radiography Dose TID 10006

From DICOM Part 16 Correction Proposal CP-1077:
This template provides information on Projection Radiography dose values accumulated on Cassette- based systems over one or more irradiation events (typically a study or a performed procedure step) from the same equipment.
class remapp.models.Accumulated_integrated_projection_radiography_dose(*args, **kwargs)

Accumulated Integrated Projection Radiography Dose TID 10007

From DICOM Part 16 Correction Proposal CP-1077:
This template provides information on Projection Radiography dose values accumulated on Integrated systems over one or more irradiation events (typically a study or a performed procedure step) from the same equipment.
class remapp.models.Patient_module_attributes(*args, **kwargs)

Patient Module C.7.1.1

From DICOM Part 3: Information Object Definitions Table C.7-1:
Specifies the Attributes of the Patient that describe and identify the Patient who is the subject of a diagnostic Study. This Module contains Attributes of the patient that are needed for diagnostic interpretation of the Image and are common for all studies performed on the patient. It contains Attributes that are also included in the Patient Modules in Section C.2.
class remapp.models.Patient_study_module_attributes(*args, **kwargs)

Patient Study Module C.7.2.2

From DICOM Part 3: Information Object Definitions Table C.7-4a:
Defines Attributes that provide information about the Patient at the time the Study started.
class remapp.models.General_equipment_module_attributes(*args, **kwargs)

General Equipment Module C.7.5.1

From DICOM Part 3: Information Object Definitions Table C.7-8:
Specifies the Attributes that identify and describe the piece of equipment that produced a Series of Composite Instances.
class remapp.models.Ct_radiation_dose(*args, **kwargs)

CT Radiation Dose TID 10011

From DICOM Part 16:
This template defines a container (the root) with subsidiary content items, each of which corresponds to a single CT X-Ray irradiation event entry. There is a defined recording observer (the system or person responsible for recording the log, generally the system). Accumulated values shall be kept for a whole Study or at least a part of a Study, if the Study is divided in the workflow of the examination, or a performed procedure step. Multiple CT Radiation Dose objects may be created for one Study.
class remapp.models.Ct_accumulated_dose_data(*args, **kwargs)

CT Accumulated Dose Data

From DICOM Part 16:
This general template provides detailed information on CT X-Ray dose value accumulations over several irradiation events from the same equipment and over the scope of accumulation specified for the report (typically a Study or a Performed Procedure Step).
class remapp.models.Ct_irradiation_event_data(*args, **kwargs)

CT Irradiation Event Data TID 10013

From DICOM Part 16:
This template conveys the dose and equipment parameters of a single irradiation event.
Additional to the template:
  • date_time_started
  • series_description
class remapp.models.Ct_xray_source_parameters(*args, **kwargs)

Container in TID 10013 to hold CT x-ray source parameters

class remapp.models.Scanning_length(*args, **kwargs)

Scanning Length TID 10014

From DICOM Part 16:
No description
class remapp.models.Ct_dose_check_details(*args, **kwargs)

CT Dose Check Details TID 10015

From DICOM Part 16:
This template records details related to the use of the NEMA Dose Check Standard (NEMA XR-25-2010).
class remapp.models.Observer_context(*args, **kwargs)

Observer Context TID 1002

From DICOM Part 16:
The observer (person or device) that created the Content Items to which this context applies.
class remapp.models.Device_participant(*args, **kwargs)

Device Participant TID 1021

From DICOM Part 16:
This template describes a device participating in an activity as other than an observer or subject. E.g. for a dose report documenting an irradiating procedure, participants include the irradiating device.
class remapp.models.Person_participant(*args, **kwargs)

Person Participant TID 1020

From DICOM Part 16:
This template describes a person participating in an activity as other than an observer or subject. E.g. for a dose report documenting an irradiating procedure, participants include the person administering the irradiation and the person authorizing the irradiation.

Filtering code

class remapp.interface.mod_filters.RFSummaryListFilter(data=None, queryset=None, prefix=None, strict=None)

Filter for fluoroscopy studies to display in web interface.

class remapp.interface.mod_filters.CTSummaryListFilter(data=None, queryset=None, prefix=None, strict=None)

Filter for CT studies to display in web interface.

class remapp.interface.mod_filters.MGSummaryListFilter(data=None, queryset=None, prefix=None, strict=None)

Filter for mammography studies to display in web interface.

Indices and tables

Note

OpenREM does not currently include a DICOM Store SCP, ie you will need to install a DICOM store server in order to send RSDRs or other DICOM files from modalities.

If you have no preference, Conquest is recommended as a free, open source, scriptable DICOM server. Please note though that you will need to include the RSRD SOP in the dgatesop.lst file.

Indices and tables