signature:
def query_reliabledictionary ( client , application_name , service_name , dictionary_name , query_string , partition_key = None , partition_id = None , output_file = None ) :
    """Query existing reliable dictionary .
 Query existing reliable dictionaries for given application and service .
 : param application _ name : Name of the application .
 : type application _ name : str
 : param service _ name : Name of the service .
 : type service _ name : str
 : param dictionary _ name : Name of the reliable dictionary .
 : type dictionary _ name : str
 : param query _ string : An OData query string . For example $ top = 10 . Check https : / / www . odata . org / documentation / for more information .
 : type query _ string : str
 : param partition _ key : Optional partition key of the desired partition , either a string if named schema or int if Int64 schema
 : type partition _ id : str
 : param partition _ id : Optional partition GUID of the owning reliable dictionary .
 : type partition _ id : str
 : param output _ file : Optional file to save the schema ."""

implementation:
cluster = Cluster . from_sfclient ( client )
dictionary = cluster . get_application ( application_name ) . get_service ( service_name ) . get_dictionary ( dictionary_name )
start = time . time ( )
if ( partition_id != None ) :
    result = dictionary . query ( query_string , PartitionLookup . ID , partition_id )
elif ( partition_key != None ) :
    result = dictionary . query ( query_string , PartitionLookup . KEY , partition_key )
else :
    result = dictionary . query ( query_string )
if type ( result ) is str :
    print ( result )
    return
else :
    result = json . dumps ( result . get ( "value" ) , indent = 4 )
print ( "Query took " + str ( time . time ( ) - start ) + " seconds" )
if ( output_file == None ) :
    output_file = "{}-{}-{}-query-output.json" . format ( application_name , service_name , dictionary_name )
with open ( output_file , "w" ) as output :
    output . write ( result )
print ( )
print ( 'Printed output to: ' + output_file )
print ( result )


signature:
def execute_reliabledictionary ( client , application_name , service_name , input_file ) :
    """Execute create , update , delete operations on existing reliable dictionaries .
 carry out create , update and delete operations on existing reliable dictionaries for given application and service .
 : param application _ name : Name of the application .
 : type application _ name : str
 : param service _ name : Name of the service .
 : type service _ name : str
 : param output _ file : input file with list of json to provide the operation information for reliable dictionaries ."""

implementation:
cluster = Cluster . from_sfclient ( client )
service = cluster . get_application ( application_name ) . get_service ( service_name )
# call get service with headers and params
with open ( input_file ) as json_file :
    json_data = json . load ( json_file )
    service . execute ( json_data )
return


signature:
def select_arg_verify ( endpoint , cert , key , pem , ca , aad , no_verify ) : # pylint : disable = invalid - name , too - many - arguments
    """Verify arguments for select command"""

implementation:
if not ( endpoint . lower ( ) . startswith ( 'http' ) or endpoint . lower ( ) . startswith ( 'https' ) ) :
    raise CLIError ( 'Endpoint must be HTTP or HTTPS' )
usage = ( 'Valid syntax : --endpoint [ [ --key --cert | --pem | --aad] ' '[ --ca | --no-verify ] ]' )
if ca and not ( pem or all ( [ key , cert ] ) ) :
    raise CLIError ( usage )
if no_verify and not ( pem or all ( [ key , cert ] ) or aad ) :
    raise CLIError ( usage )
if no_verify and ca :
    raise CLIError ( usage )
if any ( [ cert , key ] ) and not all ( [ cert , key ] ) :
    raise CLIError ( usage )
if aad and any ( [ pem , cert , key ] ) :
    raise CLIError ( usage )
if pem and any ( [ cert , key ] ) :
    raise CLIError ( usage )


signature:
def select ( endpoint , cert = None , key = None , pem = None , ca = None , # pylint : disable = invalid - name , too - many - arguments
aad = False , no_verify = False ) : # pylint : disable - msg = too - many - locals
    """Connects to a Service Fabric cluster endpoint .
 If connecting to secure cluster specify an absolute path to a cert ( . crt )
 and key file ( . key ) or a single file with both ( . pem ) . Do not specify both .
 Optionally , if connecting to a secure cluster , specify also an absolute
 path to a CA bundle file or directory of trusted CA certs .
 : param str endpoint : Cluster endpoint URL , including port and HTTP or HTTPS
 prefix
 : param str cert : Absolute path to a client certificate file
 : param str key : Absolute path to client certificate key file
 : param str pem : Absolute path to client certificate , as a . pem file
 : param str ca : Absolute path to CA certs directory to treat as valid
 or CA bundle
 file
 : param bool aad : Use Azure Active Directory for authentication
 : param bool no _ verify : Disable verification for certificates when using
 HTTPS , note : this is an insecure option and should not be used for
 production environments"""

implementation:
from sfctl . config import ( set_ca_cert , set_auth , set_aad_cache , set_cluster_endpoint , set_no_verify )
from msrest import ServiceClient , Configuration
from sfctl . auth import ClientCertAuthentication , AdalAuthentication
select_arg_verify ( endpoint , cert , key , pem , ca , aad , no_verify )
if aad :
    new_token , new_cache = get_aad_token ( endpoint , no_verify )
    set_aad_cache ( new_token , new_cache )
    rest_client = ServiceClient ( AdalAuthentication ( no_verify ) , Configuration ( endpoint ) )
    # Make sure basic GET request succeeds
    rest_client . send ( rest_client . get ( '/' ) ) . raise_for_status ( )
else :
    client_cert = None
    if pem :
        client_cert = pem
    elif cert :
        client_cert = ( cert , key )
    rest_client = ServiceClient ( ClientCertAuthentication ( client_cert , ca , no_verify ) , Configuration ( endpoint ) )
    # Make sure basic GET request succeeds
    rest_client . send ( rest_client . get ( '/' ) ) . raise_for_status ( )
set_cluster_endpoint ( endpoint )
set_no_verify ( no_verify )
set_ca_cert ( ca )
set_auth ( pem , cert , key , aad )


signature:
def get_aad_token ( endpoint , no_verify ) : # pylint : disable - msg = too - many - locals
    """Get AAD token"""

implementation:
from azure . servicefabric . service_fabric_client_ap_is import ( ServiceFabricClientAPIs )
from sfctl . auth import ClientCertAuthentication
from sfctl . config import set_aad_metadata
auth = ClientCertAuthentication ( None , None , no_verify )
client = ServiceFabricClientAPIs ( auth , base_url = endpoint )
aad_metadata = client . get_aad_metadata ( )
if aad_metadata . type != "aad" :
    raise CLIError ( "Not AAD cluster" )
aad_resource = aad_metadata . metadata
tenant_id = aad_resource . tenant
authority_uri = aad_resource . login + '/' + tenant_id
context = adal . AuthenticationContext ( authority_uri , api_version = None )
cluster_id = aad_resource . cluster
client_id = aad_resource . client
set_aad_metadata ( authority_uri , cluster_id , client_id )
code = context . acquire_user_code ( cluster_id , client_id )
print ( code [ 'message' ] )
token = context . acquire_token_with_device_code ( cluster_id , code , client_id )
print ( "Succeed!" )
return token , context . cache


signature:
def _openpyxl_read_xl ( xl_path : str ) :
    """Use openpyxl to read an Excel file ."""

implementation:
try :
    wb = load_workbook ( filename = xl_path , read_only = True )
except :
    raise
else :
    return wb


signature:
def _check_xl_path ( xl_path : str ) :
    """Return the expanded absolute path of ` xl _ path ` if
 if exists and ' xlrd ' or ' openpyxl ' depending on
 which module should be used for the Excel file in ` xl _ path ` .
 Parameters
 xl _ path : str
 Path to an Excel file
 Returns
 xl _ path : str
 User expanded and absolute path to ` xl _ path `
 module : str
 The name of the module you should use to process the
 Excel file .
 Choices : ' xlrd ' , ' pyopenxl '
 Raises
 IOError
 If the file does not exist
 RuntimError
 If a suitable reader for xl _ path is not found"""

implementation:
xl_path = op . abspath ( op . expanduser ( xl_path ) )
if not op . isfile ( xl_path ) :
    raise IOError ( "Could not find file in {}." . format ( xl_path ) )
return xl_path , _use_openpyxl_or_xlrf ( xl_path )


signature:
def read_xl ( xl_path : str ) :
    """Return the workbook from the Excel file in ` xl _ path ` ."""

implementation:
xl_path , choice = _check_xl_path ( xl_path )
reader = XL_READERS [ choice ]
return reader ( xl_path )


signature:
def get_sheet_list ( xl_path : str ) -> List :
    """Return a list with the name of the sheets in
 the Excel file in ` xl _ path ` ."""

implementation:
wb = read_xl ( xl_path )
if hasattr ( wb , 'sheetnames' ) :
    return wb . sheetnames
else :
    return wb . sheet_names ( )


signature:
def concat_sheets ( xl_path : str , sheetnames = None , add_tab_names = False ) :
    """Return a pandas DataFrame with the concat ' ed
 content of the ` sheetnames ` from the Excel file in
 ` xl _ path ` .
 Parameters
 xl _ path : str
 Path to the Excel file
 sheetnames : list of str
 List of existing sheet names of ` xl _ path ` .
 If None , will use all sheets from ` xl _ path ` .
 add _ tab _ names : bool
 If True will add a ' Tab ' column which says from which
 tab the row comes from .
 Returns
 df : pandas . DataFrame"""

implementation:
xl_path , choice = _check_xl_path ( xl_path )
if sheetnames is None :
    sheetnames = get_sheet_list ( xl_path )
sheets = pd . read_excel ( xl_path , sheetname = sheetnames )
if add_tab_names :
    for tab in sheets :
        sheets [ tab ] [ 'Tab' ] = [ tab ] * len ( sheets [ tab ] )
return pd . concat ( [ sheets [ tab ] for tab in sheets ] )


signature:
def _check_cols ( df , col_names ) :
    """Raise an AttributeError if ` df ` does not have a column named as an item of
 the list of strings ` col _ names ` ."""

implementation:
for col in col_names :
    if not hasattr ( df , col ) :
        raise AttributeError ( "DataFrame does not have a '{}' column, got {}." . format ( col , df . columns ) )


signature:
def col_values ( df , col_name ) :
    """Return a list of not null values from the ` col _ name ` column of ` df ` ."""

implementation:
_check_cols ( df , [ col_name ] )
if 'O' in df [ col_name ] or pd . np . issubdtype ( df [ col_name ] . dtype , str ) : # if the column is of strings
    return [ nom . lower ( ) for nom in df [ pd . notnull ( df ) ] [ col_name ] if not pd . isnull ( nom ) ]
else :
    return [ nom for nom in df [ pd . notnull ( df ) ] [ col_name ] if not pd . isnull ( nom ) ]


signature:
def duplicated_rows ( df , col_name ) :
    """Return a DataFrame with the duplicated values of the column ` col _ name `
 in ` df ` ."""

implementation:
_check_cols ( df , [ col_name ] )
dups = df [ pd . notnull ( df [ col_name ] ) & df . duplicated ( subset = [ col_name ] ) ]
return dups


signature:
def duplicated ( values : Sequence ) :
    """Return the duplicated items in ` values `"""

implementation:
vals = pd . Series ( values )
return vals [ vals . duplicated ( ) ]


signature:
def timestamp_with_tzinfo ( dt ) :
    """Serialize a date / time value into an ISO8601 text representation
 adjusted ( if needed ) to UTC timezone .
 For instance :
 > > > serialize _ date ( datetime ( 2012 , 4 , 10 , 22 , 38 , 20 , 604391 ) )
 '2012-04-10T22:38:20.604391Z '"""

implementation:
utc = tzutc ( )
if dt . tzinfo :
    dt = dt . astimezone ( utc ) . replace ( tzinfo = None )
return dt . isoformat ( ) + 'Z'


signature:
def _to_string ( data ) :
    """Convert to string all values in ` data ` .
 Parameters
 data : dict [ str ] - > object
 Returns
 string _ data : dict [ str ] - > str"""

implementation:
sdata = data . copy ( )
for k , v in data . items ( ) :
    if isinstance ( v , datetime ) :
        sdata [ k ] = timestamp_to_date_str ( v )
    elif not isinstance ( v , ( string_types , float , int ) ) :
        sdata [ k ] = str ( v )
return sdata


signature:
def insert_unique ( table , data , unique_fields = None , * , raise_if_found = False ) :
    """Insert ` data ` into ` table ` ensuring that data has unique values
 in ` table ` for the fields listed in ` unique _ fields ` .
 If ` raise _ if _ found ` is True , will raise an NotUniqueItemError if
 another item with the same ` unique _ fields ` values are found
 previously in ` table ` .
 If False , will return the ` eid ` from the item found .
 Parameters
 table : tinydb . Table
 data : dict
 unique _ fields : list of str
 Name of fields ( keys ) from ` data ` which are going to be used to build
 a sample to look for exactly the same values in the database .
 If None , will use every key in ` data ` .
 raise _ if _ found : bool
 Returns
 eid : int
 Id of the object inserted or the one found with same ` unique _ fields ` .
 Raises
 MoreThanOneItemError
 Raise even with ` raise _ with _ found ` = = False if it finds more than one item
 with the same values as the sample .
 NotUniqueItemError
 If ` raise _ if _ found ` is True and an item with the same ` unique _ fields `
 values from ` data ` is found in ` table ` ."""

implementation:
item = find_unique ( table , data , unique_fields )
if item is not None :
    if raise_if_found :
        raise NotUniqueItemError ( 'Not expected to find an item with the same ' 'values for {}. Inserting {} got {} in eid {}.' . format ( unique_fields , data , table . get ( eid = item ) , item ) )
    else :
        return item
return table . insert ( data )


signature:
def search_sample ( table , sample ) :
    """Search for items in ` table ` that have the same field sub - set values as in ` sample ` .
 Parameters
 table : tinydb . table
 sample : dict
 Sample data
 Returns
 search _ result : list of dict
 List of the items found . The list is empty if no item is found ."""

implementation:
query = _query_sample ( sample = sample , operators = '__eq__' )
return table . search ( query )


signature:
def search_unique ( table , sample , unique_fields = None ) :
    """Search for items in ` table ` that have the same field sub - set values as in ` sample ` .
 Expecting it to be unique , otherwise will raise an exception .
 Parameters
 table : tinydb . table
 sample : dict
 Sample data
 Returns
 search _ result : tinydb . database . Element
 Unique item result of the search .
 Raises
 KeyError :
 If the search returns for more than one entry ."""

implementation:
if unique_fields is None :
    unique_fields = list ( sample . keys ( ) )
query = _query_data ( sample , field_names = unique_fields , operators = '__eq__' )
items = table . search ( query )
if len ( items ) == 1 :
    return items [ 0 ]
if len ( items ) == 0 :
    return None
raise MoreThanOneItemError ( 'Expected to find zero or one items, but found ' '{} items.' . format ( len ( items ) ) )


signature:
def find_unique ( table , sample , unique_fields = None ) :
    """Search in ` table ` an item with the value of the ` unique _ fields ` in the ` sample ` sample .
 Check if the the obtained result is unique . If nothing is found will return an empty list ,
 if there is more than one item found , will raise an IndexError .
 Parameters
 table : tinydb . table
 sample : dict
 Sample data
 unique _ fields : list of str
 Name of fields ( keys ) from ` data ` which are going to be used to build
 a sample to look for exactly the same values in the database .
 If None , will use every key in ` data ` .
 Returns
 eid : int
 Id of the object found with same ` unique _ fields ` .
 None if none is found .
 Raises
 MoreThanOneItemError
 If more than one example is found ."""

implementation:
res = search_unique ( table , sample , unique_fields )
if res is not None :
    return res . eid
else :
    return res


signature:
def _query_sample ( sample , operators = '__eq__' ) :
    """Create a TinyDB query that looks for items that have each field in ` sample ` with a value
 compared with the correspondent operation in ` operators ` .
 Parameters
 sample : dict
 The sample data
 operators : str or list of str
 A list of comparison operations for each field value in ` sample ` .
 If this is a str , will use the same operator for all ` sample ` fields .
 If you want different operators for each field , remember to use an OrderedDict for ` sample ` .
 Check TinyDB . Query class for possible choices .
 Returns
 query : tinydb . database . Query"""

implementation:
if isinstance ( operators , str ) :
    operators = [ operators ] * len ( sample )
if len ( sample ) != len ( operators ) :
    raise ValueError ( 'Expected `operators` to be a string or a list with the same' ' length as `field_names` ({}), got {}.' . format ( len ( sample ) , operators ) )
queries = [ ]
for i , fn in enumerate ( sample ) :
    fv = sample [ fn ]
    op = operators [ i ]
    queries . append ( _build_query ( field_name = fn , field_value = fv , operator = op ) )
return _concat_queries ( queries , operators = '__and__' )


signature:
def _query_data ( data , field_names = None , operators = '__eq__' ) :
    """Create a tinyDB Query object that looks for items that confirms the correspondent operator
 from ` operators ` for each ` field _ names ` field values from ` data ` .
 Parameters
 data : dict
 The data sample
 field _ names : str or list of str
 The name of the fields in ` data ` that will be used for the query .
 operators : str or list of str
 A list of comparison operations for each field value in ` field _ names ` .
 If this is a str , will use the same operator for all ` field _ names ` .
 If you want different operators for each field , remember to use an OrderedDict for ` data ` .
 Check TinyDB . Query class for possible choices .
 Returns
 query : tinydb . database . Query"""

implementation:
if field_names is None :
    field_names = list ( data . keys ( ) )
if isinstance ( field_names , str ) :
    field_names = [ field_names ]
# using OrderedDict by default , in case operators has different operators for each field .
sample = OrderedDict ( [ ( fn , data [ fn ] ) for fn in field_names ] )
return _query_sample ( sample , operators = operators )


signature:
def _concat_queries ( queries , operators = '__and__' ) :
    """Create a tinyDB Query object that is the concatenation of each query in ` queries ` .
 The concatenation operator is taken from ` operators ` .
 Parameters
 queries : list of tinydb . Query
 The list of tinydb . Query to be joined .
 operators : str or list of str
 List of binary operators to join ` queries ` into one query .
 Check TinyDB . Query class for possible choices .
 Returns
 query : tinydb . database . Query"""

implementation:
# checks first
if not queries :
    raise ValueError ( 'Expected some `queries`, got {}.' . format ( queries ) )
if len ( queries ) == 1 :
    return queries [ 0 ]
if isinstance ( operators , str ) :
    operators = [ operators ] * ( len ( queries ) - 1 )
if len ( queries ) - 1 != len ( operators ) :
    raise ValueError ( 'Expected `operators` to be a string or a list with the same' ' length as `field_names` ({}), got {}.' . format ( len ( queries ) , operators ) )
# recursively build the query
first , rest , end = queries [ 0 ] , queries [ 1 : - 1 ] , queries [ - 1 : ] [ 0 ]
bigop = getattr ( first , operators [ 0 ] )
for i , q in enumerate ( rest ) :
    bigop = getattr ( bigop ( q ) , operators [ i ] )
return bigop ( end )


signature:
def _build_query ( field_name , field_value , operator = '__eq__' ) :
    """Create a tinyDB Query object with the format :
 ( where ( ` field _ name ` ) ` operator ` ` field _ value ` )
 Parameters
 field _ name : str
 The name of the field to be queried .
 field _ value :
 The value of the field
 operator : str
 The comparison operator .
 Check TinyDB . Query class for possible choices .
 Returns
 query : tinydb . database . Query"""

implementation:
qelem = where ( field_name )
if not hasattr ( qelem , operator ) :
    raise NotImplementedError ( 'Operator `{}` not found in query object.' . format ( operator ) )
else :
    query = getattr ( qelem , operator )
return query ( field_value )


signature:
def search_by_eid ( self , table_name , eid ) :
    """Return the element in ` table _ name ` with Object ID ` eid ` .
 If None is found will raise a KeyError exception .
 Parameters
 table _ name : str
 The name of the table to look in .
 eid : int
 The Object ID of the element to look for .
 Returns
 elem : tinydb . database . Element
 Raises
 KeyError
 If the element with ID ` eid ` is not found ."""

implementation:
elem = self . table ( table_name ) . get ( eid = eid )
if elem is None :
    raise KeyError ( 'Could not find {} with eid {}.' . format ( table_name , eid ) )
return elem


signature:
def insert_unique ( self , table_name , data , unique_fields = None , * , raise_if_found = False ) :
    """Insert ` data ` into ` table ` ensuring that data has unique values
 in ` table ` for the fields listed in ` unique _ fields ` .
 If ` raise _ if _ found ` is True , will raise an NotUniqueItemError if
 another item with the same ` unique _ fields ` values are found
 previously in ` table ` .
 If False , will return the ` eid ` from the item found .
 Parameters
 table _ name : str
 data : dict
 unique _ fields : list of str
 Name of fields ( keys ) from ` data ` which are going to be used to build
 a sample to look for exactly the same values in the database .
 If None , will use every key in ` data ` .
 raise _ if _ found : bool
 Returns
 eid : int
 Id of the object inserted or the one found with same ` unique _ fields ` .
 Raises
 MoreThanOneItemError
 Raise even with ` raise _ with _ found ` = = False if it finds more than one item
 with the same values as the sample .
 NotUniqueItemError
 If ` raise _ if _ found ` is True and an item with the same ` unique _ fields `
 values from ` data ` is found in ` table ` ."""

implementation: return insert_unique ( table = self . table ( table_name ) , data = _to_string ( data ) , unique_fields = unique_fields , raise_if_found = raise_if_found )


signature:
def search_unique ( self , table_name , sample , unique_fields = None ) :
    """Search in ` table ` an item with the value of the ` unique _ fields ` in the ` data ` sample .
 Check if the the obtained result is unique . If nothing is found will return an empty list ,
 if there is more than one item found , will raise an IndexError .
 Parameters
 table _ name : str
 sample : dict
 Sample data
 unique _ fields : list of str
 Name of fields ( keys ) from ` data ` which are going to be used to build
 a sample to look for exactly the same values in the database .
 If None , will use every key in ` data ` .
 Returns
 eid : int
 Id of the object found with same ` unique _ fields ` .
 None if none is found .
 Raises
 MoreThanOneItemError
 If more than one example is found ."""

implementation: return search_unique ( table = self . table ( table_name ) , sample = sample , unique_fields = unique_fields )


signature:
def search_sample ( self , table_name , sample ) :
    """Search for items in ` table ` that have the same field sub - set values as in ` sample ` .
 Parameters
 table _ name : str
 sample : dict
 Sample data
 Returns
 search _ result : list of dict
 List of the items found . The list is empty if no item is found ."""

implementation: return search_sample ( table = self . table ( table_name ) , sample = sample )


signature:
def is_unique ( self , table_name , sample , unique_fields = None ) :
    """Return True if an item with the value of ` unique _ fields `
 from ` data ` is unique in the table with ` table _ name ` .
 False if no sample is found or more than one is found .
 See function ` find _ unique ` for more details .
 Parameters
 table _ name : str
 sample : dict
 Sample data for query
 unique _ fields : str or list of str
 Returns
 is _ unique : bool"""

implementation:
try :
    eid = find_unique ( self . table ( table_name ) , sample = sample , unique_fields = unique_fields )
except :
    return False
else :
    return eid is not None


signature:
def update_unique ( self , table_name , fields , data , cond = None , unique_fields = None , * , raise_if_not_found = False ) :
    """Update the unique matching element to have a given set of fields .
 Parameters
 table _ name : str
 fields : dict or function [ dict - > None ]
 new data / values to insert into the unique element
 or a method that will update the elements .
 data : dict
 Sample data for query
 cond : tinydb . Query
 which elements to update
 unique _ fields : list of str
 raise _ if _ not _ found : bool
 Will raise an exception if the element is not found for update .
 Returns
 eid : int
 The eid of the updated element if found , None otherwise ."""

implementation:
eid = find_unique ( self . table ( table_name ) , data , unique_fields )
if eid is None :
    if raise_if_not_found :
        msg = 'Could not find {} with {}' . format ( table_name , data )
        if cond is not None :
            msg += ' where {}.' . format ( cond )
        raise IndexError ( msg )
else :
    self . table ( table_name ) . update ( _to_string ( fields ) , cond = cond , eids = [ eid ] )
return eid


signature:
def count ( self , table_name , sample ) :
    """Return the number of items that match the ` sample ` field values
 in table ` table _ name ` .
 Check function search _ sample for more details ."""

implementation: return len ( list ( search_sample ( table = self . table ( table_name ) , sample = sample ) ) )


signature:
def is_img ( obj ) :
    """Check for get _ data and get _ affine method in an object
 Parameters
 obj : any object
 Tested object
 Returns
 is _ img : boolean
 True if get _ data and get _ affine methods are present and callable ,
 False otherwise ."""

implementation:
try :
    get_data = getattr ( obj , 'get_data' )
    get_affine = getattr ( obj , 'get_affine' )
    return isinstance ( get_data , collections . Callable ) and isinstance ( get_affine , collections . Callable )
except AttributeError :
    return False


signature:
def get_data ( img ) :
    """Get the data in the image without having a side effect on the Nifti1Image object
 Parameters
 img : Nifti1Image
 Returns
 np . ndarray"""

implementation:
if hasattr ( img , '_data_cache' ) and img . _data_cache is None : # Copy locally the nifti _ image to avoid the side effect of data
# loading
    img = copy . deepcopy ( img )
# force garbage collector
gc . collect ( )
return img . get_data ( )


signature:
def get_shape ( img ) :
    """Return the shape of img .
 Paramerers
 img :
 Returns
 shape : tuple"""

implementation:
if hasattr ( img , 'shape' ) :
    shape = img . shape
else :
    shape = img . get_data ( ) . shape
return shape


signature:
def is_valid_coordinate ( img , i , j , k ) :
    """Return True if the given ( i , j , k ) voxel grid coordinate values are within the img boundaries .
 Parameters
 @ param img :
 @ param i :
 @ param j :
 @ param k :
 Returns
 bool"""

implementation:
imgx , imgy , imgz = get_shape ( img )
return ( i >= 0 and i < imgx ) and ( j >= 0 and j < imgy ) and ( k >= 0 and k < imgz )


signature:
def check_img_compatibility ( one_img , another_img , only_check_3d = False ) :
    """Return true if one _ img and another _ img have the same shape .
 False otherwise .
 If both are nibabel . Nifti1Image will also check for affine matrices .
 Parameters
 one _ img : nibabel . Nifti1Image or np . ndarray
 another _ img : nibabel . Nifti1Image or np . ndarray
 only _ check _ 3d : bool
 If True will check only the 3D part of the affine matrices when they have more dimensions .
 Raises
 NiftiFilesNotCompatible"""

implementation:
nd_to_check = None
if only_check_3d :
    nd_to_check = 3
if hasattr ( one_img , 'shape' ) and hasattr ( another_img , 'shape' ) :
    if not have_same_shape ( one_img , another_img , nd_to_check = nd_to_check ) :
        msg = 'Shape of the first image: \n{}\n is different from second one: \n{}' . format ( one_img . shape , another_img . shape )
        raise NiftiFilesNotCompatible ( repr_imgs ( one_img ) , repr_imgs ( another_img ) , message = msg )
if hasattr ( one_img , 'get_affine' ) and hasattr ( another_img , 'get_affine' ) :
    if not have_same_affine ( one_img , another_img , only_check_3d = only_check_3d ) :
        msg = 'Affine matrix of the first image: \n{}\n is different ' 'from second one:\n{}' . format ( one_img . get_affine ( ) , another_img . get_affine ( ) )
        raise NiftiFilesNotCompatible ( repr_imgs ( one_img ) , repr_imgs ( another_img ) , message = msg )


signature:
def have_same_affine ( one_img , another_img , only_check_3d = False ) :
    """Return True if the affine matrix of one _ img is close to the affine matrix of another _ img .
 False otherwise .
 Parameters
 one _ img : nibabel . Nifti1Image
 another _ img : nibabel . Nifti1Image
 only _ check _ 3d : bool
 If True will extract only the 3D part of the affine matrices when they have more dimensions .
 Returns
 bool
 Raises
 ValueError"""

implementation:
img1 = check_img ( one_img )
img2 = check_img ( another_img )
ndim1 = len ( img1 . shape )
ndim2 = len ( img2 . shape )
if ndim1 < 3 :
    raise ValueError ( 'Image {} has only {} dimensions, at least 3 dimensions is expected.' . format ( repr_imgs ( img1 ) , ndim1 ) )
if ndim2 < 3 :
    raise ValueError ( 'Image {} has only {} dimensions, at least 3 dimensions is expected.' . format ( repr_imgs ( img2 ) , ndim1 ) )
affine1 = img1 . get_affine ( )
affine2 = img2 . get_affine ( )
if only_check_3d :
    affine1 = affine1 [ : 3 , : 3 ]
    affine2 = affine2 [ : 3 , : 3 ]
try :
    return np . allclose ( affine1 , affine2 )
except ValueError :
    return False
except :
    raise


signature:
def _make_it_3d ( img ) :
    """Enforce that img is a 3D img - like object , if it is not , raise a TypeError .
 i . e . , remove dimensions of size 1.
 Parameters
 img : img - like object
 Returns
 3D img - like object"""

implementation:
shape = get_shape ( img )
if len ( shape ) == 3 :
    return img
elif ( len ( shape ) == 4 and shape [ 3 ] == 1 ) : # " squeeze " the image .
    try :
        data = get_data ( img )
        affine = img . get_affine ( )
        img = nib . Nifti1Image ( data [ : , : , : , 0 ] , affine )
    except Exception as exc :
        raise Exception ( "Error making image '{}' a 3D volume file." . format ( img ) ) from exc
    else :
        return img
else :
    raise TypeError ( "A 3D image is expected, but an image with a shape of {} was given." . format ( shape ) )


signature:
def check_img ( image , make_it_3d = False ) :
    """Check that image is a proper img . Turn filenames into objects .
 Parameters
 image : img - like object or str
 Can either be :
 - a file path to a Nifti image
 - any object with get _ data ( ) and get _ affine ( ) methods , e . g . , nibabel . Nifti1Image .
 If niimg is a string , consider it as a path to Nifti image and
 call nibabel . load on it . If it is an object , check if get _ data ( )
 and get _ affine ( ) methods are present , raise TypeError otherwise .
 make _ it _ 3d : boolean , optional
 If True , check if the image is a 3D image and raise an error if not .
 Returns
 result : nifti - like
 result can be nibabel . Nifti1Image or the input , as - is . It is guaranteed
 that the returned object has get _ data ( ) and get _ affine ( ) methods ."""

implementation:
if isinstance ( image , string_types ) : # a filename , load it
    if not op . exists ( image ) :
        raise FileNotFound ( image )
    try :
        img = nib . load ( image )
        if make_it_3d :
            img = _make_it_3d ( img )
    except Exception as exc :
        raise Exception ( 'Error loading image file {}.' . format ( image ) ) from exc
    else :
        return img
elif isinstance ( image , nib . Nifti1Image ) or is_img ( image ) :
    return image
else :
    raise TypeError ( 'Data given cannot be converted to a nifti' ' image: this object -"{}"- does not have' ' get_data or get_affine methods' . format ( type ( image ) ) )


signature:
def repr_imgs ( imgs ) :
    """Printing of img or imgs"""

implementation:
if isinstance ( imgs , string_types ) :
    return imgs
if isinstance ( imgs , collections . Iterable ) :
    return '[{}]' . format ( ', ' . join ( repr_imgs ( img ) for img in imgs ) )
# try get _ filename
try :
    filename = imgs . get_filename ( )
    if filename is not None :
        img_str = "{}('{}')" . format ( imgs . __class__ . __name__ , filename )
    else :
        img_str = "{}(shape={}, affine={})" . format ( imgs . __class__ . __name__ , repr ( get_shape ( imgs ) ) , repr ( imgs . get_affine ( ) ) )
except Exception as exc :
    log . error ( 'Error reading attributes from img.get_filename()' )
    return repr ( imgs )
else :
    return img_str


signature:
def have_same_shape ( array1 , array2 , nd_to_check = None ) :
    """Returns true if array1 and array2 have the same shapes , false
 otherwise .
 Parameters
 array1 : numpy . ndarray
 array2 : numpy . ndarray
 nd _ to _ check : int
 Number of the dimensions to check , i . e . , if = = 3 then will check only the 3 first numbers of array . shape .
 Returns
 bool"""

implementation:
shape1 = array1 . shape
shape2 = array2 . shape
if nd_to_check is not None :
    if len ( shape1 ) < nd_to_check :
        msg = 'Number of dimensions to check {} is out of bounds for the shape of the first image: \n{}\n.' . format ( shape1 )
        raise ValueError ( msg )
    elif len ( shape2 ) < nd_to_check :
        msg = 'Number of dimensions to check {} is out of bounds for the shape of the second image: \n{}\n.' . format ( shape2 )
        raise ValueError ( msg )
    shape1 = shape1 [ : nd_to_check ]
    shape2 = shape2 [ : nd_to_check ]
return shape1 == shape2


signature:
def have_same_geometry ( fname1 , fname2 ) :
    """@ param fname1 : string
 File path of an image
 @ param fname2 : string
 File path of an image
 @ return : bool
 True if both have the same geometry"""

implementation:
img1shape = nib . load ( fname1 ) . get_shape ( )
img2shape = nib . load ( fname2 ) . get_shape ( )
return have_same_shape ( img1shape , img2shape )


signature:
def have_same_spatial_geometry ( fname1 , fname2 ) :
    """@ param fname1 : string
 File path of an image
 @ param fname2 : string
 File path of an image
 @ return : bool
 True if both have the same geometry"""

implementation:
img1shape = nib . load ( fname1 ) . get_shape ( )
img2shape = nib . load ( fname2 ) . get_shape ( )
return img1shape [ : 3 ] == img2shape [ : 3 ]


signature:
def dir_match ( regex , wd = os . curdir ) :
    """Create a list of regex matches that result from the match _ regex
 of all file names within wd .
 The list of files will have wd as path prefix .
 @ param regex : string
 @ param wd : string
 working directory
 @ return :"""

implementation:
ls = os . listdir ( wd )
filt = re . compile ( regex ) . match
return filter_list ( ls , filt )


signature:
def recursive_dir_match ( folder_path , regex = '' ) :
    """Returns absolute paths of folders that match the regex within folder _ path and
 all its children folders .
 Note : The regex matching is done using the match function
 of the re module .
 Parameters
 folder _ path : string
 regex : string
 Returns
 A list of strings ."""

implementation:
outlist = [ ]
for root , dirs , files in os . walk ( folder_path ) :
    outlist . extend ( [ op . join ( root , f ) for f in dirs if re . match ( regex , f ) ] )
return outlist


signature:
def get_file_list ( file_dir , regex = '' ) :
    """Creates a list of files that match the search _ regex within file _ dir .
 The list of files will have file _ dir as path prefix .
 Parameters
 @ param file _ dir :
 @ param search _ regex :
 Returns :
 List of paths to files that match the search _ regex"""

implementation:
file_list = os . listdir ( file_dir )
file_list . sort ( )
if regex :
    file_list = search_list ( file_list , regex )
file_list = [ op . join ( file_dir , fname ) for fname in file_list ]
return file_list


signature:
def recursive_find_search ( folder_path , regex = '' ) :
    """Returns absolute paths of files that match the regex within file _ dir and
 all its children folders .
 Note : The regex matching is done using the search function
 of the re module .
 Parameters
 folder _ path : string
 regex : string
 Returns
 A list of strings ."""

implementation:
outlist = [ ]
for root , dirs , files in os . walk ( folder_path ) :
    outlist . extend ( [ op . join ( root , f ) for f in files if re . search ( regex , f ) ] )
return outlist


signature:
def iter_recursive_find ( folder_path , * regex ) :
    """Returns absolute paths of files that match the regexs within folder _ path and
 all its children folders .
 This is an iterator function that will use yield to return each set of
 file _ paths in one iteration .
 Will only return value if all the strings in regex match a file name .
 Note : The regex matching is done using the search function
 of the re module .
 Parameters
 folder _ path : string
 regex : strings
 Returns
 A list of strings ."""

implementation:
for root , dirs , files in os . walk ( folder_path ) :
    if len ( files ) > 0 :
        outlist = [ ]
        for f in files :
            for reg in regex :
                if re . search ( reg , f ) :
                    outlist . append ( op . join ( root , f ) )
        if len ( outlist ) == len ( regex ) :
            yield outlist


signature:
def get_all_files ( folder ) :
    """Generator that loops through all absolute paths of the files within folder
 Parameters
 folder : str
 Root folder start point for recursive search .
 Yields
 fpath : str
 Absolute path of one file in the folders"""

implementation:
for path , dirlist , filelist in os . walk ( folder ) :
    for fn in filelist :
        yield op . join ( path , fn )


signature:
def recursive_glob ( base_directory , regex = '' ) :
    """Uses glob to find all files or folders that match the regex
 starting from the base _ directory .
 Parameters
 base _ directory : str
 regex : str
 Returns
 files : list"""

implementation:
files = glob ( op . join ( base_directory , regex ) )
for path , dirlist , filelist in os . walk ( base_directory ) :
    for dir_name in dirlist :
        files . extend ( glob ( op . join ( path , dir_name , regex ) ) )
return files


signature:
def get_last_file ( input_dir , glob_pattern = '*' , key = op . getctime , reverse = True ) :
    """Return the path to the latest file in ` input _ dir ` .
 The ` key ` argument defines which information to use for sorting
 the list of files , could be :
 - creation date : os . path . getctime ,
 - modification date : os . path . getmtime ,
 etc .
 Parameters
 input _ dir : str
 Path to the folder where to perform the ` glob ` .
 glob _ pattern : str
 ` glob ` Pattern to filter the files in ` input _ dir ` .
 key : str
 Sorting key function
 reverse : bool
 Set to True if you want the sorting to be in decreasing order ,
 False otherwise .
 Returns
 latest _ filepath : str
 Path to the latest modified file in ` input _ dir ` ."""

implementation:
files = glob ( op . join ( input_dir , glob_pattern ) )
files . sort ( key = key , reverse = reverse )
return files [ 0 ]


signature:
def compose_err_msg ( msg , ** kwargs ) :
    """Append key - value pairs to msg , for display .
 Parameters
 msg : string
 arbitrary message
 kwargs : dict
 arbitrary dictionary
 Returns
 updated _ msg : string
 msg , with " key : value " appended . Only string values are appended .
 Example
 > > > compose _ err _ msg ( ' Error message with arguments . . . ' , arg _ num = 123 , arg _ str = ' filename . nii ' , arg _ bool = True )
 ' Error message with arguments . . . \\ narg _ str : filename . nii '"""

implementation:
updated_msg = msg
for k , v in sorted ( kwargs . items ( ) ) :
    if isinstance ( v , _basestring ) : # print only str - like arguments
        updated_msg += "\n" + k + ": " + v
return updated_msg


signature:
def group_dicom_files ( dicom_file_paths , header_fields ) :
    """Gets a list of DICOM file absolute paths and returns a list of lists of
 DICOM file paths . Each group contains a set of DICOM files that have
 exactly the same headers .
 Parameters
 dicom _ file _ paths : list of str
 List or set of DICOM file paths
 header _ fields : list of str
 List of header field names to check on the comparisons of the DICOM files .
 Returns
 dict of DicomFileSets
 The key is one filepath representing the group ( the first found ) ."""

implementation:
dist = SimpleDicomFileDistance ( field_weights = header_fields )
path_list = dicom_file_paths . copy ( )
path_groups = DefaultOrderedDict ( DicomFileSet )
while len ( path_list ) > 0 :
    file_path1 = path_list . pop ( )
    file_subgroup = [ file_path1 ]
    dist . set_dicom_file1 ( file_path1 )
    j = len ( path_list ) - 1
    while j >= 0 :
        file_path2 = path_list [ j ]
        dist . set_dicom_file2 ( file_path2 )
        if dist . transform ( ) :
            file_subgroup . append ( file_path2 )
            path_list . pop ( j )
        j -= 1
    path_groups [ file_path1 ] . from_set ( file_subgroup , check_if_dicoms = False )
return path_groups


signature:
def copy_groups_to_folder ( dicom_groups , folder_path , groupby_field_name ) :
    """Copy the DICOM file groups to folder _ path . Each group will be copied into
 a subfolder with named given by groupby _ field .
 Parameters
 dicom _ groups : boyle . dicom . sets . DicomFileSet
 folder _ path : str
 Path to where copy the DICOM files .
 groupby _ field _ name : str
 DICOM field name . Will get the value of this field to name the group
 folder ."""

implementation:
if dicom_groups is None or not dicom_groups :
    raise ValueError ( 'Expected a boyle.dicom.sets.DicomFileSet.' )
if not os . path . exists ( folder_path ) :
    os . makedirs ( folder_path , exist_ok = False )
for dcmg in dicom_groups :
    if groupby_field_name is not None and len ( groupby_field_name ) > 0 :
        dfile = DicomFile ( dcmg )
        dir_name = ''
        for att in groupby_field_name :
            dir_name = os . path . join ( dir_name , dfile . get_attributes ( att ) )
        dir_name = str ( dir_name )
    else :
        dir_name = os . path . basename ( dcmg )
    group_folder = os . path . join ( folder_path , dir_name )
    os . makedirs ( group_folder , exist_ok = False )
    log . debug ( 'Copying files to {}.' . format ( group_folder ) )
    import shutil
    dcm_files = dicom_groups [ dcmg ]
    for srcf in dcm_files :
        destf = os . path . join ( group_folder , os . path . basename ( srcf ) )
        while os . path . exists ( destf ) :
            destf += '+'
        shutil . copy2 ( srcf , destf )


signature:
def calculate_file_distances ( dicom_files , field_weights = None , dist_method_cls = None , ** kwargs ) :
    """Calculates the DicomFileDistance between all files in dicom _ files , using an
 weighted Levenshtein measure between all field names in field _ weights and
 their corresponding weights .
 Parameters
 dicom _ files : iterable of str
 Dicom file paths
 field _ weights : dict of str to float
 A dict with header field names to float scalar values , that
 indicate a distance measure ratio for the levenshtein distance
 averaging of all the header field names in it . e . g . , { ' PatientID ' : 1}
 dist _ method _ cls : DicomFileDistance class
 Distance method object to compare the files .
 If None , the default DicomFileDistance method using Levenshtein
 distance between the field _ wieghts will be used .
 kwargs : DicomFileDistance instantiation named arguments
 Apart from the field _ weitghts argument .
 Returns
 file _ dists : np . ndarray or scipy . sparse . lil _ matrix of shape NxN
 Levenshtein distances between each of the N items in dicom _ files ."""

implementation:
if dist_method_cls is None :
    dist_method = LevenshteinDicomFileDistance ( field_weights )
else :
    try :
        dist_method = dist_method_cls ( field_weights = field_weights , ** kwargs )
    except :
        log . exception ( 'Could not instantiate {} object with field_weights ' 'and {}' . format ( dist_method_cls , kwargs ) )
dist_dtype = np . float16
n_files = len ( dicom_files )
try :
    file_dists = np . zeros ( ( n_files , n_files ) , dtype = dist_dtype )
except MemoryError as mee :
    import scipy . sparse
    file_dists = scipy . sparse . lil_matrix ( ( n_files , n_files ) , dtype = dist_dtype )
for idxi in range ( n_files ) :
    dist_method . set_dicom_file1 ( dicom_files [ idxi ] )
    for idxj in range ( idxi + 1 , n_files ) :
        dist_method . set_dicom_file2 ( dicom_files [ idxj ] )
        if idxi != idxj :
            file_dists [ idxi , idxj ] = dist_method . transform ( )
return file_dists


signature:
def fit ( self , dcm_file1 , dcm_file2 ) :
    """Parameters
 dcm _ file1 : str ( path to file ) or DicomFile or namedtuple
 dcm _ file2 : str ( path to file ) or DicomFile or namedtuple"""

implementation:
self . set_dicom_file1 ( dcm_file1 )
self . set_dicom_file2 ( dcm_file2 )


signature:
def transform ( self ) :
    """Check the field values in self . dcmf1 and self . dcmf2 and returns True
 if all the field values are the same , False otherwise .
 Returns
 bool"""

implementation:
if self . dcmf1 is None or self . dcmf2 is None :
    return np . inf
for field_name in self . field_weights :
    if ( str ( getattr ( self . dcmf1 , field_name , '' ) ) != str ( getattr ( self . dcmf2 , field_name , '' ) ) ) :
        return False
return True


signature:
def levenshtein_analysis ( self , field_weights = None ) :
    """Updates the status of the file clusters comparing the cluster
 key files with a levenshtein weighted measure using either the
 header _ fields or self . header _ fields .
 Parameters
 field _ weights : dict of strings with floats
 A dict with header field names to float scalar values , that indicate a distance measure
 ratio for the levenshtein distance averaging of all the header field names in it .
 e . g . , { ' PatientID ' : 1}"""

implementation:
if field_weights is None :
    if not isinstance ( self . field_weights , dict ) :
        raise ValueError ( 'Expected a dict for `field_weights` parameter, ' 'got {}' . format ( type ( self . field_weights ) ) )
key_dicoms = list ( self . dicom_groups . keys ( ) )
file_dists = calculate_file_distances ( key_dicoms , field_weights , self . _dist_method_cls )
return file_dists


signature:
def dist_percentile_threshold ( dist_matrix , perc_thr = 0.05 , k = 1 ) :
    """Thresholds a distance matrix and returns the result .
 Parameters
 dist _ matrix : array _ like
 Input array or object that can be converted to an array .
 perc _ thr : float in range of [ 0,100]
 Percentile to compute which must be between 0 and 100 inclusive .
 k : int , optional
 Diagonal above which to zero elements .
 k = 0 ( the default ) is the main diagonal ,
 k < 0 is below it and k > 0 is above .
 Returns
 array _ like"""

implementation:
triu_idx = np . triu_indices ( dist_matrix . shape [ 0 ] , k = k )
upper = np . zeros_like ( dist_matrix )
upper [ triu_idx ] = dist_matrix [ triu_idx ] < np . percentile ( dist_matrix [ triu_idx ] , perc_thr )
return upper


signature:
def get_groups_in_same_folder ( self , folder_depth = 3 ) :
    """Returns a list of 2 - tuples with pairs of dicom groups that
 are in the same folder within given depth .
 Parameters
 folder _ depth : int
 Path depth to check for folder equality .
 Returns
 list of tuples of str"""

implementation:
group_pairs = [ ]
key_dicoms = list ( self . dicom_groups . keys ( ) )
idx = len ( key_dicoms )
while idx > 0 :
    group1 = key_dicoms . pop ( )
    dir_group1 = get_folder_subpath ( group1 , folder_depth )
    for group in key_dicoms :
        if group . startswith ( dir_group1 ) :
            group_pairs . append ( ( group1 , group ) )
    idx -= 1
return group_pairs


signature:
def plot_file_distances ( dist_matrix ) :
    """Plots dist _ matrix
 Parameters
 dist _ matrix : np . ndarray"""

implementation:
import matplotlib . pyplot as plt
fig = plt . figure ( )
ax = fig . add_subplot ( 111 )
ax . matshow ( dist_matrix , interpolation = 'nearest' , cmap = plt . cm . get_cmap ( 'PuBu' ) )


signature:
def merge_groups ( self , indices ) :
    """Extend the lists within the DICOM groups dictionary .
 The indices will indicate which list have to be extended by which
 other list .
 Parameters
 indices : list or tuple of 2 iterables of int , bot having the same len
 The indices of the lists that have to be merged , both iterables
 items will be read pair by pair , the first is the index to the
 list that will be extended with the list of the second index .
 The indices can be constructed with Numpy e . g . ,
 indices = np . where ( square _ matrix )"""

implementation:
try :
    merged = merge_dict_of_lists ( self . dicom_groups , indices , pop_later = True , copy = True )
    self . dicom_groups = merged
except IndexError :
    raise IndexError ( 'Index out of range to merge DICOM groups.' )


signature:
def move_to_folder ( self , folder_path , groupby_field_name = None ) :
    """Copy the file groups to folder _ path . Each group will be copied into
 a subfolder with named given by groupby _ field .
 Parameters
 folder _ path : str
 Path to where copy the DICOM files .
 groupby _ field _ name : str
 DICOM field name . Will get the value of this field to name the group
 folder . If empty or None will use the basename of the group key file ."""

implementation:
try :
    copy_groups_to_folder ( self . dicom_groups , folder_path , groupby_field_name )
except IOError as ioe :
    raise IOError ( 'Error moving dicom groups to {}.' . format ( folder_path ) ) from ioe


signature:
def get_unique_field_values_per_group ( self , field_name , field_to_use_as_key = None ) :
    """Return a dictionary where the key is the group key file path and
 the values are sets of unique values of the field name of all DICOM
 files in the group .
 Parameters
 field _ name : str
 Name of the field to read from all files
 field _ to _ use _ as _ key : str
 Name of the field to get the value and use as key .
 If None , will use the same key as the dicom _ groups .
 Returns
 Dict of sets"""

implementation:
unique_vals = DefaultOrderedDict ( set )
for dcmg in self . dicom_groups :
    for f in self . dicom_groups [ dcmg ] :
        field_val = DicomFile ( f ) . get_attributes ( field_name )
        key_val = dcmg
        if field_to_use_as_key is not None :
            try :
                key_val = str ( DicomFile ( dcmg ) . get_attributes ( field_to_use_as_key ) )
            except KeyError as ke :
                raise KeyError ( 'Error getting field {} from ' 'file {}' . format ( field_to_use_as_key , dcmg ) ) from ke
        unique_vals [ key_val ] . add ( field_val )
return unique_vals


signature:
def get_config_value ( name , fallback = None ) :
    """Gets a config by name .
 In the case where the config name is not found , will use fallback value ."""

implementation:
cli_config = CLIConfig ( SF_CLI_CONFIG_DIR , SF_CLI_ENV_VAR_PREFIX )
return cli_config . get ( 'servicefabric' , name , fallback )


signature:
def get_config_bool ( name ) :
    """Checks if a config value is set to a valid bool value ."""

implementation:
cli_config = CLIConfig ( SF_CLI_CONFIG_DIR , SF_CLI_ENV_VAR_PREFIX )
return cli_config . getboolean ( 'servicefabric' , name , False )


signature:
def set_config_value ( name , value ) :
    """Set a config by name to a value ."""

implementation:
cli_config = CLIConfig ( SF_CLI_CONFIG_DIR , SF_CLI_ENV_VAR_PREFIX )
cli_config . set_value ( 'servicefabric' , name , value )


signature:
def cert_info ( ) :
    """Path to certificate related files , either a single file path or a
 tuple . In the case of no security , returns None ."""

implementation:
sec_type = security_type ( )
if sec_type == 'pem' :
    return get_config_value ( 'pem_path' , fallback = None )
if sec_type == 'cert' :
    cert_path = get_config_value ( 'cert_path' , fallback = None )
    key_path = get_config_value ( 'key_path' , fallback = None )
    return cert_path , key_path
return None


signature:
def set_aad_cache ( token , cache ) :
    """Set AAD token cache ."""

implementation:
set_config_value ( 'aad_token' , jsonpickle . encode ( token ) )
set_config_value ( 'aad_cache' , jsonpickle . encode ( cache ) )


signature:
def set_aad_metadata ( uri , resource , client ) :
    """Set AAD metadata ."""

implementation:
set_config_value ( 'authority_uri' , uri )
set_config_value ( 'aad_resource' , resource )
set_config_value ( 'aad_client' , client )


signature:
def set_auth ( pem = None , cert = None , key = None , aad = False ) :
    """Set certificate usage paths"""

implementation:
if any ( [ cert , key ] ) and pem :
    raise ValueError ( 'Cannot specify both pem and cert or key' )
if any ( [ cert , key ] ) and not all ( [ cert , key ] ) :
    raise ValueError ( 'Must specify both cert and key' )
if pem :
    set_config_value ( 'security' , 'pem' )
    set_config_value ( 'pem_path' , pem )
elif cert or key :
    set_config_value ( 'security' , 'cert' )
    set_config_value ( 'cert_path' , cert )
    set_config_value ( 'key_path' , key )
elif aad :
    set_config_value ( 'security' , 'aad' )
else :
    set_config_value ( 'security' , 'none' )


signature:
def filter_objlist ( olist , fieldname , fieldval ) :
    """Returns a list with of the objects in olist that have a fieldname valued as fieldval
 Parameters
 olist : list of objects
 fieldname : string
 fieldval : anything
 Returns
 list of objets"""

implementation: return [ x for x in olist if getattr ( x , fieldname ) == fieldval ]


signature:
def filter_list ( lst , filt ) :
    """Parameters
 lst : list
 filter : function
 Unary string filter function
 Returns
 list
 List of items that passed the filter
 Example
 > > > l = [ ' 12123123 ' , ' N123213 ' ]
 > > > filt = re . compile ( ' \ d * ' ) . match
 > > > nu _ l = list _ filter ( l , filt )"""

implementation: return [ m for s in lst for m in ( filt ( s ) , ) if m ]


signature:
def match_list ( lst , pattern , group_names = [ ] ) :
    """Parameters
 lst : list of str
 regex : string
 group _ names : list of strings
 See re . MatchObject group docstring
 Returns
 list of strings
 Filtered list , with the strings that match the pattern"""

implementation:
filtfn = re . compile ( pattern ) . match
filtlst = filter_list ( lst , filtfn )
if not group_names :
    return [ m . string for m in filtlst ]
else :
    return [ m . group ( group_names ) for m in filtlst ]


signature:
def append_to_keys ( adict , preffix ) :
    """Parameters
 adict :
 preffix :
 Returns"""

implementation: return { preffix + str ( key ) : ( value if isinstance ( value , dict ) else value ) for key , value in list ( adict . items ( ) ) }


signature:
def is_valid_regex ( string ) :
    """Checks whether the re module can compile the given regular expression .
 Parameters
 string : str
 Returns
 boolean"""

implementation:
try :
    re . compile ( string )
    is_valid = True
except re . error :
    is_valid = False
return is_valid


signature:
def is_regex ( string ) :
    """TODO : improve this !
 Returns True if the given string is considered a regular expression ,
 False otherwise .
 It will be considered a regex if starts with a non alphabetic character
 and then correctly compiled by re . compile
 : param string : str"""

implementation:
is_regex = False
regex_chars = [ '\\' , '(' , '+' , '^' , '$' ]
for c in regex_chars :
    if string . find ( c ) > - 1 :
        return is_valid_regex ( string )
return is_regex


signature:
def is_fnmatch_regex ( string ) :
    """Returns True if the given string is considered a fnmatch
 regular expression , False otherwise .
 It will look for
 : param string : str"""

implementation:
is_regex = False
regex_chars = [ '!' , '*' , '$' ]
for c in regex_chars :
    if string . find ( c ) > - 1 :
        return True
return is_regex


signature:
def where_is ( strings , pattern , n = 1 , lookup_func = re . match ) :
    """Return index of the nth match found of pattern in strings
 Parameters
 strings : list of str
 List of strings
 pattern : str
 Pattern to be matched
 nth : int
 Number of times the match must happen to return the item index .
 lookup _ func : callable
 Function to match each item in strings to the pattern , e . g . , re . match or re . search .
 Returns
 index : int
 Index of the nth item that matches the pattern .
 If there are no n matches will return - 1"""

implementation:
count = 0
for idx , item in enumerate ( strings ) :
    if lookup_func ( pattern , item ) :
        count += 1
        if count == n :
            return idx
return - 1


signature:
def generate_config ( output_directory ) :
    """Generate a dcm2nii configuration file that disable the interactive
 mode ."""

implementation:
if not op . isdir ( output_directory ) :
    os . makedirs ( output_directory )
config_file = op . join ( output_directory , "config.ini" )
open_file = open ( config_file , "w" )
open_file . write ( "[BOOL]\nManualNIfTIConv=0\n" )
open_file . close ( )
return config_file


signature:
def add_meta_to_nii ( nii_file , dicom_file , dcm_tags = '' ) :
    """Add slice duration and acquisition times to the headers of the nifit1 files in ` nii _ file ` .
 It will add the repetition time of the DICOM file ( field : { 0x0018 , 0x0080 , DS , Repetition Time } )
 to the NifTI file as well as any other tag in ` dcm _ tags ` .
 All selected DICOM tags values are set in the ` descrip ` nifti header field .
 Note that this will modify the header content of ` nii _ file ` .
 Parameters
 nii _ files : str
 Path to the NifTI file to modify .
 dicom _ file : str
 Paths to the DICOM file from where to get the meta data .
 dcm _ tags : list of str
 List of tags from the DICOM file to read and store in the nifti file ."""

implementation:
# Load a dicom image
dcmimage = dicom . read_file ( dicom_file )
# Load the nifti1 image
image = nibabel . load ( nii_file )
# Check the we have a nifti1 format image
if not isinstance ( image , nibabel . nifti1 . Nifti1Image ) :
    raise Exception ( "Only Nifti1 image are supported not '{0}'." . format ( type ( image ) ) )
# check if dcm _ tags is one string , if yes put it in a list :
if isinstance ( dcm_tags , str ) :
    dcm_tags = [ dcm_tags ]
# Fill the nifti1 header
header = image . get_header ( )
# slice _ duration : Time for 1 slice
repetition_time = float ( dcmimage [ ( "0x0018" , "0x0080" ) ] . value )
header . set_dim_info ( slice = 2 )
nb_slices = header . get_n_slices ( )
# Force round to 0 digit after coma . If more , nibabel completes to
# 6 digits with random numbers . . .
slice_duration = round ( repetition_time / nb_slices , 0 )
header . set_slice_duration ( slice_duration )
# add free dicom fields
if dcm_tags :
    content = [ "{0}={1}" . format ( name , dcmimage [ tag ] . value ) for name , tag in dcm_tags ]
    free_field = numpy . array ( ";" . join ( content ) , dtype = header [ "descrip" ] . dtype )
    image . get_header ( ) [ "descrip" ] = free_field
# Update the image header
image . update_header ( )
# Save the filled image
nibabel . save ( image , nii_file )


signature:
def call_dcm2nii ( work_dir , arguments = '' ) :
    """Converts all DICOM files within ` work _ dir ` into one or more
 NifTi files by calling dcm2nii on this folder .
 Parameters
 work _ dir : str
 Path to the folder that contain the DICOM files
 arguments : str
 String containing all the flag arguments for ` dcm2nii ` CLI .
 Returns
 sys _ code : int
 dcm2nii execution return code"""

implementation:
if not op . exists ( work_dir ) :
    raise IOError ( 'Folder {} not found.' . format ( work_dir ) )
cmd_line = 'dcm2nii {0} "{1}"' . format ( arguments , work_dir )
log . info ( cmd_line )
return subprocess . check_call ( cmd_line , shell = True )


signature:
def convert_dcm2nii ( input_dir , output_dir , filename ) :
    """Call MRICron ' s ` dcm2nii ` to convert the DICOM files inside ` input _ dir `
 to Nifti and save the Nifti file in ` output _ dir ` with a ` filename ` prefix .
 Parameters
 input _ dir : str
 Path to the folder that contains the DICOM files
 output _ dir : str
 Path to the folder where to save the NifTI file
 filename : str
 Output file basename
 Returns
 filepaths : list of str
 List of file paths created in ` output _ dir ` ."""

implementation:
# a few checks before doing the job
if not op . exists ( input_dir ) :
    raise IOError ( 'Expected an existing folder in {}.' . format ( input_dir ) )
if not op . exists ( output_dir ) :
    raise IOError ( 'Expected an existing output folder in {}.' . format ( output_dir ) )
# create a temporary folder for dcm2nii export
tmpdir = tempfile . TemporaryDirectory ( prefix = 'dcm2nii_' )
# call dcm2nii
arguments = '-o "{}" -i y' . format ( tmpdir . name )
try :
    call_out = call_dcm2nii ( input_dir , arguments )
except :
    raise
else :
    log . info ( 'Converted "{}" to nifti.' . format ( input_dir ) )
    # get the filenames of the files that dcm2nii produced
    filenames = glob ( op . join ( tmpdir . name , '*.nii*' ) )
    # cleanup ` filenames ` , using only the post - processed ( reoriented , cropped , etc . ) images by dcm2nii
    cleaned_filenames = remove_dcm2nii_underprocessed ( filenames )
    # copy files to the output _ dir
    filepaths = [ ]
    for srcpath in cleaned_filenames :
        dstpath = op . join ( output_dir , filename )
        realpath = copy_w_plus ( srcpath , dstpath )
        filepaths . append ( realpath )
        # copy any other file produced by dcm2nii that is not a NifTI file , e . g . , * . bvals , * . bvecs , etc .
        basename = op . basename ( remove_ext ( srcpath ) )
        aux_files = set ( glob ( op . join ( tmpdir . name , '{}.*' . format ( basename ) ) ) ) - set ( glob ( op . join ( tmpdir . name , '{}.nii*' . format ( basename ) ) ) )
        for aux_file in aux_files :
            aux_dstpath = copy_w_ext ( aux_file , output_dir , remove_ext ( op . basename ( realpath ) ) )
            filepaths . append ( aux_dstpath )
    return filepaths


signature:
def remove_dcm2nii_underprocessed ( filepaths ) :
    """Return a subset of ` filepaths ` . Keep only the files that have a basename longer than the
 others with same suffix .
 This works based on that dcm2nii appends a preffix character for each processing
 step it does automatically in the DICOM to NifTI conversion .
 Parameters
 filepaths : iterable of str
 Returns
 cleaned _ paths : iterable of str"""

implementation:
cln_flist = [ ]
# sort them by size
len_sorted = sorted ( filepaths , key = len )
for idx , fpath in enumerate ( len_sorted ) :
    remove = False
    # get the basename and the rest of the files
    fname = op . basename ( fpath )
    rest = len_sorted [ idx + 1 : ]
    # check if the basename is in the basename of the rest of the files
    for rest_fpath in rest :
        rest_file = op . basename ( rest_fpath )
        if rest_file . endswith ( fname ) :
            remove = True
            break
    if not remove :
        cln_flist . append ( fpath )
return cln_flist


signature:
def dictify ( a_named_tuple ) :
    """Transform a named tuple into a dictionary"""

implementation: return dict ( ( s , getattr ( a_named_tuple , s ) ) for s in a_named_tuple . _fields )


signature:
def merge_dict_of_lists ( adict , indices , pop_later = True , copy = True ) :
    """Extend the within a dict of lists . The indices will indicate which
 list have to be extended by which other list .
 Parameters
 adict : OrderedDict
 An ordered dictionary of lists
 indices : list or tuple of 2 iterables of int , bot having the same length
 The indices of the lists that have to be merged , both iterables items
 will be read pair by pair , the first is the index to the list that
 will be extended with the list of the second index .
 The indices can be constructed with Numpy e . g . ,
 indices = np . where ( square _ matrix )
 pop _ later : bool
 If True will oop out the lists that are indicated in the second
 list of indices .
 copy : bool
 If True will perform a deep copy of the input adict before
 modifying it , hence not changing the original input .
 Returns
 Dictionary of lists
 Raises
 IndexError
 If the indices are out of range"""

implementation:
def check_indices ( idxs , x ) :
    for i in chain ( * idxs ) :
        if i < 0 or i >= x :
            raise IndexError ( "Given indices are out of dict range." )
check_indices ( indices , len ( adict ) )
rdict = adict . copy ( ) if copy else adict
dict_keys = list ( rdict . keys ( ) )
for i , j in zip ( * indices ) :
    rdict [ dict_keys [ i ] ] . extend ( rdict [ dict_keys [ j ] ] )
if pop_later :
    for i , j in zip ( * indices ) :
        rdict . pop ( dict_keys [ j ] , '' )
return rdict


signature:
def append_dict_values ( list_of_dicts , keys = None ) :
    """Return a dict of lists from a list of dicts with the same keys .
 For each dict in list _ of _ dicts with look for the values of the
 given keys and append it to the output dict .
 Parameters
 list _ of _ dicts : list of dicts
 keys : list of str
 List of keys to create in the output dict
 If None will use all keys in the first element of list _ of _ dicts
 Returns
 DefaultOrderedDict of lists"""

implementation:
if keys is None :
    keys = list ( list_of_dicts [ 0 ] . keys ( ) )
dict_of_lists = DefaultOrderedDict ( list )
for d in list_of_dicts :
    for k in keys :
        dict_of_lists [ k ] . append ( d [ k ] )
return dict_of_lists


signature:
def import_pyfile ( filepath , mod_name = None ) :
    """Imports the contents of filepath as a Python module .
 : param filepath : string
 : param mod _ name : string
 Name of the module when imported
 : return : module
 Imported module"""

implementation:
import sys
if sys . version_info . major == 3 :
    import importlib . machinery
    loader = importlib . machinery . SourceFileLoader ( '' , filepath )
    mod = loader . load_module ( mod_name )
else :
    import imp
    mod = imp . load_source ( mod_name , filepath )
return mod


signature:
def copy ( configfile = '' , destpath = '' , overwrite = False , sub_node = '' ) :
    """Copies the files in the built file tree map
 to despath .
 : param configfile : string
 Path to the FileTreeMap config file
 : param destpath : string
 Path to the files destination
 : param overwrite : bool
 Overwrite files if they already exist .
 : param sub _ node : string
 Tree map configuration sub path .
 Will copy only the contents within this sub - node"""

implementation:
log . info ( 'Running {0} {1} {2}' . format ( os . path . basename ( __file__ ) , whoami ( ) , locals ( ) ) )
assert ( os . path . isfile ( configfile ) )
if os . path . exists ( destpath ) :
    if os . listdir ( destpath ) :
        raise FolderAlreadyExists ( 'Folder {0} already exists. Please clean ' 'it or change destpath.' . format ( destpath ) )
else :
    log . info ( 'Creating folder {0}' . format ( destpath ) )
    path ( destpath ) . makedirs_p ( )
from boyle . files . file_tree_map import FileTreeMap
file_map = FileTreeMap ( )
try :
    file_map . from_config_file ( configfile )
except Exception as e :
    raise FileTreeMapError ( str ( e ) )
if sub_node :
    sub_map = file_map . get_node ( sub_node )
    if not sub_map :
        raise FileTreeMapError ( 'Could not find sub node ' '{0}' . format ( sub_node ) )
    file_map . _filetree = { }
    file_map . _filetree [ sub_node ] = sub_map
try :
    file_map . copy_to ( destpath , overwrite = overwrite )
except Exception as e :
    raise FileTreeMapError ( str ( e ) )


signature:
def get_noneid_references ( self ) :
    """Returns
 ndarray
 Array of references in self . reflst whose self id is None ."""

implementation:
# return [ self . reflst [ idx ] for idx , idval in enumerate ( self ) if idval is None ]
try :
    nun = np . array ( None ) . astype ( self . dtype )
    return np . array ( self . reflst ) [ self == nun ]
except :
    nun = None
    return np . array ( self . reflst ) [ self is None ]


signature:
def _print_general_vs_table ( self , idset1 , idset2 ) :
    """: param idset1:
 : param idset2:"""

implementation:
ref1name = ''
set1_hasref = isinstance ( idset1 , idset_with_reference )
if set1_hasref :
    ref1arr = np . array ( idset1 . reflst )
    ref1name = idset1 . refname
ref2name = ref1name
set2_hasref = isinstance ( idset2 , idset_with_reference )
if set2_hasref :
    ref2arr = np . array ( idset2 . reflst )
    ref2name = idset2 . refname
else :
    ref2name = ref1name
# First show a general table
hdr11 = '{0} > {1}' . format ( idset1 . name , idset2 . name )
hdr12 = '{0} > {1} {2}' . format ( idset1 . name , idset2 . name , ref2name )
hdr13 = '{0} < {1}' . format ( idset1 . name , idset2 . name )
hdr14 = '{0} < {1} {2}' . format ( idset1 . name , idset2 . name , ref1name )
table = [ [ hdr11 , hdr12 , hdr13 , hdr14 ] ]
set1 = set ( idset1 )
set2 = set ( idset2 )
row11 = list ( set1 - set2 )
if set1_hasref :
    row12 = [ ref1arr [ np . where ( idset1 == nom ) ] [ 0 ] for nom in row11 ]
else :
    row12 = [ 'Not found' for _ in row11 ]
row13 = list ( set2 - set1 )
if set2_hasref :
    row14 = [ ref2arr [ np . where ( idset2 == nom ) ] [ 0 ] for nom in row13 ]
else :
    row14 = [ 'Not found' for _ in row13 ]
tablst = self . _tabulate_4_lists ( row11 , row12 , row13 , row14 )
table . extend ( tablst )
if len ( table ) > 1 :
    print ( tabulate ( table , headers = 'firstrow' ) )
    print ( '\n' )


signature:
def _print_foreign_repetition_table ( self , idset1 , idset2 ) :
    """: param idset1:
 : param idset2:"""

implementation:
assert ( isinstance ( idset1 , idset_with_reference ) )
assert ( isinstance ( idset2 , idset ) )
reps = idset2 . get_repetitions ( )
if len ( reps ) < 1 :
    return
refs = np . array ( idset1 . reflst )
table = [ [ '{0} {1} values of repetitions in {2}' . format ( idset1 . name , idset1 . refname , idset2 . name ) , '' ] ]
for rep in reps :
    if np . any ( idset1 == rep ) :
        matches = refs [ np . where ( idset1 == rep ) ]
        myrep = rep
        for m in matches :
            table . append ( [ myrep , m ] )
            myrep = ''
print ( tabulate ( table , headers = 'firstrow' ) )
print ( '\n' )


signature:
def print_compare_idsets_one_ref ( self , idset1_name , idset2_name ) :
    """idset1 _ name : string
 key of an idset _ with _ reference
 idset2 _ name : string
 key of an idset"""

implementation:
try :
    idset1 = self [ idset1_name ]
    idset2 = self [ idset2_name ]
except KeyError as ke :
    log . error ( 'Error compare_idsets: getting keys {0} and {1}' . format ( idset1_name , idset2_name ) )
    import sys , pdb
    pdb . post_mortem ( sys . exc_info ( ) [ 2 ] )
    raise
assert ( isinstance ( idset1 , idset_with_reference ) )
assert ( isinstance ( idset2 , idset ) )
self . _print_general_vs_table ( idset1 , idset2 )
self . _print_foreign_repetition_table ( idset1 , idset2 )


signature:
def convert_sav ( inputfile , outputfile = None , method = 'rpy2' , otype = 'csv' ) :
    """Transforms the input . sav SPSS file into other format .
 If you don ' t specify an outputfile , it will use the
 inputfile and change its extension to . csv"""

implementation:
assert ( os . path . isfile ( inputfile ) )
assert ( method == 'rpy2' or method == 'savread' )
if method == 'rpy2' :
    df = sav_to_pandas_rpy2 ( inputfile )
elif method == 'savread' :
    df = sav_to_pandas_savreader ( inputfile )
otype_exts = { 'csv' : '.csv' , 'hdf' : '.h5' , 'stata' : '.dta' , 'json' : '.json' , 'pickle' : '.pickle' , 'excel' : '.xls' , 'html' : '.html' }
if outputfile is None :
    outputfile = inputfile . replace ( path ( inputfile ) . ext , '' )
outputfile = add_extension_if_needed ( outputfile , otype_exts [ otype ] )
if otype == 'csv' :
    df . to_csv ( outputfile )
elif otype == 'hdf' :
    df . to_hdf ( outputfile , os . path . basename ( outputfile ) )
elif otype == 'stata' :
    df . to_stata ( outputfile )
elif otype == 'json' :
    df . to_json ( outputfile )
elif otype == 'pickle' :
    df . to_pickle ( outputfile )
elif otype == 'excel' :
    df . to_excel ( outputfile )
elif otype == 'html' :
    df . to_html ( outputfile )
else :
    df . to_csv ( outputfile )


signature:
def load_mask ( image , allow_empty = True ) :
    """Load a Nifti mask volume .
 Parameters
 image : img - like object or boyle . nifti . NeuroImage or str
 Can either be :
 - a file path to a Nifti image
 - any object with get _ data ( ) and get _ affine ( ) methods , e . g . , nibabel . Nifti1Image .
 If niimg is a string , consider it as a path to Nifti image and
 call nibabel . load on it . If it is an object , check if get _ data ( )
 and get _ affine ( ) methods are present , raise TypeError otherwise .
 allow _ empty : boolean , optional
 Allow loading an empty mask ( full of 0 values )
 Returns
 nibabel . Nifti1Image with boolean data ."""

implementation:
img = check_img ( image , make_it_3d = True )
values = np . unique ( img . get_data ( ) )
if len ( values ) == 1 : # We accept a single value if it is not 0 ( full true mask ) .
    if values [ 0 ] == 0 and not allow_empty :
        raise ValueError ( 'Given mask is invalid because it masks all data' )
elif len ( values ) == 2 : # If there are 2 different values , one of them must be 0 ( background )
    if 0 not in values :
        raise ValueError ( 'Background of the mask must be represented with 0.' ' Given mask contains: {}.' . format ( values ) )
elif len ( values ) != 2 : # If there are more than 2 values , the mask is invalid
    raise ValueError ( 'Given mask is not made of 2 values: {}. ' 'Cannot interpret as true or false' . format ( values ) )
return nib . Nifti1Image ( as_ndarray ( get_img_data ( img ) , dtype = bool ) , img . get_affine ( ) , img . get_header ( ) )


signature:
def load_mask_data ( image , allow_empty = True ) :
    """Load a Nifti mask volume and return its data matrix as boolean and affine .
 Parameters
 image : img - like object or boyle . nifti . NeuroImage or str
 Can either be :
 - a file path to a Nifti image
 - any object with get _ data ( ) and get _ affine ( ) methods , e . g . , nibabel . Nifti1Image .
 If niimg is a string , consider it as a path to Nifti image and
 call nibabel . load on it . If it is an object , check if get _ data ( )
 and get _ affine ( ) methods are present , raise TypeError otherwise .
 allow _ empty : boolean , optional
 Allow loading an empty mask ( full of 0 values )
 Returns
 numpy . ndarray with dtype = = bool , numpy . ndarray of affine transformation"""

implementation:
mask = load_mask ( image , allow_empty = allow_empty )
return get_img_data ( mask ) , mask . get_affine ( )


signature:
def union_mask ( filelist ) :
    """Creates a binarised mask with the union of the files in filelist .
 Parameters
 filelist : list of img - like object or boyle . nifti . NeuroImage or str
 List of paths to the volume files containing the ROIs .
 Can either be :
 - a file path to a Nifti image
 - any object with get _ data ( ) and get _ affine ( ) methods , e . g . , nibabel . Nifti1Image .
 If niimg is a string , consider it as a path to Nifti image and
 call nibabel . load on it . If it is an object , check if get _ data ( )
 and get _ affine ( ) methods are present , raise TypeError otherwise .
 Returns
 ndarray of bools
 Mask volume
 Raises
 ValueError"""

implementation:
firstimg = check_img ( filelist [ 0 ] )
mask = np . zeros_like ( firstimg . get_data ( ) )
# create space for all features and read from subjects
try :
    for volf in filelist :
        roiimg = check_img ( volf )
        check_img_compatibility ( firstimg , roiimg )
        mask += get_img_data ( roiimg )
except Exception as exc :
    raise ValueError ( 'Error joining mask {} and {}.' . format ( repr_imgs ( firstimg ) , repr_imgs ( volf ) ) ) from exc
else :
    return as_ndarray ( mask > 0 , dtype = bool )


signature:
def apply_mask ( image , mask_img ) :
    """Read a Nifti file nii _ file and a mask Nifti file .
 Returns the voxels in nii _ file that are within the mask , the mask indices
 and the mask shape .
 Parameters
 image : img - like object or boyle . nifti . NeuroImage or str
 Can either be :
 - a file path to a Nifti image
 - any object with get _ data ( ) and get _ affine ( ) methods , e . g . , nibabel . Nifti1Image .
 If niimg is a string , consider it as a path to Nifti image and
 call nibabel . load on it . If it is an object , check if get _ data ( )
 and get _ affine ( ) methods are present , raise TypeError otherwise .
 mask _ img : img - like object or boyle . nifti . NeuroImage or str
 3D mask array : True where a voxel should be used .
 See img description .
 Returns
 vol [ mask _ indices ] , mask _ indices
 Note
 nii _ file and mask _ file must have the same shape .
 Raises
 NiftiFilesNotCompatible , ValueError"""

implementation:
img = check_img ( image )
mask = check_img ( mask_img )
check_img_compatibility ( img , mask )
vol = img . get_data ( )
mask_data , _ = load_mask_data ( mask )
return vol [ mask_data ] , mask_data


signature:
def apply_mask_4d ( image , mask_img ) : # , smooth _ mm = None , remove _ nans = True ) :
    """Read a Nifti file nii _ file and a mask Nifti file .
 Extract the signals in nii _ file that are within the mask , the mask indices
 and the mask shape .
 Parameters
 image : img - like object or boyle . nifti . NeuroImage or str
 Can either be :
 - a file path to a Nifti image
 - any object with get _ data ( ) and get _ affine ( ) methods , e . g . , nibabel . Nifti1Image .
 If niimg is a string , consider it as a path to Nifti image and
 call nibabel . load on it . If it is an object , check if get _ data ( )
 and get _ affine ( ) methods are present , raise TypeError otherwise .
 mask _ img : img - like object or boyle . nifti . NeuroImage or str
 3D mask array : True where a voxel should be used .
 See img description .
 smooth _ mm : float # TBD
 ( optional ) The size in mm of the FWHM Gaussian kernel to smooth the signal .
 If True , remove _ nans is True .
 remove _ nans : bool # TBD
 If remove _ nans is True ( default ) , the non - finite values ( NaNs and
 infs ) found in the images will be replaced by zeros .
 Returns
 session _ series , mask _ data
 session _ series : numpy . ndarray
 2D array of series with shape ( voxel number , image number )
 Note
 nii _ file and mask _ file must have the same shape .
 Raises
 FileNotFound , NiftiFilesNotCompatible"""

implementation:
img = check_img ( image )
mask = check_img ( mask_img )
check_img_compatibility ( img , mask , only_check_3d = True )
vol = get_data ( img )
series , mask_data = _apply_mask_to_4d_data ( vol , mask )
return series , mask_data


signature:
def vector_to_volume ( arr , mask , order = 'C' ) :
    """Transform a given vector to a volume . This is a reshape function for
 3D flattened and maybe masked vectors .
 Parameters
 arr : np . array
 1 - Dimensional array
 mask : numpy . ndarray
 Mask image . Must have 3 dimensions , bool dtype .
 Returns
 np . ndarray"""

implementation:
if mask . dtype != np . bool :
    raise ValueError ( "mask must be a boolean array" )
if arr . ndim != 1 :
    raise ValueError ( "vector must be a 1-dimensional array" )
if arr . ndim == 2 and any ( v == 1 for v in arr . shape ) :
    log . debug ( 'Got an array of shape {}, flattening for my purposes.' . format ( arr . shape ) )
    arr = arr . flatten ( )
volume = np . zeros ( mask . shape [ : 3 ] , dtype = arr . dtype , order = order )
volume [ mask ] = arr
return volume


signature:
def matrix_to_4dvolume ( arr , mask , order = 'C' ) :
    """Transform a given vector to a volume . This is a reshape function for
 4D flattened masked matrices where the second dimension of the matrix
 corresponds to the original 4th dimension .
 Parameters
 arr : numpy . array
 2D numpy . array
 mask : numpy . ndarray
 Mask image . Must have 3 dimensions , bool dtype .
 dtype : return type
 If None , will get the type from vector
 Returns
 data : numpy . ndarray
 Unmasked data .
 Shape : ( mask . shape [ 0 ] , mask . shape [ 1 ] , mask . shape [ 2 ] , X . shape [ 1 ] )"""

implementation:
if mask . dtype != np . bool :
    raise ValueError ( "mask must be a boolean array" )
if arr . ndim != 2 :
    raise ValueError ( "X must be a 2-dimensional array" )
if mask . sum ( ) != arr . shape [ 0 ] : # raise an error if the shape of arr is not what expected
    raise ValueError ( 'Expected arr of shape ({}, samples). Got {}.' . format ( mask . sum ( ) , arr . shape ) )
data = np . zeros ( mask . shape + ( arr . shape [ 1 ] , ) , dtype = arr . dtype , order = order )
data [ mask , : ] = arr
return data


signature:
def niftilist_mask_to_array ( img_filelist , mask_file = None , outdtype = None ) :
    """From the list of absolute paths to nifti files , creates a Numpy array
 with the masked data .
 Parameters
 img _ filelist : list of str
 List of absolute file paths to nifti files . All nifti files must have
 the same shape .
 mask _ file : str
 Path to a Nifti mask file .
 Should be the same shape as the files in nii _ filelist .
 outdtype : dtype
 Type of the elements of the array , if not set will obtain the dtype from
 the first nifti file .
 Returns
 outmat :
 Numpy array with shape N x prod ( vol . shape ) containing the N files as flat vectors .
 mask _ indices :
 Tuple with the 3D spatial indices of the masking voxels , for reshaping
 with vol _ shape and remapping .
 vol _ shape :
 Tuple with shape of the volumes , for reshaping ."""

implementation:
img = check_img ( img_filelist [ 0 ] )
if not outdtype :
    outdtype = img . dtype
mask_data , _ = load_mask_data ( mask_file )
indices = np . where ( mask_data )
mask = check_img ( mask_file )
outmat = np . zeros ( ( len ( img_filelist ) , np . count_nonzero ( mask_data ) ) , dtype = outdtype )
for i , img_item in enumerate ( img_filelist ) :
    img = check_img ( img_item )
    if not are_compatible_imgs ( img , mask ) :
        raise NiftiFilesNotCompatible ( repr_imgs ( img ) , repr_imgs ( mask_file ) )
    vol = get_img_data ( img )
    outmat [ i , : ] = vol [ indices ]
return outmat , mask_data


signature:
def create ( _ ) :
    """Create a client for Service Fabric APIs ."""

implementation:
endpoint = client_endpoint ( )
if not endpoint :
    raise CLIError ( "Connection endpoint not found. " "Before running sfctl commands, connect to a cluster using " "the 'sfctl cluster select' command." )
no_verify = no_verify_setting ( )
if security_type ( ) == 'aad' :
    auth = AdalAuthentication ( no_verify )
else :
    cert = cert_info ( )
    ca_cert = ca_cert_info ( )
    auth = ClientCertAuthentication ( cert , ca_cert , no_verify )
return ServiceFabricClientAPIs ( auth , base_url = endpoint )


signature:
def aggregate ( self , clazz , new_col , * args ) :
    """Aggregate the rows of the DataFrame into a single value .
 : param clazz : name of a class that extends class Callable
 : type clazz : class
 : param new _ col : name of the new column
 : type new _ col : str
 : param args : list of column names of the object that function
 should be applied to
 : type args : tuple
 : return : returns a new dataframe object with the aggregated value
 : rtype : DataFrame"""

implementation:
if is_callable ( clazz ) and not is_none ( new_col ) and has_elements ( * args ) :
    return self . __do_aggregate ( clazz , new_col , * args )


signature:
def subset ( self , * args ) :
    """Subset only some of the columns of the DataFrame .
 : param args : list of column names of the object that should be subsetted
 : type args : tuple
 : return : returns dataframe with only the columns you selected
 : rtype : DataFrame"""

implementation:
cols = { }
for k in self . colnames :
    if k in args :
        cols [ str ( k ) ] = self . __data_columns [ self . colnames . index ( k ) ] . values
return DataFrame ( ** cols )


signature:
def modify ( self , clazz , new_col , * args ) :
    """Modify some columns ( i . e . apply a function ) and add the
 result to the table .
 : param clazz : name of a class that extends class Callable
 : type clazz : class
 : param new _ col : name of the new column
 : type new _ col : str
 : param args : list of column names of the object that
 function should be applied to
 : type args : tuple
 : return : returns a new dataframe object with the modiefied values ,
 i . e . the new column
 : rtype : DataFrame"""

implementation:
if is_callable ( clazz ) and not is_none ( new_col ) and has_elements ( * args ) :
    return self . __do_modify ( clazz , new_col , * args )


signature:
def group ( * args ) :
    """Pipeable grouping method .
 Takes either
 - a dataframe and a tuple of strings for grouping ,
 - a tuple of strings if a dataframe has already been piped into .
 : Example :
 group ( dataframe , " column " )
 : Example :
 dataframe > > group ( " column " )
 : param args : tuple of arguments
 : type args : tuple
 : return : returns a grouped dataframe object
 : rtype : GroupedDataFrame"""

implementation:
if args and isinstance ( args [ 0 ] , dataframe . DataFrame ) :
    return args [ 0 ] . group ( * args [ 1 : ] )
elif not args :
    raise ValueError ( "No arguments provided" )
else :
    return pipeable . Pipeable ( pipeable . PipingMethod . GROUP , * args )


signature:
def aggregate ( * args ) :
    """Pipeable aggregation method .
 Takes either
 - a dataframe and a tuple of arguments required for aggregation ,
 - a tuple of arguments if a dataframe has already been piped into .
 In any case one argument has to be a class that extends callable .
 : Example :
 aggregate ( dataframe , Function , " new _ col _ name " , " old _ col _ name " )
 : Example :
 dataframe > > aggregate ( Function , " new _ col _ name " , " old _ col _ name " )
 : param args : tuple of arguments
 : type args : tuple
 : return : returns a dataframe object
 : rtype : DataFrame"""

implementation:
if args and isinstance ( args [ 0 ] , dataframe . DataFrame ) :
    return args [ 0 ] . aggregate ( args [ 1 ] , args [ 2 ] , * args [ 3 : ] )
elif not args :
    raise ValueError ( "No arguments provided" )
else :
    return pipeable . Pipeable ( pipeable . PipingMethod . AGGREGATE , * args )


signature:
def subset ( * args ) :
    """Pipeable subsetting method .
 Takes either
 - a dataframe and a tuple of arguments required for subsetting ,
 - a tuple of arguments if a dataframe has already been piped into .
 : Example :
 subset ( dataframe , " column " )
 : Example :
 dataframe > > subset ( " column " )
 : param args : tuple of arguments
 : type args : tuple
 : return : returns a dataframe object
 : rtype : DataFrame"""

implementation:
if args and isinstance ( args [ 0 ] , dataframe . DataFrame ) :
    return args [ 0 ] . subset ( * args [ 1 : ] )
elif not args :
    raise ValueError ( "No arguments provided" )
else :
    return pipeable . Pipeable ( pipeable . PipingMethod . SUBSET , * args )


signature:
def modify ( * args ) :
    """Pipeable modification method
 Takes either
 - a dataframe and a tuple of arguments required for modification ,
 - a tuple of arguments if a dataframe has already been piped into .
 In any case one argument has to be a class that extends callable .
 : Example :
 modify ( dataframe , Function , " new _ col _ name " , " old _ col _ name " )
 : Example :
 dataframe > > modify ( Function , " new _ col _ name " , " old _ col _ name " )
 : param args : tuple of arguments
 : type args : tuple
 : return : returns a dataframe object
 : rtype : DataFrame"""

implementation:
if args and isinstance ( args [ 0 ] , dataframe . DataFrame ) :
    return args [ 0 ] . modify ( args [ 1 ] , args [ 2 ] , * args [ 3 : ] )
elif not args :
    raise ValueError ( "No arguments provided" )
else :
    return pipeable . Pipeable ( pipeable . PipingMethod . MODIFY , * args )


signature:
def _escape_char ( c , escape_char = ESCAPE_CHAR ) :
    """Escape a single character"""

implementation:
buf = [ ]
for byte in c . encode ( 'utf8' ) :
    buf . append ( escape_char )
    buf . append ( '%X' % _ord ( byte ) )
return '' . join ( buf )


signature:
def escape ( to_escape , safe = SAFE , escape_char = ESCAPE_CHAR , allow_collisions = False ) :
    """Escape a string so that it only contains characters in a safe set .
 Characters outside the safe list will be escaped with _ % x _ ,
 where % x is the hex value of the character .
 If ` allow _ collisions ` is True , occurrences of ` escape _ char `
 in the input will not be escaped .
 In this case , ` unescape ` cannot be used to reverse the transform
 because occurrences of the escape char in the resulting string are ambiguous .
 Only use this mode when :
 1 . collisions cannot occur or do not matter , and
 2 . unescape will never be called .
 . . versionadded : 1.0
 allow _ collisions argument .
 Prior to 1.0 , behavior was the same as allow _ collisions = False ( default ) ."""

implementation:
if isinstance ( to_escape , bytes ) : # always work on text
    to_escape = to_escape . decode ( 'utf8' )
if not isinstance ( safe , set ) :
    safe = set ( safe )
if allow_collisions :
    safe . add ( escape_char )
elif escape_char in safe : # escape char can ' t be in safe list
    safe . remove ( escape_char )
chars = [ ]
for c in to_escape :
    if c in safe :
        chars . append ( c )
    else :
        chars . append ( _escape_char ( c , escape_char ) )
return u'' . join ( chars )


signature:
def unescape ( escaped , escape_char = ESCAPE_CHAR ) :
    """Unescape a string escaped with ` escape `
 escape _ char must be the same as that used in the call to escape ."""

implementation:
if isinstance ( escaped , bytes ) : # always work on text
    escaped = escaped . decode ( 'utf8' )
escape_pat = re . compile ( re . escape ( escape_char ) . encode ( 'utf8' ) + b'([a-z0-9]{2})' , re . IGNORECASE )
buf = escape_pat . subn ( _unescape_char , escaped . encode ( 'utf8' ) ) [ 0 ]
return buf . decode ( 'utf8' )


signature:
def can_send ( self , user , notice_type ) :
    """Determines whether this backend is allowed to send a notification to
 the given user and notice _ type ."""

implementation:
from notification . models import NoticeSetting
return NoticeSetting . for_user ( user , notice_type , self . medium_id ) . send


signature:
def get_formatted_messages ( self , formats , label , context ) :
    """Returns a dictionary with the format identifier as the key . The values are
 are fully rendered templates with the given context ."""

implementation:
format_templates = { }
for fmt in formats : # conditionally turn off autoescaping for . txt extensions in format
    if fmt . endswith ( ".txt" ) :
        context . autoescape = False
    format_templates [ fmt ] = render_to_string ( ( "notification/%s/%s" % ( label , fmt ) , "notification/%s" % fmt ) , context_instance = context )
return format_templates


signature:
def copy_attributes ( source , destination , ignore_patterns = [ ] ) :
    """Copy the attributes from a source object to a destination object ."""

implementation:
for attr in _wildcard_filter ( dir ( source ) , * ignore_patterns ) :
    setattr ( destination , attr , getattr ( source , attr ) )


signature:
def row ( self , idx ) :
    """Returns DataFrameRow of the DataFrame given its index .
 : param idx : the index of the row in the DataFrame .
 : return : returns a DataFrameRow"""

implementation: return DataFrameRow ( idx , [ x [ idx ] for x in self ] , self . colnames )


signature:
def notice_settings ( request ) :
    """The notice settings view .
 Template : : template : ` notification / notice _ settings . html `
 Context :
 notice _ types
 A list of all : model : ` notification . NoticeType ` objects .
 notice _ settings
 A dictionary containing ` ` column _ headers ` ` for each ` ` NOTICE _ MEDIA ` `
 and ` ` rows ` ` containing a list of dictionaries : ` ` notice _ type ` ` , a
 : model : ` notification . NoticeType ` object and ` ` cells ` ` , a list of
 tuples whose first value is suitable for use in forms and the second
 value is ` ` True ` ` or ` ` False ` ` depending on a ` ` request . POST ` `
 variable called ` ` form _ label ` ` , whose valid value is ` ` on ` ` ."""

implementation:
notice_types = NoticeType . objects . all ( )
settings_table = [ ]
for notice_type in notice_types :
    settings_row = [ ]
    for medium_id , medium_display in NOTICE_MEDIA :
        form_label = "%s_%s" % ( notice_type . label , medium_id )
        setting = NoticeSetting . for_user ( request . user , notice_type , medium_id )
        if request . method == "POST" :
            if request . POST . get ( form_label ) == "on" :
                if not setting . send :
                    setting . send = True
                    setting . save ( )
            else :
                if setting . send :
                    setting . send = False
                    setting . save ( )
        settings_row . append ( ( form_label , setting . send ) )
    settings_table . append ( { "notice_type" : notice_type , "cells" : settings_row } )
if request . method == "POST" :
    next_page = request . POST . get ( "next_page" , "." )
    return HttpResponseRedirect ( next_page )
settings = { "column_headers" : [ medium_display for medium_id , medium_display in NOTICE_MEDIA ] , "rows" : settings_table , }
return render_to_response ( "notification/notice_settings.html" , { "notice_types" : notice_types , "notice_settings" : settings , } , context_instance = RequestContext ( request ) )


signature:
def query ( self , input = '' , params = { } ) :
    """Query Wolfram Alpha and return a Result object"""

implementation:
# Get and construct query parameters
# Default parameters
payload = { 'input' : input , 'appid' : self . appid }
# Additional parameters ( from params ) , formatted for url
for key , value in params . items ( ) : # Check if value is list or tuple type ( needs to be comma joined )
    if isinstance ( value , ( list , tuple ) ) :
        payload [ key ] = ',' . join ( value )
    else :
        payload [ key ] = value
# Catch any issues with connecting to Wolfram Alpha API
try :
    r = requests . get ( "http://api.wolframalpha.com/v2/query" , params = payload )
    # Raise Exception ( to be returned as error )
    if r . status_code != 200 :
        raise Exception ( 'Invalid response status code: %s' % ( r . status_code ) )
    if r . encoding != 'utf-8' :
        raise Exception ( 'Invalid encoding: %s' % ( r . encoding ) )
except Exception , e :
    return Result ( error = e )
return Result ( xml = r . text )


signature:
def pods ( self ) :
    """Return list of all Pod objects in result"""

implementation:
# Return empty list if xml _ tree is not defined ( error Result object )
if not self . xml_tree :
    return [ ]
# Create a Pod object for every pod group in xml
return [ Pod ( elem ) for elem in self . xml_tree . findall ( 'pod' ) ]


signature:
def format ( self ) :
    """Dictionary of available formats , corresponding to a list of the values
 Example : pod . format [ ' plaintext ' ] will return a list of every plaintext
 content in the pod ' s subpods"""

implementation:
formats = { }
# Iterate through all the tags ( formats ) in subpods
# ' state ' is a tag but not an acceptable format
for subpod in self . root . findall ( 'subpod' ) : # elem will be a specific format
    for elem in list ( subpod ) : # skip any subpod state xml groups ( not a format )
        if elem . tag == 'state' :
            continue
        # Content of elem ( specific format )
        content = elem . text
        # img needs special content packaging
        if elem . tag == 'img' :
            content = { 'url' : elem . get ( 'src' ) , 'alt' : elem . get ( 'alt' ) , 'title' : elem . get ( 'title' ) , 'width' : int ( elem . get ( 'width' , 0 ) ) , 'height' : int ( elem . get ( 'height' , 0 ) ) }
        # Create / append to return dict
        if elem . tag not in formats :
            formats [ elem . tag ] = [ content ]
        else :
            formats [ elem . tag ] . append ( content )
return formats


signature:
def find ( self , * args ) :
    """Find a node in the tree . If the node is not found it is added first and then returned .
 : param args : a tuple
 : return : returns the node"""

implementation:
curr_node = self . __root
return self . __traverse ( curr_node , 0 , * args )


signature:
def get_notification_language ( user ) :
    """Returns site - specific notification language for this user . Raises
 LanguageStoreNotAvailable if this site does not use translated
 notifications ."""

implementation:
if getattr ( settings , "NOTIFICATION_LANGUAGE_MODULE" , False ) :
    try :
        app_label , model_name = settings . NOTIFICATION_LANGUAGE_MODULE . split ( "." )
        model = models . get_model ( app_label , model_name )
        # pylint : disable - msg = W0212
        language_model = model . _default_manager . get ( user__id__exact = user . id )
        if hasattr ( language_model , "language" ) :
            return language_model . language
    except ( ImportError , ImproperlyConfigured , model . DoesNotExist ) :
        raise LanguageStoreNotAvailable
raise LanguageStoreNotAvailable


signature:
def send_now ( users , label , extra_context = None , sender = None ) :
    """Creates a new notice .
 This is intended to be how other apps create new notices .
 notification . send ( user , " friends _ invite _ sent " , {
 " spam " : " eggs " ,
 " foo " : " bar " ,"""

implementation:
sent = False
if extra_context is None :
    extra_context = { }
notice_type = NoticeType . objects . get ( label = label )
current_language = get_language ( )
for user in users : # get user language for user from language store defined in
# NOTIFICATION _ LANGUAGE _ MODULE setting
    try :
        language = get_notification_language ( user )
    except LanguageStoreNotAvailable :
        language = None
    if language is not None : # activate the user ' s language
        activate ( language )
    for backend in NOTIFICATION_BACKENDS . values ( ) :
        if backend . can_send ( user , notice_type ) :
            backend . deliver ( user , sender , notice_type , extra_context )
            sent = True
# reset environment to original language
activate ( current_language )
return sent


signature:
def send ( * args , ** kwargs ) :
    """A basic interface around both queue and send _ now . This honors a global
 flag NOTIFICATION _ QUEUE _ ALL that helps determine whether all calls should
 be queued or not . A per call ` ` queue ` ` or ` ` now ` ` keyword argument can be
 used to always override the default global behavior ."""

implementation:
queue_flag = kwargs . pop ( "queue" , False )
now_flag = kwargs . pop ( "now" , False )
assert not ( queue_flag and now_flag ) , "'queue' and 'now' cannot both be True."
if queue_flag :
    return queue ( * args , ** kwargs )
elif now_flag :
    return send_now ( * args , ** kwargs )
else :
    if QUEUE_ALL :
        return queue ( * args , ** kwargs )
    else :
        return send_now ( * args , ** kwargs )