niftynet.utilities.decorators module

decorators.py

def singleton(cls): 修饰类为单例

niftynet.utilities.download module

download.py
'''
Downloading model zoo specifications and model zoo contents.[model zoo框架]
'''
def download(example_ids,download_if_already_existing=False,verbose=True):
    '''  
    -下载标准NiftyNet示例，如数据，样本
        - example_ids:要下载的样本的标识符列表
        - download_if_already_existing: If true, data will always be downloaded
        - verbose: If true, download info will be printed
    '''
def download_file(url, download_path):#将资源URL中的文件下载到给定位置

def download_and_decompress(url, download_path, verbose=True):#从资源URL下载存档并解压缩到指定位置

class ConfigStore(object): #使用本地缓存，管理'基于远程仓库'的配置文件存储

    def __init__(self, global_config, verbose=True):
    def exists(self, example_id): #判断参数example_id是否存在(无论是远程还是本地)
    def update_if_required(self,example_id,download_if_already_existing=False):
    # 1)如果数据可更新，则依据配置文件下载文件.2)如果无需更新并且并无报错，则返回True
    
    @staticmethod
    def _check_minimum_versions(remote_config): #检查当前是否为minimum版本(API\NiftyNet)
    
    @staticmethod
    def _is_update_required(current_config, remote_config): #判断是否需要更新(当本地没有版本信息且版本信息被远程指定时进行更新)
    
    def _download(self, remote_config_sections, example_id):
    def _get_local_download_path(self, remote_config, example_id):        
    def _replace_local_with_remote(self, example_id):
    def _are_data_missing(self, remote_config_sections, example_id):

class ConfigStoreCache(object): #配置文件的一份本地缓存
    def __init__(self, cache_folder):
    def exists(self, example_id):
    def get_local_path(self, example_id): #返回本地缓存配置文件的全路径
    def get_local_cache_folder(self):
    def get_download_params(self, example_id):

class RemoteProxy(object):  #使用本地缓存的远程配置文件存储(远程代理)
    def __init__(self, parent_store_folder, base_url):
    def exists(self, example_id):  #如果记录存在于本地或远程，则返回True
    def update(self, example_id):   #从远程存储中检索最新记录，并将其本地放入远程缓存中
    def get_download_params(self, example_id):  #返回此example_id的本地配置文件
    def get_local_path(self, example_id):   #返回'本地缓存的配置文件的'完整路径
    
class RemoteConfigStore(object):    #远程配置文件存储
    def __init__(self, base_url):   
    def exists(self, example_id):   #如果该记录存于远程服务器中，返回True
    def get_url(self, example_id):  #获得example_id记录的URL
    
def raw_file_url(base_url, example_id=None):    #返回GitLab服务器上原始文件的URL

def url_exists(url):    # 如果指定的url存在，则返回true(不带任何重定向)

def progress_bar_wrapper(count, block_size, total_size): #使用' url retrieve hook'格式的公共进度条

def main():
    """
    Launch download process with user-specified options.
    依据用户指定的选项启动下载过程.

    """
    arg_parser = argparse.ArgumentParser(
        description="Download NiftyNet sample data")
    arg_parser.add_argument(
        "-r", "--retry",
        help="Force data to be downloaded again",
        required=False,
        action='store_true')
    arg_parser.add_argument(
        'sample_id',
        nargs='+',
        help="Identifier string(s) for the example(s) to download")
    version_string = get_niftynet_version_string()
    arg_parser.add_argument(
        "-v", "--version",
        action='version',
        version=version_string)
    args = arg_parser.parse_args()

    if not download(args.sample_id, args.retry):
        return -1

    return 0

niftynet.utilities.filename_matching module

filename_matching.py
'''
Matching file names by configuration options.
'''
class KeywordsMatching(object):
    '''
    This class is responsible for the search of the appropriate(适当的) files to use as input based on the constraints given in the config file.
    '''
    
    def __init__(self,list_paths=(),list_contain=(),list_not_contain=(),regex_remove=()):
    
    @classmethod
    def from_dict(cls, input_dict, default_folder=None): # This function creates the corresponding matching object with the list of constraints for each of these subtypes.( 'path_to_search', 'filename_contains' and  'filename_not_contains')
    
    def matching_subjects_and_filenames(self): #此功能执行相关文件(存储在filename_list)的'搜索'和'提取'相应的可能的主题名称(存储在subjectname_list)列表
               
    def __is_a_candidate(self, x): 
    def __extract_subject_id_from(self, fullname): #此函数返回给定文件名中潜在主题名称的列表，知道强加的约束。 从文件名中删除约束字符串以提供可能的名称列表。 如果在从约束中减少文件名后，名称为空，则返回初始文件名。 如果remove不为空，则仅删除remove中指示的字符串。 否则，默认情况下将删除filename_contains中的所有内容
     '''
     This function returns a list of potential subject names from a given filename, knowing the imposed constraints. Constraints strings are removed from the filename to provide the list of possible names. If after reduction of the filename from the constraints the name is empty the initial filename is returned.if remove is not empty, will remove only the strings indicated in remove. Otherwise, by default will remove all those in filename_contains             '''
    def __check_unique_names(self, file_list, id_list):
    def __str__(self):
    def to_string(self): #Formatting(格式化) the class as an intuitive string for printing.

niftynet.utilities.histogram_standardisation module

histogram_standardisation.py
'''
This implementation only supports input images with floating point number,
(not integers). [注: histogram_柱状图/直方图  standardisation_标准化]
'''
def __compute_percentiles(img, mask, cutoff): # Creates the list of percentile(百分位) values to be used as landmarks for the linear fitting.
def __standardise_cutoff(cutoff, type_hist='quartile'): #Standardises the cutoff(截止) values given in the configuration [注: cut-off值是被检分析物的量值]
def create_mapping_from_multimod_arrayfiles(array_files,field,modalities,mod_to_train,cutoff,masking_function): #基于文件列表执行映射创建。 对于每个文件（可能是多模式），为每种模态定义地标并存储在数据库中。 返回这些地标的平均值，提供用于任何新输入数据的线性映射的地标
    '''
    Performs the mapping creation based on a list of files. For each of the
    files (potentially multimodal), the landmarks are defined for each
    modality and stored in a database. The average of these landmarks is
    returned providing the landmarks to use for the linear mapping of any
    new incoming data  
    '''
def create_standard_range():
def __averaged_mapping(perc_database, s1, s2): #Map the landmarks of the database to the chosen range
def transform_by_mapping(img, mask, mapping, cutoff, type_hist='quartile'):#Performs the standardisation of a given image.
def smooth_threshold(value, mode='high'):
def read_mapping_file(mapping_file): #Reads an existing(现有的) mapping file with the given modalities(模态).
def write_all_mod_mapping(hist_model_file, mapping):#Function to modify the model file with the mapping if needed according to existent(现有的) mapping(映射) and modalities(模态).backup(备份) existing file first.
def __force_writing_new_mapping(filename, mapping_dict):#Writes a mapping(映射) dictionary to file.

niftynet.utilities.niftynet_global_config module

niftynet_global_config.py
'''
NiftyNet user folder configuration
'''
@singleton
class NiftyNetGlobalConfig(object):#Global configuration settings.
    def __init__(self):
    def setup(self): #Read variables from system environment and make directories.
    @staticmethod
    def __create_module(path):# Create the 'passed' path, i.e. folder and place an empty ``__init__.py`` file inside.

    @staticmethod
    def __load_or_create(config_file): 
    '''
    Load passed configuration file, if it exists; create a default otherwise. 
    If this method finds an incorrect config file, it backs the file up(备份) with a human-readable timestamp suffix and creates a default one.
    '''
    def get_niftynet_home_folder(self): #Return the folder containing NiftyNet models and data.
    def get_niftynet_config_folder(self): #Return the folder containing NiftyNet global configuration.
    def get_default_examples_folder(self):#Return the default folder containing NiftyNet examples.
    def get_download_server_url(self):#Return the URL to the NiftyNet examples server(示例服务器).

niftynet.utilities.niftynet_launch_config module

niftynet_launch_config.py
'''
NiftyNet launch configuration
'''
class NiftyNetLaunchConfig(configparser.ConfigParser): #Launch configuration settings.

niftynet.utilities.restore_initializer module

restore_initializer.py
'''
A checkpoint-restoring Tensorflow initializer.
'''
class _Restore(init_ops.Initializer):# Initializer that restores tensors from a checkpoint.
    def __init__(self, filename, var_name, scope=None):
    def _partition_spec(self, shape, partition_info):# Build magic (and sparsely documented) shapes_and_slices spec string.
    def __call__(self, shape, dtype=None, partition_info=None):#Creating different RestoreV2 ops when a single one could output several tensors seems inefficient(低效), but that's actually what tf.Saver.restore_op (via tf.BaseSaverBuilder) does too.

niftynet.utilities.user_parameters_custom module

user_parameters_custom.py
'''
This module defines task specific parameters
'''
def add_customised_args(parser, task_name): #loading keywords arguments to parser by task name.
def __add_regression_args(parser): #keywords defined for regression(回归) tasks.
def __add_segmentation_args(parser):#keywords defined for segmentation tasks(分段任务).
def __add_gan_args(parser): #keywords defined for GAN.
def __add_classification_args(parser):#keywords defined for classification(分类).
def __add_autoencoder_args(parser): #keywords defined for autoencoder(自动编码器).
def __add_registration_args(parser):#keywords defined for image registration(图像注册).

SUPPORTED_ARG_SECTIONS = {
    'REGRESSION': __add_regression_args,
    'SEGMENTATION': __add_segmentation_args,
    'CLASSIFICATION': __add_classification_args,
    'AUTOENCODER': __add_autoencoder_args,
    'GAN': __add_gan_args,
    'REGISTRATION': __add_registration_args
}

niftynet.utilities.user_parameters_default module

user_parameters_default.py
'''
This module defines niftynet parameters and their defaults.
'''
def add_application_args(parser): #Common(常用) keywords for all applications.
def add_inference_args(parser): #keywords defined for inference(推理\推论统计) action.
def add_evaluation_args(parser):#keywords defined for evaluation(评估) action.
def add_input_data_args(parser):#keywords defined for input data specification(规范) section.
def add_network_args(parser):#keywords defined for network specification(规范).
def add_training_args(parser):#keywords defined for the training(训练) action.

SUPPORTED_DEFAULT_SECTIONS = {
    'SYSTEM': add_application_args,
    'NETWORK': add_network_args,
    'TRAINING': add_training_args,
    'INFERENCE': add_inference_args,
    'EVALUATION': add_evaluation_args,
}

niftynet.utilities.user_parameters_helper module

user_parameters_helper.py
'''
This module mainly defines types and casting(转换) methods for input parameters
'''
def str2boolean(string_input): #将用户输入配置字符串转换为布尔值.convert user input config string to boolean.
def int_array(string_input): #将输入转换为int值的元组.convert input into a tuple of int values.
def float_array(string_input): #将输入转换为浮点值的元组.convert input into a tuple of float values.
def str_array(string_input):#将输入转换为字符串元组.convert input into a tuple of strings.
def make_input_tuple(input_str, element_type=string_types):#将输入转换为输入元组.converting input into a tuple of input.
def standardise_section_name(configparser, old_name):#重命名configparser部分。当用户指定复杂的部分名称时，此帮助程序很有用.rename configparser section.This helper is useful when user specifies complex section names.
def standardise_string(input_string): #使用户的输入一致用下划线替换不在set [0-9a-zA-Z]中的任何字符.to make the user's input consistent replace any characters not in set [0-9a-zA-Z] with underscore _
def has_section_in_config(config, required_custom_section):#检查配置文件中是否存在section名称如果不存在则引发值错误.check if section name exists in a config file raises value error if it doesn't exist.
def add_input_name_args(parser, supported_input): #添加定义输入部分分组的关键字（主要用于多模式输入规范）adding keywords that defines grouping of the input sections(mainly used for multi-modal input specifications).
def spatialnumarray(string_input):#如果输入少于3个元素，则此函数从字符串输入中解析3元素元组，重复最后一个元素(作为填充).This function parses a 3-element tuple from a string input if the input has less than 3 elements, the last element is repeated as padding.
def spatial_atleast3d(string_input):#此函数从字符串输入中解析3元素元组。如果长度小于3，则输入将填充1.This function parses a 3-element tuple from a string input.The input will be padded with ones, if the length is less than 3.[注:spatial_立体的]

niftynet.utilities.user_parameters_parser module

user_parameters_parser.py
'''
Parse user configuration file
'''
def available_keywords(): # 返回解析器中定义的所有可能关键字的列表（删除部分中的重复项）returns a list of all possible keywords defined in the parsers(duplicates from sections are removed.)
def run():#meta_parser首先用于查找配置文件的位置.基于application_name或meta_parser.prog名称，组织节解析器以查找系统参数和特定于应用程序的参数.meta_parser is first used to find out location of the configuration file. Based on the application_name or meta_parser.prog name, the section parsers are organised to find system parameters and application specific parameters.
def _parse_arguments_by_section(parents,section,args_from_config_file,args_from_cmd,required_section): # 此函数首先根据节名称将参数名称添加到解析器。然后它将配置文件中的值作为暂定参数加载。最后，它使用命令行输入覆盖现有的“名称，值”对。命令行输入仅覆盖系统/自定义参数。输入数据相关参数需要在配置文件中定义。This function first adds parameter names to a parser,according to the section name.Then it loads values from configuration files as tentative params.Finally it overrides existing pairs of 'name, value' with commandline inputs.Commandline inputs only override system/custom parameters.input data related parameters needs to be defined in config file.
def _check_config_file_keywords(config):#检查配置文件，验证针对解析器参数列表提供的关键字.check config files, validate keywords provided against parsers' argument list.
def _check_cmd_remaining_keywords(args_from_cmdline):#从命令行输入中检查剩余参数的列表。 通常`args_from_cmd`应为空; 非空列表表示无法识别的参数。check list of remaining arguments from the command line input. Normally `args_from_cmd` should be empty; non-empty list means unrecognised parameters.
def _raises_bad_keys(keys, error_info='config file'):#如果密钥不在系统密钥集中，则会引发值错误。 `error_info`用于自定义错误消息。raises value error if keys is not in the system key set. `error_info` is used to customise the error message.
def __resolve_config_file_path(cmdline_arg):#搜索配置文件的绝对文件名。 从用户提供的`-c`值开始。Search for the absolute file name of the configuration file. starting from `-c` value provided by the user.

niftynet.utilities.user_parameters_regex module

user_parameters_regex.py 
'''
regular expressions to match tuples from user inputs 
'''
def match_array(string_input, type_str): #将输入字符串与`type_str`类型的元素元组进行匹配.matching input string to a tuple of elements in `type_str` type

niftynet.utilities.util_common module

util_common.py
def traverse_nested(input_lists, types=(list, tuple)):# Flatten(展开) a nested list or tuple.[注: traverse_遍历]
def list_depth_count(input_list):#此函数计算嵌套列表的最大深度(递归).这用于检查用户输入和系统API的兼容性，仅用于列表或元组.This function count the maximum depth of a nested list (recursively).This is used to check compatibility of users' input and system API only to be used for list or tuple.
def average_gradients(multi_device_gradients):#输入梯度按设备分组，此功能平均多个设备的梯度。 the input gradients are grouped by device,this function average the gradients of multiple devices.
def __average_grads(tower_grads):#Performs and return the average of the gradients
def has_bad_inputs(input_args): #Check if all input params have been properly set in the configuration file.
def __print_argparse_section(args, section):
def print_save_input_parameters(args, txt_file=None)
class MorphologyOps(object):# Class that performs the morphological(形态) operations needed to get notably connected component. To be used in the evaluation(评估).
    def __init__(self, binary_img, neigh):
    def border_map(self):   #Creates the border for a 3D image
    def foreground_component(self):
def CachedFunction(func):   
def CachedFunctionByID(func):
class CacheFunctionOutput(object): #this provides a decorator to cache function outputs to avoid repeating some heavy function computations
    def __init__(self, func):
    def __get__(self, obj, _=None):
    def __call__(self, *args, **kw):
def look_up_operations(type_str, supported): 
    '''
    This function validates(验证) the ``type_str`` against the supported set.

    if ``supported`` is a ``set``, returns ``type_str``
    if ``supported`` is a ``dict``, return ``supported[type_str]``
    else: raise an error possibly with a guess of the closest match.
    '''
def damerau_levenshtein_distance(s1, s2): #Calculates an edit distance, for typo(输入错误) detection. 
def otsu_threshold(img, nbins=256): # Implementation of otsu(大津法) thresholding
def print_progress_bar(iteration, total,prefix='', suffix='', decimals=1, length=10, fill='='): #Call in a loop to create terminal progress bar.
def set_cuda_device(cuda_devices): 
class ParserNamespace(object): #Parser namespace for representing parsed parameters from config file
    def __init__(self, **kwargs):
    def update(self, **kwargs):
def device_string(n_devices=0, device_id=0, is_worker=True, is_training=True): #assigning CPU/GPU based on user specifications
def tf_config(): #tensorflow system configurations

• OTSU大津法(又称最大类间方差法)是一种确定图像二值化分割阈值的算法，由日本学者大津于1979年提出.

• CUDA(Compute Unified Device Architecture，统一计算架构)是由NVIDIA所推出的一種整合技術，是該公司對於GPGPU的正式名稱。

niftynet.utilities.util_csv module

util_csv.py  
'''
对csv文件的列表匹配、查找、join、删重、写入等操作
'''
def match_first_degree(name_list1, name_list2): # First immediate matching between two possible name lists (exact equality between one item of list1 and of list2
def __find_max_overlap_in_list(name, list_names): # Given a name and list of names to match it to, find the maximum overlap existing.
def match_second_degree(name_list1, name_list2): 
    '''
    Perform the double matching between two lists of possible names.
    First find the direct matches, remove them from the ones still to match 
    and match the remaining ones using the maximum overlap(最大重叠).
    Returns the name match for each list, and the index correspondences(对应关系).
    '''
def join_subject_id_and_filename_list(name_list, list_files):# From the list of list of names and the list of list of files corresponding to each constraint find the association between a single name id and the different file lists
def remove_duplicated_names(name_list):#From a list of list of names remove the items that are duplicated
def write_csv(csv_file, list_combined):# csv writer has different behaviour in python 2/3
def match_and_write_filenames_to_csv(list_constraints, csv_file):# Combine all elements of file searching until finally writing the names

• CSV (Comma Separated Values)，即逗号分隔值（也称字符分隔值，因为分隔符可以不是逗号），是一种常用的文本格式，用以存储表格数据，包括数字或者字符。很多程序在处理数据时都会碰到csv这种格式的文件，它的使用是比较广泛的（Kaggle上一些题目提供的数据就是csv格式），csv虽然使用广泛，但却没有通用的标准，所以在处理csv格式时常常会碰到麻烦，幸好python内置了csv模块。

niftynet.utilities.util_import module

util_import.py 
'''
check module to be imported
'''
def require_module(name,min_version=None,descriptor='Optional',mandatory=False):
    '''
    Check if the module exists, and satisfies the minimum version requirement.
    Returns the imported module if it satisfies requirements.
    Raises(引发) ImportError and AssertionError.
    '''

niftynet.utilities.versioneer_version module

versioneer_version.py
    '''
    This file helps to compute a version number in source trees obtained from git-archive tarball (such as those provided by githubs download-from-tag feature). Distribution tarballs (built by setup.py sdist) and build directories (produced by setup.py build) will contain a much shorter file that just contains the computed version number.
    '''
def get_keywords(): #Get the keywords needed to look up the version information.
class VersioneerConfig: #Container for Versioneer configuration parameters.
def get_config(): #Create, populate(填充) and return the VersioneerConfig() object.
class NotThisMethod(Exception): #Exception raised if a method is not valid for the current scenario(方案脚本).
def register_vcs_handler(vcs, method):  # Decorator to mark a method as the handler for a particular VCS.
def run_command(commands, args, cwd=None, verbose=False, hide_stderr=False,env=None):#Call the given command(s).
def versions_from_parentdir(parentdir_prefix, root, verbose):#Try to determine the version from the parent directory name

@register_vcs_handler("git", "get_keywords")
def git_get_keywords(versionfile_abs):#Extract version information from the given file.

@register_vcs_handler("git", "keywords")
def git_versions_from_keywords(keywords, tag_prefix, verbose):#Get version information from git keywords.

@register_vcs_handler("git", "pieces_from_vcs")
def git_pieces_from_vcs(tag_prefix, root, verbose, run_command=run_command): #Get version from 'git describe' in the root of the source tree.

def plus_or_dot(pieces):#Return a + if we don't already have one, else return a .
def render_pep440(pieces):#Build up version string, with post-release "local version identifier"
def render_pep440_pre(pieces): #TAG[.post.devDISTANCE] -- No -dirty.
def render_pep440_post(pieces): #TAG[.postDISTANCE[.dev0]+gHEX] .
def render_pep440_old(pieces): #"TAG[.postDISTANCE[.dev0]]
def render_git_describe(pieces): #TAG[-DISTANCE-gHEX][-dirty].
def render_git_describe_long(pieces):#TAG-DISTANCE-gHEX[-dirty].
def render(pieces, style):#Render the given version pieces into the requested style.
def get_versions(): #Get version information or return default if unable to do so.

niftynet.utilities.versioning module

versioning.py
def get_niftynet_version_string(): #Return a user-visible string describing the name and product version.
def get_niftynet_version(): #Return a user-visible string describing the product version.(被get_niftynet_version_string():调用)
def check_pep_440(): #正则表达式(Regex)用于检查PEP 440的符合性

Summary

- niftynet.utilities.decorators module

- niftynet.utilities.download module
  - Downloading model zoo specifications and model zoo contents.[model zoo框架]
- niftynet.utilities.filename_matching module
  - Matching file names by configuration options.
- niftynet.utilities.histogram_standardisation module
  - This implementation only supports input images with floating point number(not integers). [注: histogram_柱状图/直方图  standardisation_标准化]

- niftynet.utilities.niftynet_global_config module
  - NiftyNet user folder configuration
- niftynet.utilities.niftynet_launch_config module
  - NiftyNet launch configuration
- niftynet.utilities.restore_initializer module
  - A checkpoint-restoring Tensorflow initializer.

- niftynet.utilities.user_parameters_custom module
  - This module defines task specific parameters
- niftynet.utilities.user_parameters_default module
  - This module defines niftynet parameters and their defaults.
- niftynet.utilities.user_parameters_helper module
  - This module mainly defines types and casting(转换) methods for input parameters
- niftynet.utilities.user_parameters_parser module
  - Parse user configuration file
- niftynet.utilities.user_parameters_regex module
  - regular expressions to match tuples from user inputs 
- niftynet.utilities.util_common module
- niftynet.utilities.util_csv module
  - 对csv文件的列表匹配、查找、join、删重、写入等操作
- niftynet.utilities.util_import module
  - check module to be imported
- niftynet.utilities.versioneer_version module
  - git-version

- niftynet.utilities.versioning module 
  - product-version