dbdicom 0.2.1__py3-none-any.whl → 0.2.3__py3-none-any.whl

dbdicom/record.py

@@ -1,10 +1,14 @@
 # Importing annotations to handle or sign in import type hints
 from __future__ import annotations
 
+import os
+import datetime
+
 # Import packages
 import numpy as np
 import pandas as pd
 import dbdicom.ds.dataset as dbdataset
+from dbdicom.ds import MRImage
 from dbdicom.utils.files import export_path
 
 
@@ -15,12 +19,14 @@ class Record():
 
     def __init__(self, create, manager, uid='Database', key=None, **kwargs):   
 
+        self._logfile = None
         self._key = key
         self._mute = False
         self.uid = uid
         self.attributes = kwargs
         self.manager = manager
         self.new = create
+        
     
     def __eq__(self, other):
         if other is None:
@@ -34,13 +40,13 @@ class Record():
         return self.get_values(attributes)
 
     def __setattr__(self, attribute, value):
-        if attribute in ['_key','_mute', 'uid', 'manager', 'attributes', 'new']:
+        if attribute in ['_key','_mute', 'uid', 'manager', 'attributes', 'new', '_logfile']:
             self.__dict__[attribute] = value
         else:
-            self.set_values([attribute], [value])
+            self._set_values([attribute], [value])
            
     def __setitem__(self, attributes, values):
-        self.set_values(attributes, values)
+        self._set_values(attributes, values)
 
     def loc(self):
         return self.manager._loc(self.name, self.uid)
@@ -86,7 +92,80 @@ class Record():
     def dialog(self):
         return self.manager.dialog
     
+    def set_log(self, filepath:str=None):
+        """Set a new file for logging.
+
+        Args:
+            filepath: full path to a log file. If not provided the current log file is removed. Alternatively the value 'Default' can be assigned, in which case a standard file at the same location of the database is automatically opened. Defaults to None.
+
+        Raises:
+            FileNotFoundError: if the log file cannot be written to.
+
+        See also:
+            `log`
+
+        Examples:
+
+            Set a new log file:
+
+            >>> record.set_log('path/to/logfile')
+            
+            and start logging:
+
+            >>> record.log('Starting new calculation...)
+
+            Alternatively, start a new log at the default location:
+
+            >>> record.set_log('Default')
+        """
+        if filepath is None:
+            self._logfile = None
+            return
+        if filepath == 'Default':
+            # Use default log name
+            self._logfile = os.path.join(self.manager.path, "activity_log.txt")
+        else:
+            self._logfile = filepath
+        try:
+            file = open(self._logfile, 'a')
+            file.write(str(datetime.datetime.now())[0:19] + "Starting a new log..")
+            file.close()
+        except:
+            msg = 'Cannot write to log ' + self._logfile
+            raise FileNotFoundError(msg)
+        
+    def log(self, message:str):
+        """Write an entry in the log file.
+
+        If no logfile is set, this function only writes a message in the terminal.
+
+        Args:
+            message (str): text message to be written in the log file. The function automatically includes some timing information so this does not need to be included in the message. 
+
+        Raises:
+            FileNotFoundError: if the log file cannot be written to.
 
+        See also:
+            `set_log`
+
+        Examples:
+            Set a default file for logging and write a first message:
+
+            >>> record.set_log('Default')
+            >>> record.log('Starting new calculation...)
+        """
+        
+        self.message(message)
+        if self._logfile is None:
+            return
+        try:
+            file = open(self._logfile, 'a')
+            file.write("\n"+str(datetime.datetime.now())[0:19] + ": " + message)
+            file.close()
+        except:
+            msg = 'Cannot write to log ' + self._logfile
+            raise FileNotFoundError(msg)
+        
     
 # Properties
 
@@ -100,7 +179,7 @@ class Record():
         Example:
             Print a summary of a database:
 
-            >>> database = db.database_hollywood()
+            >>> database = db.dro.database_hollywood()
             >>> database.print()
             ---------- DATABASE --------------
             Location:  In memory
@@ -212,7 +291,7 @@ class Record():
             Populate the series with a numpy array and verify that it is now no longer empty:
 
             >>> zeros = np.zeros((3, 2, 128, 128))
-            >>> series.set_ndarray(zeros)
+            >>> series.set_pixel_values(zeros)
             >>> print(series.empty())
             False
         """
@@ -327,7 +406,7 @@ class Record():
         Example:
             Find the patients of a given database:
 
-            >>> database = db.database_hollywood()
+            >>> database = db.dro.database_hollywood()
             >>> patients = database.children()
             >>> print([p.PatientName for p in patients])
             ['James Bond', 'Scarface']
@@ -368,7 +447,7 @@ class Record():
         Example:
             Retrieve a study from a database, and find all other studies performed on the same patient:
 
-            >>> database = db.database_hollywood()
+            >>> database = db.dro.database_hollywood()
             >>> study = database.studies()[0]
             >>> print([s.StudyDescription for s in study.siblings()])
             ['Xray']
@@ -402,7 +481,7 @@ class Record():
         Example:
             Find all series in a database, and print their labels:
 
-            >>> database = db.database_hollywood()
+            >>> database = db.dro.database_hollywood()
             >>> series_list = database.series()
             >>> print([s.label() for s in series_list])
             ['Series 001 [Localizer]', 'Series 002 [T2w]', 'Series 001 [Chest]', 'Series 002 [Head]', 'Series 001 [Localizer]', 'Series 002 [T2w]', 'Series 001 [Chest]', 'Series 002 [Head]']
@@ -447,7 +526,7 @@ class Record():
         Example:
             Find all studies in a database:
 
-            >>> database = db.database_hollywood()
+            >>> database = db.dro.database_hollywood()
             >>> studies_list = database.studies()
             >>> print([s.label() for s in studies_list])
             ['Study MRI [19821201]', 'Study Xray [19821205]', 'Study MRI [19850105]', 'Study Xray [19850106]']
@@ -486,7 +565,7 @@ class Record():
         Example:
             Find all patients in a database:
 
-            >>> database = db.database_hollywood()
+            >>> database = db.dro.database_hollywood()
             >>> patients_list = database.patients()
             >>> print([s.label() for s in patients_list])
             ['Patient James Bond', 'Patient Scarface']
@@ -906,8 +985,6 @@ class Record():
         return self
 
 
-
-
     def copy_to(self, parent, **kwargs):
         """Return a copy of the record under another parent.
 
@@ -1385,6 +1462,7 @@ class Record():
             My message:
         """
         self._mute = True
+        self.status.muted = True
         
     def unmute(self):
         """Allow the object from sending status updates to the user
@@ -1415,6 +1493,7 @@ class Record():
             Hello World
         """
         self._mute = False
+        self.status.muted = False
 
     def type(self):
         return self.__class__.__name__
@@ -1436,8 +1515,8 @@ class Record():
         return self.manager._extract(self.keys())
         #return self.manager.register.loc[self.keys(),:]
     
-    def instances(self, sort=True, sortby=None, **kwargs): 
-        inst = self.manager.instances(keys=self.keys(), sort=sort, sortby=sortby, **kwargs)
+    def instances(self, sort=True, sortby=None, select={}, **kwargs): 
+        inst = self.manager.instances(keys=self.keys(), sort=sort, sortby=sortby, select=select, **kwargs)
         return [self.record('Instance', uid, key) for key, uid in inst.items()]
 
     def images(self, sort=True, sortby=None, **kwargs): 
@@ -1529,21 +1608,26 @@ class Record():
         self.manager._write_df()
 
 
-
-
-
-
     def new_instance(self, dataset=None, **kwargs):
         attr = {**kwargs, **self.attributes}
         uid, key = self.manager.new_instance(parent=self.uid, dataset=dataset, **attr)
         return self.record('Instance', uid, key, **attr)
 
-    def set_values(self, attributes, values):
+    def _set_values(self, attributes, values):
         keys = self.keys()
         self._key = self.manager.set_values(attributes, values, keys)
 
     def get_values(self, attributes):
         return self.manager.get_values(attributes, self.keys())
+    
+    def init_dataset(self, dtype='mri'):
+        if dtype=='mri':
+            ds = MRImage()
+        else: # dummy option for now
+            ds = MRImage()
+        for a in self.attributes:
+            ds.set_values(a, self.attributes[a])
+        return ds
 
     def get_dataset(self):
         ds = self.manager.get_dataset(self.uid, self.keys())
@@ -1552,8 +1636,6 @@ class Record():
     def set_dataset(self, dataset):
         self.manager.set_dataset(self.uid, dataset, self.keys())
 
-
-
     def read_dataframe(*args, **kwargs):
         return read_dataframe(*args, **kwargs)
 
@@ -1582,14 +1664,55 @@ class Record():
 #
 
 
-def copy_to(records, target):
+def copy_to(records:list, parent:Record):
+    """Copy a list of records to a new parent.
+
+    Args:
+        records (list): list of Records of the same type
+        parent (Record): location for the copies.
+
+    See also:
+        `copy`
+        `move_to`
+
+    Example:
+
+        Consider the hollywood demo database:
+
+        >>> database = db.dro.database_hollywood()
+
+        There are currently two MRI studies in the database:
+
+        >>> MRIs = database.studies(StudyDescription='MRI)
+        >>> len(MRIs)
+        2
+
+        Create a new patient and copy the MRI studies there:
+
+        >>> tarantino = database.new_patient(PatientName='Tarantino')
+        >>> db.copy_to(MRIs, tarantino)
+        >>> tarantino_MRIs = tarantino.studies()
+        >>> len(tarantino_MRIs)
+        2
+
+        Note that all header information is automatically updated:
+
+        >>> tarantino_MRIs[0].PatientName
+        Tarantino
+
+        Since the studies were copied, the originals remained and the total number of studies in the database has increased:
+
+        >>> MRIs = database.studies(StudyDescription='MRI)
+        >>> len(MRIs)
+        4
+    """
     if not isinstance(records, list):
-        return records.copy_to(target)
+        return records.copy_to(parent)
     copy = []
-    desc = target.label()
+    desc = parent.label()
     for r, record in enumerate(records):
-        record.status.progress(r+1, len(records), 'Copying ' + desc)
-        copy_record = record.copy_to(target)
+        record.progress(r+1, len(records), 'Copying ' + desc)
+        copy_record = record.copy_to(parent)
         if isinstance(copy_record, list):
             copy += copy_record
         else:
@@ -1597,9 +1720,55 @@ def copy_to(records, target):
     record.status.hide()
     return copy
 
-def move_to(records, target):
-    #if type(records) is np.ndarray:
-    #    records = records.tolist()
+def move_to(records:list, target:Record):
+    """Move a list of records to a new parent.
+
+    Args:
+        records (list): list of Records of the same type
+        parent (Record): location for the copies.
+
+    See also:
+        `copy`
+        `copy_to`
+
+    Example:
+
+        Consider the hollywood demo database:
+
+        >>> database = db.dro.database_hollywood()
+
+        There are currently two MRI studies in the database:
+
+        >>> MRIs = database.studies(StudyDescription='MRI)
+        >>> len(MRIs)
+        2
+
+        Create a new patient and move the MRI studies there:
+
+        >>> tarantino = database.new_patient(PatientName='Tarantino')
+        >>> db.copy_to(MRIs, tarantino)
+        >>> tarantino_MRIs = tarantino.studies()
+        >>> len(tarantino_MRIs)
+        2
+
+        Note that all header information is automatically updated:
+
+        >>> tarantino_MRIs[0].PatientName
+        Tarantino
+
+        Since the studies were moved, the total number of studies in the database has stayed the same:
+
+        >>> MRIs = database.studies(StudyDescription='MRI)
+        >>> len(MRIs)
+        2
+
+        And the original patients do not have any MRI studies left:
+
+        >>> jb = database.patients(PatientName = 'James Bond')
+        >>> MRIs = jb[0].studies(StudyDescription='MRI')
+        >>> len(MRIs)
+        0
+    """
     if not isinstance(records, list):
         records = [records]
     mgr = records[0].manager
@@ -1607,7 +1776,7 @@ def move_to(records, target):
     mgr.move_to(uids, target.uid, **target.attributes)
     return records
 
-def group(records, into=None, inplace=False):
+def group(records:list, into:Record=None, inplace=False)->Record:
     if not isinstance(records, list):
         records = [records]
     if into is None:
@@ -1618,17 +1787,69 @@ def group(records, into=None, inplace=False):
         copy_to(records, into)
     return into
 
-def merge(records, into=None, inplace=False):
+def merge(records:list, into:Record=None, inplace=False)->Record:
+    """Merge a list of records into a single new record.
+
+    Args:
+        records (list): list of Records of the same type
+        into (Record, optional): location for the merged series. If None is provided, the merged series is created in the parent of the first record in the list. Defaults to None.
+        inplace (bool, optional): If set to True, the original series will be removed and only the merged series retain. If set to False the original series will contine to exist. Default is False.
+
+    Returns: 
+        new_record (Record): the merged record.
+
+    See also:
+        `copy`
+        `copy_to`
+
+    Example:
+
+        The first patient in the hollywood demo database currently has two studies
+
+        >>> database = db.dro.database_hollywood()
+        >>> jb = database.patients(PatientName = 'James Bond')[0]
+        >>> len(jb.studies())
+        2
+
+        If we merge them together, the patient now has three studies, the original MRI and Xray studies, and the new merged study:
+
+        >>> new_study = db.merge(jb.studies())
+        >>> len(jb.studies())
+        3
+        >>> jb.StudyDescription
+        ['MRI', 'New Study', 'Xray']
+
+        Since the original MRI and Xray studies had two series each, the new study now has 2+2=4 series:
+
+        >>> len(new_study.series())
+        4 
+
+        We have used here the default setting of ``inplace=False``, so the original series are preserved. To see what happens with ``inplace=True``, lets merge all 3 studies of the patient: 
+
+        >>> single_jb_study = db.merge(jb.studies(), inplace=True)
+
+        Since we have merged in place, the original 3 studies have been removed and there is now only one study left.
+        
+        >>> len(jb.studies())
+        1
+
+        The new study now groups the 8 series that were in the original 3 studies:
+
+        >>> len(single_jb_study.series())
+        8
+    """
     if not isinstance(records, list):
         records = [records]
     children = []
     for record in records:
         children += record.children()
-    new_series = group(children, into=into, inplace=inplace)
+    new_record = group(children, into=into, inplace=inplace)
     if inplace:
         for record in records:
             record.remove()
-    return new_series
+    return new_record
+
+
 
 
 # 
@@ -1637,11 +1858,18 @@ def merge(records, into=None, inplace=False):
 
 
 
-
-def read_dataframe(record, tags):
+def read_dataframe(record, tags, select={}, **filters):
     if set(tags) <= set(record.manager.columns):
-        return record.register()[tags]  
-    instances = record.instances()
+        df = record.register()[tags] 
+        filters = {**select, **filters}
+        for f in filters:
+            if f in df:
+                if isinstance(filters[f], np.ndarray):
+                    df = df[df[f].isin(filters[f])]
+                else:
+                    df = df[df[f] == filters[f]] 
+        return df
+    instances = record.instances(select=select, **filters)
     return _read_dataframe_from_instance_array_values(instances, tags)
 
 
@@ -1662,9 +1890,4 @@ def _read_dataframe_from_instance_array_values(instances, tags):
         indices.append(index)
         data.append(values)
         instance.progress(i+1, len(instances), 'Reading dataframe..')
-    return pd.DataFrame(data, index=indices, columns=tags)
-
-
-
-
-
+    return pd.DataFrame(data, index=indices, columns=tags)

dbdicom/types/instance.py

@@ -46,10 +46,13 @@ class Instance(Record):
         ds = self.get_dataset()
         return ds.get_pixel_array()
 
-    def set_array(self, array):
+    def set_array(self, array): # obsolete
+        self.set_pixel_array(array)
+
+    def set_pixel_values(self, array):
         self.set_pixel_array(array)
         
-    def set_pixel_array(self, array):
+    def set_pixel_array(self, array): # make private
         ds = self.get_dataset()
         if ds is None:
             ds = new_dataset('MRImage')
@@ -137,6 +140,17 @@ class Instance(Record):
             width = self.WindowWidth,
             center = self.WindowCenter,
         )
+    
+    def set_affine(self, affine):
+        p = image.dismantle_affine_matrix(affine)
+        self.read()
+        self.SpacingBetweenSlices = p['SpacingBetweenSlices']
+        self.SliceThickness = p['SpacingBetweenSlices']
+        self.PixelSpacing = p['PixelSpacing']
+        self.ImageOrientationPatient = p['ImageOrientationPatient']
+        self.ImagePositionPatient = p['ImagePositionPatient']
+        self.SliceLocation = np.dot(p['ImagePositionPatient'], p['slice_cosine'])
+        self.clear()
 
 
 def map_to(source, target):
@@ -179,7 +193,7 @@ def map_to(source, target):
 
     return result
 
-
+# Obsolete
 def map_mask_to(record, target):
     """Map non-zero image pixels onto a target image.
     Overwrite pixel values in the target"""