dbdicom 0.2.0__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.
 
@@ -1117,6 +1194,187 @@ class Record():
         self.manager.clear(self.uid, keys=self.keys())
 
 
+    def export_as_dicom(self, path:str):
+        """Export record in DICOM format to an external directory.
+
+        Note since this is exporting outside of the current database this will assign new identifiers to the exported data. 
+
+        Args:
+            path (str): path to export directory.
+
+        See Also:
+            :func:`~export_as_png`
+            :func:`~export_as_nifti`
+            :func:`~export_as_npy`
+            :func:`~export_as_csv`
+
+        Example:
+
+            Create a 4D series and export as DICOM
+
+            >>> series = db.ones((128, 128, 10, 5))
+            >>> path = 'path\\to\\empty\\folder'
+            >>> series.export_as_dicom(path)
+
+            This should create a single folder in the directory, populated with 50 DICOM files.
+        """
+        if self.name == 'Database':
+            folder = 'Database' 
+        else:
+            folder = self.label()
+        path = export_path(path, folder)
+        for child in self.children():
+            child.export_as_dicom(path)
+
+
+    def export_as_png(self, path:str, center:float=None, width:float=None, colormap:str=None): 
+        """Export record in PNG format.
+
+        Args:
+            path (str): path to export directory.
+            center (float, optional): center of the color window. Defaults to None, in which case the center is taken from the DICOM header.
+            width (float, optional): width of the color window. Defaults to None, in which case the width is taken from the DICOM header.
+            colormap (str, optional): color map to use as lookup table. Any valid matplotlib colormap can be entered here. Please the `matplotlib colormap reference <https://matplotlib.org/stable/gallery/color/colormap_reference.html>`_ for a complete list. Defaults to None, in which case the colormap is taken from the DICOM header. 
+
+        See Also:
+            :func:`~export_as_dicom`
+            :func:`~export_as_nifti`
+            :func:`~export_as_npy`
+            :func:`~export_as_csv`
+
+        Example:
+
+            Create a 4D series and export as PNG, using the colormap plasma:
+
+            >>> series = db.ones((128, 128, 10, 5))
+            >>> path = 'path\\to\\empty\\folder'
+            >>> series.export_as_png(path, center=1, width=0.5, colormap='plasma')
+
+            This should create a single folder in the directory, populated with 50 PNG files.
+        """
+        if self.name == 'Database':
+            folder = 'Database' 
+        else:
+            folder = self.label()
+        path = export_path(path, folder)
+        for child in self.children():
+            child.export_as_png(path, center=center, width=width, colormap=colormap)
+
+    def export_as_csv(self, path:str):
+        """Export record in CSV format to an external directory.
+
+        Args:
+            path (str): path to export directory.
+
+        See Also:
+            :func:`~export_as_png`
+            :func:`~export_as_nifti`
+            :func:`~export_as_npy`
+            :func:`~export_as_dicom`
+
+        Example:
+
+            Create a 4D series and export as CSV:
+
+            >>> series = db.ones((128, 128, 10, 5))
+            >>> path = 'path\\to\\empty\\folder'
+            >>> series.export_as_csv(path)
+
+            This should create a single folder in the directory, populated with 50 CSV files.
+        """
+        if self.name == 'Database':
+            folder = 'Database' 
+        else:
+            folder = self.label()
+        path = export_path(path, folder)
+        for child in self.children():
+            child.export_as_csv(path)
+
+
+    def export_as_nifti(self, path:str, dims:tuple=None):
+        """Export record in NIFTI format to an external directory.
+
+        Args:
+            path (str): path to export directory.
+            dims (tuple, optional): when set, volumes are extracted along the given dimensions and exported in single files. If dims is not set, each image will be exported in its own file. 
+
+        See Also:
+            :func:`~export_as_png`
+            :func:`~export_as_dicom`
+            :func:`~export_as_npy`
+            :func:`~export_as_csv`
+
+        Example:
+
+            Create a 4D series and export as NIFTI:
+
+            >>> series = db.ones((128, 128, 10, 5))
+            >>> path = 'path\\to\\empty\\folder'
+            >>> series.export_as_nifti(path)
+
+            This should create a single folder in the directory, populated with 50 NIFTI files.
+
+            In order to export the entire series in a single volume, provide the dimensions along which the volume is to be taken:
+
+            >>> dims = ('SliceLocation', 'AcquisitionTime')
+            >>> series.export_as_nifti(path, dims=dims)
+
+            This will now create a single nifti file.
+
+            Note: in this case the dimensions must be specified as slice location and acquisition time because these are the default dimensions used by series creation functions like :func:`~ones`.
+        """
+        if self.name == 'Database':
+            folder = 'Database' 
+        else:
+            folder = self.label()
+        path = export_path(path, folder)
+        for child in self.children():
+            child.export_as_nifti(path, dims=dims)
+
+
+    def export_as_npy(self, path:str, dims:tuple=None):
+        """Export record in numpy's NPY format to an external directory.
+
+        Args:
+            path (str): path to export directory.
+            dims (tuple, optional): when set, volumes are extracted along the given dimensions and exported in single files. If dims is not set (None), each image will be exported in its own file. Defaults to None.
+
+        See Also:
+            :func:`~export_as_png`
+            :func:`~export_as_nifti`
+            :func:`~export_as_dicom`
+            :func:`~export_as_csv`
+
+        Example:
+
+            Create a 4D series:
+
+            >>> series = db.ones((128, 128, 10, 5))
+
+            Export the series as npy, with each slice in a separate file:
+
+            >>> path = 'path\\to\\empty\\folder'
+            >>> series.export_as_npy(path)
+
+            This will create 50 npy files in the folder, one for each image. To save the entire volume in a single file, specify the dimensions of the volume:
+
+            >>> dims = ('SliceLocation', 'AcquisitionTime')
+            >>> series.export_as_npy(path, dims)
+
+            This will create a single npy file. 
+
+            Note: in this case the dimensions must be specified as slice location and acquisition time because these are the default dimensions used by series creation functions like :func:`~ones`.
+        """
+        if self.name == 'Database':
+            folder = 'Database' 
+        else:
+            folder = self.label()
+        path = export_path(path, folder)
+        for child in self.children():
+            child.export_as_npy(path, dims=dims)
+
+
+
     def progress(self, value: float, maximum: float, message: str=None):
         """Print progress message to the terminal..
 
@@ -1204,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
@@ -1234,6 +1493,7 @@ class Record():
             Hello World
         """
         self._mute = False
+        self.status.muted = False
 
     def type(self):
         return self.__class__.__name__
@@ -1255,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): 
@@ -1348,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())
@@ -1371,45 +1636,6 @@ class Record():
     def set_dataset(self, dataset):
         self.manager.set_dataset(self.uid, dataset, self.keys())
 
-    def export_as_dicom(self, path):
-        if self.name == 'Database':
-            folder = 'Database' 
-        else:
-            folder = self.label()
-        path = export_path(path, folder)
-        for child in self.children():
-            child.export_as_dicom(path)
-
-    def export_as_png(self, path): 
-        if self.name == 'Database':
-            folder = 'Database' 
-        else:
-            folder = self.label()
-        path = export_path(path, folder)
-        for child in self.children():
-            child.export_as_png(path)
-
-    def export_as_csv(self, path):
-        if self.name == 'Database':
-            folder = 'Database' 
-        else:
-            folder = self.label()
-        path = export_path(path, folder)
-        for child in self.children():
-            child.export_as_csv(path)
-
-    def export_as_nifti(self, path):
-        if self.name == 'Database':
-            folder = 'Database' 
-        else:
-            folder = self.label()
-        path = export_path(path, folder)
-        for child in self.children():
-            child.export_as_nifti(path)
-
-    # def sort(self, sortby=['StudyDate','SeriesNumber','InstanceNumber']):
-    #     self.manager.register.sort_values(sortby, inplace=True)
-
     def read_dataframe(*args, **kwargs):
         return read_dataframe(*args, **kwargs)
 
@@ -1438,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:
@@ -1453,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
@@ -1463,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:
@@ -1474,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
+
+
 
 
 # 
@@ -1493,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)
 
 
@@ -1518,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)