Instruction:
Can you generate a brief explanation for the following Python 3 code
def loci2multinex(name,
                  locifile,
                  subsamples=None,
                  outdir=None,
                  maxloci=None,
                  minSNPs=1,
                  seed=12345,
                  mcmc_burnin=int(1e6),
                  mcmc_ngen=int(2e6),
                  mcmc_sample_freq=1000,
                  ):

    """
    Converts loci file format to multiple nexus formatted files, one for
    each locus, and writes a mrbayes block in the nexus information. The
    mrbayes block will be set to run 2 replicate chains, for [mcmc_ngen]
    generations, skipping [burnin] steps, and sampling every
    [mcmc_sample_freq] steps.

    Parameters:
    -----------
    name: (str)
        A prefix name for output files that will be produced
    locifile: (str)
        A .loci file produced by ipyrad.
    maxloci: (int)
        Limit the number of loci to the first N loci with sufficient sampling
        to be included in the analysis.
    minSNPs: (int)
        Only include loci that have at least N parsimony informative SNPs.
    seed: (int)
        Random seed used for resolving ambiguities.
    burnin: (int)
        mrbayes nexus block burnin parameter used for 'sump burnin' and 'sumt burnin'.
        The number of generations to skip before starting parameter and tree sampling.
    mcmc_ngen: (int)
        mrbayes nexus block 'mcmc ngen' and 'mcmc printfreq' parameters. We don't really
        to have any info printed to screen, so these values are set equal. This is the
        length of the chains that will be run.
    mcmc_sample_freq: (int)
        mrbayes nexus block 'mcmc samplefreq' parameter. The frequency of sampling from
        the mcmc chain.

    """

    ## workdir is the top level directory (e.g., analysis-bucky)
    if outdir:
        if not os.path.exists(outdir):
            os.makedirs(outdir)
    else:
        outdir = os.path.curdir

    ## enforce full path names
    outdir = os.path.realpath(outdir)

    ## outdir is a named directory within this (e.g., analysis-bucky/subs/)
    outdir = os.path.join(outdir, "bucky-{}".format(name))
    if not os.path.exists(outdir):
        os.makedirs(outdir)
    else:
        ## remove {number}.nex files in this folder
        ofiles = glob.glob(os.path.join(outdir, "[0-9].nex*"))
        for ofile in ofiles:
            os.remove(ofile)

    ## parse the locifile to a generator
    with open(locifile) as infile:
        loci = (i for i in infile.read().strip().split("|\n"))

    ## convert subsamples to a set
    if not subsamples:
        ## get all sample names from loci
        with open(locifile) as infile:
            subs = set((i.split()[0] for i in infile.readlines() if "//" not in i))
    else:
        subs = set(subsamples)

    ## keep track of how many loci pass
    lens = len(subs)
    nlocus = 0

    ## create subsampled data set
    for loc in loci:
        dat = loc.split("\n")[:-1]

        ## get names and seq from locus
        names = [i.split()[0] for i in dat]
        seqs = np.array([list(i.split()[1]) for i in dat])

        ## check that locus has required samples for each subtree
        if len(set(names).intersection(set(subs))) == lens:
            ## order the same way every time
            seqsamp = seqs[[names.index(tax) for tax in subs]]
            seqsamp = _resolveambig(seqsamp)
            pis = _count_PIS(seqsamp, minSNPs)

            if pis:
                nlocus += 1
                ## remove invariable columns given this subsampling
                copied = seqsamp.copy()
                copied[copied == "-"] = "N"
                rmcol = np.all(copied == "N", axis=0)
                seqsamp = seqsamp[:, ~rmcol]

                ## write to a nexus file
                mdict = dict(zip(subs, [i.tostring() for i in seqsamp]))
                nexmake(mdict, nlocus, outdir, mcmc_burnin, mcmc_ngen, mcmc_sample_freq)

    print "wrote {} nexus files to {}".format(nlocus, outdir)

Response: This function takes a loci file and returns a nexus formatted file that can be used to generate multiple nexus files.


Instruction:
How would you explain what the following Python 3 function does
def nexmake(mdict, nlocus, dirs, mcmc_burnin, mcmc_ngen, mcmc_sample_freq):
    ## create matrix as a string
    max_name_len = max([len(i) for i in mdict])
    namestring = "{:<" + str(max_name_len+1) + "} {}\n"
    matrix = ""
    for i in mdict.items():
        matrix += namestring.format(i[0], i[1])

    ## write nexus block
    handle = os.path.join(dirs, "{}.nex".format(nlocus))
    with open(handle, 'w') as outnex:
        outnex.write(NEXBLOCK.format(**{
            "ntax": len(mdict),
            "nchar": len(mdict.values()[0]),
            "matrix": matrix,
            "ngen": mcmc_ngen,
            "sfreq": mcmc_sample_freq,
            "burnin": mcmc_burnin,
            }))

Response:
function that creates a NEXUS
    file with a mrbayes analysis block.


Instruction:
Can you create a Python 3 function that
calls fastq - dump on the given SRRs and writes them to the workdir.

Response:
def call_fastq_dump_on_SRRs(self, srr, outname, paired):
    """
    calls fastq-dump on SRRs, relabels fastqs by their accession
    names, and writes them to the workdir. Saves temp sra files
    in the designated tmp folder and immediately removes them.
    """

    ## build command for fastq-dumping
    fd_cmd = [
        "fastq-dump", srr,
        "--accession", outname,
        "--outdir", self.workdir,
        "--gzip",
        ]
    if paired:
        fd_cmd += ["--split-files"]

    ## call fq dump command
    proc = sps.Popen(fd_cmd, stderr=sps.STDOUT, stdout=sps.PIPE)
    o, e = proc.communicate()

    ## delete the stupid temp sra file from the place
    ## that it is very hard-coded to be written to, and
    ## LEFT IN, for some crazy reason.
    srafile = os.path.join(self.workdir, "sra", srr+".sra")
    if os.path.exists(srafile):
        os.remove(srafile)


Instruction:
Make a summary of the following Python 3 code
def fields_checker(fields):
    ## make sure fields will work
    if isinstance(fields, int):
        fields = str(fields)
    if isinstance(fields, str):
        if "," in fields:
            fields = [str(i) for i in fields.split(",")]
        else:
            fields = [str(fields)]
    elif isinstance(fields, (tuple, list)):
        fields = [str(i) for i in fields]
    else:
        raise IPyradWarningExit("fields not properly formatted")

    ## do not allow zero in fields
    fields = [i for i in fields if i != '0']

    return fields

Response: checks if a list of fields is properly formatted


Instruction:
Write a Python 3 script for
downloading the accessions into a temporary directory and run the work.

Response:
def run(self,
        force=False,
        ipyclient=None,
        name_fields=30,
        name_separator="_",
        dry_run=False):
        """
        Download the accessions into a the designated workdir.

        Parameters
        ----------
        force: (bool)
            If force=True then existing files with the same name
            will be overwritten.

        ipyclient: (ipyparallel.Client)
            If provided, work will be distributed across a parallel
            client, otherwise download will be run on a single core.

        name_fields: (int, str):
            Provide the index of the name fields to be used as a prefix
            for fastq output files. The default is 30, which is the
            SampleName field. Use sra.fetch_fields to see all available
            fields and their indices. A likely alternative is 1 (Run).
            If multiple are listed then they will be joined by a "_"
            character. For example (29,30) would yield something like:
            latin-name_sample-name (e.g., mus_musculus-NR10123).

        dry_run: (bool)
            If True then a table of file names that _would_ be downloaded
            will be shown, but the actual files will note be downloaded.
        """

        ## temporarily set directory for tmpfiles used by fastq-dump
        ## if this fails then just skip it.
        try:
            ## ensure output directory, also used as tmpdir
            if not os.path.exists(self.workdir):
                os.makedirs(self.workdir)

            ## get original directory for sra files
            ## probably /home/ncbi/public/sra by default.
            self._set_vdbconfig_path()

            ## register ipyclient for cleanup
            if ipyclient:
                self._ipcluster["pids"] = {}
                for eid in ipyclient.ids:
                    engine = ipyclient[eid]
                    if not engine.outstanding:
                        pid = engine.apply(os.getpid).get()
                        self._ipcluster["pids"][eid] = pid

            ## submit jobs to engines or local
            self._submit_jobs(
                force=force,
                ipyclient=ipyclient,
                name_fields=name_fields,
                name_separator=name_separator,
                dry_run=dry_run,
                )

        except IPyradWarningExit as inst:
            print(inst)
        ## exceptions to catch, cleanup and handle ipyclient interrupts
        except KeyboardInterrupt:
            print("keyboard interrupt...")
        except Exception as inst:
            print("Exception in run() - {}".format(inst))
        finally:
            ## reset working sra path
            self._restore_vdbconfig_path()

            ## if it made a new sra directory then it should be empty when
            ## we are finished if all .sra files were removed. If so, then
            ## let's also remove the dir. if not empty, leave it.
            sradir = os.path.join(self.workdir, "sra")
            if os.path.exists(sradir) and (not os.listdir(sradir)):
                shutil.rmtree(sradir)
            else:
                ## print warning
                try:
                    print(FAILED_DOWNLOAD.format(os.listdir(sradir)))
                except OSError as inst:
                    ## If sra dir doesn't even exist something very bad is broken.
                    raise IPyradWarningExit("Download failed. Exiting.")
                ## remove fastq file matching to cached sra file
                for srr in os.listdir(sradir):
                    isrr = srr.split(".")[0]
                    ipath = os.path.join(self.workdir, "*_{}*.gz".format(isrr))
                    ifile = glob.glob(ipath)[0]
                    if os.path.exists(ifile):
                        os.remove(ifile)
                ## remove cache of sra files
                shutil.rmtree(sradir)

            ## cleanup ipcluster shutdown
            if ipyclient:
                ## send SIGINT (2) to all engines still running tasks
                try:
                    ipyclient.abort()
                    time.sleep(0.5)
                    for engine_id, pid in self._ipcluster["pids"].items():
                        if ipyclient.queue_status()[engine_id]["tasks"]:
                            os.kill(pid, 2)
                        time.sleep(0.1)
                except ipp.NoEnginesRegistered:
                    pass
                ## clean memory space
                if not ipyclient.outstanding:
                    ipyclient.purge_everything()
                ## uh oh, kill everything, something bad happened
                else:
                    ipyclient.shutdown(hub=True, block=False)
                    ipyclient.close()
                    print("\nwarning: ipcluster shutdown and must be restarted")


Instruction:
Given the following Python 3 function, write the documentation
def _submit_jobs(self,
        force,
        ipyclient,
        name_fields,
        name_separator,
        dry_run):
        """
        Download the accessions into a the designated workdir.
        If file already exists it will only be overwritten if
        force=True. Temporary files are removed.
        """

        ## get Run data with default fields (1,4,6,30)
        df = self.fetch_runinfo(range(31), quiet=True)
        sys.stdout.flush()

        ## if not ipyclient then use multiprocessing
        if ipyclient:
            lb = ipyclient.load_balanced_view()

        ## if Run has samples with same name (replicates) then
        ## we need to include the accessions in the file names
        if name_fields:
            ## indexing requires -1 ints
            fields = [int(i)-1 for i in fields_checker(name_fields)]
            ## make accession names, no spaces allowed
            df['Accession'] = pd.Series(df[df.columns[fields[0]]], index=df.index)
            for field in fields[1:]:
                df.Accession += name_separator + df[df.columns[field]]
            df.Accession = [i.replace(" ", "_") for i in df.Accession]
            ## check that names are unique
            if not df.Accession.shape[0] == df.Accession.unique().shape[0]:
                raise IPyradWarningExit("names are not unique:\n{}"\
                    .format(df.Accession))

        ## backup default naming scheme
        else:
            if len(set(df.SampleName)) != len(df.SampleName):
                accs = (i+"-"+j for i, j in zip(df.SampleName, df.Run))
                df.Accession = accs
            else:
                df.Accession = df.SampleName

        if dry_run:
            print("\rThe following files will be written to: {}".format(self.workdir))
            print("{}\n".format(df.Accession))
        else:
            ## iterate over and download
            asyncs = []
            for idx in df.index:

                ## get args for this run
                srr = df.Run[idx]
                outname = df.Accession[idx]
                paired = df.spots_with_mates.values.astype(int).nonzero()[0].any()
                fpath = os.path.join(self.workdir, outname+".fastq.gz")

                ## skip if exists and not force
                skip = False
                if force:
                    if os.path.exists(fpath):
                        os.remove(fpath)
                else:
                    if os.path.exists(fpath):
                        skip = True
                        sys.stdout.flush()
                        print("[skip] file already exists: {}".format(fpath))

                ## single job progress bar
                tidx = df.Accession.shape[0]
                #if not ipyclient:

                ## submit job to run
                if not skip:
                    args = (self, srr, outname, paired)
                    if ipyclient:
                        async = lb.apply_async(call_fastq_dump_on_SRRs, *args)
                        asyncs.append(async)
                    else:
                        print("Downloading file {}/{}: {}".format(idx+1, tidx, fpath))
                        call_fastq_dump_on_SRRs(*args)
                        sys.stdout.flush()

            ## progress bar while blocking parallel
            if ipyclient:
                tots = df.Accession.shape[0]
                printstr = " Downloading fastq files | {} | "
                start = time.time()
                while 1:
                    elapsed = datetime.timedelta(seconds=int(time.time()-start))
                    ready = sum([i.ready() for i in asyncs])
                    progressbar(tots, ready, printstr.format(elapsed), spacer="")
                    time.sleep(0.1)
                    if tots == ready:
                        print("")
                        break
                self._report(tots)

                ## check for fails
                for async in asyncs:
                    if not async.successful():
                        raise IPyradWarningExit(async.result())

Response: Submit jobs to the user.


Instruction:
Given the following Python 3 function, write the documentation
def fetch_runinfo(self, fields=None, quiet=False):
        if not quiet:
            print("\rFetching project data...", end="")

        ## if no entry then fetch (nearly) all fields.
        if fields == None:
            fields = range(30)
        fields = fields_checker(fields)

        ## command strings
        es_cmd = [
            "esearch",
            "-db", "sra",
            "-query", self.accession,
        ]

        ef_cmd = [
            "efetch",
            "--format", "runinfo",
        ]

        cut_cmd = [
            "cut",
            "-d", ",",
            "-f", ",".join(fields),
        ]

        ## pipe commands together
        proc1 = sps.Popen(es_cmd, stderr=sps.STDOUT, stdout=sps.PIPE)
        proc2 = sps.Popen(ef_cmd, stdin=proc1.stdout, stderr=sps.STDOUT, stdout=sps.PIPE)
        proc3 = sps.Popen(cut_cmd, stdin=proc2.stdout, stderr=sps.STDOUT, stdout=sps.PIPE)
        o, e = proc3.communicate()
        proc2.stdout.close()
        proc1.stdout.close()

        if o:
            vals = o.strip().split("\n")
            names = vals[0].split(",")
            items = [i.split(",") for i in vals[1:] if i not in ["", vals[0]]]
            return pd.DataFrame(items, columns=names)
        else:
            raise IPyradWarningExit("no samples found in {}".format(self.accession))

Response: Fetch the runinfo for the specified fields from the specified project.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def Async(cls, token, session=None, **options):
        return cls(token, session=session, is_async=True, **options)

Response: Returns the client in async mode.


Instruction:
How would you implement a function in Python 3 that
gets the CR Constants for a specific resource

Response:
def get_constants(self, **params: keys):
        """Get the CR Constants

        Parameters
        ----------
        \*\*keys: Optional[list] = None
            Filter which keys should be included in the
            response
        \*\*exclude: Optional[list] = None
            Filter which keys should be excluded from the
            response
        \*\*timeout: Optional[int] = None
            Custom timeout that overwrites Client.timeout
        """
        url = self.api.CONSTANTS
        return self._get_model(url, **params)


Instruction:
How would you explain what the following Python 3 function does
def get_player(self, *tags: crtag, **params: keys):
        url = self.api.PLAYER + '/' + ','.join(tags)
        return self._get_model(url, FullPlayer, **params)

Response: Get a player information by tag.


Instruction:
Given the following Python 3 function, write the documentation
def get_player_verify(self, tag: crtag, apikey: str, **params: keys):
        url = self.api.PLAYER + '/' + tag + '/verify'
        params.update({'token': apikey})
        return self._get_model(url, FullPlayer, **params)

Response:
This endpoint is restricted tournament to
            certain members of the community


Instruction:
Can you implement a function in Python 3 that
gets a player s battle log.

Response:
def get_player_battles(self, *tags: crtag, **params: keys):
        """Get a player's battle log

        Parameters
        ----------
        \*tags: str
            Valid player tags. Minimum length: 3
            Valid characters: 0289PYLQGRJCUV
        \*\*keys: Optional[list] = None
            Filter which keys should be included in the
            response
        \*\*exclude: Optional[list] = None
            Filter which keys should be excluded from the
            response
        \*\*max: Optional[int] = None
            Limit the number of items returned in the response
        \*\*page: Optional[int] = None
            Works with max, the zero-based page of the
            items
        \*\*timeout: Optional[int] = None
            Custom timeout that overwrites Client.timeout
        """
        url = self.api.PLAYER + '/' + ','.join(tags) + '/battles'
        return self._get_model(url, **params)


Instruction:
Implement a function in Python 3 to
get a clan information for a set of tags

Response:
def get_clan(self, *tags: crtag, **params: keys):
        """Get a clan information

        Parameters
        ----------
        \*tags: str
            Valid clan tags. Minimum length: 3
            Valid characters: 0289PYLQGRJCUV
        \*\*keys: Optional[list] = None
            Filter which keys should be included in the
            response
        \*\*exclude: Optional[list] = None
            Filter which keys should be excluded from the
            response
        \*\*timeout: Optional[int] = None
            Custom timeout that overwrites Client.timeout
        """
        url = self.api.CLAN + '/' + ','.join(tags)
        return self._get_model(url, FullClan, **params)


Instruction:
Write a Python 3 script for
getting a list of clans that are being tracked by having cr - api. com or royaleapi. com or .

Response:
def get_tracking_clans(self, **params: keys):
        """Get a list of clans that are being
        tracked by having either cr-api.com or
        royaleapi.com in the description

        Parameters
        ----------
        \*\*keys: Optional[list] = None
            Filter which keys should be included in the
            response
        \*\*exclude: Optional[list] = None
            Filter which keys should be excluded from the
            response
        \*\*max: Optional[int] = None
            Limit the number of items returned in the response
        \*\*page: Optional[int] = None
            Works with max, the zero-based page of the
            items
        \*\*timeout: Optional[int] = None
            Custom timeout that overwrites Client.timeout
        """
        url = self.api.CLAN + '/tracking'
        return self._get_model(url, **params)


Instruction:
How would you explain what the following Python 3 function does
def get_clan_tracking(self, *tags: crtag, **params: keys):
        url = self.api.CLAN + '/' + ','.join(tags) + '/tracking'
        return self._get_model(url, **params)

Response:
Returns True if the clan is currently being tracked by the API by having either cr - api. com or royaleapi. com
            in the clan description.


Instruction:
Implement a function in Python 3 to
get inforamtion about a clan s current clan war

Response:
def get_clan_war(self, tag: crtag, **params: keys):
        """Get inforamtion about a clan's current clan war

        Parameters
        ----------
        *tag: str
            A valid clan tag. Minimum length: 3
            Valid characters: 0289PYLQGRJCUV
        \*\*keys: Optional[list] = None
            Filter which keys should be included in the
            response
        \*\*exclude: Optional[list] = None
            Filter which keys should be excluded from the
            response
        \*\*timeout: Optional[int] = None
            Custom timeout that overwrites Client.timeout
        """
        url = self.api.CLAN + '/' + tag + '/war'
        return self._get_model(url, **params)


Instruction:
Here you have a function in Python 3, explain what it does
def get_tournament(self, tag: crtag, **params: keys):
        url = self.api.TOURNAMENT + '/' + tag
        return self._get_model(url, **params)

Response: Get a tournament information from a specific tournament.


Instruction:
Make a summary of the following Python 3 code
def search_tournaments(self, **params: keys):
        url = self.api.TOURNAMENT + '/search'
        return self._get_model(url, PartialClan, **params)

Response: Search for a tournament s tournaments


Instruction:
Create a Python 3 function for
getting a list of top clans by war

Response:
def get_top_war_clans(self, country_key='', **params: keys):
        """Get a list of top clans by war

        location_id: Optional[str] = ''
            A location ID or '' (global)
            See https://github.com/RoyaleAPI/cr-api-data/blob/master/json/regions.json
            for a list of acceptable location IDs
        \*\*keys: Optional[list] = None
            Filter which keys should be included in the
            response
        \*\*exclude: Optional[list] = None
            Filter which keys should be excluded from the
            response
        \*\*max: Optional[int] = None
            Limit the number of items returned in the response
        \*\*page: Optional[int] = None
            Works with max, the zero-based page of the
            items
        \*\*timeout: Optional[int] = None
            Custom timeout that overwrites Client.timeout
        """
        url = self.api.TOP + '/war/' + str(country_key)
        return self._get_model(url, PartialClan, **params)


Instruction:
Make a summary of the following Python 3 code
def get_top_players(self, country_key='', **params: keys):
        url = self.api.TOP + '/players/' + str(country_key)
        return self._get_model(url, PartialPlayerClan, **params)

Response: Get a list of top players in a given country


Instruction:
Write a Python 3 function that can
get a list of popular clans for a specific key.

Response:
def get_popular_clans(self, **params: keys):
        """Get a list of most queried clans

        \*\*keys: Optional[list] = None
            Filter which keys should be included in the
            response
        \*\*exclude: Optional[list] = None
            Filter which keys should be excluded from the
            response
        \*\*max: Optional[int] = None
            Limit the number of items returned in the response
        \*\*page: Optional[int] = None
            Works with max, the zero-based page of the
            items
        \*\*timeout: Optional[int] = None
            Custom timeout that overwrites Client.timeout
        """
        url = self.api.POPULAR + '/clans'
        return self._get_model(url, PartialClan, **params)


Instruction:
How would you explain what the following Python 3 function does
def get_popular_players(self, **params: keys):
        url = self.api.POPULAR + '/players'
        return self._get_model(url, PartialPlayerClan, **params)

Response: Get a list of popular players in the cluster.


Instruction:
Write a Python 3 function for
getting a list of popular tournaments for a specific tournament.

Response:
def get_popular_tournaments(self, **params: keys):
        """Get a list of most queried tournaments

        \*\*keys: Optional[list] = None
            Filter which keys should be included in the
            response
        \*\*exclude: Optional[list] = None
            Filter which keys should be excluded from the
            response
        \*\*max: Optional[int] = None
            Limit the number of items returned in the response
        \*\*page: Optional[int] = None
            Works with max, the zero-based page of the
            items
        \*\*timeout: Optional[int] = None
            Custom timeout that overwrites Client.timeout
        """
        url = self.api.POPULAR + '/tournament'
        return self._get_model(url, PartialTournament, **params)


Instruction:
Can you create a Python 3 function that
gets a list of most queried decks for a specific locale

Response:
def get_popular_decks(self, **params: keys):
        """Get a list of most queried decks

        \*\*keys: Optional[list] = None
            Filter which keys should be included in the
            response
        \*\*exclude: Optional[list] = None
            Filter which keys should be excluded from the
            response
        \*\*max: Optional[int] = None
            Limit the number of items returned in the response
        \*\*page: Optional[int] = None
            Works with max, the zero-based page of the
            items
        \*\*timeout: Optional[int] = None
            Custom timeout that overwrites Client.timeout
        """
        url = self.api.POPULAR + '/decks'
        return self._get_model(url, **params)


Instruction:
Implement a Python 3 function for
getting a list of known tournaments for a given tournament.

Response:
def get_known_tournaments(self, **params: tournamentfilter):
        """Get a list of queried tournaments

        \*\*keys: Optional[list] = None
            Filter which keys should be included in the
            response
        \*\*exclude: Optional[list] = None
            Filter which keys should be excluded from the
            response
        \*\*max: Optional[int] = None
            Limit the number of items returned in the response
        \*\*page: Optional[int] = None
            Works with max, the zero-based page of the
            items
        \*\*timeout: Optional[int] = None
            Custom timeout that overwrites Client.timeout
        """
        url = self.api.TOURNAMENT + '/known'
        return self._get_model(url, PartialTournament, **params)


Instruction:
Write a Python 3 script for
getting information about a tournament with the specified tournament tag.

Response:
def get_player(self, tag: crtag, timeout=None):
        """Get information about a player

        Parameters
        ----------
        tag: str
            A valid tournament tag. Minimum length: 3
            Valid characters: 0289PYLQGRJCUV
        timeout: Optional[int] = None
            Custom timeout that overwrites Client.timeout
        """
        url = self.api.PLAYER + '/' + tag
        return self._get_model(url, FullPlayer, timeout=timeout)


Instruction:
Create a Python 3 function to
check the API Key of a player. This endpoint has been **restricted** to certain members of the community Raises BadRequest if the apikey is invalid Parameters ---------- tag: str A valid tournament tag. Minimum length: 3 Valid characters: 0289PYLQGRJCUV apikey: str The API Key in the player's settings timeout: Optional[int] = None Custom timeout that overwrites Client.timeout

Response:
def get_player_verify(self, tag: crtag, apikey: str, timeout=None):
        """Check the API Key of a player.
        This endpoint has been **restricted** to
        certain members of the community

        Raises BadRequest if the apikey is invalid

        Parameters
        ----------
        tag: str
            A valid tournament tag. Minimum length: 3
            Valid characters: 0289PYLQGRJCUV
        apikey: str
            The API Key in the player's settings
        timeout: Optional[int] = None
            Custom timeout that overwrites Client.timeout
        """
        url = self.api.PLAYER + '/' + tag + '/verifytoken'
        return self._get_model(url, FullPlayer, timeout=timeout, method='POST', json={'token': apikey})


Instruction:
Write a Python 3 script for
getting a player s battle log.

Response:
def get_player_battles(self, tag: crtag, **params: keys):
        """Get a player's battle log

        Parameters
        ----------
        tag: str
            A valid tournament tag. Minimum length: 3
            Valid characters: 0289PYLQGRJCUV
        \*\*limit: Optional[int] = None
            Limit the number of items returned in the response
        \*\*timeout: Optional[int] = None
            Custom timeout that overwrites Client.timeout
        """
        url = self.api.PLAYER + '/' + tag + '/battlelog'
        return self._get_model(url, **params)


Instruction:
Can you tell what is the following Python 3 function doing
def get_player_chests(self, tag: crtag, timeout: int=None):
        url = self.api.PLAYER + '/' + tag + '/upcomingchests'
        return self._get_model(url, timeout=timeout)

Response: Get information about a player s chests.


Instruction:
Explain what the following Python 3 code does
def get_clan(self, tag: crtag, timeout: int=None):
        url = self.api.CLAN + '/' + tag
        return self._get_model(url, FullClan, timeout=timeout)

Response: Get inforamtion about a clan.


Instruction:
Can you tell what is the following Python 3 function doing
def search_clans(self, **params: clansearch):
        url = self.api.CLAN
        return self._get_model(url, PartialClan, **params)

Response: Search for a clan.


Instruction:
Write a Python 3 script for
getting inforamtion about a clan s current clan war

Response:
def get_clan_war(self, tag: crtag, timeout: int=None):
        """Get inforamtion about a clan's current clan war

        Parameters
        ----------
        tag: str
            A valid tournament tag. Minimum length: 3
            Valid characters: 0289PYLQGRJCUV
        timeout: Optional[int] = None
            Custom timeout that overwrites Client.timeout
        """
        url = self.api.CLAN + '/' + tag + '/currentwar'
        return self._get_model(url, timeout=timeout)


Instruction:
Make a summary of the following Python 3 code
def get_tournament(self, tag: crtag, timeout=0):
        url = self.api.TOURNAMENT + '/' + tag
        return self._get_model(url, PartialTournament, timeout=timeout)

Response: Get a tournament information by its tag.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def search_tournaments(self, name: str, **params: keys):
        url = self.api.TOURNAMENT
        params['name'] = name
        return self._get_model(url, PartialTournament, **params)

Response: Search for a tournament by its name.


Instruction:
How would you explain what the following Python 3 function does
def get_all_cards(self, timeout: int=None):
        url = self.api.CARDS
        return self._get_model(url, timeout=timeout)

Response:
Get a list of all the cards in the game
Taxonomy API.


Instruction:
How would you implement a function in Python 3 that
gets a list of all locations in the cluster.

Response:
def get_all_locations(self, timeout: int=None):
        """Get a list of all locations

        Parameters
        ----------
        timeout: Optional[int] = None
            Custom timeout that overwrites Client.timeout
        """
        url = self.api.LOCATIONS
        return self._get_model(url, timeout=timeout)


Instruction:
How would you explain what the following Python 3 function does
def get_location(self, location_id: int, timeout: int=None):
        url = self.api.LOCATIONS + '/' + str(location_id)
        return self._get_model(url, timeout=timeout)

Response: Get a location information by location ID


Instruction:
Can you generate a brief explanation for the following Python 3 code
def get_top_clans(self, location_id='global', **params: keys):
        url = self.api.LOCATIONS + '/' + str(location_id) + '/rankings/clans'
        return self._get_model(url, PartialClan, **params)

Response: Get a list of top clans by trophy


Instruction:
Can you create a Python 3 function that
gets a list of top players in a location.

Response:
def get_top_players(self, location_id='global', **params: keys):
        """Get a list of top players

        Parameters
        ----------
        location_id: Optional[str] = 'global'
            A location ID or global
            See https://github.com/RoyaleAPI/cr-api-data/blob/master/json/regions.json
            for a list of acceptable location IDs
        \*\*limit: Optional[int] = None
            Limit the number of items returned in the response
        \*\*timeout: Optional[int] = None
            Custom timeout that overwrites Client.timeout
        """
        url = self.api.LOCATIONS + '/' + str(location_id) + '/rankings/players'
        return self._get_model(url, PartialPlayerClan, **params)


Instruction:
Explain what the following Python 3 code does
def get_clan_image(self, obj: BaseAttrDict):

        try:
            badge_id = obj.clan.badge_id
        except AttributeError:
            try:
                badge_id = obj.badge_id
            except AttributeError:
                return 'https://i.imgur.com/Y3uXsgj.png'

        if badge_id is None:
            return 'https://i.imgur.com/Y3uXsgj.png'

        for i in self.constants.alliance_badges:
            if i.id == badge_id:
                return 'https://royaleapi.github.io/cr-api-assets/badges/' + i.name + '.png'

Response: Get the clan badge image URL


Instruction:
How would you explain what the following Python 3 function does
def get_arena_image(self, obj: BaseAttrDict):
        badge_id = obj.arena.id
        for i in self.constants.arenas:
            if i.id == badge_id:
                return 'https://royaleapi.github.io/cr-api-assets/arenas/arena{}.png'.format(i.arena_id)

Response: Get the arena image URL for the given object.


Instruction:
Can you implement a function in Python 3 that
returns the card info from constants. cards or None if no card info is found.

Response:
def get_card_info(self, card_name: str):
        """Returns card info from constants

        Parameters
        ---------
        card_name: str
            A card name

        Returns None or Constants
        """
        for c in self.constants.cards:
            if c.name == card_name:
                return c


Instruction:
Make a summary of the following Python 3 code
def get_rarity_info(self, rarity: str):
        for c in self.constants.rarities:
            if c.name == rarity:
                return c

Response: Returns card info from constants. rarities.


Instruction:
Make a summary of the following Python 3 code
def get_deck_link(self, deck: BaseAttrDict):
        deck_link = 'https://link.clashroyale.com/deck/en?deck='

        for i in deck:
            card = self.get_card_info(i.name)
            deck_link += '{0.id};'.format(card)

        return deck_link

Response: Form a deck link


Instruction:
How would you explain what the following Python 3 function does
def get_datetime(self, timestamp: str, unix=True):
        time = datetime.strptime(timestamp, '%Y%m%dT%H%M%S.%fZ')
        if unix:
            return int(time.timestamp())
        else:
            return time

Response: Converts a %Y%m%dT%H%M%S.%fZ format to a UNIX timestamp or a datetime. datetime object


Instruction:
Given the following Python 3 function, write the documentation
def get_clan(self):
        try:
            return self.client.get_clan(self.clan.tag)
        except AttributeError:
            try:
                return self.client.get_clan(self.tag)
            except AttributeError:
                raise ValueError('This player does not have a clan.')

Response: a sync function to return clan.


Instruction:
Make a summary of the following Python 3 code
def coerce_annotation(ann, namespace):
    '''Validate that the annotation has the correct namespace,
    and is well-formed.

    If the annotation is not of the correct namespace, automatic conversion
    is attempted.

    Parameters
    ----------
    ann : jams.Annotation
        The annotation object in question

    namespace : str
        The namespace pattern to match `ann` against

    Returns
    -------
    ann_coerced: jams.Annotation
        The annotation coerced to the target namespace

    Raises
    ------
    NamespaceError
        If `ann` does not match the proper namespace

    SchemaError
        If `ann` fails schema validation

    See Also
    --------
    jams.nsconvert.convert
    '''

    ann = convert(ann, namespace)
    ann.validate(strict=True)

    return ann

Response: Validate that the annotation is of the correct namespace and is well - formed.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def beat(ref, est, **kwargs):
    r'''Beat tracking evaluation

    Parameters
    ----------
    ref : jams.Annotation
        Reference annotation object
    est : jams.Annotation
        Estimated annotation object
    kwargs
        Additional keyword arguments

    Returns
    -------
    scores : dict
        Dictionary of scores, where the key is the metric name (str) and
        the value is the (float) score achieved.

    See Also
    --------
    mir_eval.beat.evaluate

    Examples
    --------
    >>> # Load in the JAMS objects
    >>> ref_jam = jams.load('reference.jams')
    >>> est_jam = jams.load('estimated.jams')
    >>> # Select the first relevant annotations
    >>> ref_ann = ref_jam.search(namespace='beat')[0]
    >>> est_ann = est_jam.search(namespace='beat')[0]
    >>> scores = jams.eval.beat(ref_ann, est_ann)
    '''

    namespace = 'beat'
    ref = coerce_annotation(ref, namespace)
    est = coerce_annotation(est, namespace)

    ref_times, _ = ref.to_event_values()
    est_times, _ = est.to_event_values()

    return mir_eval.beat.evaluate(ref_times, est_times, **kwargs)

Response: r Beat tracking evaluation of a given reference and estimated object.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def chord(ref, est, **kwargs):
    r'''Chord evaluation

    Parameters
    ----------
    ref : jams.Annotation
        Reference annotation object
    est : jams.Annotation
        Estimated annotation object
    kwargs
        Additional keyword arguments

    Returns
    -------
    scores : dict
        Dictionary of scores, where the key is the metric name (str) and
        the value is the (float) score achieved.

    See Also
    --------
    mir_eval.chord.evaluate

    Examples
    --------
    >>> # Load in the JAMS objects
    >>> ref_jam = jams.load('reference.jams')
    >>> est_jam = jams.load('estimated.jams')
    >>> # Select the first relevant annotations
    >>> ref_ann = ref_jam.search(namespace='chord')[0]
    >>> est_ann = est_jam.search(namespace='chord')[0]
    >>> scores = jams.eval.chord(ref_ann, est_ann)
    '''

    namespace = 'chord'
    ref = coerce_annotation(ref, namespace)
    est = coerce_annotation(est, namespace)
    ref_interval, ref_value = ref.to_interval_values()
    est_interval, est_value = est.to_interval_values()

    return mir_eval.chord.evaluate(ref_interval, ref_value,
                                   est_interval, est_value, **kwargs)

Response: Chord evaluation for a single resource in the JAMS file.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def hierarchy_flatten(annotation):
    '''Flatten a multi_segment annotation into mir_eval style.

    Parameters
    ----------
    annotation : jams.Annotation
        An annotation in the `multi_segment` namespace

    Returns
    -------
    hier_intervalss : list
        A list of lists of intervals, ordered by increasing specificity.

    hier_labels : list
        A list of lists of labels, ordered by increasing specificity.
    '''

    intervals, values = annotation.to_interval_values()

    ordering = dict()

    for interval, value in zip(intervals, values):
        level = value['level']
        if level not in ordering:
            ordering[level] = dict(intervals=list(), labels=list())

        ordering[level]['intervals'].append(interval)
        ordering[level]['labels'].append(value['label'])

    levels = sorted(list(ordering.keys()))
    hier_intervals = [ordering[level]['intervals'] for level in levels]
    hier_labels = [ordering[level]['labels'] for level in levels]

    return hier_intervals, hier_labels

Response: Flatten a multi_segment annotation into mir_eval style.


Instruction:
Here you have a function in Python 3, explain what it does
def hierarchy(ref, est, **kwargs):
    r'''Multi-level segmentation evaluation

    Parameters
    ----------
    ref : jams.Annotation
        Reference annotation object
    est : jams.Annotation
        Estimated annotation object
    kwargs
        Additional keyword arguments

    Returns
    -------
    scores : dict
        Dictionary of scores, where the key is the metric name (str) and
        the value is the (float) score achieved.

    See Also
    --------
    mir_eval.hierarchy.evaluate

    Examples
    --------
    >>> # Load in the JAMS objects
    >>> ref_jam = jams.load('reference.jams')
    >>> est_jam = jams.load('estimated.jams')
    >>> # Select the first relevant annotations
    >>> ref_ann = ref_jam.search(namespace='multi_segment')[0]
    >>> est_ann = est_jam.search(namespace='multi_segment')[0]
    >>> scores = jams.eval.hierarchy(ref_ann, est_ann)
    '''
    namespace = 'multi_segment'
    ref = coerce_annotation(ref, namespace)
    est = coerce_annotation(est, namespace)
    ref_hier, ref_hier_lab = hierarchy_flatten(ref)
    est_hier, est_hier_lab = hierarchy_flatten(est)

    return mir_eval.hierarchy.evaluate(ref_hier, ref_hier_lab,
                                       est_hier, est_hier_lab,
                                       **kwargs)

Response: Multi - level segmentation evaluation


Instruction:
Explain what the following Python 3 code does
def melody(ref, est, **kwargs):
    r'''Melody extraction evaluation

    Parameters
    ----------
    ref : jams.Annotation
        Reference annotation object
    est : jams.Annotation
        Estimated annotation object
    kwargs
        Additional keyword arguments

    Returns
    -------
    scores : dict
        Dictionary of scores, where the key is the metric name (str) and
        the value is the (float) score achieved.

    See Also
    --------
    mir_eval.melody.evaluate

    Examples
    --------
    >>> # Load in the JAMS objects
    >>> ref_jam = jams.load('reference.jams')
    >>> est_jam = jams.load('estimated.jams')
    >>> # Select the first relevant annotations
    >>> ref_ann = ref_jam.search(namespace='pitch_contour')[0]
    >>> est_ann = est_jam.search(namespace='pitch_contour')[0]
    >>> scores = jams.eval.melody(ref_ann, est_ann)
    '''

    namespace = 'pitch_contour'
    ref = coerce_annotation(ref, namespace)
    est = coerce_annotation(est, namespace)

    ref_times, ref_p = ref.to_event_values()
    est_times, est_p = est.to_event_values()

    ref_freq = np.asarray([p['frequency'] * (-1)**(~p['voiced']) for p in ref_p])
    est_freq = np.asarray([p['frequency'] * (-1)**(~p['voiced']) for p in est_p])

    return mir_eval.melody.evaluate(ref_times, ref_freq,
                                    est_times, est_freq,
                                    **kwargs)

Response: r Melody extraction of a single object.


Instruction:
Make a summary of the following Python 3 code
def pattern_to_mireval(ann):
    '''Convert a pattern_jku annotation object to mir_eval format.

    Parameters
    ----------
    ann : jams.Annotation
        Must have `namespace='pattern_jku'`

    Returns
    -------
    patterns : list of list of tuples
        - `patterns[x]` is a list containing all occurrences of pattern x

        - `patterns[x][y]` is a list containing all notes for
           occurrence y of pattern x

        - `patterns[x][y][z]` contains a time-note tuple
          `(time, midi note)`
    '''

    # It's easier to work with dictionaries, since we can't assume
    # sequential pattern or occurrence identifiers

    patterns = defaultdict(lambda: defaultdict(list))

    # Iterate over the data in interval-value format

    for time, observation in zip(*ann.to_event_values()):

        pattern_id = observation['pattern_id']
        occurrence_id = observation['occurrence_id']
        obs = (time, observation['midi_pitch'])

        # Push this note observation into the correct pattern/occurrence
        patterns[pattern_id][occurrence_id].append(obs)

    # Convert to list-list-tuple format for mir_eval
    return [list(_.values()) for _ in six.itervalues(patterns)]

Response: Convert a pattern_jku annotation object to mir_eval format.


Instruction:
Can you tell what is the following Python 3 function doing
def pattern(ref, est, **kwargs):
    r'''Pattern detection evaluation

    Parameters
    ----------
    ref : jams.Annotation
        Reference annotation object
    est : jams.Annotation
        Estimated annotation object
    kwargs
        Additional keyword arguments

    Returns
    -------
    scores : dict
        Dictionary of scores, where the key is the metric name (str) and
        the value is the (float) score achieved.

    See Also
    --------
    mir_eval.pattern.evaluate

    Examples
    --------
    >>> # Load in the JAMS objects
    >>> ref_jam = jams.load('reference.jams')
    >>> est_jam = jams.load('estimated.jams')
    >>> # Select the first relevant annotations
    >>> ref_ann = ref_jam.search(namespace='pattern_jku')[0]
    >>> est_ann = est_jam.search(namespace='pattern_jku')[0]
    >>> scores = jams.eval.pattern(ref_ann, est_ann)
    '''

    namespace = 'pattern_jku'
    ref = coerce_annotation(ref, namespace)
    est = coerce_annotation(est, namespace)

    ref_patterns = pattern_to_mireval(ref)
    est_patterns = pattern_to_mireval(est)

    return mir_eval.pattern.evaluate(ref_patterns, est_patterns, **kwargs)

Response:
r'''Pattern detection evaluation

    Parameters
    ----------
    ref : jams.Annotation
        Reference annotation object
    est : jams.Annotation
        Estimated annotation object
    kwargs
        Additional keyword arguments

    Returns
    -------
    scores : dict
        Dictionary of scores, where the key is the metric name (str) and
        the value is the (float) score achieved.

    See Also
    --------
    mir_eval.pattern.evaluate

    Examples
    --------
    >>> # Load in the JAMS objects
    >>> ref_jam = jams.load('reference.jams')
    >>> est_jam = jams.load('estimated.jams')
    >>> # Select the first relevant annotations
    >>> ref_ann = ref_jam.search(namespace='pattern_jku')[0]
    >>> est_ann = est_jam.search(namespace='pattern_jku')[0]
    >>> scores = jams.eval.pattern(ref_ann, est_ann)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def transcription(ref, est, **kwargs):
    r'''Note transcription evaluation

    Parameters
    ----------
    ref : jams.Annotation
        Reference annotation object
    est : jams.Annotation
        Estimated annotation object
    kwargs
        Additional keyword arguments

    Returns
    -------
    scores : dict
        Dictionary of scores, where the key is the metric name (str) and
        the value is the (float) score achieved.

    See Also
    --------
    mir_eval.transcription.evaluate

    Examples
    --------
    >>> # Load in the JAMS objects
    >>> ref_jam = jams.load('reference.jams')
    >>> est_jam = jams.load('estimated.jams')
    >>> # Select the first relevant annotations. You can use any annotation
    >>> # type that can be converted to pitch_contour (such as pitch_midi)
    >>> ref_ann = ref_jam.search(namespace='pitch_contour')[0]
    >>> est_ann = est_jam.search(namespace='note_hz')[0]
    >>> scores = jams.eval.transcription(ref_ann, est_ann)
    '''

    namespace = 'pitch_contour'
    ref = coerce_annotation(ref, namespace)
    est = coerce_annotation(est, namespace)
    ref_intervals, ref_p = ref.to_interval_values()
    est_intervals, est_p = est.to_interval_values()

    ref_pitches = np.asarray([p['frequency'] * (-1)**(~p['voiced']) for p in ref_p])
    est_pitches = np.asarray([p['frequency'] * (-1)**(~p['voiced']) for p in est_p])

    return mir_eval.transcription.evaluate(
        ref_intervals, ref_pitches, est_intervals, est_pitches, **kwargs)

Response: r Note transcription evaluation for a single object.


Instruction:
Create a Python 3 function for
adding a namespace definition to our working set.

Response:
def add_namespace(filename):
    '''Add a namespace definition to our working set.

    Namespace files consist of partial JSON schemas defining the behavior
    of the `value` and `confidence` fields of an Annotation.

    Parameters
    ----------
    filename : str
        Path to json file defining the namespace object
    '''
    with open(filename, mode='r') as fileobj:
        __NAMESPACE__.update(json.load(fileobj))


Instruction:
Here you have a function in Python 3, explain what it does
def namespace(ns_key):
    '''Construct a validation schema for a given namespace.

    Parameters
    ----------
    ns_key : str
        Namespace key identifier (eg, 'beat' or 'segment_tut')

    Returns
    -------
    schema : dict
        JSON schema of `namespace`
    '''

    if ns_key not in __NAMESPACE__:
        raise NamespaceError('Unknown namespace: {:s}'.format(ns_key))

    sch = copy.deepcopy(JAMS_SCHEMA['definitions']['SparseObservation'])

    for key in ['value', 'confidence']:
        try:
            sch['properties'][key] = __NAMESPACE__[ns_key][key]
        except KeyError:
            pass

    return sch

Response: Construct a validation schema for a given namespace.


Instruction:
Here you have a function in Python 3, explain what it does
def namespace_array(ns_key):
    '''Construct a validation schema for arrays of a given namespace.

    Parameters
    ----------
    ns_key : str
        Namespace key identifier

    Returns
    -------
    schema : dict
        JSON schema of `namespace` observation arrays
    '''

    obs_sch = namespace(ns_key)
    obs_sch['title'] = 'Observation'

    sch = copy.deepcopy(JAMS_SCHEMA['definitions']['SparseObservationList'])
    sch['items'] = obs_sch
    return sch

Response: Construct a validation schema for arrays of a given namespace.


Instruction:
Can you implement a function in Python 3 that
returns the allowed values for an enumerated namespace.

Response:
def values(ns_key):
    '''Return the allowed values for an enumerated namespace.

    Parameters
    ----------
    ns_key : str
        Namespace key identifier

    Returns
    -------
    values : list

    Raises
    ------
    NamespaceError
        If `ns_key` is not found, or does not have enumerated values

    Examples
    --------
    >>> jams.schema.values('tag_gtzan')
    ['blues', 'classical', 'country', 'disco', 'hip-hop', 'jazz',
     'metal', 'pop', 'reggae', 'rock']
    '''

    if ns_key not in __NAMESPACE__:
        raise NamespaceError('Unknown namespace: {:s}'.format(ns_key))

    if 'enum' not in __NAMESPACE__[ns_key]['value']:
        raise NamespaceError('Namespace {:s} is not enumerated'.format(ns_key))

    return copy.copy(__NAMESPACE__[ns_key]['value']['enum'])


Instruction:
Given the following Python 3 function, write the documentation
def get_dtypes(ns_key):
    '''Get the dtypes associated with the value and confidence fields
    for a given namespace.

    Parameters
    ----------
    ns_key : str
        The namespace key in question

    Returns
    -------
    value_dtype, confidence_dtype : numpy.dtype
        Type identifiers for value and confidence fields.
    '''

    # First, get the schema
    if ns_key not in __NAMESPACE__:
        raise NamespaceError('Unknown namespace: {:s}'.format(ns_key))

    value_dtype = __get_dtype(__NAMESPACE__[ns_key].get('value', {}))
    confidence_dtype = __get_dtype(__NAMESPACE__[ns_key].get('confidence', {}))

    return value_dtype, confidence_dtype

Response:
Get the dtypes associated with the value and confidence fields
    for a given namespace.


Instruction:
Make a summary of the following Python 3 code
def list_namespaces():
    '''Print out a listing of available namespaces'''
    print('{:30s}\t{:40s}'.format('NAME', 'DESCRIPTION'))
    print('-' * 78)
    for sch in sorted(__NAMESPACE__):
        desc = __NAMESPACE__[sch]['description']
        desc = (desc[:44] + '..') if len(desc) > 46 else desc
        print('{:30s}\t{:40s}'.format(sch, desc))

Response: Print out a listing of available namespaces


Instruction:
Can you tell what is the following Python 3 function doing
def __get_dtype(typespec):
    '''Get the dtype associated with a jsonschema type definition

    Parameters
    ----------
    typespec : dict
        The schema definition

    Returns
    -------
    dtype : numpy.dtype
        The associated dtype
    '''

    if 'type' in typespec:
        return __TYPE_MAP__.get(typespec['type'], np.object_)

    elif 'enum' in typespec:
        # Enums map to objects
        return np.object_

    elif 'oneOf' in typespec:
        # Recurse
        types = [__get_dtype(v) for v in typespec['oneOf']]

        # If they're not all equal, return object
        if all([t == types[0] for t in types]):
            return types[0]

    return np.object_

Response: Get the dtype associated with a jsonschema type definition


Instruction:
Write a Python 3 function for
loading the schema file from the package.

Response:
def __load_jams_schema():
    '''Load the schema file from the package.'''

    schema_file = os.path.join(SCHEMA_DIR, 'jams_schema.json')

    jams_schema = None
    with open(resource_filename(__name__, schema_file), mode='r') as fdesc:
        jams_schema = json.load(fdesc)

    if jams_schema is None:
        raise JamsError('Unable to load JAMS schema')

    return jams_schema


Instruction:
Make a summary of the following Python 3 code
def import_lab(namespace, filename, infer_duration=True, **parse_options):
    r'''Load a .lab file as an Annotation object.

    .lab files are assumed to have the following format:

        ``TIME_START\tTIME_END\tANNOTATION``

    By default, .lab files are assumed to have columns separated by one
    or more white-space characters, and have no header or index column
    information.

    If the .lab file contains only two columns, then an empty duration
    field is inferred.

    If the .lab file contains more than three columns, each row's
    annotation value is assigned the contents of last non-empty column.

    Parameters
    ----------
    namespace : str
        The namespace for the new annotation

    filename : str
        Path to the .lab file

    infer_duration : bool
        If `True`, interval durations are inferred from `(start, end)` columns,
        or difference between successive times.

        If `False`, interval durations are assumed to be explicitly coded as
        `(start, duration)` columns.  If only one time column is given, then
        durations are set to 0.

        For instantaneous event annotations (e.g., beats or onsets), this
        should be set to `False`.

    parse_options : additional keyword arguments
        Passed to ``pandas.DataFrame.read_csv``

    Returns
    -------
    annotation : Annotation
        The newly constructed annotation object

    See Also
    --------
    pandas.DataFrame.read_csv
    '''

    # Create a new annotation object
    annotation = core.Annotation(namespace)

    parse_options.setdefault('sep', r'\s+')
    parse_options.setdefault('engine', 'python')
    parse_options.setdefault('header', None)
    parse_options.setdefault('index_col', False)

    # This is a hack to handle potentially ragged .lab data
    parse_options.setdefault('names', range(20))

    data = pd.read_csv(filename, **parse_options)

    # Drop all-nan columns
    data = data.dropna(how='all', axis=1)

    # Do we need to add a duration column?
    # This only applies to event annotations
    if len(data.columns) == 2:
        # Insert a column of zeros after the timing
        data.insert(1, 'duration', 0)
        if infer_duration:
            data['duration'][:-1] = data.loc[:, 0].diff()[1:].values

    else:
        # Convert from time to duration
        if infer_duration:
            data.loc[:, 1] -= data[0]

    for row in data.itertuples():
        time, duration = row[1:3]

        value = [x for x in row[3:] if x is not None][-1]

        annotation.append(time=time,
                          duration=duration,
                          confidence=1.0,
                          value=value)

    return annotation

Response: Imports a. lab file into a new Annotation object.


Instruction:
Here you have a function in Python 3, explain what it does
def expand_filepaths(base_dir, rel_paths):
    return [os.path.join(base_dir, os.path.normpath(rp)) for rp in rel_paths]

Response: Expand a list of relative paths to a give base directory.


Instruction:
Make a summary of the following Python 3 code
def find_with_extension(in_dir, ext, depth=3, sort=True):
    assert depth >= 1
    ext = ext.strip(os.extsep)
    match = list()
    for n in range(1, depth+1):
        wildcard = os.path.sep.join(["*"]*n)
        search_path = os.path.join(in_dir, os.extsep.join([wildcard, ext]))
        match += glob.glob(search_path)

    if sort:
        match.sort()
    return match

Response: Naive depth - search into a directory for files with a given extension.


Instruction:
Can you tell what is the following Python 3 function doing
def get_comments(jam, ann):
    '''Get the metadata from a jam and an annotation, combined as a string.

    Parameters
    ----------
    jam : JAMS
        The jams object

    ann : Annotation
        An annotation object

    Returns
    -------
    comments : str
        The jam.file_metadata and ann.annotation_metadata, combined and serialized
    '''
    jam_comments = jam.file_metadata.__json__
    ann_comments = ann.annotation_metadata.__json__
    return json.dumps({'metadata': jam_comments,
                       'annotation metadata': ann_comments},
                      indent=2)

Response: Get the metadata from a jam and an annotation as a string.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def lab_dump(ann, comment, filename, sep, comment_char):
    '''Save an annotation as a lab/csv.

    Parameters
    ----------
    ann : Annotation
        The annotation object

    comment : str
        The comment string header

    filename : str
        The output filename

    sep : str
        The separator string for output

    comment_char : str
        The character used to denote comments
    '''

    intervals, values = ann.to_interval_values()

    frame = pd.DataFrame(columns=['Time', 'End Time', 'Label'],
                         data={'Time': intervals[:, 0],
                               'End Time': intervals[:, 1],
                               'Label': values})

    with open(filename, 'w') as fdesc:
        for line in comment.split('\n'):
            fdesc.write('{:s}  {:s}\n'.format(comment_char, line))

        frame.to_csv(path_or_buf=fdesc, index=False, sep=sep)

Response: Save an annotation as a lab / csv.


Instruction:
How would you explain what the following Python 3 function does
def convert_jams(jams_file, output_prefix, csv=False, comment_char='#', namespaces=None):
    '''Convert jams to labs.

    Parameters
    ----------
    jams_file : str
        The path on disk to the jams file in question

    output_prefix : str
        The file path prefix of the outputs

    csv : bool
        Whether to output in csv (True) or lab (False) format

    comment_char : str
        The character used to denote comments

    namespaces : list-like
        The set of namespace patterns to match for output
    '''

    if namespaces is None:
        raise ValueError('No namespaces provided. Try ".*" for all namespaces.')

    jam = jams.load(jams_file)

    # Get all the annotations
    # Filter down to the unique ones
    # For each annotation
    #     generate the comment string
    #     generate the output filename
    #     dump to csv

    # Make a counter object for each namespace type
    counter = collections.Counter()

    annotations = []

    for query in namespaces:
        annotations.extend(jam.search(namespace=query))

    if csv:
        suffix = 'csv'
        sep = ','
    else:
        suffix = 'lab'
        sep = '\t'

    for ann in annotations:
        index = counter[ann.namespace]
        counter[ann.namespace] += 1
        filename = os.path.extsep.join([get_output_name(output_prefix,
                                                        ann.namespace,
                                                        index),
                                        suffix])

        comment = get_comments(jam, ann)

        # Dump to disk
        lab_dump(ann, comment, filename, sep, comment_char)

Response: Convert jams file to labs.


Instruction:
Can you implement a function in Python 3 that
parses command line arguments and return a dictionary of arguments.

Response:
def parse_arguments(args):
    '''Parse arguments from the command line'''
    parser = argparse.ArgumentParser(description='Convert JAMS to .lab files')

    parser.add_argument('-c',
                        '--comma-separated',
                        dest='csv',
                        action='store_true',
                        default=False,
                        help='Output in .csv instead of .lab')

    parser.add_argument('--comment', dest='comment_char', type=str, default='#',
                        help='Comment character')

    parser.add_argument('-n',
                        '--namespace',
                        dest='namespaces',
                        nargs='+',
                        default=['.*'],
                        help='One or more namespaces to output.  Default is all.')

    parser.add_argument('jams_file',
                        help='Path to the input jams file')

    parser.add_argument('output_prefix', help='Prefix for output files')

    return vars(parser.parse_args(args))


Instruction:
Write a Python 3 function that can
convert a given annotation to the target namespace.

Response:
def convert(annotation, target_namespace):
    '''Convert a given annotation to the target namespace.

    Parameters
    ----------
    annotation : jams.Annotation
        An annotation object

    target_namespace : str
        The target namespace

    Returns
    -------
    mapped_annotation : jams.Annotation
        if `annotation` already belongs to `target_namespace`, then
        it is returned directly.

        otherwise, `annotation` is copied and automatically converted
        to the target namespace.

    Raises
    ------
    SchemaError
        if the input annotation fails to validate

    NamespaceError
        if no conversion is possible

    Examples
    --------
    Convert frequency measurements in Hz to MIDI

    >>> ann_midi = jams.convert(ann_hz, 'note_midi')

    And back to Hz

    >>> ann_hz2 = jams.convert(ann_midi, 'note_hz')
    '''

    # First, validate the input. If this fails, we can't auto-convert.
    annotation.validate(strict=True)

    # If we're already in the target namespace, do nothing
    if annotation.namespace == target_namespace:
        return annotation

    if target_namespace in __CONVERSION__:
        # Otherwise, make a copy to mangle
        annotation = deepcopy(annotation)

        # Look for a way to map this namespace to the target
        for source in __CONVERSION__[target_namespace]:
            if annotation.search(namespace=source):
                return __CONVERSION__[target_namespace][source](annotation)

    # No conversion possible
    raise NamespaceError('Unable to convert annotation from namespace='
                         '"{0}" to "{1}"'.format(annotation.namespace,
                                                 target_namespace))


Instruction:
Can you generate the documentation for the following Python 3 function
def can_convert(annotation, target_namespace):
    '''Test if an annotation can be mapped to a target namespace

    Parameters
    ----------
    annotation : jams.Annotation
        An annotation object

    target_namespace : str
        The target namespace

    Returns
    -------
    True
        if `annotation` can be automatically converted to
        `target_namespace`

    False
        otherwise
    '''

    # If we're already in the target namespace, do nothing
    if annotation.namespace == target_namespace:
        return True

    if target_namespace in __CONVERSION__:
        # Look for a way to map this namespace to the target
        for source in __CONVERSION__[target_namespace]:
            if annotation.search(namespace=source):
                return True
    return False

Response: Test if an annotation can be mapped to a target namespace


Instruction:
Make a summary of the following Python 3 code
def pitch_hz_to_contour(annotation):
    '''Convert a pitch_hz annotation to a contour'''
    annotation.namespace = 'pitch_contour'
    data = annotation.pop_data()

    for obs in data:
        annotation.append(time=obs.time, duration=obs.duration,
                          confidence=obs.confidence,
                          value=dict(index=0,
                                     frequency=np.abs(obs.value),
                                     voiced=obs.value > 0))
    return annotation

Response: Convert a pitch_hz annotation to a contour


Instruction:
Here you have a function in Python 3, explain what it does
def note_hz_to_midi(annotation):
    '''Convert a pitch_hz annotation to pitch_midi'''

    annotation.namespace = 'note_midi'

    data = annotation.pop_data()

    for obs in data:
        annotation.append(time=obs.time, duration=obs.duration,
                          confidence=obs.confidence,
                          value=12 * (np.log2(obs.value) - np.log2(440.0)) + 69)

    return annotation

Response: Convert a pitch_hz annotation to pitch_midi


Instruction:
Implement a function in Python 3 to
convert scaper annotations to tag_open

Response:
def scaper_to_tag(annotation):
    '''Convert scaper annotations to tag_open'''

    annotation.namespace = 'tag_open'

    data = annotation.pop_data()
    for obs in data:
        annotation.append(time=obs.time, duration=obs.duration,
                          confidence=obs.confidence, value=obs.value['label'])

    return annotation


Instruction:
How would you explain what the following Python 3 function does
def load(path_or_file, validate=True, strict=True, fmt='auto'):

    with _open(path_or_file, mode='r', fmt=fmt) as fdesc:
        jam = JAMS(**json.load(fdesc))

    if validate:
        jam.validate(strict=strict)

    return jam

Response: r Loads a JAMS object from a file.


Instruction:
Create a Python 3 function for
popping a prefix from a query string.

Response:
def query_pop(query, prefix, sep='.'):
    '''Pop a prefix from a query string.

    Parameters
    ----------
    query : str
        The query string

    prefix : str
        The prefix string to pop, if it exists

    sep : str
        The string to separate fields

    Returns
    -------
    popped : str
        `query` with a `prefix` removed from the front (if found)
        or `query` if the prefix was not found

    Examples
    --------
    >>> query_pop('Annotation.namespace', 'Annotation')
    'namespace'
    >>> query_pop('namespace', 'Annotation')
    'namespace'

    '''

    terms = query.split(sep)

    if terms[0] == prefix:
        terms = terms[1:]

    return sep.join(terms)


Instruction:
How would you explain what the following Python 3 function does
def match_query(string, query):
    '''Test if a string matches a query.

    Parameters
    ----------
    string : str
        The string to test

    query : string, callable, or object
        Either a regular expression, callable function, or object.

    Returns
    -------
    match : bool
        `True` if:
        - `query` is a callable and `query(string) == True`
        - `query` is a regular expression and `re.match(query, string)`
        - or `string == query` for any other query

        `False` otherwise

    '''

    if six.callable(query):
        return query(string)

    elif (isinstance(query, six.string_types) and
          isinstance(string, six.string_types)):
        return re.match(query, string) is not None

    else:
        return query == string

Response: Test if a string matches a query.


Instruction:
Can you tell what is the following Python 3 function doing
def summary(obj, indent=0):
    '''Helper function to format repr strings for JObjects and friends.

    Parameters
    ----------
    obj
        The object to repr

    indent : int >= 0
        indent each new line by `indent` spaces

    Returns
    -------
    r : str
        If `obj` has a `__summary__` method, it is used.

        If `obj` is a `SortedKeyList`, then it returns a description
        of the length of the list.

        Otherwise, `repr(obj)`.
    '''
    if hasattr(obj, '__summary__'):
        rep = obj.__summary__()
    elif isinstance(obj, SortedKeyList):
        rep = '<{:d} observations>'.format(len(obj))
    else:
        rep = repr(obj)

    return rep.replace('\n', '\n' + ' ' * indent)

Response: Helper function to format repr strings for JObjects and friends.


Instruction:
Implement a Python 3 function for
updating the attributes of a JObject.

Response:
def update(self, **kwargs):
        '''Update the attributes of a JObject.

        Parameters
        ----------
        kwargs
            Keyword arguments of the form `attribute=new_value`

        Examples
        --------
        >>> J = jams.JObject(foo=5)
        >>> J.dumps()
        '{"foo": 5}'
        >>> J.update(bar='baz')
        >>> J.dumps()
        '{"foo": 5, "bar": "baz"}'
        '''
        for name, value in six.iteritems(kwargs):
            setattr(self, name, value)


Instruction:
Write a Python 3 script to
search this object and its descendants.

Response:
def search(self, **kwargs):
        '''Query this object (and its descendants).

        Parameters
        ----------
        kwargs
            Each `(key, value)` pair encodes a search field in `key`
            and a target value in `value`.

            `key` must be a string, and should correspond to a property in
            the JAMS object hierarchy, e.g., 'Annotation.namespace` or `email`

            `value` must be either an object (tested for equality), a
            string describing a search pattern (regular expression), or a
            lambda function which evaluates to `True` if the candidate
            object matches the search criteria and `False` otherwise.

        Returns
        -------
        match : bool
            `True` if any of the search keys match the specified value,
            `False` otherwise, or if the search keys do not exist
            within the object.

        Examples
        --------
        >>> J = jams.JObject(foo=5, needle='quick brown fox')
        >>> J.search(needle='.*brown.*')
        True
        >>> J.search(needle='.*orange.*')
        False
        >>> J.search(badger='.*brown.*')
        False
        >>> J.search(foo=5)
        True
        >>> J.search(foo=10)
        False
        >>> J.search(foo=lambda x: x < 10)
        True
        >>> J.search(foo=lambda x: x > 10)
        False
        '''

        match = False

        r_query = {}
        myself = self.__class__.__name__

        # Pop this object name off the query
        for k, value in six.iteritems(kwargs):
            k_pop = query_pop(k, myself)

            if k_pop:
                r_query[k_pop] = value

        if not r_query:
            return False

        for key in r_query:
            if hasattr(self, key):
                match |= match_query(getattr(self, key), r_query[key])

        if not match:
            for attr in dir(self):
                obj = getattr(self, attr)

                if isinstance(obj, JObject):
                    match |= obj.search(**r_query)

        return match


Instruction:
Given the following Python 3 function, write the documentation
def validate(self, strict=True):
        '''Validate a JObject against its schema

        Parameters
        ----------
        strict : bool
            Enforce strict schema validation

        Returns
        -------
        valid : bool
            True if the jam validates
            False if not, and `strict==False`

        Raises
        ------
        SchemaError
            If `strict==True` and `jam` fails validation
        '''

        valid = True

        try:
            jsonschema.validate(self.__json__, self.__schema__)

        except jsonschema.ValidationError as invalid:
            if strict:
                raise SchemaError(str(invalid))
            else:
                warnings.warn(str(invalid))

            valid = False

        return valid

Response: Validate a JObject against its schema.


Instruction:
Given the following Python 3 function, write the documentation
def append(self, time=None, duration=None, value=None, confidence=None):
        '''Append an observation to the data field

        Parameters
        ----------
        time : float >= 0
        duration : float >= 0
            The time and duration of the new observation, in seconds
        value
        confidence
            The value and confidence of the new observations.

            Types and values should conform to the namespace of the
            Annotation object.

        Examples
        --------
        >>> ann = jams.Annotation(namespace='chord')
        >>> ann.append(time=3, duration=2, value='E#')
        '''

        self.data.add(Observation(time=float(time),
                                  duration=float(duration),
                                  value=value,
                                  confidence=confidence))

Response: Append an observation to the data field


Instruction:
Can you implement a function in Python 3 that
adds observations from row - major storage.

Response:
def append_records(self, records):
        '''Add observations from row-major storage.

        This is primarily useful for deserializing sparsely packed data.

        Parameters
        ----------
        records : iterable of dicts or Observations
            Each element of `records` corresponds to one observation.
        '''
        for obs in records:
            if isinstance(obs, Observation):
                self.append(**obs._asdict())
            else:
                self.append(**obs)


Instruction:
Write a Python 3 script for
adding observations from column - major storage.

Response:
def append_columns(self, columns):
        '''Add observations from column-major storage.

        This is primarily used for deserializing densely packed data.

        Parameters
        ----------
        columns : dict of lists
            Keys must be `time, duration, value, confidence`,
            and each much be a list of equal length.

        '''
        self.append_records([dict(time=t, duration=d, value=v, confidence=c)
                             for (t, d, v, c)
                             in six.moves.zip(columns['time'],
                                              columns['duration'],
                                              columns['value'],
                                              columns['confidence'])])


Instruction:
How would you explain what the following Python 3 function does
def validate(self, strict=True):
        '''Validate this annotation object against the JAMS schema,
        and its data against the namespace schema.

        Parameters
        ----------
        strict : bool
            If `True`, then schema violations will cause an Exception.
            If `False`, then schema violations will issue a warning.

        Returns
        -------
        valid : bool
            `True` if the object conforms to schema.
            `False` if the object fails to conform to schema,
            but `strict == False`.

        Raises
        ------
        SchemaError
            If `strict == True` and the object fails validation

        See Also
        --------
        JObject.validate
        '''

        # Get the schema for this annotation
        ann_schema = schema.namespace_array(self.namespace)

        valid = True

        try:
            jsonschema.validate(self.__json_light__(data=False),
                                schema.JAMS_SCHEMA)

            # validate each record in the frame
            data_ser = [serialize_obj(obs) for obs in self.data]
            jsonschema.validate(data_ser, ann_schema)

        except jsonschema.ValidationError as invalid:
            if strict:
                raise SchemaError(str(invalid))
            else:
                warnings.warn(str(invalid))
            valid = False

        return valid

Response: Validate this object against the JAMS schema and its data against the namespace schema.


Instruction:
Can you generate the documentation for the following Python 3 function
def trim(self, start_time, end_time, strict=False):
        '''
        Trim the annotation and return as a new `Annotation` object.

        Trimming will result in the new annotation only containing observations
        that occur in the intersection of the time range spanned by the
        annotation and the time range specified by the user. The new annotation
        will span the time range ``[trim_start, trim_end]`` where
        ``trim_start = max(self.time, start_time)`` and ``trim_end =
        min(self.time + self.duration, end_time)``.

        If ``strict=False`` (default) observations that start before
        ``trim_start`` and end after it will be trimmed such that they start at
        ``trim_start``, and similarly observations that start before
        ``trim_end`` and end after it will be trimmed to end at ``trim_end``.
        If ``strict=True`` such borderline observations will be discarded.

        The new duration of the annotation will be ``trim_end - trim_start``.

        Note that if the range defined by ``[start_time, end_time]``
        doesn't intersect with the original time range spanned by the
        annotation the resulting annotation will contain no observations, will
        have the same start time as the original annotation and have duration
        0.

        This function also copies over all the annotation metadata from the
        original annotation and documents the trim operation by adding a list
        of tuples to the annotation's sandbox keyed by
        ``Annotation.sandbox.trim`` which documents each trim operation with a
        tuple ``(start_time, end_time, trim_start, trim_end)``.

        Parameters
        ----------
        start_time : float
            The desired start time for the trimmed annotation in seconds.
        end_time
            The desired end time for the trimmed annotation in seconds. Must be
            greater than ``start_time``.
        strict : bool
            When ``False`` (default) observations that lie at the boundaries of
            the trimming range (given by ``[trim_start, trim_end]`` as
            described above), i.e. observations that start before and end after
            either the trim start or end time, will have their time and/or
            duration adjusted such that only the part of the observation that
            lies within the trim range is kept. When ``True`` such observations
            are discarded and not included in the trimmed annotation.

        Returns
        -------
        ann_trimmed : Annotation
            The trimmed annotation, returned as a new jams.Annotation object.
            If the trim range specified by ``[start_time, end_time]`` does not
            intersect at all with the original time range of the annotation a
            warning will be issued and the returned annotation will be empty.

        Raises
        ------
        ParameterError
            If ``end_time`` is not greater than ``start_time``.

        Examples
        --------
        >>> ann = jams.Annotation(namespace='tag_open', time=2, duration=8)
        >>> ann.append(time=2, duration=2, value='one')
        >>> ann.append(time=4, duration=2, value='two')
        >>> ann.append(time=6, duration=2, value='three')
        >>> ann.append(time=7, duration=2, value='four')
        >>> ann.append(time=8, duration=2, value='five')
        >>> ann_trim = ann.trim(5, 8, strict=False)
        >>> print(ann_trim.time, ann_trim.duration)
        (5, 3)
        >>> ann_trim.to_dataframe()
           time  duration  value confidence
        0     5         1    two       None
        1     6         2  three       None
        2     7         1   four       None
        >>> ann_trim_strict = ann.trim(5, 8, strict=True)
        >>> print(ann_trim_strict.time, ann_trim_strict.duration)
        (5, 3)
        >>> ann_trim_strict.to_dataframe()
           time  duration  value confidence
        0     6         2  three       None
        '''
        # Check for basic start_time and end_time validity
        if end_time <= start_time:
            raise ParameterError(
                'end_time must be greater than start_time.')

        # If the annotation does not have a set duration value, we'll assume
        # trimming is possible (up to the user to ensure this is valid).
        if self.duration is None:
            orig_time = start_time
            orig_duration = end_time - start_time
            warnings.warn(
                "Annotation.duration is not defined, cannot check "
                "for temporal intersection, assuming the annotation "
                "is valid between start_time and end_time.")
        else:
            orig_time = self.time
            orig_duration = self.duration

        # Check whether there is intersection between the trim range and
        # annotation: if not raise a warning and set trim_start and trim_end
        # appropriately.
        if start_time > (orig_time + orig_duration) or (end_time < orig_time):
            warnings.warn(
                'Time range defined by [start_time,end_time] does not '
                'intersect with the time range spanned by this annotation, '
                'the trimmed annotation will be empty.')
            trim_start = self.time
            trim_end = trim_start
        else:
            # Determine new range
            trim_start = max(orig_time, start_time)
            trim_end = min(orig_time + orig_duration, end_time)

        # Create new annotation with same namespace/metadata
        ann_trimmed = Annotation(
            self.namespace,
            data=None,
            annotation_metadata=self.annotation_metadata,
            sandbox=self.sandbox,
            time=trim_start,
            duration=trim_end - trim_start)

        # Selectively add observations based on their start time / duration
        # We do this rather than copying and directly manipulating the
        # annotation' data frame (which might be faster) since this way trim is
        # independent of the internal data representation.
        for obs in self.data:

            obs_start = obs.time
            obs_end = obs_start + obs.duration

            if obs_start < trim_end and obs_end > trim_start:

                new_start = max(obs_start, trim_start)
                new_end = min(obs_end, trim_end)
                new_duration = new_end - new_start

                if ((not strict) or
                        (new_start == obs_start and new_end == obs_end)):
                    ann_trimmed.append(time=new_start,
                                       duration=new_duration,
                                       value=obs.value,
                                       confidence=obs.confidence)

        if 'trim' not in ann_trimmed.sandbox.keys():
            ann_trimmed.sandbox.update(
                trim=[{'start_time': start_time, 'end_time': end_time,
                       'trim_start': trim_start, 'trim_end': trim_end}])
        else:
            ann_trimmed.sandbox.trim.append(
                {'start_time': start_time, 'end_time': end_time,
                 'trim_start': trim_start, 'trim_end': trim_end})

        return ann_trimmed

Response: Trim the annotation and return as a new Annotation object.


Instruction:
Write a Python 3 function for
slicing the annotation and return as a new Annotation object.

Response:
def slice(self, start_time, end_time, strict=False):
        '''
        Slice the annotation and return as a new `Annotation` object.

        Slicing has the same effect as trimming (see `Annotation.trim`) except
        that while trimming does not modify the start time of the annotation or
        the observations it contains, slicing will set the new annotation's
        start time to ``max(0, trimmed_annotation.time - start_time)`` and the
        start time of its observations will be set with respect to this new
        reference start time.

        This function documents the slice operation by adding a list of tuples
        to the annotation's sandbox keyed by ``Annotation.sandbox.slice`` which
        documents each slice operation with a tuple
        ``(start_time, end_time, slice_start, slice_end)``, where
        ``slice_start`` and ``slice_end`` are given by ``trim_start`` and
        ``trim_end`` (see `Annotation.trim`).

        Since slicing is implemented  using trimming, the trimming operation
        will also be documented in ``Annotation.sandbox.trim`` as described in
        `Annotation.trim`.

        This function is useful for example when trimming an audio file,
        allowing the user to trim the annotation while ensuring all time
        information matches the new trimmed audio file.

        Parameters
        ----------
        start_time : float
            The desired start time for slicing in seconds.
        end_time
            The desired end time for slicing in seconds. Must be greater than
            ``start_time``.
        strict : bool
            When ``False`` (default) observations that lie at the boundaries of
            the slice (see `Annotation.trim` for details) will have their time
            and/or duration adjusted such that only the part of the observation
            that lies within the slice range is kept. When ``True`` such
            observations are discarded and not included in the sliced
            annotation.

        Returns
        -------
        sliced_ann : Annotation
            The sliced annotation.

        See Also
        --------
        Annotation.trim

        Examples
        --------
        >>> ann = jams.Annotation(namespace='tag_open', time=2, duration=8)
        >>> ann.append(time=2, duration=2, value='one')
        >>> ann.append(time=4, duration=2, value='two')
        >>> ann.append(time=6, duration=2, value='three')
        >>> ann.append(time=7, duration=2, value='four')
        >>> ann.append(time=8, duration=2, value='five')
        >>> ann_slice = ann.slice(5, 8, strict=False)
        >>> print(ann_slice.time, ann_slice.duration)
        (0, 3)
        >>> ann_slice.to_dataframe()
           time  duration  value confidence
        0   0.0       1.0    two       None
        1   1.0       2.0  three       None
        2   2.0       1.0   four       None
        >>> ann_slice_strict = ann.slice(5, 8, strict=True)
        >>> print(ann_slice_strict.time, ann_slice_strict.duration)
        (0, 3)
        >>> ann_slice_strict.to_dataframe()
           time  duration  value confidence
        0   1.0       2.0  three       None
        '''
        # start by trimming the annotation
        sliced_ann = self.trim(start_time, end_time, strict=strict)
        raw_data = sliced_ann.pop_data()

        # now adjust the start time of the annotation and the observations it
        # contains.

        for obs in raw_data:
            new_time = max(0, obs.time - start_time)
            # if obs.time > start_time,
            #   duration doesn't change
            # if obs.time < start_time,
            #   duration shrinks by start_time - obs.time
            sliced_ann.append(time=new_time,
                              duration=obs.duration,
                              value=obs.value,
                              confidence=obs.confidence)

        ref_time = sliced_ann.time
        slice_start = ref_time
        slice_end = ref_time + sliced_ann.duration

        if 'slice' not in sliced_ann.sandbox.keys():
            sliced_ann.sandbox.update(
                slice=[{'start_time': start_time, 'end_time': end_time,
                        'slice_start': slice_start, 'slice_end': slice_end}])
        else:
            sliced_ann.sandbox.slice.append(
                {'start_time': start_time, 'end_time': end_time,
                 'slice_start': slice_start, 'slice_end': slice_end})

        # Update the timing for the sliced annotation
        sliced_ann.time = max(0, ref_time - start_time)

        return sliced_ann


Instruction:
Explain what the following Python 3 code does
def pop_data(self):
        '''Replace this observation's data with a fresh container.

        Returns
        -------
        annotation_data : SortedKeyList
            The original annotation data container
        '''

        data = self.data
        self.data = SortedKeyList(key=self._key)
        return data

Response: Replace this observation s data with a fresh container.


Instruction:
Write a Python 3 script for
extracting observation data in a mir_eval - friendly format.

Response:
def to_interval_values(self):
        '''Extract observation data in a `mir_eval`-friendly format.

        Returns
        -------
        intervals : np.ndarray [shape=(n, 2), dtype=float]
            Start- and end-times of all valued intervals

            `intervals[i, :] = [time[i], time[i] + duration[i]]`

        labels : list
            List view of value field.
        '''

        ints, vals = [], []
        for obs in self.data:
            ints.append([obs.time, obs.time + obs.duration])
            vals.append(obs.value)

        if not ints:
            return np.empty(shape=(0, 2), dtype=float), []

        return np.array(ints), vals


Instruction:
Create a Python 3 function to
extract observation data in a mir_eval - friendly format.

Response:
def to_event_values(self):
        '''Extract observation data in a `mir_eval`-friendly format.

        Returns
        -------
        times : np.ndarray [shape=(n,), dtype=float]
            Start-time of all observations

        labels : list
            List view of value field.
        '''
        ints, vals = [], []
        for obs in self.data:
            ints.append(obs.time)
            vals.append(obs.value)

        return np.array(ints), vals


Instruction:
Given the following Python 3 function, write the documentation
def to_samples(self, times, confidence=False):
        '''Sample the annotation at specified times.

        Parameters
        ----------
        times : np.ndarray, non-negative, ndim=1
            The times (in seconds) to sample the annotation

        confidence : bool
            If `True`, return both values and confidences.
            If `False` (default) only return values.

        Returns
        -------
        values : list
            `values[i]` is a list of observation values for intervals
            that cover `times[i]`.

        confidence : list (optional)
            `confidence` values corresponding to `values`
        '''
        times = np.asarray(times)
        if times.ndim != 1 or np.any(times < 0):
            raise ParameterError('times must be 1-dimensional and non-negative')

        idx = np.argsort(times)
        samples = times[idx]

        values = [list() for _ in samples]
        confidences = [list() for _ in samples]

        for obs in self.data:
            start = np.searchsorted(samples, obs.time)
            end = np.searchsorted(samples, obs.time + obs.duration, side='right')
            for i in range(start, end):
                values[idx[i]].append(obs.value)
                confidences[idx[i]].append(obs.confidence)

        if confidence:
            return values, confidences
        else:
            return values

Response: Sample the annotation at specified times.


Instruction:
Make a summary of the following Python 3 code
def to_html(self, max_rows=None):
        '''Render this annotation list in HTML

        Returns
        -------
        rendered : str
            An HTML table containing this annotation's data.
        '''
        n = len(self.data)

        div_id = _get_divid(self)

        out = r'''

                            <button
                                type="button"
                                data-toggle="collapse"
                                data-parent="#accordion"
                                href="#{0}"
                                aria-expanded="false"
                                class="collapsed btn btn-info btn-block"
                                aria-controls="{0}">
                                {1:s}
                                {2:d}
                            </button>

'''.format(div_id, self.namespace, n)

        out += r'''

'''.format(div_id)

        out += r'''

                        {}

'''.format(self.annotation_metadata._repr_html_())
        out += r'''

                        {}

'''.format(self.sandbox._repr_html_())

        # -- Annotation content starts here
        out += r'''

                            time
                            duration
                            value
                            confidence

'''.format(self.namespace, n)

        out += r'''
'''

        if max_rows is None or n <= max_rows:
            out += self._fmt_rows(0, n)
        else:
            out += self._fmt_rows(0, max_rows//2)
            out += r'''

                            ...
                            ...
                            ...
                            ...
                            ...

'''
            out += self._fmt_rows(n-max_rows//2, n)

        out += r'''
'''

        out += r'''

'''

        out += r'''

'''
        return out

Response: Render this annotation list in HTML.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _key(cls, obs):
        '''Provides sorting index for Observation objects'''
        if not isinstance(obs, Observation):
            raise JamsError('{} must be of type jams.Observation'.format(obs))

        return obs.time

Response: Provides sorting index for Observation objects


Instruction:
Can you implement a function in Python 3 that
filters the annotation array down to only those Annotation objects matching the query.

Response:
def search(self, **kwargs):
        '''Filter the annotation array down to only those Annotation
        objects matching the query.

        Parameters
        ----------
        kwargs : search parameters
            See JObject.search

        Returns
        -------
        results : AnnotationArray
            An annotation array of the objects matching the query

        See Also
        --------
        JObject.search
        '''

        results = AnnotationArray()

        for annotation in self:
            if annotation.search(**kwargs):
                results.append(annotation)

        return results