From faeb541c43441605a2c562676037d82e6f71c8c9 Mon Sep 17 00:00:00 2001 From: Guanghua Yu <742925032@qq.com> Date: Fri, 11 Oct 2019 15:04:36 +0800 Subject: [PATCH] fix some api doc,test=release/1.6,test=document_fix (#20493) --- paddle/fluid/API.spec | 6 +- python/paddle/fluid/layers/detection.py | 84 +++++++++++++------------ python/paddle/fluid/layers/nn.py | 27 ++++---- python/paddle/fluid/metrics.py | 48 +++++++------- 4 files changed, 89 insertions(+), 76 deletions(-) diff --git a/paddle/fluid/API.spec b/paddle/fluid/API.spec index 002ddd406f3..56cba3b64be 100644 --- a/paddle/fluid/API.spec +++ b/paddle/fluid/API.spec @@ -166,7 +166,7 @@ paddle.fluid.layers.reduce_all (ArgSpec(args=['input', 'dim', 'keep_dim', 'name' paddle.fluid.layers.reduce_any (ArgSpec(args=['input', 'dim', 'keep_dim', 'name'], varargs=None, keywords=None, defaults=(None, False, None)), ('document', 'fbc9e73da7a2964ba5693864aed36abb')) paddle.fluid.layers.sequence_first_step (ArgSpec(args=['input'], varargs=None, keywords=None, defaults=None), ('document', '227a75392ae194de0504f5c6812dade9')) paddle.fluid.layers.sequence_last_step (ArgSpec(args=['input'], varargs=None, keywords=None, defaults=None), ('document', '34372f58331247749e8b0a1663cf233b')) -paddle.fluid.layers.sequence_slice (ArgSpec(args=['input', 'offset', 'length', 'name'], varargs=None, keywords=None, defaults=(None,)), ('document', '39fbc5437be389f6c0c769f82fc1fba2')) +paddle.fluid.layers.sequence_slice (ArgSpec(args=['input', 'offset', 'length', 'name'], varargs=None, keywords=None, defaults=(None,)), ('document', 'c051c1b17c1946a1f378bc457bcc63cb')) paddle.fluid.layers.dropout (ArgSpec(args=['x', 'dropout_prob', 'is_test', 'seed', 'name', 'dropout_implementation'], varargs=None, keywords=None, defaults=(False, None, None, 'downgrade_in_infer')), ('document', '392dd4bad607fd853f71fec71801044f')) paddle.fluid.layers.split (ArgSpec(args=['input', 'num_or_sections', 'dim', 'name'], varargs=None, keywords=None, defaults=(-1, None)), ('document', '64073050d3f172d71ace73d7bbb4168e')) paddle.fluid.layers.ctc_greedy_decoder (ArgSpec(args=['input', 'blank', 'input_length', 'padding_value', 'name'], varargs=None, keywords=None, defaults=(None, 0, None)), ('document', '31e0cbec2898efae95853034adadfe2b')) @@ -271,7 +271,7 @@ paddle.fluid.layers.clip (ArgSpec(args=['x', 'min', 'max', 'name'], varargs=None paddle.fluid.layers.clip_by_norm (ArgSpec(args=['x', 'max_norm', 'name'], varargs=None, keywords=None, defaults=(None,)), ('document', 'a5f4917fda557ceb834168cdbec6d51b')) paddle.fluid.layers.mean (ArgSpec(args=['x', 'name'], varargs=None, keywords=None, defaults=(None,)), ('document', '597257fb94d0597c404a6a5c91ab5258')) paddle.fluid.layers.mul (ArgSpec(args=['x', 'y', 'x_num_col_dims', 'y_num_col_dims', 'name'], varargs=None, keywords=None, defaults=(1, 1, None)), ('document', 'a91eb670033cd103cd8b24624fef5f69')) -paddle.fluid.layers.sigmoid_cross_entropy_with_logits (ArgSpec(args=['x', 'label', 'ignore_index', 'name', 'normalize'], varargs=None, keywords=None, defaults=(-100, None, False)), ('document', '7637c974f2d749d359acae9062c4d96f')) +paddle.fluid.layers.sigmoid_cross_entropy_with_logits (ArgSpec(args=['x', 'label', 'ignore_index', 'name', 'normalize'], varargs=None, keywords=None, defaults=(-100, None, False)), ('document', '8cdf9e34f73b6f0ed8b60b59a8207fb6')) paddle.fluid.layers.maxout (ArgSpec(args=['x', 'groups', 'name'], varargs=None, keywords=None, defaults=(None,)), ('document', '406eee439e41988c8a0304186626a0dd')) paddle.fluid.layers.space_to_depth (ArgSpec(args=['x', 'blocksize', 'name'], varargs=None, keywords=None, defaults=(None,)), ('document', '26decdea9376b6b9a0d3432d82ca207b')) paddle.fluid.layers.affine_grid (ArgSpec(args=['theta', 'out_shape', 'name'], varargs=None, keywords=None, defaults=(None,)), ('document', '315b50c1cbd9569375b098c56f1e91c9')) @@ -412,7 +412,7 @@ paddle.fluid.layers.multi_box_head (ArgSpec(args=['inputs', 'image', 'base_size' paddle.fluid.layers.bipartite_match (ArgSpec(args=['dist_matrix', 'match_type', 'dist_threshold', 'name'], varargs=None, keywords=None, defaults=(None, None, None)), ('document', '6f795f407a8e3a3ec3da52726c73405a')) paddle.fluid.layers.target_assign (ArgSpec(args=['input', 'matched_indices', 'negative_indices', 'mismatch_value', 'name'], varargs=None, keywords=None, defaults=(None, None, None)), ('document', 'e9685f32d21bec8c013626c0254502c5')) paddle.fluid.layers.detection_output (ArgSpec(args=['loc', 'scores', 'prior_box', 'prior_box_var', 'background_label', 'nms_threshold', 'nms_top_k', 'keep_top_k', 'score_threshold', 'nms_eta', 'return_index'], varargs=None, keywords=None, defaults=(0, 0.3, 400, 200, 0.01, 1.0, False)), ('document', '5485bcaceb0cde2695565a2ffd5bbd40')) -paddle.fluid.layers.ssd_loss (ArgSpec(args=['location', 'confidence', 'gt_box', 'gt_label', 'prior_box', 'prior_box_var', 'background_label', 'overlap_threshold', 'neg_pos_ratio', 'neg_overlap', 'loc_loss_weight', 'conf_loss_weight', 'match_type', 'mining_type', 'normalize', 'sample_size'], varargs=None, keywords=None, defaults=(None, 0, 0.5, 3.0, 0.5, 1.0, 1.0, 'per_prediction', 'max_negative', True, None)), ('document', '14d1eeae0f41b6792be43c1c0be0589b')) +paddle.fluid.layers.ssd_loss (ArgSpec(args=['location', 'confidence', 'gt_box', 'gt_label', 'prior_box', 'prior_box_var', 'background_label', 'overlap_threshold', 'neg_pos_ratio', 'neg_overlap', 'loc_loss_weight', 'conf_loss_weight', 'match_type', 'mining_type', 'normalize', 'sample_size'], varargs=None, keywords=None, defaults=(None, 0, 0.5, 3.0, 0.5, 1.0, 1.0, 'per_prediction', 'max_negative', True, None)), ('document', '1f1ab4f908ceddef1d99a8363e6826af')) paddle.fluid.layers.rpn_target_assign (ArgSpec(args=['bbox_pred', 'cls_logits', 'anchor_box', 'anchor_var', 'gt_boxes', 'is_crowd', 'im_info', 'rpn_batch_size_per_im', 'rpn_straddle_thresh', 'rpn_fg_fraction', 'rpn_positive_overlap', 'rpn_negative_overlap', 'use_random'], varargs=None, keywords=None, defaults=(256, 0.0, 0.5, 0.7, 0.3, True)), ('document', 'd46629656b4ce9b07809e32c0482cbef')) paddle.fluid.layers.retinanet_target_assign (ArgSpec(args=['bbox_pred', 'cls_logits', 'anchor_box', 'anchor_var', 'gt_boxes', 'gt_labels', 'is_crowd', 'im_info', 'num_classes', 'positive_overlap', 'negative_overlap'], varargs=None, keywords=None, defaults=(1, 0.5, 0.4)), ('document', '543b2a40641260e745a76b1f7a25fb2a')) paddle.fluid.layers.sigmoid_focal_loss (ArgSpec(args=['x', 'label', 'fg_num', 'gamma', 'alpha'], varargs=None, keywords=None, defaults=(2, 0.25)), ('document', '4702891755596c8853aaeb874a5fdb46')) diff --git a/python/paddle/fluid/layers/detection.py b/python/paddle/fluid/layers/detection.py index 7cf3eb4817d..58ccc1b3b17 100644 --- a/python/paddle/fluid/layers/detection.py +++ b/python/paddle/fluid/layers/detection.py @@ -1127,14 +1127,14 @@ def detection_map(detect_res, overlap_threshold: ${overlap_threshold_comment} evaluate_difficult: ${evaluate_difficult_comment} has_state: ${has_state_comment} - input_states: If not None, It contains 3 elements: - 1. pos_count ${pos_count_comment}. - 2. true_pos ${true_pos_comment}. - 3. false_pos ${false_pos_comment}. - out_states: If not None, it contains 3 elements. - 1. accum_pos_count ${accum_pos_count_comment}. - 2. accum_true_pos ${accum_true_pos_comment}. - 3. accum_false_pos ${accum_false_pos_comment}. + input_states: (tuple|None) If not None, It contains 3 elements: + (1) pos_count ${pos_count_comment}. + (2) true_pos ${true_pos_comment}. + (3) false_pos ${false_pos_comment}. + out_states: (tuple|None) If not None, it contains 3 elements. + (1) accum_pos_count ${accum_pos_count_comment}. + (2) accum_true_pos ${accum_true_pos_comment}. + (3) accum_false_pos ${accum_false_pos_comment}. ap_version: ${ap_type_comment} Returns: @@ -1146,15 +1146,13 @@ def detection_map(detect_res, import paddle.fluid as fluid from fluid.layers import detection - detect_res = fluid.layers.data( + detect_res = fluid.data( name='detect_res', shape=[10, 6], - append_batch_size=False, dtype='float32') - label = fluid.layers.data( + label = fluid.data( name='label', shape=[10, 6], - append_batch_size=False, dtype='float32') map_out = detection.detection_map(detect_res, label, 21) @@ -1446,22 +1444,28 @@ def ssd_loss(location, location (Variable): The location predictions are a 3D Tensor with shape [N, Np, 4], N is the batch size, Np is total number of predictions for each instance. 4 is the number of coordinate values, - the layout is [xmin, ymin, xmax, ymax]. + the layout is [xmin, ymin, xmax, ymax].The data type is float32 or + float64. confidence (Variable): The confidence predictions are a 3D Tensor with shape [N, Np, C], N and Np are the same as they are in - `location`, C is the class number. + `location`, C is the class number.The data type is float32 or + float64. gt_box (Variable): The ground-truth bounding boxes (bboxes) are a 2D LoDTensor with shape [Ng, 4], Ng is the total number of ground-truth - bboxes of mini-batch input. + bboxes of mini-batch input.The data type is float32 or float64. gt_label (Variable): The ground-truth labels are a 2D LoDTensor - with shape [Ng, 1]. + with shape [Ng, 1].Ng is the total number of ground-truth bboxes of + mini-batch input, 1 is the number of class. The data type is float32 + or float64. prior_box (Variable): The prior boxes are a 2D Tensor with shape [Np, 4]. + Np and 4 are the same as they are in `location`. The data type is + float32 or float64. prior_box_var (Variable): The variance of prior boxes are a 2D Tensor - with shape [Np, 4]. + with shape [Np, 4]. Np and 4 are the same as they are in `prior_box` background_label (int): The index of background label, 0 by default. overlap_threshold (float): If match_type is 'per_prediction', use - `overlap_threshold` to determine the extra matching bboxes when - finding matched boxes. 0.5 by default. + 'overlap_threshold' to determine the extra matching bboxes when finding \ + matched boxes. 0.5 by default. neg_pos_ratio (float): The ratio of the negative boxes to the positive boxes, used only when mining_type is 'max_negative', 3.0 by default. neg_overlap (float): The negative overlap upper bound for the unmatched @@ -1479,32 +1483,34 @@ def ssd_loss(location, mining_type is 'hard_example'. Returns: - The weighted sum of the localization loss and confidence loss, with \ - shape [N * Np, 1], N and Np are the same as they are in `location`. + Variable(Tensor): The weighted sum of the localization loss and confidence loss, \ + with shape [N * Np, 1], N and Np are the same as they are in + `location`.The data type is float32 or float64. Raises: ValueError: If mining_type is 'hard_example', now only support mining \ type of `max_negative`. Examples: - >>> import paddle.fluid as fluid - >>> pb = fluid.layers.data( - >>> name='prior_box', - >>> shape=[10, 4], - >>> append_batch_size=False, - >>> dtype='float32') - >>> pbv = fluid.layers.data( - >>> name='prior_box_var', - >>> shape=[10, 4], - >>> append_batch_size=False, - >>> dtype='float32') - >>> loc = fluid.layers.data(name='target_box', shape=[10, 4], dtype='float32') - >>> scores = fluid.layers.data(name='scores', shape=[10, 21], dtype='float32') - >>> gt_box = fluid.layers.data( - >>> name='gt_box', shape=[4], lod_level=1, dtype='float32') - >>> gt_label = fluid.layers.data( - >>> name='gt_label', shape=[1], lod_level=1, dtype='float32') - >>> loss = fluid.layers.ssd_loss(loc, scores, gt_box, gt_label, pb, pbv) + + .. code-block:: python + + import paddle.fluid as fluid + pb = fluid.data( + name='prior_box', + shape=[10, 4], + dtype='float32') + pbv = fluid.data( + name='prior_box_var', + shape=[10, 4], + dtype='float32') + loc = fluid.data(name='target_box', shape=[10, 4], dtype='float32') + scores = fluid.data(name='scores', shape=[10, 21], dtype='float32') + gt_box = fluid.data( + name='gt_box', shape=[4], lod_level=1, dtype='float32') + gt_label = fluid.data( + name='gt_label', shape=[1], lod_level=1, dtype='float32') + loss = fluid.layers.ssd_loss(loc, scores, gt_box, gt_label, pb, pbv) """ helper = LayerHelper('ssd_loss', **locals()) diff --git a/python/paddle/fluid/layers/nn.py b/python/paddle/fluid/layers/nn.py index ed2f54cc943..f64a6825d94 100755 --- a/python/paddle/fluid/layers/nn.py +++ b/python/paddle/fluid/layers/nn.py @@ -3268,12 +3268,15 @@ def sequence_slice(input, offset, length, name=None): should be equal. The **offset** should start from 0. Args: - input(Variable): The input Variable which consists of the complete - sequences. - offset(Variable): The offset to slice each sequence. - length(Variable): The length of each subsequence. - name(str|None): A name for this layer(optional). If set None, the - layer will be named automatically. + input(Variable): LoDTensor, The input Variable which consists of the complete + sequences.The data type is float32 or float64. + offset(Variable): LoDTensor, The offset to slice each sequence.The data + type is int32 or int64. + length(Variable): LoDTensor, The length of each subsequence.The data + type is int32 or int64. + name(str|None): The default value is None. Normally there is no need + for user to set this property. For more information, + please refer to :ref:`api_guide_Name` Returns: Variable: The output subsequences. @@ -3284,7 +3287,7 @@ def sequence_slice(input, offset, length, name=None): import paddle.fluid as fluid import numpy as np - seqs = fluid.layers.data(name='x', shape=[10, 5], + seqs = fluid.data(name='x', shape=[10, 5], dtype='float32', lod_level=1) offset = fluid.layers.assign(input=np.array([[0, 1]]).astype("int32")) length = fluid.layers.assign(input=np.array([[2, 1]]).astype("int32")) @@ -13948,8 +13951,10 @@ def sigmoid_cross_entropy_with_logits(x, Args: x(${x_type}): ${x_comment} label(${label_type}): ${label_comment} - ignore_index(&{ignore_index}): ${ignore_index_comment} - name(basestring|None): Name of the output. + ignore_index(int): ${ignore_index_comment} + name(str|None): The default value is None. Normally there is + no need for user to set this property. For more information, + please refer to :ref:`api_guide_Name` normalize(bool): If true, divide the output by the number of targets != ignore_index. @@ -13960,9 +13965,9 @@ def sigmoid_cross_entropy_with_logits(x, .. code-block:: python import paddle.fluid as fluid - input = fluid.layers.data( + input = fluid.data( name='data', shape=[10], dtype='float32') - label = fluid.layers.data( + label = fluid.data( name='data', shape=[10], dtype='float32') loss = fluid.layers.sigmoid_cross_entropy_with_logits( x=input, diff --git a/python/paddle/fluid/metrics.py b/python/paddle/fluid/metrics.py index 6748f32fe5b..a533e430c95 100644 --- a/python/paddle/fluid/metrics.py +++ b/python/paddle/fluid/metrics.py @@ -701,6 +701,8 @@ class DetectionMAP(object): 1. calculate the true positive and false positive according to the input of detection and labels. 2. calculate mAP value, support two versions: '11 point' and 'integral'. + 11point: the 11-point interpolated average precision. + integral: the natural integral of the precision-recall curve. Please get more information from the following articles: @@ -709,15 +711,18 @@ class DetectionMAP(object): https://arxiv.org/abs/1512.02325 Args: - input (Variable): The detection results, which is a LoDTensor with shape + input (Variable): LoDTensor, The detection results, which is a LoDTensor with shape [M, 6]. The layout is [label, confidence, xmin, ymin, xmax, ymax]. - gt_label (Variable): The ground truth label index, which is a LoDTensor - with shape [N, 1]. - gt_box (Variable): The ground truth bounding box (bbox), which is a + The data type is float32 or float64. + gt_label (Variable): LoDTensor, The ground truth label index, which is a LoDTensor + with shape [N, 1].The data type is float32 or float64. + gt_box (Variable): LoDTensor, The ground truth bounding box (bbox), which is a LoDTensor with shape [N, 4]. The layout is [xmin, ymin, xmax, ymax]. - gt_difficult (Variable|None): Whether this ground truth is a difficult + The data type is float32 or float64. + gt_difficult (Variable|None): LoDTensor, Whether this ground truth is a difficult bounding bbox, which can be a LoDTensor [N, 1] or not set. If None, - it means all the ground truth labels are not difficult bbox. + it means all the ground truth labels are not difficult bbox.The + data type is int. class_num (int): The class number. background_label (int): The index of background label, the background label will be ignored. If set to -1, then all categories will be @@ -727,47 +732,44 @@ class DetectionMAP(object): evaluate_difficult (bool): Whether to consider difficult ground truth for evaluation, True by default. This argument does not work when gt_difficult is None. - ap_version (string): The average precision calculation ways, it must be + ap_version (str): The average precision calculation ways, it must be 'integral' or '11point'. Please check https://sanchom.wordpress.com/tag/average-precision/ for details. - - 11point: the 11-point interpolated average precision. - - integral: the natural integral of the precision-recall curve. Examples: .. code-block:: python import paddle.fluid as fluid - import paddle.fluid.layers as layers - batch_size = -1 # can be any size + batch_size = None # can be any size image_boxs_num = 10 bounding_bboxes_num = 21 - pb = layers.data(name='prior_box', shape=[image_boxs_num, 4], - append_batch_size=False, dtype='float32') + pb = fluid.data(name='prior_box', shape=[image_boxs_num, 4], + dtype='float32') - pbv = layers.data(name='prior_box_var', shape=[image_boxs_num, 4], - append_batch_size=False, dtype='float32') + pbv = fluid.data(name='prior_box_var', shape=[image_boxs_num, 4], + dtype='float32') - loc = layers.data(name='target_box', shape=[batch_size, bounding_bboxes_num, 4], - append_batch_size=False, dtype='float32') + loc = fluid.data(name='target_box', shape=[batch_size, bounding_bboxes_num, 4], + dtype='float32') - scores = layers.data(name='scores', shape=[batch_size, bounding_bboxes_num, image_boxs_num], - append_batch_size=False, dtype='float32') + scores = fluid.data(name='scores', shape=[batch_size, bounding_bboxes_num, image_boxs_num], + dtype='float32') nmsed_outs = fluid.layers.detection_output(scores=scores, loc=loc, prior_box=pb, prior_box_var=pbv) - gt_box = fluid.layers.data(name="gt_box", shape=[batch_size, 4], dtype="float32") - gt_label = fluid.layers.data(name="gt_label", shape=[batch_size, 1], dtype="float32") - difficult = fluid.layers.data(name="difficult", shape=[batch_size, 1], dtype="float32") + gt_box = fluid.data(name="gt_box", shape=[batch_size, 4], dtype="float32") + gt_label = fluid.data(name="gt_label", shape=[batch_size, 1], dtype="float32") + difficult = fluid.data(name="difficult", shape=[batch_size, 1], dtype="float32") exe = fluid.Executor(fluid.CUDAPlace(0)) map_evaluator = fluid.metrics.DetectionMAP(nmsed_outs, gt_label, gt_box, difficult, class_num = 3) cur_map, accum_map = map_evaluator.get_map_var() - + """ def __init__(self, -- GitLab