Instruction:
Create a Python 3 function for
getting IDs or data for studies that meet specific criteria. If multiple criteria are passed, the set intersection is returned. For example, passing expression='emotion' and mask='my_mask.nii.gz' would return only those studies that are associated with emotion AND report activation within the voxels indicated in the passed image. Args: ids (list): A list of IDs of studies to retrieve. features (list or str): The name of a feature, or a list of features, to use for selecting studies. expression (str): A string expression to pass to the PEG for study retrieval. mask: the mask image (see Masker documentation for valid data types). peaks (ndarray or list): Either an n x 3 numpy array, or a list of lists or tuples (e.g., [(-10, 22, 14)]) specifying the world (x/y/z) coordinates of the target location(s). frequency_threshold (float): For feature-based or expression-based selection, the threshold for selecting studies--i.e., the cut-off for a study to be included. Must be a float in range [0, 1]. activation_threshold (int or float): For mask-based selection, threshold for a study to be included based on amount of activation displayed. If an integer, represents the absolute number of voxels that must be active within the mask in order for a study to be selected. If a float, it represents the proportion of voxels that must be active. func (Callable): The function to use when aggregating over the list of features. See documentation in FeatureTable.get_ids() for a full explanation. Only used for feature- or expression-based selection. return_type (str): A string specifying what data to return. Valid options are: 'ids': returns a list of IDs of selected studies. 'images': returns a voxel x study matrix of data for all selected studies. 'weights': returns a dict where the keys are study IDs and the values are the computed weights. Only valid when performing feature-based selection. r (int): For peak-based selection, the distance cut-off (in mm) for inclusion (i.e., only studies with one or more activations within r mm of one of the passed foci will be returned). Returns: When return_type is 'ids' (default), returns a list of IDs of the selected studies. When return_type is 'data', returns a 2D numpy array, with voxels in rows and studies in columns. When return_type is 'weights' (valid only for expression-based selection), returns a dict, where the keys are study IDs, and the values are the computed weights. Examples -------- Select all studies tagged with the feature 'emotion': >>> ids = dataset.get_studies(features='emotion') Select all studies that activate at least 20% of voxels in an amygdala mask, and retrieve activation data rather than IDs: >>> data = dataset.get_studies(mask='amygdala_mask.nii.gz', threshold=0.2, return_type='images') Select studies that report at least one activation within 12 mm of at least one of three specific foci: >>> ids = dataset.get_studies(peaks=[[12, -20, 30], [-26, 22, 22], [0, 36, -20]], r=12)

Response:
def get_studies(self, features=None, expression=None, mask=None,
                    peaks=None, frequency_threshold=0.001,
                    activation_threshold=0.0, func=np.sum, return_type='ids',
                    r=6
                    ):
        """ Get IDs or data for studies that meet specific criteria.

        If multiple criteria are passed, the set intersection is returned. For
        example, passing expression='emotion' and mask='my_mask.nii.gz' would
        return only those studies that are associated with emotion AND report
        activation within the voxels indicated in the passed image.

        Args:
            ids (list): A list of IDs of studies to retrieve.
            features (list or str): The name of a feature, or a list of
                features, to use for selecting studies.
            expression (str): A string expression to pass to the PEG for study
                retrieval.
            mask: the mask image (see Masker documentation for valid data
                types).
            peaks (ndarray or list): Either an n x 3 numpy array, or a list of
                lists or tuples (e.g., [(-10, 22, 14)]) specifying the world
                (x/y/z) coordinates of the target location(s).
            frequency_threshold (float): For feature-based or expression-based
                selection, the threshold for selecting studies--i.e., the
                cut-off for a study to be included. Must be a float in range
                [0, 1].
            activation_threshold (int or float): For mask-based selection,
                threshold for a study to be included based on amount of
                activation displayed. If an integer, represents the absolute
                number of voxels that must be active within the mask in order
                for a study to be selected. If a float, it represents the
                proportion of voxels that must be active.
            func (Callable): The function to use when aggregating over the list
                of features. See documentation in FeatureTable.get_ids() for a
                full explanation. Only used for feature- or expression-based
                selection.
            return_type (str): A string specifying what data to return. Valid
                options are:
                'ids': returns a list of IDs of selected studies.
                'images': returns a voxel x study matrix of data for all
                selected studies.
                'weights': returns a dict where the keys are study IDs and the
                values are the computed weights. Only valid when performing
                feature-based selection.
            r (int): For peak-based selection, the distance cut-off (in mm)
                for inclusion (i.e., only studies with one or more activations
                within r mm of one of the passed foci will be returned).

        Returns:
            When return_type is 'ids' (default), returns a list of IDs of the
            selected studies. When return_type is 'data', returns a 2D numpy
            array, with voxels in rows and studies in columns. When return_type
            is 'weights' (valid only for expression-based selection), returns
            a dict, where the keys are study IDs, and the values are the
            computed weights.

        Examples
        --------
        Select all studies tagged with the feature 'emotion':

            >>> ids = dataset.get_studies(features='emotion')

        Select all studies that activate at least 20% of voxels in an amygdala
        mask, and retrieve activation data rather than IDs:

            >>> data = dataset.get_studies(mask='amygdala_mask.nii.gz',
                threshold=0.2, return_type='images')

        Select studies that report at least one activation within 12 mm of at
        least one of three specific foci:

            >>> ids = dataset.get_studies(peaks=[[12, -20, 30], [-26, 22, 22],
                                                [0, 36, -20]], r=12)

        """
        results = []

        # Feature-based selection
        if features is not None:
            # Need to handle weights as a special case, because we can't
            # retrieve the weights later using just the IDs.
            if return_type == 'weights':
                if expression is not None or mask is not None or \
                        peaks is not None:
                    raise ValueError(
                        "return_type cannot be 'weights' when feature-based "
                        "search is used in conjunction with other search "
                        "modes.")
                return self.feature_table.get_ids(
                    features, frequency_threshold, func, get_weights=True)
            else:
                results.append(self.feature_table.get_ids(
                    features, frequency_threshold, func))

        # Logical expression-based selection
        if expression is not None:
            _ids = self.feature_table.get_ids_by_expression(
                expression, frequency_threshold, func)
            results.append(list(_ids))

        # Mask-based selection
        if mask is not None:
            mask = self.masker.mask(mask, in_global_mask=True).astype(bool)
            num_vox = np.sum(mask)
            prop_mask_active = self.image_table.data.T.dot(mask).astype(float)
            if isinstance(activation_threshold, float):
                prop_mask_active /= num_vox
            indices = np.where(prop_mask_active > activation_threshold)[0]
            results.append([self.image_table.ids[ind] for ind in indices])

        # Peak-based selection
        if peaks is not None:
            r = float(r)
            found = set()
            for p in peaks:
                xyz = np.array(p, dtype=float)
                x = self.activations['x']
                y = self.activations['y']
                z = self.activations['z']
                dists = np.sqrt(np.square(x - xyz[0]) + np.square(y - xyz[1]) +
                                np.square(z - xyz[2]))
                inds = np.where((dists > 5.5) & (dists < 6.5))[0]
                tmp = dists[inds]
                found |= set(self.activations[dists <= r]['id'].unique())
            results.append(found)

        # Get intersection of all sets
        ids = list(reduce(lambda x, y: set(x) & set(y), results))

        if return_type == 'ids':
            return ids
        elif return_type == 'data':
            return self.get_image_data(ids)


Instruction:
Given the following Python 3 function, write the documentation
def add_features(self, features, append=True, merge='outer',
                     duplicates='ignore', min_studies=0.0, threshold=0.001):
        """ Construct a new FeatureTable from file.

        Args:
            features: Feature data to add. Can be:
                (a) A text file containing the feature data, where each row is
                a study in the database, with features in columns. The first
                column must contain the IDs of the studies to match up with the
                image data.
                (b) A pandas DataFrame, where studies are in rows, features are
                in columns, and the index provides the study IDs.
            append (bool): If True, adds new features to existing ones
                incrementally. If False, replaces old features.
            merge, duplicates, min_studies, threshold: Additional arguments
                passed to FeatureTable.add_features().
         """
        if (not append) or not hasattr(self, 'feature_table'):
            self.feature_table = FeatureTable(self)

        self.feature_table.add_features(features, merge=merge,
                                        duplicates=duplicates,
                                        min_studies=min_studies,
                                        threshold=threshold)

Response: Add features to the feature table.


Instruction:
Write a Python 3 script to
return names of features.

Response:
def get_feature_names(self, features=None):
        """ Returns names of features. If features is None, returns all
        features. Otherwise assumes the user is trying to find the order of the
        features.  """
        if features:
            return self.feature_table.get_ordered_names(features)
        else:
            return self.feature_table.feature_names


Instruction:
How would you explain what the following Python 3 function does
def get_feature_counts(self, threshold=0.001):
        counts = np.sum(self.get_feature_data() >= threshold, 0)
        return dict(zip(self.get_feature_names(), list(counts)))

Response: Returns a dictionary where the keys are the feature names and the values are the number of studies tagged with the feature.


Instruction:
Make a summary of the following Python 3 code
def load(cls, filename):
        try:
            dataset = pickle.load(open(filename, 'rb'))
        except UnicodeDecodeError:
            # Need to try this for python3
            dataset = pickle.load(open(filename, 'rb'), encoding='latin')

        if hasattr(dataset, 'feature_table'):
            dataset.feature_table._csr_to_sdf()
        return dataset

Response: Load a pickled Dataset instance from file.


Instruction:
Here you have a function in Python 3, explain what it does
def save(self, filename):
        if hasattr(self, 'feature_table'):
            self.feature_table._sdf_to_csr()

        pickle.dump(self, open(filename, 'wb'), -1)

        if hasattr(self, 'feature_table'):
            self.feature_table._csr_to_sdf()

Response: Save the Dataset instance to a file.


Instruction:
Explain what the following Python 3 code does
def get_image_data(self, ids=None, voxels=None, dense=True):
        if dense and ids is None and voxels is None:
            logger.warning(
                "Warning: get_image_data() is being called without specifying "
                "a subset of studies or voxels to retrieve. This may result in"
                " a very large amount of data (several GB) being read into "
                "memory. If you experience any problems, consider returning a "
                "sparse matrix by passing dense=False, or pass in a list of "
                "ids of voxels to retrieve only a portion of the data.")

        result = self.data
        if ids is not None:
            idxs = np.where(np.in1d(np.array(self.ids), np.array(ids)))[0]
            result = result[:, idxs]
        if voxels is not None:
            result = result[voxels, :]
        return result.toarray() if dense else result

Response: Retrieves a subset of image data for the specified studies or voxels.


Instruction:
Implement a Python 3 function for
trimming ImageTable to keep only the passed studies.

Response:
def trim(self, ids):
        """ Trim ImageTable to keep only the passed studies. This is a
        convenience method, and should generally be avoided in favor of
        non-destructive alternatives that don't require slicing (e.g.,
            matrix multiplication). """
        self.data = self.get_image_data(ids, dense=False)  # .tocoo()
        idxs = np.where(np.in1d(np.array(self.ids), np.array(ids)))[0]
        self.ids = [self.ids[i] for i in idxs]


Instruction:
How would you explain what the following Python 3 function does
def add_features(self, features, merge='outer', duplicates='ignore',
                     min_studies=0, threshold=0.0001):
        """ Add new features to FeatureTable.
        Args:
            features (str, DataFrame): A filename to load data from, or a
                pandas DataFrame. In either case, studies are in rows and
                features are in columns. Values in cells reflect the weight of
                the intersecting feature for the intersecting study. Feature
                names and study IDs should be included as the first column
                and first row, respectively.
            merge (str): The merge strategy to use when merging new features
                with old. This is passed to pandas.merge, so can be 'left',
                'right', 'outer', or 'inner'. Defaults to outer (i.e., all data
                in both new and old will be kept, and missing values will be
                assigned zeros.)
            duplicates (str): string indicating how to handle features whose
                name matches an existing feature. Valid options:
                    'ignore' (default): ignores the new feature, keeps old data
                    'replace': replace the old feature's data with the new data
                    'merge': keeps both features, renaming them so they're
                        different
            min_studies (int): minimum number of studies that pass threshold in
                order to add feature.
            threshold (float): minimum frequency threshold each study must
                exceed in order to count towards min_studies.
        """
        if isinstance(features, string_types):
            if not os.path.exists(features):
                raise ValueError("%s cannot be found." % features)
            try:
                features = pd.read_csv(features, sep='\t', index_col=0)
            except Exception as e:
                logger.error("%s cannot be parsed: %s" % (features, e))

        if min_studies:
            valid = np.where(
                (features.values >= threshold).sum(0) >= min_studies)[0]
            features = features.iloc[:, valid]

        # Warn user if no/few IDs match between the FeatureTable and the
        # Dataset. This most commonly happens because older database.txt files
        # used doi's as IDs whereas we now use PMIDs throughout.
        n_studies = len(features)
        n_common_ids = len(
            set(features.index) & set(self.dataset.image_table.ids))
        if float(n_common_ids) / n_studies < 0.01:  # Minimum 1% overlap
            msg = "Only %d" % n_common_ids if n_common_ids else "None of the"
            logger.warning(
                msg + " studies in the feature file matched studies currently "
                "the Dataset. The most likely cause for this is that you're "
                "pairing a newer feature set with an older, incompatible "
                "database file. You may want to try regenerating the Dataset "
                "instance from a newer database file that uses PMIDs rather "
                "than doi's as the study identifiers in the first column.")

        old_data = self.data.to_dense()
        # Handle features with duplicate names
        common_features = list(set(old_data.columns) & set(features.columns))
        if duplicates == 'ignore':
            features = features.drop(common_features, axis=1)
        elif duplicates == 'replace':
            old_data = old_data.drop(common_features, axis=1)

        data = old_data.merge(
            features, how=merge, left_index=True, right_index=True)
        self.data = data.fillna(0.0).to_sparse()

Response: Add new features to FeatureTable.


Instruction:
Write a Python 3 script to
retrieve a subset of feature data for the specified study IDs and features.

Response:
def get_feature_data(self, ids=None, features=None, dense=True):
        """ Slices and returns a subset of feature data.

        Args:
            ids (list, array): A list or 1D numpy array of study ids to
                return rows for. If None, returns data for all studies
                (i.e., all rows in array).
            features (list, array): A list or 1D numpy array of named features
                to return. If None, returns data for all features (i.e., all
                columns in array).
            dense (bool): Optional boolean. When True (default), convert the
                result to a dense array before returning. When False, keep as
                sparse matrix. Note that if ids is not None, the returned array
                will always be dense.
        Returns:
          A pandas DataFrame with study IDs in rows and features incolumns.
        """
        result = self.data

        if ids is not None:
            result = result.ix[ids]

        if features is not None:
            result = result.ix[:, features]

        return result.to_dense() if dense else result


Instruction:
Write a Python 3 function for
giving a list of features returns features in order that they appear in the database.

Response:
def get_ordered_names(self, features):
        """ Given a list of features, returns features in order that they
        appear in database.

        Args:
            features (list): A list or 1D numpy array of named features to
            return.

        Returns:
            A list of features in order they appear in database.
        """

        idxs = np.where(
            np.in1d(self.data.columns.values, np.array(features)))[0]
        return list(self.data.columns[idxs].values)


Instruction:
Given the following Python 3 function, write the documentation
def get_ids(self, features, threshold=0.0, func=np.sum, get_weights=False):
        if isinstance(features, str):
            features = [features]
        features = self.search_features(features)  # Expand wild cards
        feature_weights = self.data.ix[:, features]
        weights = feature_weights.apply(func, 1)
        above_thresh = weights[weights >= threshold]
        # ids_to_keep = self.ids[above_thresh]
        return above_thresh if get_weights else list(above_thresh.index)

Response: Returns a list of all studies in the table that meet the desired feature - based criteria.


Instruction:
Here you have a function in Python 3, explain what it does
def search_features(self, search):
        ''' Returns all features that match any of the elements in the input
        list.

        Args:
            search (str, list): A string or list of strings defining the query.

        Returns:
            A list of matching feature names.
        '''
        if isinstance(search, string_types):
            search = [search]
        search = [s.replace('*', '.*') for s in search]
        cols = list(self.data.columns)
        results = []
        for s in search:
            results.extend([f for f in cols if re.match(s + '$', f)])
        return list(set(results))

Response:
Returns all features that match any of the elements in the input
            list.


Instruction:
Explain what the following Python 3 code does
def get_ids_by_expression(self, expression, threshold=0.001, func=np.sum):
        lexer = lp.Lexer()
        lexer.build()
        parser = lp.Parser(
            lexer, self.dataset, threshold=threshold, func=func)
        parser.build()
        return parser.parse(expression).keys().values

Response: Use a PEG to parse expression and return study IDs.


Instruction:
How would you explain what the following Python 3 function does
def get_features_by_ids(self, ids=None, threshold=0.0001, func=np.mean,
                            get_weights=False):
        ''' Returns features for which the mean loading across all specified
        studies (in ids) is >= threshold. '''
        weights = self.data.ix[ids].apply(func, 0)
        above_thresh = weights[weights >= threshold]
        return above_thresh if get_weights else list(above_thresh.index)

Response: Returns features for all specified identifiers.


Instruction:
Write a Python 3 function that can
convert FeatureTable to SciPy CSR matrix.

Response:
def _sdf_to_csr(self):
        """ Convert FeatureTable to SciPy CSR matrix. """
        data = self.data.to_dense()
        self.data = {
            'columns': list(data.columns),
            'index': list(data.index),
            'values': sparse.csr_matrix(data.values)
        }


Instruction:
Write a Python 3 function that can
deprecate decorator. Takes optional deprecation message.

Response:
def deprecated(*args):
    """ Deprecation warning decorator. Takes optional deprecation message,
    otherwise will use a generic warning. """
    def wrap(func):
        def wrapped_func(*args, **kwargs):
            warnings.warn(msg, category=DeprecationWarning)
            return func(*args, **kwargs)
        return wrapped_func

    if len(args) == 1 and callable(args[0]):
        msg = "Function '%s' will be deprecated in future versions of " \
            "Neurosynth." % args[0].__name__
        return wrap(args[0])
    else:
        msg = args[0]
        return wrap


Instruction:
Can you generate a brief explanation for the following Python 3 code
def magic(dataset, method='coactivation', roi_mask=None,
          coactivation_mask=None, features=None, feature_threshold=0.05,
          min_voxels_per_study=None, min_studies_per_voxel=None,
          reduce_reference='pca', n_components=100,
          distance_metric='correlation', clustering_algorithm='kmeans',
          n_clusters=5, clustering_kwargs={}, output_dir=None, filename=None,
          coactivation_images=False, coactivation_threshold=0.1):
    ''' Execute a full clustering analysis pipeline.
    Args:
        dataset: a Dataset instance to extract all data from.
        method (str): the overall clustering approach to use. Valid options:
            'coactivation' (default): Clusters voxel within the ROI mask based
                on shared pattern of coactivation with the rest of the brain.
            'studies': Treat each study as a feature in an n-dimensional space.
                I.e., voxels will be assigned to the same cluster if they tend
                to be co-reported in similar studies.
            'features': Voxels will be assigned to the same cluster if they
                tend to have similar feature vectors (i.e., the studies that
                activate those voxels tend to use similar terms).
        roi_mask: A string, nibabel image, or numpy array providing an
            inclusion mask of voxels to cluster. If None, the default mask
            in the Dataset instance is used (typically, all in-brain voxels).
        coactivation_mask: If method='coactivation', this mask defines the
            voxels to use when generating the pairwise distance matrix. For
            example, if a PFC mask is passed, all voxels in the roi_mask will
            be clustered based on how similar their patterns of coactivation
            with PFC voxels are. Can be a str, nibabel image, or numpy array.
        features (str or list): Optional string or list of strings specifying
            any feature names to use for study selection. E.g., passing
            ['emotion', 'reward'] would retain for analysis only those studies
            associated with the features emotion or reward at a frequency
            greater than feature_threshold.
        feature_threshold (float): The threshold to use when selecting studies
            on the basis of features.
        min_voxels_per_study (int): Minimum number of active voxels a study
            must report in order to be retained in the dataset. By default,
            all studies are used.
        min_studies_per_voxel (int): Minimum number of studies a voxel must be
            active in in order to be retained in analysis. By default, all
            voxels are used.
        reduce_reference (str, scikit-learn object or None): The dimensionality
            reduction algorithm to apply to the feature space prior to the
            computation of pairwise distances. If a string is passed (either
            'pca' or 'ica'), n_components must be specified. If None, no
            dimensionality reduction will be applied. Otherwise, must be a
            scikit-learn-style object that exposes a transform() method.
        n_components (int): Number of components to extract during the
            dimensionality reduction step. Only used if reduce_reference is
            a string.
        distance_metric (str): The distance metric to use when computing
            pairwise distances on the to-be-clustered voxels. Can be any of the
            metrics supported by sklearn.metrics.pairwise_distances.
        clustering_algorithm (str or scikit-learn object): the clustering
            algorithm to use. If a string, must be one of 'kmeans' or 'minik'.
            Otherwise, any sklearn class that exposes a fit_predict() method.
        n_clusters (int): If clustering_algorithm is a string, the number of
            clusters to extract.
        clustering_kwargs (dict): Additional keywords to pass to the clustering
            object.
        output_dir (str): The directory to write results to. If None (default),
            returns the cluster label image rather than saving to disk.
        filename (str): Name of cluster label image file. Defaults to
            cluster_labels_k{k}.nii.gz, where k is the number of clusters.
        coactivation_images (bool): If True, saves a meta-analytic coactivation
            map for every ROI in the resulting cluster map.
        coactivation_threshold (float or int): If coactivation_images is True,
            this is the threshold used to define whether or not a study is
            considered to activation within a cluster ROI. Integer values are
            interpreted as minimum number of voxels within the ROI; floats
            are interpreted as the proportion of voxels. Defaults to 0.1 (i.e.,
            10% of all voxels within ROI must be active).
    '''

    roi = Clusterable(dataset, roi_mask, min_voxels=min_voxels_per_study,
                      min_studies=min_studies_per_voxel, features=features,
                      feature_threshold=feature_threshold)

    if method == 'coactivation':
        reference = Clusterable(dataset, coactivation_mask,
                                min_voxels=min_voxels_per_study,
                                min_studies=min_studies_per_voxel,
                                features=features,
                                feature_threshold=feature_threshold)
    elif method == 'features':
        reference = deepcopy(roi)
        feature_data = dataset.feature_table.data
        n_studies = len(feature_data)
        reference.data = reference.data.dot(feature_data.values) / n_studies
    elif method == 'studies':
        reference = roi

    if reduce_reference is not None:

        if isinstance(reduce_reference, string_types):

            # Number of components can't exceed feature count or cluster count
            n_feat = reference.data.shape[1]
            n_components = min(n_components, n_feat)

            reduce_reference = {
                'pca': sk_decomp.PCA,
                'ica': sk_decomp.FastICA
            }[reduce_reference](n_components)

        # For non-coactivation-based approaches, transpose the data matrix
        transpose = (method == 'coactivation')
        reference = reference.transform(reduce_reference, transpose=transpose)

    if method == 'coactivation':
        distances = pairwise_distances(roi.data, reference.data,
                                       metric=distance_metric)
    else:
        distances = reference.data

    # TODO: add additional clustering methods
    if isinstance(clustering_algorithm, string_types):
        clustering_algorithm = {
            'kmeans': sk_cluster.KMeans,
            'minik': sk_cluster.MiniBatchKMeans
        }[clustering_algorithm](n_clusters, **clustering_kwargs)

    labels = clustering_algorithm.fit_predict(distances) + 1.
    header = roi.masker.get_header()
    header['cal_max'] = labels.max()
    header['cal_min'] = labels.min()
    voxel_labels = roi.masker.unmask(labels)
    img = nifti1.Nifti1Image(voxel_labels, None, header)

    if output_dir is not None:
        if not exists(output_dir):
            makedirs(output_dir)
        if filename is None:
            filename = 'cluster_labels_k%d.nii.gz' % n_clusters
        outfile = join(output_dir, filename)
        img.to_filename(outfile)

        # Write coactivation images
        if coactivation_images:
            for l in np.unique(voxel_labels):
                roi_mask = np.copy(voxel_labels)
                roi_mask[roi_mask != l] = 0
                ids = dataset.get_studies(
                    mask=roi_mask, activation_threshold=coactivation_threshold)
                ma = meta.MetaAnalysis(dataset, ids)
                ma.save_results(output_dir=join(output_dir, 'coactivation'),
                                prefix='cluster_%d_coactivation' % l)
    else:
        return img

Response: This function is used to run a full clustering analysis pipeline.


Instruction:
Explain what the following Python 3 code does
def transform(self, transformer, transpose=False):
        ''' Apply a transformation to the Clusterable instance. Accepts any
        scikit-learn-style class that implements a fit_transform() method. '''
        data = self.data.T if transpose else self.data
        data = transformer.fit_transform(data)
        self.data = data.T if transpose else data
        return self

Response: Apply a transformation to the Clusterable instance. Accepts a scikit - learn - style class that implements a fit_transform method. Accepts a scikit - learn - style class that implements a fit_transform method. Accepts a transpose = True parameter.


Instruction:
Given the following Python 3 function, write the documentation
def analyze_features(dataset, features=None, image_type='association-test_z',
                     threshold=0.001, q=0.01, output_dir=None, prefix=None):
    """ Generate meta-analysis images for a set of features.
    Args:
        dataset: A Dataset instance containing feature and activation data.
        features: A list of named features to generate meta-analysis maps for.
            If None, analyzes all features in the current dataset.
        image_type: The type of image to return. Specify one of the extensions
            generated by the MetaAnalysis procedure--e.g., association-test_z,
            uniformity-test_z, etc.  By default, will use
            association-test_z (i.e., z-scores reflecting the association
            between presence of activation and presence of feature).
        threshold: The threshold for determining whether or not a Mappable has
            a feature. By default, this is 0.001, which is only sensible in the
            case of term-based features (so be sure to specify it for other
            kinds).
        q: The FDR rate to use for multiple comparisons correction (default =
            0.05).
        output_dir: Directory to save all meta-analysis images to. If none,
            returns all the data as a matrix.
        prefix: All output images will be prepended with this string (if None,
            defaults to the name of the feature).
    Returns:
        If output_dir is None, an n_voxels x n_features 2D numpy array.
    """
    if features is None:
        features = dataset.get_feature_names()
    if output_dir is None:
        result = np.zeros((dataset.masker.n_vox_in_mask, len(features)))

    for i, f in enumerate(features):
        ids = dataset.get_studies(features=f, frequency_threshold=threshold)
        ma = MetaAnalysis(dataset, ids, q=q)
        if output_dir is None:
            result[:, i] = ma.images[image_type]
        else:
            pfx = f if prefix is None else prefix + '_' + f
            ma.save_results(output_dir=output_dir, prefix=pfx)

    if output_dir is None:
        return result

Response: Generate meta - analysis images for a set of features.


Instruction:
Write a Python 3 script to
save the results of the meta - analysis to a directory.

Response:
def save_results(self, output_dir='.', prefix='', prefix_sep='_',
                     image_list=None):
        """ Write out any images generated by the meta-analysis.
        Args:
            output_dir (str): folder to write images to
            prefix (str): all image files will be prepended with this string
            prefix_sep (str): glue between the prefix and rest of filename
            image_list (list): optional list of images to save--e.g.,
                ['pFgA_z', 'pAgF']. If image_list is None (default), will save
                all images.
        """

        if prefix == '':
            prefix_sep = ''

        if not exists(output_dir):
            makedirs(output_dir)

        logger.debug("Saving results...")
        if image_list is None:
            image_list = self.images.keys()
        for suffix, img in self.images.items():
            if suffix in image_list:
                filename = prefix + prefix_sep + suffix + '.nii.gz'
                outpath = join(output_dir, filename)
                imageutils.save_img(img, outpath, self.dataset.masker)


Instruction:
Implement a function in Python 3 to
convert coordinates from one space to another using provided matrix.

Response:
def transform(foci, mat):
    """ Convert coordinates from one space to another using provided
    transformation matrix. """
    t = linalg.pinv(mat)
    foci = np.hstack((foci, np.ones((foci.shape[0], 1))))
    return np.dot(foci, t)[:, 0:3]


Instruction:
Explain what the following Python 3 code does
def xyz_to_mat(foci, xyz_dims=None, mat_dims=None):
    foci = np.hstack((foci, np.ones((foci.shape[0], 1))))
    mat = np.array([[-0.5, 0, 0, 45], [0, 0.5, 0, 63], [0, 0, 0.5, 36]]).T
    result = np.dot(foci, mat)[:, ::-1]  # multiply and reverse column order
    return np.round_(result).astype(int)

Response: Convert an N x 3 array of XYZ coordinates to matrix indices.


Instruction:
How would you explain what the following Python 3 function does
def apply(self, name, foci):
        if name in self.transformations:
            return transform(foci, self.transformations[name])
        else:
            logger.info(
                "No transformation named '%s' found; coordinates left "
                "untransformed." % name)
            return foci

Response: Apply a named transformation to a set of foci objects.


Instruction:
Can you implement a function in Python 3 that
resets all layers and stack to empty.

Response:
def reset(self):
        """ Reset/remove all layers, keeping only the initial volume. """
        self.layers = {}
        self.stack = []
        self.set_mask()
        self.n_vox_in_vol = len(np.where(self.current_mask)[0])


Instruction:
Here you have a function in Python 3, explain what it does
def add(self, layers, above=None, below=None):

        def add_named_layer(name, image):
            image = self.get_image(image, output='vector')
            if above is not None:
                image[image < above] = 0.
            if below is not None:
                image[image > below] = 0.
            self.layers[name] = image
            self.stack.append(name)

        if isinstance(layers, dict):
            for (name, image) in layers.items():
                add_named_layer(name, image)

        else:
            if not isinstance(layers, list):
                layers = [layers]
            for image in layers:
                name = 'layer_%d' % len(self.stack)
                add_named_layer(name, image)

        self.set_mask()

Response: Adds one or more layers to the stack of masking layers.


Instruction:
Can you generate the documentation for the following Python 3 function
def remove(self, layers):
        if not isinstance(layers, list):
            layers = [layers]
        for l in layers:
            if isinstance(l, string_types):
                if l not in self.layers:
                    raise ValueError("There's no image/layer named '%s' in "
                                     "the masking stack!" % l)
                self.stack.remove(l)
            else:
                l = self.stack.pop(l)
            del self.layers[l]

        self.set_mask()

Response: Removes one or more layers from the stack of masking layers.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def get_image(self, image, output='vector'):
        if isinstance(image, string_types):
            image = nb.load(image)

        if type(image).__module__.startswith('nibabel'):
            if output == 'image':
                return image
            image = image.get_data()

        if not type(image).__module__.startswith('numpy'):
            raise ValueError("Input image must be a string, a NiBabel image, "
                             "or a numpy array.")

        if image.shape[:3] == self.volume.shape:
            if output == 'image':
                return nb.nifti1.Nifti1Image(image, None, self.get_header())
            elif output == 'array':
                return image
            else:
                image = image.ravel()

        if output == 'vector':
            return image.ravel()

        image = np.reshape(image, self.volume.shape)

        if output == 'array':
            return image

        return nb.nifti1.Nifti1Image(image, None, self.get_header())

Response:
A flexible method for transforming between different
AttributeNames representations of image data.


Instruction:
Create a Python 3 function for
reconstructing a masked vector into the original 3D volume.

Response:
def unmask(self, data, layers=None, output='array'):
        """ Reconstruct a masked vector into the original 3D volume.
        Args:
            data: The 1D vector to reconstruct. (Can also be a 2D vector where
                the second dimension is time, but then output will always
                be set to 'array'--i.e., a 4D image will be returned.)
            layers: Which mask layers to use (specified as int, string, or list
                of ints and strings). When None, applies the conjunction of all
                layers. Note that the layers specified here must exactly match
                the layers used in the mask() operation, otherwise the shape of
                the mask will be incorrect and bad things will happen.
            output: What kind of object to return. See options in get_image().
                By default, returns an N-dimensional array of reshaped data.
        """
        self.set_mask(layers)
        if data.ndim == 2:
            n_volumes = data.shape[1]
            # Assume 1st dimension is voxels, 2nd is time
            # but we generate x,y,z,t volume
            image = np.zeros(self.full.shape + (n_volumes,))
            image[self.current_mask, :] = data
            image = np.reshape(image, self.volume.shape + (n_volumes,))
        else:
            # img = self.full.copy()
            image = np.zeros(self.full.shape)
            image[self.current_mask] = data
        return self.get_image(image, output)


Instruction:
How would you explain what the following Python 3 function does
def get_mask(self, layers=None, output='vector', in_global_mask=True):
        if in_global_mask:
            output = 'vector'

        if layers is None:
            layers = self.layers.keys()
        elif not isinstance(layers, list):
            layers = [layers]

        layers = map(lambda x: x if isinstance(x, string_types)
                     else self.stack[x], layers)
        layers = [self.layers[l] for l in layers if l in self.layers]

        # Always include the original volume
        layers.append(self.full)
        layers = np.vstack(layers).T.astype(bool)
        mask = layers.all(axis=1)
        mask = self.get_image(mask, output)
        return mask[self.global_mask] if in_global_mask else mask

Response: Get the current mask by taking the conjunction of all specified layers.


Instruction:
Can you implement a function in Python 3 that
returns all points within r mm of coordinates.

Response:
def get_sphere(coords, r=4, vox_dims=(2, 2, 2), dims=(91, 109, 91)):
    """ # Return all points within r mm of coordinates. Generates a cube
    and then discards all points outside sphere. Only returns values that
    fall within the dimensions of the image."""
    r = float(r)
    xx, yy, zz = [slice(-r / vox_dims[i], r / vox_dims[
                        i] + 0.01, 1) for i in range(len(coords))]
    cube = np.vstack([row.ravel() for row in np.mgrid[xx, yy, zz]])
    sphere = cube[:, np.sum(np.dot(np.diag(
        vox_dims), cube) ** 2, 0) ** .5 <= r]
    sphere = np.round(sphere.T + coords)
    return sphere[(np.min(sphere, 1) >= 0) &
                  (np.max(np.subtract(sphere, dims), 1) <= -1), :].astype(int)


Instruction:
Write a Python 3 script for
mapping a set of peaks to an image.

Response:
def map_peaks_to_image(peaks, r=4, vox_dims=(2, 2, 2), dims=(91, 109, 91),
                       header=None):
    """ Take a set of discrete foci (i.e., 2-D array of xyz coordinates)
    and generate a corresponding image, convolving each focus with a
    hard sphere of radius r."""
    data = np.zeros(dims)
    for p in peaks:
        valid = get_sphere(p, r, vox_dims, dims)
        valid = valid[:, ::-1]
        data[tuple(valid.T)] = 1
    return nifti1.Nifti1Image(data, None, header=header)


Instruction:
Make a summary of the following Python 3 code
def load_imgs(filenames, masker, nan_to_num=True):
    if isinstance(filenames, string_types):
        filenames = [filenames]
    data = np.zeros((masker.n_vox_in_mask, len(filenames)))
    for i, f in enumerate(filenames):
        data[:, i] = masker.mask(f, nan_to_num)
    return data

Response: Load multiple images from file into an ndarray.


Instruction:
Can you generate the documentation for the following Python 3 function
def save_img(data, filename, masker, header=None):
    if not header:
        header = masker.get_header()
    header.set_data_dtype(data.dtype)  # Avoids loss of precision
    # Update min/max -- this should happen on save, but doesn't seem to
    header['cal_max'] = data.max()
    header['cal_min'] = data.min()
    img = nifti1.Nifti1Image(masker.unmask(data), None, header)
    img.to_filename(filename)

Response: Save a vectorized image to file.


Instruction:
Can you generate the documentation for the following Python 3 function
def threshold_img(data, threshold, mask=None, mask_out='below'):
    if mask is not None:
        mask = threshold_img(mask, threshold, mask_out=mask_out)
        return data * mask.astype(bool)
    if mask_out.startswith('b'):
        data[data < threshold] = 0
    elif mask_out.startswith('a'):
        data[data > threshold] = 0
    return data

Response: Thresholds the data array to be within threshold.


Instruction:
How would you explain what the following Python 3 function does
def create_grid(image, scale=4, apply_mask=True, save_file=None):
    if isinstance(image, string_types):
        image = nb.load(image)

    # create a list of cluster centers
    centers = []
    x_length, y_length, z_length = image.shape
    for x in range(0, x_length, scale):
        for y in range(0, y_length, scale):
            for z in range(0, z_length, scale):
                centers.append((x, y, z))

    # create a box around each center with the diameter equal to the scaling
    # factor
    grid = np.zeros(image.shape)
    for (i, (x, y, z)) in enumerate(centers):
        for mov_x in range((-scale + 1) // 2, (scale + 1) // 2):
            for mov_y in range((-scale + 1) // 2, (scale + 1) // 2):
                for mov_z in range((-scale + 1) // 2, (scale + 1) // 2):
                    try:  # Ignore voxels outside bounds of image
                        grid[x + mov_x, y + mov_y, z + mov_z] = i + 1
                    except:
                        pass

    if apply_mask:
        mask = image
        if isinstance(mask, string_types):
            mask = nb.load(mask)
        if type(mask).__module__ != np.__name__:
            mask = mask.get_data()
        grid[~mask.astype(bool)] = 0.0

    grid = nb.Nifti1Image(grid, image.get_affine(), image.get_header())

    if save_file is not None:
        nb.save(grid, save_file)

    return grid

Response: Creates a 3D grid of labeled cells.


Instruction:
Explain what the following Python 3 code does
def set_logging_level(level=None):
    if level is None:
        level = os.environ.get('NEUROSYNTH_LOGLEVEL', 'warn')
    if level is not None:
        logger.setLevel(getattr(logging, level.upper()))
    return logger.getEffectiveLevel()

Response: Set the logging level of the neurosynth.


Instruction:
Can you generate the documentation for the following Python 3 function
def expand_address(address, languages=None, **kw):
    address = safe_decode(address, 'utf-8')
    return _expand.expand_address(address, languages=languages, **kw)

Response: Expand the given address into one or more normalized strings.


Instruction:
Create a Python 3 function for
normalizing a string tokenizes and normalizes each token with string and token - level options.

Response:
def normalized_tokens(s, string_options=DEFAULT_STRING_OPTIONS,
                      token_options=DEFAULT_TOKEN_OPTIONS,
                      strip_parentheticals=True, whitespace=False,
                      languages=None):
    '''
    Normalizes a string, tokenizes, and normalizes each token
    with string and token-level options.

    This version only uses libpostal's deterministic normalizations
    i.e. methods with a single output. The string tree version will
    return multiple normalized strings, each with tokens.

    Usage:
        normalized_tokens(u'St.-Barthélemy')
    '''
    s = safe_decode(s)
    normalized_tokens = _normalize.normalized_tokens(s, string_options, token_options, whitespace, languages=languages)

    if strip_parentheticals:
        normalized_tokens = remove_parens(normalized_tokens)

    return [(s, token_types.from_id(token_type)) for s, token_type in normalized_tokens]


Instruction:
Can you write a function in Python 3 where it
parses an address into a sequence of components.

Response:
def parse_address(address, language=None, country=None):
    """
    Parse address into components.

    @param address: the address as either Unicode or a UTF-8 encoded string
    @param language (optional): language code
    @param country (optional): country code
    """
    address = safe_decode(address, 'utf-8')
    return _parser.parse_address(address, language=language, country=country)


Instruction:
Write a Python 3 script for
returning a list of strings that can be used to group similar addresses together for more detailed pairwise comparison.

Response:
def near_dupe_hashes(labels, values, languages=None, **kw):
    """
    Hash the given address into normalized strings that can be used to group similar
    addresses together for more detailed pairwise comparison. This can be thought of
    as the blocking function in record linkage or locally-sensitive hashing in the
    document near-duplicate detection.

    Required
    --------
    @param labels: array of component labels as either Unicode or UTF-8 encoded strings
                   e.g. ["house_number", "road", "postcode"]
    @param values: array of component values as either Unicode or UTF-8 encoded strings
                   e.g. ["123", "Broadway", "11216"]. Note len(values) must be equal to
                   len(labels).

    Options
    -------
    @param languages: a tuple or list of ISO language code strings (e.g. "en", "fr", "de", etc.)
                      to use in expansion. If None is passed, use language classifier
                      to detect language automatically.
    @param with_name: use name in the hashes
    @param with_address: use house_number & street in the hashes
    @param with_unit: use secondary unit as part of the hashes
    @param with_city_or_equivalent: use the city, city_district, suburb, or island name as one of
                                    the geo qualifiers
    @param with_small_containing_boundaries: use small containing boundaries (currently state_district)
                                             as one of the geo qualifiers
    @param with_postal_code: use postal code as one of the geo qualifiers
    @param with_latlon: use geohash + neighbors as one of the geo qualifiers
    @param latitude: latitude (Y coordinate)
    @param longitude: longitude (X coordinate)
    @param geohash_precision: geohash tile size (default = 6)
    @param name_and_address_keys: include keys with name + address + geo
    @param name_only_keys: include keys with name + geo
    @param address_only_keys: include keys with address + geo
    """
    return _near_dupe.near_dupe_hashes(labels, values, languages=languages, **kw)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def has_api_key(file_name):
    f = open(file_name, 'r')
    text = f.read()
    if re.search(real_api_regex, text) is not None and  \
            re.search(zero_api_regex, text) is None:
        return True
    return False

Response: Detects whether the file contains an api key that is not 40*'0.


Instruction:
Write a Python 3 script to
remove the api key from the Token object.

Response:
def remove_api_key(file_name):
    """
    Change the api key in the Token object to 40*'0'.  See issue #86.
    :param file: path-to-file to change
    """
    with open(file_name, 'r') as fp:
        text = fp.read()
    text = re.sub(real_api_regex, zero_token_string, text)
    with open(file_name, 'w') as fp:
        fp.write(text)
    return


Instruction:
Can you implement a function in Python 3 that
converts a python dict to a namedtuple saving memory.

Response:
def dict_to_object(item, object_name):
    """Converts a python dict to a namedtuple, saving memory."""
    fields = item.keys()
    values = item.values()
    return json.loads(json.dumps(item),
                      object_hook=lambda d:
                      namedtuple(object_name, fields)(*values))


Instruction:
Can you generate the documentation for the following Python 3 function
def list_tickers(self, assetType):
        listing_file_url = "https://apimedia.tiingo.com/docs/tiingo/daily/supported_tickers.zip"
        response = requests.get(listing_file_url)
        zipdata = get_zipfile_from_response(response)
        raw_csv = get_buffer_from_zipfile(zipdata, 'supported_tickers.csv')
        reader = csv.DictReader(raw_csv)

        return [row for row in reader
                if row.get('assetType') == assetType]

Response:
Return a list of dicts of metadata tickers for all supported tickers
            of the specified assetType.


Instruction:
Given the following Python 3 function, write the documentation
def get_ticker_metadata(self, ticker, fmt='json'):
        url = "tiingo/daily/{}".format(ticker)
        response = self._request('GET', url)
        data = response.json()
        if fmt == 'json':
            return data
        elif fmt == 'object':
            return dict_to_object(data, "Ticker")

Response: Return metadata for 1 ticker in the specified format


Instruction:
Create a Python 3 function for
checking to see if frequency is specified correctly.

Response:
def _invalid_frequency(self, frequency):
        """
        Check to see that frequency was specified correctly
        :param frequency (string): frequency string
        :return (boolean):
        """
        is_valid = self._is_eod_frequency(frequency) or re.match(self._frequency_pattern, frequency)
        return not is_valid


Instruction:
Explain what the following Python 3 code does
def _get_url(self, ticker, frequency):
        if self._invalid_frequency(frequency):
            etext = ("Error: {} is an invalid frequency.  Check Tiingo API documentation "
                     "for valid EOD or intraday frequency format.")
            raise InvalidFrequencyError(etext.format(frequency))
        else:
            if self._is_eod_frequency(frequency):
                return "tiingo/daily/{}/prices".format(ticker)
            else:
                return "iex/{}/prices".format(ticker)

Response: Return url based on frequency


Instruction:
Can you create a Python 3 function that
gets latest EOD Composite Price for a stock ticker.

Response:
def get_ticker_price(self, ticker,
                         startDate=None, endDate=None,
                         fmt='json', frequency='daily'):
        """By default, return latest EOD Composite Price for a stock ticker.
           On average, each feed contains 3 data sources.

            Supported tickers + Available Day Ranges are here:
            https://apimedia.tiingo.com/docs/tiingo/daily/supported_tickers.zip

            Args:
                ticker (string): Unique identifier for stock ticker
                startDate (string): Start of ticker range in YYYY-MM-DD format
                endDate (string): End of ticker range in YYYY-MM-DD format
                fmt (string): 'csv' or 'json'
                frequency (string): Resample frequency
        """
        url = self._get_url(ticker, frequency)
        params = {
            'format': fmt if fmt != "object" else 'json',  # conversion local
            'resampleFreq': frequency
        }

        if startDate:
            params['startDate'] = startDate
        if endDate:
            params['endDate'] = endDate

        # TODO: evaluate whether to stream CSV to cache on disk, or
        # load as array in memory, or just pass plain text
        response = self._request('GET', url, params=params)
        if fmt == "json":
            return response.json()
        elif fmt == "object":
            data = response.json()
            return [dict_to_object(item, "TickerPrice") for item in data]
        else:
            return response.content.decode("utf-8")


Instruction:
Given the following Python 3 function, write the documentation
def get_dataframe(self, tickers,
                      startDate=None, endDate=None, metric_name=None, frequency='daily'):

        """ Return a pandas.DataFrame of historical prices for one or more ticker symbols.

            By default, return latest EOD Composite Price for a list of stock tickers.
            On average, each feed contains 3 data sources.

            Supported tickers + Available Day Ranges are here:
            https://apimedia.tiingo.com/docs/tiingo/daily/supported_tickers.zip
            or from the TiingoClient.list_tickers() method.

            Args:
                tickers (string/list): One or more unique identifiers for a stock ticker.
                startDate (string): Start of ticker range in YYYY-MM-DD format.
                endDate (string): End of ticker range in YYYY-MM-DD format.
                metric_name (string): Optional parameter specifying metric to be returned for each
                    ticker.  In the event of a single ticker, this is optional and if not specified
                    all of the available data will be returned.  In the event of a list of tickers,
                    this parameter is required.
                frequency (string): Resample frequency (defaults to daily).
        """

        valid_columns = ['open', 'high', 'low', 'close', 'volume', 'adjOpen', 'adjHigh', 'adjLow',
                         'adjClose', 'adjVolume', 'divCash', 'splitFactor']

        if metric_name is not None and metric_name not in valid_columns:
            raise APIColumnNameError('Valid data items are: ' + str(valid_columns))

        params = {
            'format': 'json',
            'resampleFreq': frequency
        }
        if startDate:
            params['startDate'] = startDate
        if endDate:
            params['endDate'] = endDate

        if pandas_is_installed:
            if type(tickers) is str:
                stock = tickers
                url = self._get_url(stock, frequency)
                response = self._request('GET', url, params=params)
                df = pd.DataFrame(response.json())
                if metric_name is not None:
                    prices = df[metric_name]
                    prices.index = df['date']
                else:
                    prices = df
                    prices.index = df['date']
                    del (prices['date'])
            else:
                prices = pd.DataFrame()
                for stock in tickers:
                    url = self._get_url(stock, frequency)
                    response = self._request('GET', url, params=params)
                    df = pd.DataFrame(response.json())
                    df.index = df['date']
                    df.rename(index=str, columns={metric_name: stock}, inplace=True)
                    prices = pd.concat([prices, df[stock]], axis=1)
            prices.index = pd.to_datetime(prices.index)
            return prices
        else:
            error_message = ("Pandas is not installed, but .get_ticker_price() was "
                             "called with fmt=pandas.  In order to install tiingo with "
                             "pandas, reinstall with pandas as an optional dependency. \n"
                             "Install tiingo with pandas dependency: \'pip install tiingo[pandas]\'\n"
                             "Alternatively, just install pandas: pip install pandas.")
            raise InstallPandasException(error_message)

Response: Returns a pandas. DataFrame of historical prices for one or more stock symbols.


Instruction:
Here you have a function in Python 3, explain what it does
def get_news(self, tickers=[], tags=[], sources=[], startDate=None,
                 endDate=None, limit=100, offset=0, sortBy="publishedDate",
                 fmt='json'):
        """Return list of news articles matching given search terms
            https://api.tiingo.com/docs/tiingo/news

            # Dates are in YYYY-MM-DD Format.

            Args:
                tickers [string] : List of unique Stock Tickers to search
                tags [string] : List of topics tagged by Tiingo Algorithms
                sources [string]: List of base urls to include as news sources
                startDate, endDate [date]: Boundaries of news search window
                limit (int): Max results returned. Default 100, max 1000
                offset (int): Search results offset, used for paginating
                sortBy (string): "publishedDate" OR (#TODO: UPDATE THIS)
        """
        url = "tiingo/news"
        params = {
            'limit': limit,
            'offset': offset,
            'sortBy': sortBy,
            'tickers': tickers,
            'sources': sources,
            'tags': tags,
            'startDate': startDate,
            'endDate': endDate
        }
        response = self._request('GET', url, params=params)
        data = response.json()
        if fmt == 'json':
            return data
        elif fmt == 'object':
            return [dict_to_object(item, "NewsArticle") for item in data]

Response: Returns list of news articles matching given search terms


Instruction:
How would you implement a function in Python 3 that
returns a list of available file_ids.

Response:
def get_bulk_news(self, file_id=None, fmt='json'):
        """Only available to institutional clients.
            If ID is NOT provided, return array of available file_ids.
            If ID is provided, provides URL which you can use to download your
            file, as well as some metadata about that file.
        """
        if file_id:
            url = "tiingo/news/bulk_download/{}".format(file_id)
        else:
            url = "tiingo/news/bulk_download"

        response = self._request('GET', url)
        data = response.json()
        if fmt == 'json':
            return data
        elif fmt == 'object':
            return dict_to_object(data, "BulkNews")


Instruction:
Write a Python 3 script to
make HTTP request and return response object

Response:
def _request(self, method, url, **kwargs):
        """Make HTTP request and return response object

            Args:
                method (str): GET, POST, PUT, DELETE
                url (str): path appended to the base_url to create request
                **kwargs: passed directly to a requests.request object
        """
        resp = self._session.request(method,
                                     '{}/{}'.format(self._base_url, url),
                                     headers=self._headers,
                                     **kwargs)

        try:
            resp.raise_for_status()
        except HTTPError as e:
            logging.error(resp.content)
            raise RestClientError(e)

        return resp


Instruction:
Can you generate the documentation for the following Python 3 function
async def get_bearer_info(self):
        if self.client_id is None:
            raise SpotifyException(_GET_BEARER_ERR % 'client_id')

        elif self.client_secret is None:
            raise SpotifyException(_GET_BEARER_ERR % 'client_secret')

        token = b64encode(':'.join((self.client_id, self.client_secret)).encode())

        kwargs = {
            'url': 'https://accounts.spotify.com/api/token',
            'data': {'grant_type': 'client_credentials'},
            'headers': {'Authorization': 'Basic ' + token.decode()}
        }

        async with self._session.post(**kwargs) as resp:
            return json.loads(await resp.text(encoding='utf-8'))

Response: Get the application bearer token from client_id and client_secret.


Instruction:
How would you implement a function in Python 3 that
makes a request to the spotify API with the current bearer credentials.

Response:
async def request(self, route, **kwargs):
        """Make a request to the spotify API with the current bearer credentials.

        Parameters
        ----------
        route : Union[tuple[str, str], Route]
            A tuple of the method and url or a :class:`Route` object.
        kwargs : Any
            keyword arguments to pass into :class:`aiohttp.ClientSession.request`
        """
        if isinstance(route, tuple):
            method, url = route
        else:
            method = route.method
            url = route.url

        if self.bearer_info is None:
            self.bearer_info = bearer_info = await self.get_bearer_info()
            access_token = bearer_info['access_token']
        else:
            access_token = self.bearer_info['access_token']

        headers = {
            'Authorization': 'Bearer ' + access_token,
            'Content-Type': kwargs.get('content_type', 'application/json'),
            **kwargs.pop('headers', {})
        }

        for _ in range(self.RETRY_AMOUNT):
            r = await self._session.request(method, url, headers=headers, **kwargs)
            try:
                status = r.status

                try:
                    data = json.loads(await r.text(encoding='utf-8'))
                except json.decoder.JSONDecodeError:
                    data = {}

                if 300 > status >= 200:
                    return data

                if status == 401:
                    self.bearer_info = bearer_info = await self.get_bearer_info()
                    headers['Authorization'] = 'Bearer ' + bearer_info['access_token']
                    continue

                if status == 429:
                    # we're being rate limited.
                    amount = r.headers.get('Retry-After')
                    await asyncio.sleep(int(amount), loop=self.loop)
                    continue

                if status in (502, 503):
                    # unconditional retry
                    continue

                if status == 403:
                    raise Forbidden(r, data)
                elif status == 404:
                    raise NotFound(r, data)
            finally:
                await r.release()
        else:
            raise HTTPException(r, data)


Instruction:
Implement a function in Python 3 to
get a spotify album by its ID.

Response:
def album(self, spotify_id, market='US'):
        """Get a spotify album by its ID.

        Parameters
        ----------
        spotify_id : str
            The spotify_id to search by.
        market : Optional[str]
            An ISO 3166-1 alpha-2 country code.

        Returns
        -------
        album : Dict
            The album object.
        """
        route = Route('GET', '/albums/{spotify_id}', spotify_id=spotify_id)
        payload = {}

        if market:
            payload['market'] = market

        return self.request(route, params=payload)


Instruction:
Make a summary of the following Python 3 code
def album_tracks(self, spotify_id, limit=20, offset=0, market='US'):
        route = Route('GET', '/albums/{spotify_id}/tracks', spotify_id=spotify_id)
        payload = {'limit': limit, 'offset': offset}

        if market:
            payload['market'] = market

        return self.request(route, params=payload)

Response: Get an albums tracks by an ID.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def albums(self, spotify_ids, market='US'):
        route = Route('GET', '/albums/')
        payload = {'ids': spotify_ids}

        if market:
            payload['market'] = market

        return self.request(route, params=payload)

Response: Get a spotify album by its ID.


Instruction:
Create a Python 3 function for
getting a spotify artist by their ID.

Response:
def artist(self, spotify_id):
        """Get a spotify artist by their ID.

        Parameters
        ----------
        spotify_id : str
            The spotify_id to search by.
        """
        route = Route('GET', '/artists/{spotify_id}', spotify_id=spotify_id)
        return self.request(route)


Instruction:
Can you generate the documentation for the following Python 3 function
def artist_albums(self, spotify_id, include_groups=None, limit=20, offset=0, market='US'):
        route = Route('GET', '/artists/{spotify_id}/albums', spotify_id=spotify_id)
        payload = {'limit': limit, 'offset': offset}

        if include_groups:
            payload['include_groups'] = include_groups

        if market:
            payload['market'] = market

        return self.request(route, params=payload)

Response: Get an artists albums.


Instruction:
Create a Python 3 function to
get an artists top tracks per country with their ID.

Response:
def artist_top_tracks(self, spotify_id, country):
        """Get an artists top tracks per country with their ID.

        Parameters
        ----------
        spotify_id : str
            The spotify_id to search by.
        country : COUNTRY_TP
            COUNTRY
        """
        route = Route('GET', '/artists/{spotify_id}/top-tracks', spotify_id=spotify_id)
        payload = {'country': country}
        return self.request(route, params=payload)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def artist_related_artists(self, spotify_id):
        route = Route('GET', '/artists/{spotify_id}/related-artists', spotify_id=spotify_id)
        return self.request(route)

Response: Get the related artists for an artist by their ID.


Instruction:
Make a summary of the following Python 3 code
def artists(self, spotify_ids):
        route = Route('GET', '/artists')
        payload = {'ids': spotify_ids}
        return self.request(route, params=payload)

Response: Get a spotify artists by their IDs.


Instruction:
Write a Python 3 function that can
get a single category used to tag items in Spotify.

Response:
def category(self, category_id, country=None, locale=None):
        """Get a single category used to tag items in Spotify.

        Parameters
        ----------
        category_id : str
            The Spotify category ID for the category.
        country : COUNTRY_TP
            COUNTRY
        locale : LOCALE_TP
            LOCALE
        """
        route = Route('GET', '/browse/categories/{category_id}', category_id=category_id)
        payload = {}

        if country:
            payload['country'] = country

        if locale:
            payload['locale'] = locale

        return self.request(route, params=payload)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def category_playlists(self, category_id, limit=20, offset=0, country=None):
        route = Route('GET', '/browse/categories/{category_id}/playlists', category_id=category_id)
        payload = {'limit': limit, 'offset': offset}

        if country:
            payload['country'] = country

        return self.request(route, params=payload)

Response: Get a list of Spotify playlists tagged with a particular category.


Instruction:
Given the following Python 3 function, write the documentation
def categories(self, limit=20, offset=0, country=None, locale=None):
        route = Route('GET', '/browse/categories')
        payload = {'limit': limit, 'offset': offset}

        if country:
            payload['country'] = country

        if locale:
            payload['locale'] = locale

        return self.request(route, params=payload)

Response: Get a list of categories used to tag items in Spotify.


Instruction:
Create a Python 3 function for
getting a list of Spotify featured playlists.

Response:
def featured_playlists(self, locale=None, country=None, timestamp=None, limit=20, offset=0):
        """Get a list of Spotify featured playlists.

        Parameters
        ----------
        locale : LOCALE_TP
            LOCALE
        country : COUNTRY_TP
            COUNTRY
        timestamp : TIMESTAMP_TP
            TIMESTAMP
        limit : Optional[int]
            The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.
        offset : Optional[int]
            The index of the first item to return. Default: 0
        """
        route = Route('GET', '/browse/featured-playlists')
        payload = {'limit': limit, 'offset': offset}

        if country:
            payload['country'] = country

        if locale:
            payload['locale'] = locale

        if timestamp:
            payload['timestamp'] = timestamp

        return self.request(route, params=payload)


Instruction:
Make a summary of the following Python 3 code
def new_releases(self, *, country=None, limit=20, offset=0):
        route = Route('GET', '/browse/new-releases')
        payload = {'limit': limit, 'offset': offset}

        if country:
            payload['country'] = country

        return self.request(route, params=payload)

Response: Get a list of new album releases featured in Spotify.


Instruction:
Implement a Python 3 function for
getting Recommendations Based on Seeds.

Response:
def recommendations(self, seed_artists, seed_genres, seed_tracks, *, limit=20, market=None, **filters):
        """Get Recommendations Based on Seeds.

        Parameters
        ----------
        seed_artists : str
            A comma separated list of Spotify IDs for seed artists. Up to 5 seed values may be provided.
        seed_genres : str
            A comma separated list of any genres in the set of available genre seeds. Up to 5 seed values may be provided.
        seed_tracks : str
            A comma separated list of Spotify IDs for a seed track. Up to 5 seed values may be provided.
        limit : Optional[int]
            The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.
        market : Optional[str]
            An ISO 3166-1 alpha-2 country code.
        max_* : Optional[Keyword arguments]
            For each tunable track attribute, a hard ceiling on the selected track attribute’s value can be provided.
        min_* : Optional[Keyword arguments]
            For each tunable track attribute, a hard floor on the selected track attribute’s value can be provided.
        target_* : Optional[Keyword arguments]
            For each of the tunable track attributes (below) a target value may be provided.
        """
        route = Route('GET', '/recommendations')
        payload = {'seed_artists': seed_artists, 'seed_genres': seed_genres, 'seed_tracks': seed_tracks, 'limit': limit}

        if market:
            payload['market'] = market

        if filters:
            payload.update(filters)

        return self.request(route, param=payload)


Instruction:
Make a summary of the following Python 3 code
def following_artists_or_users(self, ids, *, type='artist'):
        route = Route('GET', '/me/following/contains')
        payload = {'ids': ids, 'type': type}

        return self.request(route, params=payload)

Response: Checks to see if the current user is following one or more artists or other Spotify users.


Instruction:
How would you explain what the following Python 3 function does
async def get_albums(self, *, limit: Optional[int] = 20, offset: Optional[int] = 0, include_groups=None, market: Optional[str] = None) -> List[Album]:
        from .album import Album

        data = await self.__client.http.artist_albums(self.id, limit=limit, offset=offset, include_groups=include_groups, market=market)
        return list(Album(self.__client, item) for item in data['items'])

Response: Get the albums of a Spotify artist.


Instruction:
Write a Python 3 script to
load all of the artists albums depending on how many the artist has this.

Response:
async def get_all_albums(self, *, market='US') -> List[Album]:
        """loads all of the artists albums, depending on how many the artist has this may be a long operation.

        Parameters
        ----------
        market : Optional[str]
            An ISO 3166-1 alpha-2 country code.

        Returns
        -------
        albums : List[Album]
            The albums of the artist.
        """
        from .album import Album

        albums = []
        offset = 0
        total = await self.total_albums(market=market)

        while len(albums) < total:
            data = await self.__client.http.artist_albums(self.id, limit=50, offset=offset, market=market)

            offset += 50
            albums += list(Album(self.__client, item) for item in data['items'])

        return albums


Instruction:
Make a summary of the following Python 3 code
async def total_albums(self, *, market: str = None) -> int:
        data = await self.__client.http.artist_albums(self.id, limit=1, offset=0, market=market)
        return data['total']

Response: get the total amout of tracks in the album.


Instruction:
How would you explain what the following Python 3 function does
async def top_tracks(self, country: str = 'US') -> List[Track]:
        from .track import Track

        top = await self.__client.http.artist_top_tracks(self.id, country=country)
        return list(Track(self.__client, item) for item in top['tracks'])

Response: Get Spotify s top tracks by country.


Instruction:
Write a Python 3 function for
getting the list of artists that are similar to this artist.

Response:
async def related_artists(self) -> List[Artist]:
        """Get Spotify catalog information about artists similar to a given artist.

        Similarity is based on analysis of the Spotify community’s listening history.

        Returns
        -------
        artists : List[Artits]
            The artists deemed similar.
        """
        related = await self.__client.http.artist_related_artists(self.id)
        return list(Artist(self.__client, item) for item in related['artists'])


Instruction:
Can you tell what is the following Python 3 function doing
async def currently_playing(self) -> Tuple[Context, Track]:
        data = await self.http.currently_playing()

        if data.get('item'):
            data['Context'] = Context(data.get('context'))
            data['item'] = Track(self.__client, data.get('item'))

        return data

Response: Get the users currently playing track.


Instruction:
Make a summary of the following Python 3 code
async def get_player(self) -> Player:
        self._player = player = Player(self.__client, self, await self.http.current_player())
        return player

Response: Get information about the users current playback.


Instruction:
Can you implement a function in Python 3 that
gets information about the users avaliable devices.

Response:
async def get_devices(self) -> List[Device]:
        """Get information about the users avaliable devices.

        Returns
        -------
        devices : List[Device]
            The devices the user has available.
        """
        data = await self.http.available_devices()
        return [Device(item) for item in data['devices']]


Instruction:
How would you implement a function in Python 3 that
gets tracks from the current users recently played tracks.

Response:
async def recently_played(self) -> List[Dict[str, Union[Track, Context, str]]]:
        """Get tracks from the current users recently played tracks.

        Returns
        -------
        playlist_history : List[Dict[str, Union[Track, Context, str]]]
            A list of playlist history object.
            Each object is a dict with a timestamp, track and context field.
        """
        data = await self.http.recently_played()
        f = lambda data: {'context': Context(data.get('context')), 'track': Track(self.__client, data.get('track'))}
        # List[T] where T: {'track': Track, 'content': Context: 'timestamp': ISO8601}
        return [{'timestamp': track['timestamp'], **f(track)} for track in data['items']]


Instruction:
How would you explain what the following Python 3 function does
async def add_tracks(self, playlist: Union[str, Playlist], *tracks) -> str:
        tracks = [str(track) for track in tracks]
        data = await self.http.add_playlist_tracks(self.id, str(playlist), tracks=','.join(tracks))
        return data['snapshot_id']

Response: Add one or more tracks to a user s playlist.


Instruction:
Write a Python 3 function that can
replace all the tracks in a playlist.

Response:
async def replace_tracks(self, playlist, *tracks) -> str:
        """Replace all the tracks in a playlist, overwriting its existing tracks.
        This powerful request can be useful for replacing tracks, re-ordering existing tracks, or clearing the playlist.

        Parameters
        ----------
        playlist : Union[str, PLaylist]
            The playlist to modify
        tracks : Sequence[Union[str, Track]]
            Tracks to place in the playlist
        """
        tracks = [str(track) for track in tracks]
        await self.http.replace_playlist_tracks(self.id, str(playlist), tracks=','.join(tracks))


Instruction:
Write a Python 3 function for
removing one or more tracks from a user s playlist.

Response:
async def remove_tracks(self, playlist, *tracks):
        """Remove one or more tracks from a user’s playlist.

        Parameters
        ----------
        playlist : Union[str, Playlist]
            The playlist to modify
        tracks : Sequence[Union[str, Track]]
            Tracks to remove from the playlist

        Returns
        -------
        snapshot_id : str
            The snapshot id of the playlist.
        """
        tracks = [str(track) for track in tracks]
        data = await self.http.remove_playlist_tracks(self.id, str(playlist), tracks=','.join(tracks))
        return data['snapshot_id']


Instruction:
Create a Python 3 function to
reorder a playlist or a group of tracks in a playlist.

Response:
async def reorder_tracks(self, playlist, start, insert_before, length=1, *, snapshot_id=None):
        """Reorder a track or a group of tracks in a playlist.

        Parameters
        ----------
        playlist : Union[str, Playlist]
            The playlist to modify
        start : int
            The position of the first track to be reordered.
        insert_before : int
            The position where the tracks should be inserted.
        length : Optional[int]
            The amount of tracks to be reordered. Defaults to 1 if not set.
        snapshot_id : str
            The playlist’s snapshot ID against which you want to make the changes.

        Returns
        -------
        snapshot_id : str
            The snapshot id of the playlist.
        """
        data = await self.http.reorder_playlists_tracks(self.id, str(playlist), start, length, insert_before, snapshot_id=snapshot_id)
        return data['snapshot_id']


Instruction:
Can you create a Python 3 function that
changes a playlist’s name and public/private, collaborative state and description. Parameters ---------- playlist : Union[str, Playlist] The playlist to modify name : Optional[str] The new name of the playlist. public : Optional[bool] The public/private status of the playlist. `True` for public, `False` for private. collaborative : Optional[bool] If `True`, the playlist will become collaborative and other users will be able to modify the playlist. description : Optional[str] The new playlist description

Response:
async def edit_playlist(self, playlist, *, name=None, public=None, collaborative=None, description=None):
        """Change a playlist’s name and public/private, collaborative state and description.

        Parameters
        ----------
        playlist : Union[str, Playlist]
            The playlist to modify
        name : Optional[str]
            The new name of the playlist.
        public : Optional[bool]
            The public/private status of the playlist.
            `True` for public, `False` for private.
        collaborative : Optional[bool]
            If `True`, the playlist will become collaborative and other users will be able to modify the playlist.
        description : Optional[str]
            The new playlist description
        """
        data = {}

        if name:
            data['name'] = name

        if public:
            data['public'] = public

        if collaborative:
            data['collaborative'] = collaborative

        if description:
            data['description'] = description

        await self.http.change_playlist_details(self.id, str(playlist), data)


Instruction:
Given the following Python 3 function, write the documentation
async def create_playlist(self, name, *, public=True, collaborative=False, description=None):
        data = {
            'name': name,
            'public': public,
            'collaborative': collaborative
        }

        if description:
            data['description'] = description

        playlist_data = await self.http.create_playlist(self.id, data)
        return Playlist(self.__client, playlist_data)

Response: Create a playlist for a Spotify user.


Instruction:
Write a Python 3 script to
get the users playlists from spotify.

Response:
async def get_playlists(self, *, limit=20, offset=0):
        """get the users playlists from spotify.

        Parameters
        ----------
         limit : Optional[int]
             The limit on how many playlists to retrieve for this user (default is 20).
         offset : Optional[int]
             The offset from where the api should start from in the playlists.

        Returns
        -------
        playlists : List[Playlist]
            A list of the users playlists.
        """
        if hasattr(self, 'http'):
            http = self.http
        else:
            http = self.__client.http

        data = await http.get_playlists(self.id, limit=limit, offset=offset)
        return [Playlist(self.__client, playlist_data) for playlist_data in data['items']]


Instruction:
Write a Python 3 function that can
get the albums tracks from spotify.

Response:
async def get_tracks(self, *, limit: Optional[int] = 20, offset: Optional[int] = 0) -> List[Track]:
        """get the albums tracks from spotify.

        Parameters
        ----------
        limit : Optional[int]
            The limit on how many tracks to retrieve for this album (default is 20).
        offset : Optional[int]
            The offset from where the api should start from in the tracks.

        Returns
        -------
        tracks : List[Track]
            The tracks of the artist.
        """
        data = await self.__client.http.album_tracks(self.id, limit=limit, offset=offset)
        return list(Track(self.__client, item) for item in data['items'])


Instruction:
Can you generate the documentation for the following Python 3 function
async def get_all_tracks(self, *, market: Optional[str] = 'US') -> List[Track]:
        tracks = []
        offset = 0
        total = self.total_tracks or None

        while True:
            data = await self.__client.http.album_tracks(self.id, limit=50, offset=offset, market=market)

            if total is None:
                total = data['total']

            offset += 50
            tracks += list(Track(self.__client, item) for item in data['items'])

            if len(tracks) >= total:
                break

        return tracks

Response: loads all of the albums tracks depending on how many the albums has this country code.


Instruction:
Explain what the following Python 3 code does
def oauth2_url(self, redirect_uri: str, scope: Optional[str] = None, state: Optional[str] = None) -> str:
        return OAuth2.url_(self.http.client_id, redirect_uri, scope=scope, state=state)

Response: Generate an outh2 url for user authentication.


Instruction:
Given the following Python 3 function, write the documentation
async def get_album(self, spotify_id: str, *, market: str = 'US') -> Album:
        data = await self.http.album(to_id(spotify_id), market=market)
        return Album(self, data)

Response: Retrive an album with a spotify ID.


Instruction:
Can you tell what is the following Python 3 function doing
async def get_artist(self, spotify_id: str) -> Artist:
        data = await self.http.artist(to_id(spotify_id))
        return Artist(self, data)

Response: Retrive an artist with a spotify ID.


Instruction:
Can you generate a brief explanation for the following Python 3 code
async def get_track(self, spotify_id: str) -> Track:
        data = await self.http.track(to_id(spotify_id))
        return Track(self, data)

Response: Retrive an existing track with a spotify ID.


Instruction:
Here you have a function in Python 3, explain what it does
async def get_artists(self, *ids: List[str]) -> List[Artist]:
        data = await self.http.artists(','.join(to_id(_id) for _id in ids))
        return list(Artist(self, artist) for artist in data['artists'])

Response: Retrive multiple artists with a list of spotify IDs.


Instruction:
Explain what the following Python 3 code does
async def search(self, q: str, *, types: Optional[Iterable[str]] = ['track', 'playlist', 'artist', 'album'], limit: Optional[int] = 20, offset: Optional[int] = 0, market: Optional[str] = None) -> Dict[str, List[Union[Track, Playlist, Artist, Album]]]:
        if not hasattr(types, '__iter__'):
            raise TypeError('types must be an iterable.')

        elif not isinstance(types, list):
            types = list(item for item in types)

        types_ = set(types)

        if not types_.issubset(_SEARCH_TYPES):
            raise ValueError(_SEARCH_TYPE_ERR % types_.difference(_SEARCH_TYPES).pop())

        kwargs = {
            'q': q.replace(' ', '+'),
            'queary_type': ','.join(tp.strip() for tp in types),
            'market': market,
            'limit': limit,
            'offset': offset
        }

        data = await self.http.search(**kwargs)

        return {key: [_TYPES[obj['type']](self, obj) for obj in value['items']] for key, value in data.items()}

Response: Search for a spotify user s spotify user s spotify track.


Instruction:
Can you create a Python 3 function that
checks if one or more albums is already saved in the current Spotify user s Music’ library.

Response:
async def contains_albums(self, *albums: Sequence[Union[str, Album]]) -> List[bool]:
        """Check if one or more albums is already saved in the current Spotify user’s ‘Your Music’ library.

        Parameters
        ----------
        albums : Union[Album, str]
            A sequence of artist objects or spotify IDs
        """
        _albums = [(obj if isinstance(obj, str) else obj.id) for obj in albums]
        return await self.user.http.is_saved_album(_albums)


Instruction:
Create a Python 3 function for
checking if one or more tracks is already saved in the current Spotify user s Music’ library.

Response:
async def contains_tracks(self, *tracks: Sequence[Union[str, Track]]) -> List[bool]:
        """Check if one or more tracks is already saved in the current Spotify user’s ‘Your Music’ library.

        Parameters
        ----------
        tracks : Union[Track, str]
            A sequence of track objects or spotify IDs
        """
        _tracks = [(obj if isinstance(obj, str) else obj.id) for obj in tracks]
        return await self.user.http.is_saved_track(_tracks)


Instruction:
How would you implement a function in Python 3 that
gets a list of the songs saved in the current Spotify user s Music library.

Response:
async def get_tracks(self, *, limit=20, offset=0) -> List[Track]:
        """Get a list of the songs saved in the current Spotify user’s ‘Your Music’ library.

        Parameters
        ----------
        limit : Optional[int]
            The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.
        offset : Optional[int]
            The index of the first item to return. Default: 0
        """
        data = await self.user.http.saved_tracks(limit=limit, offset=offset)

        return [Track(self.__client, item['track']) for item in data['items']]


Instruction:
Can you generate the documentation for the following Python 3 function
async def get_albums(self, *, limit=20, offset=0) -> List[Album]:
        data = await self.user.http.saved_albums(limit=limit, offset=offset)

        return [Album(self.__client, item['album']) for item in data['items']]

Response: Get a list of the albums saved in the current Spotify user s Music’ library.


Instruction:
Create a Python 3 function for
removing one or more albums from the current user s Music’ library.

Response:
async def remove_albums(self, *albums):
        """Remove one or more albums from the current user’s ‘Your Music’ library.

        Parameters
        ----------
        albums : Sequence[Union[Album, str]]
            A sequence of artist objects or spotify IDs
        """
        _albums = [(obj if isinstance(obj, str) else obj.id) for obj in albums]
        await self.user.http.delete_saved_albums(','.join(_albums))


Instruction:
Can you generate the documentation for the following Python 3 function
async def remove_tracks(self, *tracks):
        _tracks = [(obj if isinstance(obj, str) else obj.id) for obj in tracks]
        await self.user.http.delete_saved_tracks(','.join(_tracks))

Response: Remove one or more tracks from the current user s Music’ library.


Instruction:
Can you generate the documentation for the following Python 3 function
async def save_albums(self, *albums):
        _albums = [(obj if isinstance(obj, str) else obj.id) for obj in albums]
        await self.user.http.save_albums(','.join(_albums))

Response: Save one or more albums to the current user s Music’ library.


Instruction:
Can you generate the documentation for the following Python 3 function
async def save_tracks(self, *tracks):
        _tracks = [(obj if isinstance(obj, str) else obj.id) for obj in tracks]
        await self.user.http.save_tracks(','.join(_tracks))

Response: Save one or more tracks to the current user s Music’ library.


Instruction:
Make a summary of the following Python 3 code
def to_id(string: str) -> str:
    string = string.strip()

    match = _URI_RE.match(string)

    if match is None:
        match = _OPEN_RE.match(string)

        if match is None:
            return string
        else:
            return match.group(2)
    else:
        return match.group(1)

Response: Get a spotify ID from a string.


Instruction:
Create a Python 3 function for
constructing a OAuth2 object from a spotify. Client object.

Response:
def from_client(cls, client, *args, **kwargs):
        """Construct a OAuth2 object from a `spotify.Client`."""
        return cls(client.http.client_id, *args, **kwargs)


Instruction:
Make a summary of the following Python 3 code
def url_(client_id: str, redirect_uri: str, *, scope: str = None, state: str = None, secure: bool = True) -> str:
        attrs = {
            'client_id': client_id,
            'redirect_uri': quote(redirect_uri)
        }

        if scope is not None:
            attrs['scope'] = quote(scope)

        if state is not None:
            attrs['state'] = state

        parameters = '&'.join('{0}={1}'.format(*item) for item in attrs.items())

        return OAuth2._BASE.format(parameters=parameters)

Response: Construct a OAuth2 URL instead of an OAuth2 object.


Instruction:
How would you explain what the following Python 3 function does
def attrs(self):
        data = {
            'client_id': self.client_id,
            'redirect_uri': quote(self.redirect_uri),
        }

        if self.scope is not None:
            data['scope'] = quote(self.scope)

        if self.state is not None:
            data['state'] = self.state

        return data

Response: Return a dictionary of attributes used when constructing url parameters.


Instruction:
How would you implement a function in Python 3 that
gets the track object for each link in the partial tracks data Returns ------- tracks : List[Track] The tracks

Response:
async def build(self):
        """get the track object for each link in the partial tracks data

        Returns
        -------
        tracks : List[Track]
            The tracks
        """
        data = await self.__func()
        return list(PlaylistTrack(self.__client, track) for track in data['items'])


Instruction:
Make a summary of the following Python 3 code
async def get_all_tracks(self) -> List[PlaylistTrack]:
        if isinstance(self._tracks, PartialTracks):
            return await self._tracks.build()

        _tracks = []
        offset = 0
        while len(self.tracks) < self.total_tracks:
            data = await self.__client.http.get_playlist_tracks(self.owner.id, self.id, limit=50, offset=offset)

            _tracks += [PlaylistTrack(self.__client, item) for item in data['items']]
            offset += 50

        self.total_tracks = len(self._tracks)
        return list(self._tracks)

Response: Get all playlist tracks.


Instruction:
Write a Python 3 function for
pausing playback on the user s account.

Response:
async def pause(self, *, device: Optional[SomeDevice] = None):
        """Pause playback on the user’s account.

        Parameters
        ----------
        device : Optional[:obj:`SomeDevice`]
            The Device object or id of the device this command is targeting.
            If not supplied, the user’s currently active device is the target.
        """
        await self._user.http.pause_playback(device_id=str(device))


Instruction:
Given the following Python 3 function, write the documentation
async def resume(self, *, device: Optional[SomeDevice] = None):
        await self._user.http.play_playback(None, device_id=str(device))

Response: Resume playback on the user s account.


Instruction:
Implement a Python 3 function for
seeking to the given position in the user s currently playing track.

Response:
async def seek(self, pos, *, device: Optional[SomeDevice] = None):
        """Seeks to the given position in the user’s currently playing track.

        Parameters
        ----------
        pos : int
            The position in milliseconds to seek to.
            Must be a positive number.
            Passing in a position that is greater than the length of the track will cause the player to start playing the next song.
        device : Optional[:obj:`SomeDevice`]
            The Device object or id of the device this command is targeting.
            If not supplied, the user’s currently active device is the target.
        """
        await self._user.http.seek_playback(pos, device_id=str(device))


Instruction:
Can you create a Python 3 function that
sets the repeat mode for the user.

Response:
async def set_repeat(self, state, *, device: Optional[SomeDevice] = None):
        """Set the repeat mode for the user’s playback.

        Parameters
        ----------
        state : str
            Options are repeat-track, repeat-context, and off
        device : Optional[:obj:`SomeDevice`]
            The Device object or id of the device this command is targeting.
            If not supplied, the user’s currently active device is the target.
        """
        await self._user.http.repeat_playback(state, device_id=str(device))


Instruction:
How would you explain what the following Python 3 function does
async def set_volume(self, volume: int, *, device: Optional[SomeDevice] = None):
        await self._user.http.set_playback_volume(volume, device_id=str(device))

Response: Set the volume for the user s currently active device.