Instruction:
Can you create a Python 3 function that
parses the data reference box.

Response:
def parse(cls, fptr, offset, length):
        """Parse data reference box.

        Parameters
        ----------
        fptr : file
            Open file object.
        offset : int
            Start position of box in bytes.
        length : int
            Length of the box in bytes.

        Returns
        -------
        DataReferenceBox
            Instance of the current data reference box.
        """
        num_bytes = offset + length - fptr.tell()
        read_buffer = fptr.read(num_bytes)

        # Read the number of data references
        ndr, = struct.unpack_from('>H', read_buffer, offset=0)

        # Need to keep track of where the next url box starts.
        box_offset = 2

        data_entry_url_box_list = []
        for j in range(ndr):

            # Create an in-memory binary stream for each URL box.
            box_fptr = io.BytesIO(read_buffer[box_offset:])
            box_buffer = box_fptr.read(8)
            (box_length, box_id) = struct.unpack_from('>I4s', box_buffer,
                                                      offset=0)
            box = DataEntryURLBox.parse(box_fptr, 0, box_length)

            # Need to adjust the box start to that of the "real" file.
            box.offset = offset + 8 + box_offset
            data_entry_url_box_list.append(box)

            # Point to the next embedded URL box.
            box_offset += box_length

        return cls(data_entry_url_box_list, length=length, offset=offset)


Instruction:
Create a Python 3 function for
validating the box before writing to file.

Response:
def _validate(self, writing=False):
        """
        Validate the box before writing to file.
        """
        if self.brand not in ['jp2 ', 'jpx ']:
            msg = ("The file type brand was '{brand}'.  "
                   "It should be either 'jp2 ' or 'jpx '.")
            msg = msg.format(brand=self.brand)
            if writing:
                raise IOError(msg)
            else:
                warnings.warn(msg, UserWarning)
        for item in self.compatibility_list:
            if item not in self._valid_cls:
                msg = ("The file type compatibility list {items} is "
                       "not valid.  All items should be members of "
                       "{valid_entries}.")
                msg = msg.format(items=self.compatibility_list,
                                 valid_entries=self._valid_cls)
                if writing:
                    raise IOError(msg)
                else:
                    warnings.warn(msg, UserWarning)


Instruction:
How would you code a function in Python 3 to
write a File Type box to file.

Response:
def write(self, fptr):
        """Write a File Type box to file.
        """
        self._validate(writing=True)
        length = 16 + 4 * len(self.compatibility_list)
        fptr.write(struct.pack('>I4s', length, b'ftyp'))
        fptr.write(self.brand.encode())
        fptr.write(struct.pack('>I', self.minor_version))

        for item in self.compatibility_list:
            fptr.write(item.encode())


Instruction:
Make a summary of the following Python 3 code
def parse(cls, fptr, offset, length):
        num_bytes = offset + length - fptr.tell()
        read_buffer = fptr.read(num_bytes)
        # Extract the brand, minor version.
        (brand, minor_version) = struct.unpack_from('>4sI', read_buffer, 0)
        if sys.hexversion >= 0x030000:
            brand = brand.decode('utf-8')

        # Extract the compatibility list.  Each entry has 4 bytes.
        num_entries = int((length - 16) / 4)
        compatibility_list = []
        for j in range(int(num_entries)):
            entry, = struct.unpack_from('>4s', read_buffer, 8 + j * 4)
            if sys.hexversion >= 0x03000000:
                try:
                    entry = entry.decode('utf-8')
                except UnicodeDecodeError:
                    # The entry is invalid, but we've got code to catch this
                    # later on.
                    pass

            compatibility_list.append(entry)

        return cls(brand=brand, minor_version=minor_version,
                   compatibility_list=compatibility_list,
                   length=length, offset=offset)

Response: Parse the JPEG 2000 file type box.


Instruction:
How would you code a function in Python 3 to
write a fragment list box to file.

Response:
def write(self, fptr):
        """Write a fragment list box to file.
        """
        self._validate(writing=True)
        num_items = len(self.fragment_offset)
        length = 8 + 2 + num_items * 14
        fptr.write(struct.pack('>I4s', length, b'flst'))
        fptr.write(struct.pack('>H', num_items))
        for j in range(num_items):
            write_buffer = struct.pack('>QIH',
                                       self.fragment_offset[j],
                                       self.fragment_length[j],
                                       self.data_reference[j])
            fptr.write(write_buffer)


Instruction:
Can you generate the documentation for the following Python 3 function
def parse(cls, fptr, offset, length):
        num_bytes = offset + length - fptr.tell()
        read_buffer = fptr.read(num_bytes)
        num_fragments, = struct.unpack_from('>H', read_buffer, offset=0)

        lst = struct.unpack_from('>' + 'QIH' * num_fragments,
                                 read_buffer,
                                 offset=2)
        frag_offset = lst[0::3]
        frag_len = lst[1::3]
        data_reference = lst[2::3]
        return cls(frag_offset, frag_len, data_reference,
                   length=length, offset=offset)

Response: Parse the JPX free box.


Instruction:
Make a summary of the following Python 3 code
def _validate(self, writing=False):
        box_ids = [box.box_id for box in self.box]
        if len(box_ids) != 1 or box_ids[0] != 'flst':
            msg = ("Fragment table boxes must have a single fragment list "
                   "box as a child box.")
            self._dispatch_validation_error(msg, writing=writing)

Response: Self - validate the box before writing.


Instruction:
How would you code a function in Python 3 to
write a fragment table box to file.

Response:
def write(self, fptr):
        """Write a fragment table box to file.
        """
        self._validate(writing=True)
        self._write_superbox(fptr, b'ftbl')


Instruction:
Given the following Python 3 function, write the documentation
def parse(cls, fptr, offset, length):
        # Must seek to end of box.
        nbytes = offset + length - fptr.tell()
        fptr.read(nbytes)
        return cls(length=length, offset=offset)

Response: Parse a JPX free box.


Instruction:
Make a summary of the following Python 3 code
def write(self, fptr):
        fptr.write(struct.pack('>I4s', 22, b'ihdr'))

        # signedness and bps are stored together in a single byte
        bit_depth_signedness = 0x80 if self.signed else 0x00
        bit_depth_signedness |= self.bits_per_component - 1
        read_buffer = struct.pack('>IIHBBBB',
                                  self.height,
                                  self.width,
                                  self.num_components,
                                  bit_depth_signedness,
                                  self.compression,
                                  1 if self.colorspace_unknown else 0,
                                  1 if self.ip_provided else 0)
        fptr.write(read_buffer)

Response: Write an Image Header box to file.


Instruction:
Make a summary of the following Python 3 code
def parse(cls, fptr, offset, length):
        # Read the box information
        read_buffer = fptr.read(14)
        params = struct.unpack('>IIHBBBB', read_buffer)
        height = params[0]
        width = params[1]
        num_components = params[2]
        bits_per_component = (params[3] & 0x7f) + 1
        signed = (params[3] & 0x80) > 1
        compression = params[4]
        colorspace_unknown = True if params[5] else False
        ip_provided = True if params[6] else False

        return cls(height, width, num_components=num_components,
                   bits_per_component=bits_per_component,
                   signed=signed,
                   compression=compression,
                   colorspace_unknown=colorspace_unknown,
                   ip_provided=ip_provided,
                   length=length, offset=offset)

Response: Parse the JPEG 2000 image header box.


Instruction:
Can you tell what is the following Python 3 function doing
def parse(cls, fptr, offset, length):
        nbytes = length - 8
        data = fptr.read(nbytes)
        bpc = tuple(((x & 0x7f) + 1) for x in bytearray(data))
        signed = tuple(((x & 0x80) > 0) for x in bytearray(data))

        return cls(bpc, signed, length=length, offset=offset)

Response: Parse bits per component of the current log entry.


Instruction:
Create a Python 3 function to
parse the JPEG 2000 header box.

Response:
def parse(cls, fptr, offset, length):
        """Parse JPEG 2000 header box.

        Parameters
        ----------
        fptr : file
            Open file object.
        offset : int
            Start position of box in bytes.
        length : int
            Length of the box in bytes.

        Returns
        -------
        JP2HeaderBox
            Instance of the current JP2 header box.
        """
        box = cls(length=length, offset=offset)

        # The JP2 header box is a superbox, so go ahead and parse its child
        # boxes.
        box.box = box.parse_superbox(fptr)

        return box


Instruction:
Given the following Python 3 function, write the documentation
def write(self, fptr):
        fptr.write(struct.pack('>I4s', 12, b'jP  '))
        fptr.write(struct.pack('>BBBB', *self.signature))

Response: Write a JPEG 2000 Signature box to file.


Instruction:
How would you implement a function in Python 3 that
parses the JPEG 2000 signature box.

Response:
def parse(cls, fptr, offset, length):
        """Parse JPEG 2000 signature box.

        Parameters
        ----------
        fptr : file
            Open file object.
        offset : int
            Start position of box in bytes.
        length : int
            Length of the box in bytes.

        Returns
        -------
        JPEG2000SignatureBox
            Instance of the current JPEG2000 signature box.
        """
        read_buffer = fptr.read(4)
        signature = struct.unpack('>BBBB', read_buffer)

        return cls(signature=signature, length=length, offset=offset)


Instruction:
How would you code a function in Python 3 to
verify that the box obeys the specifications.

Response:
def _validate(self, writing=False):
        """Verify that the box obeys the specifications."""
        if ((len(self.bits_per_component) != len(self.signed)) or
                (len(self.signed) != self.palette.shape[1])):
            msg = ("The length of the 'bits_per_component' and the 'signed' "
                   "members must equal the number of columns of the palette.")
            self._dispatch_validation_error(msg, writing=writing)
        bps = self.bits_per_component
        if writing and not all(b == bps[0] for b in bps):
            # We don't support writing palettes with bit depths that are
            # different.
            msg = "Writing palettes with varying bit depths is not supported."
            self._dispatch_validation_error(msg, writing=writing)


Instruction:
How would you explain what the following Python 3 function does
def write(self, fptr):
        self._validate(writing=True)
        bytes_per_row = sum(self.bits_per_component) / 8
        bytes_per_palette = bytes_per_row * self.palette.shape[0]
        box_length = 8 + 3 + self.palette.shape[1] + bytes_per_palette

        # Write the usual (L, T) header.
        write_buffer = struct.pack('>I4s', int(box_length), b'pclr')
        fptr.write(write_buffer)

        # NE, NPC
        write_buffer = struct.pack('>HB', self.palette.shape[0],
                                   self.palette.shape[1])
        fptr.write(write_buffer)

        # Bits Per Sample.  Signed components aren't supported.
        bps_signed = [x - 1 for x in self.bits_per_component]
        write_buffer = struct.pack('>' + 'B' * self.palette.shape[1],
                                   *bps_signed)
        fptr.write(write_buffer)

        # C(i,j)
        fptr.write(memoryview(self.palette))

Response: Write a Palette box to file.


Instruction:
Create a Python 3 function for
parsing the current NCBI - 2001 color palette box.

Response:
def parse(cls, fptr, offset, length):
        """Parse palette box.

        Parameters
        ----------
        fptr : file
            Open file object.
        offset : int
            Start position of box in bytes.
        length : int
            Length of the box in bytes.

        Returns
        -------
        PaletteBox
            Instance of the current palette box.
        """
        num_bytes = offset + length - fptr.tell()
        read_buffer = fptr.read(num_bytes)
        nrows, ncols = struct.unpack_from('>HB', read_buffer, offset=0)

        bps_signed = struct.unpack_from('>' + 'B' * ncols, read_buffer,
                                        offset=3)
        bps = [((x & 0x7f) + 1) for x in bps_signed]
        signed = [((x & 0x80) > 1) for x in bps_signed]

        # Are any components signed or differently sized?  We don't handle
        # that.
        if any(signed) or len(set(bps)) != 1:
            msg = ("Palettes with signed components or differently sized "
                   "components are not supported.")
            raise IOError(msg)

        # The palette is unsigned and all components have the same width.
        # This should cover all but a vanishingly small share of palettes.
        b = bps[0]
        dtype = np.uint8 if b <=8 else np.uint16 if b <= 16 else np.uint32

        palette = np.frombuffer(read_buffer[3 + ncols:], dtype=dtype)
        palette = np.reshape(palette, (nrows, ncols))

        return cls(palette, bps, signed, length=length, offset=offset)


Instruction:
Here you have a function in Python 3, explain what it does
def parse(cls, fptr, offset, length):
        num_bytes = offset + length - fptr.tell()
        read_buffer = fptr.read(num_bytes)
        mask_length, = struct.unpack_from('>B', read_buffer, offset=0)

        # Fully Understands Aspect Mask
        # Decodes Completely Mask
        fuam = dcm = standard_flag = standard_mask = []
        vendor_feature = vendor_mask = []

        # The mask length tells us the format string to use when unpacking
        # from the buffer read from file.
        try:
            mask_format = {1: 'B', 2: 'H', 4: 'I', 8: 'Q'}[mask_length]
            fuam, dcm = struct.unpack_from('>' + mask_format * 2, read_buffer,
                                           offset=1)
            std_flg_offset = 1 + 2 * mask_length
            data = _parse_standard_flag(read_buffer[std_flg_offset:],
                                        mask_length)
            standard_flag, standard_mask = data

            nflags = len(standard_flag)
            vndr_offset = 1 + 2 * mask_length + 2 + (2 + mask_length) * nflags
            data = _parse_vendor_features(read_buffer[vndr_offset:],
                                          mask_length)
            vendor_feature, vendor_mask = data

        except KeyError:
            msg = ('The ReaderRequirements box (rreq) has a mask length of '
                   '{length} bytes, but only values of 1, 2, 4, or 8 are '
                   'supported.  The box contents will not be interpreted.')
            warnings.warn(msg.format(length=mask_length), UserWarning)

        return cls(fuam, dcm, standard_flag, standard_mask,
                   vendor_feature, vendor_mask,
                   length=length, offset=offset)

Response: Parse the reader requirements box.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def parse(cls, fptr, offset, length):
        read_buffer = fptr.read(10)
        (rn1, rd1, rn2, rd2, re1, re2) = struct.unpack('>HHHHBB', read_buffer)
        vres = rn1 / rd1 * math.pow(10, re1)
        hres = rn2 / rd2 * math.pow(10, re2)

        return cls(vres, hres, length=length, offset=offset)

Response:
Parse CaptureResolutionBox.
            returns CaptureResolutionBox instance.


Instruction:
Explain what the following Python 3 code does
def write(self, fptr):
        length = 8 + len(self.label.encode())
        fptr.write(struct.pack('>I4s', length, b'lbl '))
        fptr.write(self.label.encode())

Response: Write a Label box to file.


Instruction:
Can you tell what is the following Python 3 function doing
def parse(cls, fptr, offset, length):
        num_bytes = offset + length - fptr.tell()
        read_buffer = fptr.read(num_bytes)
        label = read_buffer.decode('utf-8')
        return cls(label, length=length, offset=offset)

Response:
Parse a LabelBox
            box.


Instruction:
Explain what the following Python 3 code does
def parse(cls, fptr, offset, length):
        num_bytes = offset + length - fptr.tell()
        raw_data = fptr.read(num_bytes)
        num_associations = int(len(raw_data) / 4)
        lst = struct.unpack('>' + 'I' * num_associations, raw_data)
        return cls(lst, length=length, offset=offset)

Response: Parse the n - tuple label list box.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def write(self, fptr):
        fptr.write(struct.pack('>I4s',
                               len(self.associations) * 4 + 8, b'nlst'))

        fmt = '>' + 'I' * len(self.associations)
        write_buffer = struct.pack(fmt, *self.associations)
        fptr.write(write_buffer)

Response: Write a NumberList box to file.


Instruction:
Write a Python 3 function that can
write an XML box to file.

Response:
def write(self, fptr):
        """
        Write an XML box to file.
        """
        read_buffer = ET.tostring(self.xml.getroot(), encoding='utf-8')
        fptr.write(struct.pack('>I4s', len(read_buffer) + 8, b'xml '))
        fptr.write(read_buffer)


Instruction:
Explain what the following Python 3 code does
def parse(cls, fptr, offset, length):
        num_bytes = offset + length - fptr.tell()
        read_buffer = fptr.read(num_bytes)

        if sys.hexversion < 0x03000000 and codecs.BOM_UTF8 in read_buffer:
            # Python3 with utf-8 handles this just fine.  Actually so does
            # Python2 right here since we decode using utf-8.  The real
            # problem comes when __str__ is used on the XML box, and that
            # is where Python2 falls short because of the ascii codec.
            msg = ('A BOM (byte order marker) was detected and '
                   'removed from the XML contents in the box starting at byte '
                   'offset {offset:d}.')
            msg = msg.format(offset=offset)
            warnings.warn(msg, UserWarning)
            read_buffer = read_buffer.replace(codecs.BOM_UTF8, b'')

        try:
            text = read_buffer.decode('utf-8')
        except UnicodeDecodeError as err:
            # Possibly bad string of bytes to begin with.
            # Try to search for <?xml and go from there.
            decl_start = read_buffer.find(b'<?xml')
            if decl_start <= -1:
                # Nope, that's not it.  All is lost.
                msg = ('A problem was encountered while parsing an XML box:'
                       '\n\n\t"{error}"\n\nNo XML was retrieved.')
                warnings.warn(msg.format(error=str(err)), UserWarning)
                return XMLBox(xml=None, length=length, offset=offset)

            text = read_buffer[decl_start:].decode('utf-8')

            # Let the user know that the XML box was problematic.
            msg = ('A UnicodeDecodeError was encountered parsing an XML box '
                   'at byte position {offset:d} ({reason}), but the XML was '
                   'still recovered.')
            msg = msg.format(offset=offset, reason=err.reason)
            warnings.warn(msg, UserWarning)

        # Strip out any trailing nulls, as they can foul up XML parsing.
        text = text.rstrip(chr(0))
        bfptr = io.BytesIO(text.encode('utf-8'))

        try:
            xml = ET.parse(bfptr)
        except ET.ParseError as err:
            msg = ('A problem was encountered while parsing an XML box:'
                   '\n\n\t"{reason}"\n\nNo XML was retrieved.')
            msg = msg.format(reason=str(err))
            warnings.warn(msg, UserWarning)
            xml = None

        return cls(xml=xml, length=length, offset=offset)

Response: Parse an XML box.


Instruction:
How would you explain what the following Python 3 function does
def write(self, fptr):
        num_uuids = len(self.ulst)
        length = 4 + 4 + 2 + num_uuids * 16
        write_buffer = struct.pack('>I4sH', length, b'ulst', num_uuids)
        fptr.write(write_buffer)

        for j in range(num_uuids):
            fptr.write(self.ulst[j].bytes)

Response: Write a UUID list box to file.


Instruction:
Implement a function in Python 3 to
parse the UUIDListBox object.

Response:
def parse(cls, fptr, offset, length):
        """Parse UUIDList box.

        Parameters
        ----------
        f : file
            Open file object.
        offset : int
            Start position of box in bytes.
        length : int
            Length of the box in bytes.

        Returns
        -------
        UUIDListBox
            Instance of the current UUID list box.
        """
        num_bytes = offset + length - fptr.tell()
        read_buffer = fptr.read(num_bytes)

        num_uuids, = struct.unpack_from('>H', read_buffer)

        ulst = []
        for j in range(num_uuids):
            uuid_buffer = read_buffer[2 + j * 16:2 + (j + 1) * 16]
            ulst.append(UUID(bytes=uuid_buffer))

        return cls(ulst, length=length, offset=offset)


Instruction:
Create a Python 3 function to
write a data entry url box to file.

Response:
def write(self, fptr):
        """Write a data entry url box to file.
        """
        # Make sure it is written out as null-terminated.
        url = self.url
        if self.url[-1] != chr(0):
            url = url + chr(0)
        url = url.encode()

        length = 8 + 1 + 3 + len(url)
        write_buffer = struct.pack('>I4sBBBB',
                                   length, b'url ',
                                   self.version,
                                   self.flag[0], self.flag[1], self.flag[2])
        fptr.write(write_buffer)
        fptr.write(url)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def parse(cls, fptr, offset, length):
        num_bytes = offset + length - fptr.tell()
        read_buffer = fptr.read(num_bytes)
        data = struct.unpack_from('>BBBB', read_buffer)
        version = data[0]
        flag = data[1:4]

        url = read_buffer[4:].decode('utf-8').rstrip(chr(0))
        return cls(version, flag, url, length=length, offset=offset)

Response: Parse the data entry URL box.


Instruction:
Given the following Python 3 function, write the documentation
def _print_geotiff(self):
        if self.data is None:
            return "corrupt"
        in_mem_name = '/vsimem/geo.tif'
        gdal.FileFromMemBuffer(in_mem_name, self.raw_data)
        gtif = gdal.Open(in_mem_name)

        # Report projection
        proj_ref = gtif.GetProjectionRef()
        sref = osr.SpatialReference()
        sref.ImportFromWkt(proj_ref)
        psz_pretty_wkt = sref.ExportToPrettyWkt(False)

        # report geotransform
        geo_transform = gtif.GetGeoTransform(can_return_null=True)
        fmt = ('Origin = ({origin_x:.15f},{origin_y:.15f})\n'
               'Pixel Size = ({pixel_x:.15f},{pixel_y:.15f})')
        geotransform_str = fmt.format(origin_x=geo_transform[0],
                                      origin_y=geo_transform[3],
                                      pixel_x=geo_transform[1],
                                      pixel_y=geo_transform[5])

        # setup projected to lat/long transform if appropriate
        if proj_ref is not None and len(proj_ref) > 0:
            hProj = osr.SpatialReference(proj_ref)
            if hProj is not None:
                hLatLong = hProj.CloneGeogCS()

            if hLatLong is not None:
                gdal.PushErrorHandler('CPLQuietErrorHandler')
                hTransform = osr.CoordinateTransformation(hProj, hLatLong)
                gdal.PopErrorHandler()
                msg = 'Unable to load PROJ.4 library'

        # report corners
        uleft = self.GDALInfoReportCorner(gtif, hTransform, "Upper Left", 0, 0)
        lleft = self.GDALInfoReportCorner(gtif, hTransform, "Lower Left",
                                          0, gtif.RasterYSize)
        uright = self.GDALInfoReportCorner(gtif, hTransform, "Upper Right",
                                           gtif.RasterXSize, 0)
        lright = self.GDALInfoReportCorner(gtif, hTransform, "Lower Right",
                                           gtif.RasterXSize, gtif.RasterYSize)
        center = self.GDALInfoReportCorner(gtif, hTransform, "Center",
                                           gtif.RasterXSize / 2.0,
                                           gtif.RasterYSize / 2.0)

        gdal.Unlink(in_mem_name)

        fmt = ("Coordinate System =\n"
               "{coordinate_system}\n"
               "{geotransform}\n"
               "Corner Coordinates:\n"
               "{upper_left}\n"
               "{lower_left}\n"
               "{upper_right}\n"
               "{lower_right}\n"
               "{center}")
        msg = fmt.format(coordinate_system=self._indent(psz_pretty_wkt),
                         geotransform=geotransform_str,
                         upper_left=uleft, upper_right=uright,
                         lower_left=lleft, lower_right=lright, center=center)
        return msg

Response:
Print geotiff information.  Shamelessly ripped off from gdalinfo.py

        Returns
        -------
        str
            String representation of the degenerate geotiff.


Instruction:
How would you implement a function in Python 3 that
writes a UUID box to file.

Response:
def write(self, fptr):
        """Write a UUID box to file.
        """
        length = 4 + 4 + 16 + len(self.raw_data)
        write_buffer = struct.pack('>I4s', length, b'uuid')
        fptr.write(write_buffer)
        fptr.write(self.uuid.bytes)
        fptr.write(self.raw_data)


Instruction:
Can you create a Python 3 function that
parses the UUID box.

Response:
def parse(cls, fptr, offset, length):
        """Parse UUID box.

        Parameters
        ----------
        fptr : file
            Open file object.
        offset : int
            Start position of box in bytes.
        length : int
            Length of the box in bytes.

        Returns
        -------
        UUIDBox
            Instance of the current UUID box.
        """
        num_bytes = offset + length - fptr.tell()
        read_buffer = fptr.read(num_bytes)
        the_uuid = UUID(bytes=read_buffer[0:16])
        return cls(the_uuid, read_buffer[16:], length=length, offset=offset)


Instruction:
Given the following Python 3 function, write the documentation
def _parse_precinct_size(spcod):
    spcod = np.frombuffer(spcod, dtype=np.uint8)
    precinct_size = []
    for item in spcod:
        ep2 = (item & 0xF0) >> 4
        ep1 = item & 0x0F
        precinct_size.append((2 ** ep1, 2 ** ep2))
    return tuple(precinct_size)

Response: Compute precinct size from SPcod or SPcoc.


Instruction:
Here you have a function in Python 3, explain what it does
def _context_string(context):
    msg = 'Code block context:\n            '
    lines = ['Selective arithmetic coding bypass:  {0}',
             'Reset context probabilities on coding pass boundaries:  {1}',
             'Termination on each coding pass:  {2}',
             'Vertically stripe causal context:  {3}',
             'Predictable termination:  {4}',
             'Segmentation symbols:  {5}']
    msg += '\n            '.join(lines)
    msg = msg.format(((context & 0x01) > 0),
                     ((context & 0x02) > 0),
                     ((context & 0x04) > 0),
                     ((context & 0x08) > 0),
                     ((context & 0x10) > 0),
                     ((context & 0x20) > 0))
    return msg

Response: Produce a string to represent the code block context


Instruction:
Explain what the following Python 3 code does
def parse_quantization(read_buffer, sqcd):
    numbytes = len(read_buffer)

    exponent = []
    mantissa = []

    if sqcd & 0x1f == 0:  # no quantization
        data = struct.unpack('>' + 'B' * numbytes, read_buffer)
        for j in range(len(data)):
            exponent.append(data[j] >> 3)
            mantissa.append(0)
    else:
        fmt = '>' + 'H' * int(numbytes / 2)
        data = struct.unpack(fmt, read_buffer)
        for j in range(len(data)):
            exponent.append(data[j] >> 11)
            mantissa.append(data[j] & 0x07ff)

    return mantissa, exponent

Response: Tease out the quantization values from the given buffer.


Instruction:
Given the following Python 3 function, write the documentation
def _print_quantization_style(sqcc):

    msg = '\n    Quantization style:  '
    if sqcc & 0x1f == 0:
        msg += 'no quantization, '
    elif sqcc & 0x1f == 1:
        msg += 'scalar implicit, '
    elif sqcc & 0x1f == 2:
        msg += 'scalar explicit, '
    return msg

Response: Print the quantization style of the current resource.


Instruction:
Explain what the following Python 3 code does
def _parse_unrecognized_segment(self, fptr):
        msg = ("Unrecognized codestream marker 0x{marker_id:x} encountered at "
               "byte offset {offset}.")
        msg = msg.format(marker_id=self._marker_id, offset=fptr.tell())
        warnings.warn(msg, UserWarning)
        cpos = fptr.tell()
        read_buffer = fptr.read(2)
        next_item, = struct.unpack('>H', read_buffer)
        fptr.seek(cpos)
        if ((next_item & 0xff00) >> 8) == 255:
                # No segment associated with this marker, so reset
                # to two bytes after it.
            segment = Segment(id='0x{0:x}'.format(self._marker_id),
                              offset=self._offset, length=0)
        else:
            segment = self._parse_reserved_segment(fptr)
        return segment

Response: Parse an unrecognized segment.


Instruction:
Implement a Python 3 function for
parsing the reserved segment.

Response:
def _parse_reserved_segment(self, fptr):
        """Parse valid marker segment, segment description is unknown.

        Parameters
        ----------
        fptr : file object
            The file to parse.

        Returns
        -------
        Segment
            The current segment.
        """
        offset = fptr.tell() - 2

        read_buffer = fptr.read(2)
        length, = struct.unpack('>H', read_buffer)
        if length > 0:
            data = fptr.read(length - 2)
        else:
            data = None

        segment = Segment(marker_id='0x{0:x}'.format(self._marker_id),
                          offset=offset, length=length, data=data)
        return segment


Instruction:
Write a Python 3 script to
parse the tile part bit stream for SOP EPH marker segments.

Response:
def _parse_tile_part_bit_stream(self, fptr, sod_marker, tile_length):
        """Parse the tile part bit stream for SOP, EPH marker segments."""
        read_buffer = fptr.read(tile_length)
        # The tile length could possibly be too large and extend past
        # the end of file.  We need to be a bit resilient.
        count = min(tile_length, len(read_buffer))
        packet = np.frombuffer(read_buffer, dtype=np.uint8, count=count)

        indices = np.where(packet == 0xff)
        for idx in indices[0]:
            try:
                if packet[idx + 1] == 0x91 and (idx < (len(packet) - 5)):
                    offset = sod_marker.offset + 2 + idx
                    length = 4
                    nsop = packet[(idx + 4):(idx + 6)].view('uint16')[0]
                    if sys.byteorder == 'little':
                        nsop = nsop.byteswap()
                    segment = SOPsegment(nsop, length, offset)
                    self.segment.append(segment)
                elif packet[idx + 1] == 0x92:
                    offset = sod_marker.offset + 2 + idx
                    length = 0
                    segment = EPHsegment(length, offset)
                    self.segment.append(segment)
            except IndexError:
                continue


Instruction:
Given the following Python 3 function, write the documentation
def _parse_cme_segment(self, fptr):
        offset = fptr.tell() - 2

        read_buffer = fptr.read(4)
        data = struct.unpack('>HH', read_buffer)
        length = data[0]
        rcme = data[1]
        ccme = fptr.read(length - 4)

        return CMEsegment(rcme, ccme, length, offset)

Response: Parse the CME marker segment.


Instruction:
Write a Python 3 script for
parsing the COC marker segment.

Response:
def _parse_coc_segment(self, fptr):
        """Parse the COC marker segment.

        Parameters
        ----------
        fptr : file
            Open file object.

        Returns
        -------
        COCSegment
            The current COC segment.
        """
        kwargs = {}
        offset = fptr.tell() - 2
        kwargs['offset'] = offset

        read_buffer = fptr.read(2)
        length, = struct.unpack('>H', read_buffer)
        kwargs['length'] = length

        fmt = '>B' if self._csiz <= 255 else '>H'
        nbytes = 1 if self._csiz <= 255 else 2
        read_buffer = fptr.read(nbytes)
        ccoc, = struct.unpack(fmt, read_buffer)

        read_buffer = fptr.read(1)
        scoc, = struct.unpack('>B', read_buffer)

        numbytes = offset + 2 + length - fptr.tell()
        read_buffer = fptr.read(numbytes)
        spcoc = np.frombuffer(read_buffer, dtype=np.uint8)
        spcoc = spcoc

        return COCsegment(ccoc, scoc, spcoc, length, offset)


Instruction:
Create a Python 3 function to
parse the COD segment.

Response:
def _parse_cod_segment(cls, fptr):
        """Parse the COD segment.

        Parameters
        ----------
        fptr : file
            Open file object.

        Returns
        -------
        CODSegment
            The current COD segment.
        """
        offset = fptr.tell() - 2

        read_buffer = fptr.read(2)
        length, = struct.unpack('>H', read_buffer)

        read_buffer = fptr.read(length - 2)

        lst = struct.unpack_from('>BBHBBBBBB', read_buffer, offset=0)
        scod, prog, nlayers, mct, nr, xcb, ycb, cstyle, xform = lst

        if len(read_buffer) > 10:
            precinct_size = _parse_precinct_size(read_buffer[10:])
        else:
            precinct_size = None

        sop = (scod & 2) > 0
        eph = (scod & 4) > 0

        if sop or eph:
            cls._parse_tpart_flag = True
        else:
            cls._parse_tpart_flag = False

        pargs = (scod, prog, nlayers, mct, nr, xcb, ycb, cstyle, xform,
                 precinct_size)

        return CODsegment(*pargs, length=length, offset=offset)


Instruction:
Write a Python 3 function for
parsing the CRG marker segment.

Response:
def _parse_crg_segment(self, fptr):
        """Parse the CRG marker segment.

        Parameters
        ----------
        fptr : file
            Open file object.

        Returns
        -------
        CRGSegment
            The current CRG segment.
        """
        offset = fptr.tell() - 2

        read_buffer = fptr.read(2)
        length, = struct.unpack('>H', read_buffer)

        read_buffer = fptr.read(4 * self._csiz)
        data = struct.unpack('>' + 'HH' * self._csiz, read_buffer)
        xcrg = data[0::2]
        ycrg = data[1::2]

        return CRGsegment(xcrg, ycrg, length, offset)


Instruction:
How would you explain what the following Python 3 function does
def _parse_eoc_segment(self, fptr):
        offset = fptr.tell() - 2
        length = 0

        return EOCsegment(length, offset)

Response: Parse the end - of - codestream marker segment.


Instruction:
Implement a function in Python 3 to
parse the PLT segment.

Response:
def _parse_plt_segment(self, fptr):
        """Parse the PLT segment.

        The packet headers are not parsed, i.e. they remain uninterpreted raw
        data buffers.

        Parameters
        ----------
        fptr : file
            Open file object.

        Returns
        -------
        PLTSegment
            The current PLT segment.
        """
        offset = fptr.tell() - 2

        read_buffer = fptr.read(3)
        length, zplt = struct.unpack('>HB', read_buffer)

        numbytes = length - 3
        read_buffer = fptr.read(numbytes)
        iplt = np.frombuffer(read_buffer, dtype=np.uint8)

        packet_len = []
        plen = 0
        for byte in iplt:
            plen |= (byte & 0x7f)
            if byte & 0x80:
                # Continue by or-ing in the next byte.
                plen <<= 7
            else:
                packet_len.append(plen)
                plen = 0

        iplt = packet_len

        return PLTsegment(zplt, iplt, length, offset)


Instruction:
Can you tell what is the following Python 3 function doing
def _parse_pod_segment(self, fptr):
        offset = fptr.tell() - 2

        read_buffer = fptr.read(2)
        length, = struct.unpack('>H', read_buffer)

        n = ((length - 2) / 7) if self._csiz < 257 else ((length - 2) / 9)
        n = int(n)
        nbytes = n * 7 if self._csiz < 257 else n * 9
        read_buffer = fptr.read(nbytes)
        fmt = '>' + 'BBHBBB' * n if self._csiz < 257 else '>' + 'BHHBHB' * n
        pod_params = struct.unpack(fmt, read_buffer)

        return PODsegment(pod_params, length, offset)

Response: Parse the POD segment.


Instruction:
How would you explain what the following Python 3 function does
def _parse_ppm_segment(self, fptr):
        offset = fptr.tell() - 2

        read_buffer = fptr.read(3)
        length, zppm = struct.unpack('>HB', read_buffer)

        numbytes = length - 3
        read_buffer = fptr.read(numbytes)

        return PPMsegment(zppm, read_buffer, length, offset)

Response: Parse the PPM segment.


Instruction:
Explain what the following Python 3 code does
def _parse_ppt_segment(self, fptr):
        offset = fptr.tell() - 2

        read_buffer = fptr.read(3)
        length, zppt = struct.unpack('>HB', read_buffer)
        length = length
        zppt = zppt

        numbytes = length - 3
        ippt = fptr.read(numbytes)

        return PPTsegment(zppt, ippt, length, offset)

Response: Parse the PPT segment.


Instruction:
Implement a function in Python 3 to
parse the QCC segment.

Response:
def _parse_qcc_segment(cls, fptr):
        """Parse the QCC segment.

        Parameters
        ----------
        fptr : file object
            The file to parse.

        Returns
        -------
        QCCSegment
            The current QCC segment.
        """
        offset = fptr.tell() - 2

        read_buffer = fptr.read(2)
        length, = struct.unpack('>H', read_buffer)

        read_buffer = fptr.read(length - 2)
        fmt = '>HB' if cls._csiz > 256 else '>BB'
        mantissa_exponent_offset = 3 if cls._csiz > 256 else 2
        cqcc, sqcc = struct.unpack_from(fmt, read_buffer)
        if cqcc >= cls._csiz:
            msg = ("Invalid QCC component number ({invalid_comp_no}), "
                   "the actual number of components is only {valid_comp_no}.")
            msg = msg.format(invalid_comp_no=cqcc, valid_comp_no=cls._csiz)
            warnings.warn(msg, UserWarning)

        spqcc = read_buffer[mantissa_exponent_offset:]

        return QCCsegment(cqcc, sqcc, spqcc, length, offset)


Instruction:
How would you implement a function in Python 3 that
parses the QCD segment.

Response:
def _parse_qcd_segment(self, fptr):
        """Parse the QCD segment.

        Parameters
        ----------
        fptr : file
            Open file object.

        Returns
        -------
        QCDSegment
            The current QCD segment.
        """
        offset = fptr.tell() - 2

        read_buffer = fptr.read(3)
        length, sqcd = struct.unpack('>HB', read_buffer)
        spqcd = fptr.read(length - 3)

        return QCDsegment(sqcd, spqcd, length, offset)


Instruction:
Here you have a function in Python 3, explain what it does
def _parse_rgn_segment(cls, fptr):
        offset = fptr.tell() - 2

        read_buffer = fptr.read(2)
        length, = struct.unpack('>H', read_buffer)

        nbytes = 3 if cls._csiz < 257 else 4
        fmt = '>BBB' if cls._csiz < 257 else '>HBB'
        read_buffer = fptr.read(nbytes)
        data = struct.unpack(fmt, read_buffer)

        length = length
        crgn = data[0]
        srgn = data[1]
        sprgn = data[2]

        return RGNsegment(crgn, srgn, sprgn, length, offset)

Response: Parse the RGN segment.


Instruction:
Can you create a Python 3 function that
parses the SIZ segment.

Response:
def _parse_siz_segment(cls, fptr):
        """Parse the SIZ segment.

        Parameters
        ----------
        fptr : file
            Open file object.

        Returns
        -------
        SIZSegment
            The current SIZ segment.
        """
        offset = fptr.tell() - 2

        read_buffer = fptr.read(2)
        length, = struct.unpack('>H', read_buffer)

        read_buffer = fptr.read(length - 2)
        data = struct.unpack_from('>HIIIIIIIIH', read_buffer)

        rsiz = data[0]
        if rsiz not in _KNOWN_PROFILES:
            msg = "Invalid profile: (Rsiz={rsiz}).".format(rsiz=rsiz)
            warnings.warn(msg, UserWarning)

        xysiz = (data[1], data[2])
        xyosiz = (data[3], data[4])
        xytsiz = (data[5], data[6])
        xytosiz = (data[7], data[8])

        # Csiz is the number of components
        Csiz = data[9]

        data = struct.unpack_from('>' + 'B' * (length - 36 - 2),
                                  read_buffer, offset=36)

        bitdepth = tuple(((x & 0x7f) + 1) for x in data[0::3])
        signed = tuple(((x & 0x80) > 0) for x in data[0::3])
        xrsiz = data[1::3]
        yrsiz = data[2::3]

        for j, subsampling in enumerate(zip(xrsiz, yrsiz)):
            if 0 in subsampling:
                msg = ("Invalid subsampling value for component {comp}: "
                       "dx={dx}, dy={dy}.")
                msg = msg.format(comp=j, dx=subsampling[0], dy=subsampling[1])
                warnings.warn(msg, UserWarning)

        try:
            num_tiles_x = (xysiz[0] - xyosiz[0]) / (xytsiz[0] - xytosiz[0])
            num_tiles_y = (xysiz[1] - xyosiz[1]) / (xytsiz[1] - xytosiz[1])
        except ZeroDivisionError:
            msg = ("Invalid tile specification:  "
                   "size of {num_tile_rows} x {num_tile_cols}, "
                   "offset of {row_offset} x {col_offset}.")
            msg = msg.format(num_tile_rows=xytsiz[1],
                             num_tile_cols=xytsiz[0],
                             row_offset=xytosiz[1],
                             col_offset=xytosiz[0])
            warnings.warn(msg, UserWarning)
        else:
            numtiles = math.ceil(num_tiles_x) * math.ceil(num_tiles_y)
            if numtiles > 65535:
                msg = "Invalid number of tiles: ({numtiles})."
                msg = msg.format(numtiles=numtiles)
                warnings.warn(msg, UserWarning)

        kwargs = {
            'rsiz': rsiz,
            'xysiz': xysiz,
            'xyosiz': xyosiz,
            'xytsiz': xytsiz,
            'xytosiz': xytosiz,
            'Csiz': Csiz,
            'bitdepth': bitdepth,
            'signed': signed,
            'xyrsiz': (xrsiz, yrsiz),
            'length': length,
            'offset': offset
        }
        segment = SIZsegment(**kwargs)

        # Need to keep track of the number of components from SIZ for
        # other segments.
        cls._csiz = Csiz

        return segment


Instruction:
Implement a Python 3 function for
parsing the current SOD segment.

Response:
def _parse_sod_segment(self, fptr):
        """Parse the SOD (start-of-data) segment.

        Parameters
        ----------
        fptr : file
            Open file object.

        Returns
        -------
        SODSegment
            The current SOD segment.
        """
        offset = fptr.tell() - 2
        length = 0

        return SODsegment(length, offset)


Instruction:
Can you create a Python 3 function that
parses the SOT segment.

Response:
def _parse_sot_segment(self, fptr):
        """Parse the SOT segment.

        Parameters
        ----------
        fptr : file
            Open file object.

        Returns
        -------
        SOTSegment
            The current SOT segment.
        """
        offset = fptr.tell() - 2

        read_buffer = fptr.read(10)
        data = struct.unpack('>HHIBB', read_buffer)

        length = data[0]
        isot = data[1]
        psot = data[2]
        tpsot = data[3]
        tnsot = data[4]

        segment = SOTsegment(isot, psot, tpsot, tnsot, length, offset)

        # Need to keep easy access to tile offsets and lengths for when
        # we encounter start-of-data marker segments.

        self._tile_offset.append(segment.offset)
        if segment.psot == 0:
            tile_part_length = (self.offset + self.length -
                                segment.offset - 2)
        else:
            tile_part_length = segment.psot
        self._tile_length.append(tile_part_length)

        return segment


Instruction:
Write a Python 3 function that can
parse the TLM segment.

Response:
def _parse_tlm_segment(self, fptr):
        """Parse the TLM segment.

        Parameters
        ----------
        fptr : file
            Open file object.

        Returns
        -------
        TLMSegment
            The current TLM segment.
        """
        offset = fptr.tell() - 2

        read_buffer = fptr.read(2)
        length, = struct.unpack('>H', read_buffer)

        read_buffer = fptr.read(length - 2)
        ztlm, stlm = struct.unpack_from('>BB', read_buffer)
        ttlm_st = (stlm >> 4) & 0x3
        ptlm_sp = (stlm >> 6) & 0x1

        nbytes = length - 4
        if ttlm_st == 0:
            ntiles = nbytes / ((ptlm_sp + 1) * 2)
        else:
            ntiles = nbytes / (ttlm_st + (ptlm_sp + 1) * 2)

        if ttlm_st == 0:
            ttlm = None
            fmt = ''
        elif ttlm_st == 1:
            fmt = 'B'
        elif ttlm_st == 2:
            fmt = 'H'

        if ptlm_sp == 0:
            fmt += 'H'
        else:
            fmt += 'I'

        data = struct.unpack_from('>' + fmt * int(ntiles), read_buffer,
                                  offset=2)
        if ttlm_st == 0:
            ttlm = None
            ptlm = data
        else:
            ttlm = data[0::2]
            ptlm = data[1::2]

        return TLMsegment(ztlm, ttlm, ptlm, length, offset)


Instruction:
Implement a Python 3 function for
parsing the reserved marker.

Response:
def _parse_reserved_marker(self, fptr):
        """Marker range between 0xff30 and 0xff39.
        """
        the_id = '0x{0:x}'.format(self._marker_id)
        segment = Segment(marker_id=the_id, offset=self._offset, length=0)
        return segment


Instruction:
Can you generate the documentation for the following Python 3 function
def to_json(self):
        event_as_dict = copy.deepcopy(self.event_body)
        if self.timestamp:
            if "keen" in event_as_dict:
                event_as_dict["keen"]["timestamp"] = self.timestamp.isoformat()
            else:
                event_as_dict["keen"] = {"timestamp": self.timestamp.isoformat()}
        return json.dumps(event_as_dict)

Response: Serializes the event to JSON.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def add_event(self, event_collection, event_body, timestamp=None):
        event = Event(self.project_id, event_collection, event_body,
                      timestamp=timestamp)
        self.persistence_strategy.persist(event)

Response: Adds an event to the local cache.


Instruction:
Create a Python 3 function for
generating an image beacon URL.

Response:
def generate_image_beacon(self, event_collection, event_body, timestamp=None):
        """ Generates an image beacon URL.

        :param event_collection: the name of the collection to insert the
        event to
        :param event_body: dict, the body of the event to insert the event to
        :param timestamp: datetime, optional, the timestamp of the event
        """
        event = Event(self.project_id, event_collection, event_body,
                      timestamp=timestamp)
        event_json = event.to_json()
        return "{0}/{1}/projects/{2}/events/{3}?api_key={4}&data={5}".format(
            self.api.base_url, self.api.api_version, self.project_id, self._url_escape(event_collection),
            self.api.write_key.decode(sys.getdefaultencoding()), self._base64_encode(event_json)
        )


Instruction:
Create a Python 3 function to
delete events from the specified event collection.

Response:
def delete_events(self, event_collection, timeframe=None, timezone=None, filters=None):
        """ Deletes events.

        :param event_collection: string, the event collection from which event are being deleted
        :param timeframe: string or dict, the timeframe in which the events happened
        example: "previous_7_days"
        :param timezone: int, the timezone you'd like to use for the timeframe
        and interval in seconds
        :param filters: array of dict, contains the filters you'd like to apply to the data
        example: [{"property_name":"device", "operator":"eq", "property_value":"iPhone"}]

        """
        params = self.get_params(timeframe=timeframe, timezone=timezone, filters=filters)
        return self.api.delete_events(event_collection, params)


Instruction:
How would you explain what the following Python 3 function does
def create_access_key(self, name, is_active=True, permitted=[], options={}):

        return self.api.create_access_key(name=name, is_active=is_active,
                                          permitted=permitted, options=options)

Response: Creates a new master key.


Instruction:
Create a Python 3 function to
replace the name is_active permitted and options values of a given access key.

Response:
def update_access_key_full(self, access_key_id, name, is_active, permitted, options):
        """
        Replaces the 'name', 'is_active', 'permitted', and 'options' values of a given key.
        A master key must be set first.

        :param access_key_id: the 'key' value of the access key for which the values will be replaced
        :param name: the new name desired for this access key
        :param is_active: whether the key should become enabled (True) or revoked (False)
        :param permitted: the new list of permissions desired for this access key
        :param options: the new dictionary of options for this access key
        """
        return self.api.update_access_key_full(access_key_id, name, is_active, permitted, options)


Instruction:
How would you implement a function in Python 3 that
performs a select unique query Returns an array of the unique values of a target property for events that meet the given criteria. :param event_collection: string, the name of the collection to query :param target_property: string, the name of the event property you would like use :param timeframe: string or dict, the timeframe in which the events happened example: "previous_7_days" :param timezone: int, the timezone you'd like to use for the timeframe and interval in seconds :param interval: string, the time interval used for measuring data over time example: "daily" :param filters: array of dict, contains the filters you'd like to apply to the data example: [{"property_name":"device", "operator":"eq", "property_value":"iPhone"}] :param group_by: string or array of strings, the name(s) of the properties you would like to group your results by. example: "customer.id" or ["browser","operating_system"] :param order_by: dictionary or list of dictionary objects containing the property_name(s) to order by and the desired direction(s) of sorting. Example: {"property_name":"result", "direction":keen.direction.DESCENDING} May not be used without a group_by specified. :param limit: positive integer limiting the displayed results of a query using order_by :param max_age: an integer, greater than 30 seconds, the maximum 'staleness' you're willing to trade for increased query performance, in seconds

Response:
def select_unique(self, event_collection, target_property, timeframe=None, timezone=None, interval=None,
                      filters=None, group_by=None, order_by=None, max_age=None, limit=None):
        """ Performs a select unique query

        Returns an array of the unique values of a target property for events that meet the given criteria.

        :param event_collection: string, the name of the collection to query
        :param target_property: string, the name of the event property you would like use
        :param timeframe: string or dict, the timeframe in which the events
        happened example: "previous_7_days"
        :param timezone: int, the timezone you'd like to use for the timeframe
        and interval in seconds
        :param interval: string, the time interval used for measuring data over
        time example: "daily"
        :param filters: array of dict, contains the filters you'd like to apply to the data
        example: [{"property_name":"device", "operator":"eq", "property_value":"iPhone"}]
        :param group_by: string or array of strings, the name(s) of the properties you would
        like to group your results by.  example: "customer.id" or ["browser","operating_system"]
        :param order_by: dictionary or list of dictionary objects containing the property_name(s)
        to order by and the desired direction(s) of sorting.
        Example: {"property_name":"result", "direction":keen.direction.DESCENDING}
        May not be used without a group_by specified.
        :param limit: positive integer limiting the displayed results of a query using order_by
        :param max_age: an integer, greater than 30 seconds, the maximum 'staleness' you're
        willing to trade for increased query performance, in seconds

        """
        params = self.get_params(event_collection=event_collection, timeframe=timeframe, timezone=timezone,
                                 interval=interval, filters=filters, group_by=group_by, order_by=order_by,
                                 target_property=target_property, max_age=max_age, limit=limit)
        return self.api.query("select_unique", params)


Instruction:
Write a Python 3 function that can
perform a data extraction Returns either a JSON object of events or a response indicating an email will be sent to you with data. :param event_collection: string, the name of the collection to query :param timeframe: string or dict, the timeframe in which the events happened example: "previous_7_days" :param timezone: int, the timezone you'd like to use for the timeframe and interval in seconds :param filters: array of dict, contains the filters you'd like to apply to the data example: [{"property_name":"device", "operator":"eq", "property_value":"iPhone"}] :param latest: int, the number of most recent records you'd like to return :param email: string, optional string containing an email address to email results to :param property_names: string or list of strings, used to limit the properties returned

Response:
def extraction(self, event_collection, timeframe=None, timezone=None, filters=None, latest=None,
                   email=None, property_names=None):
        """ Performs a data extraction

        Returns either a JSON object of events or a response
         indicating an email will be sent to you with data.

        :param event_collection: string, the name of the collection to query
        :param timeframe: string or dict, the timeframe in which the events
        happened example: "previous_7_days"
        :param timezone: int, the timezone you'd like to use for the timeframe
        and interval in seconds
        :param filters: array of dict, contains the filters you'd like to apply to the data
        example: [{"property_name":"device", "operator":"eq", "property_value":"iPhone"}]
        :param latest: int, the number of most recent records you'd like to return
        :param email: string, optional string containing an email address to email results to
        :param property_names: string or list of strings, used to limit the properties returned

        """
        params = self.get_params(event_collection=event_collection, timeframe=timeframe, timezone=timezone,
                                 filters=filters, latest=latest, email=email, property_names=property_names)
        return self.api.query("extraction", params)


Instruction:
How would you explain what the following Python 3 function does
def funnel(self, steps, timeframe=None, timezone=None, max_age=None, all_keys=False):
        params = self.get_params(
            steps=steps,
            timeframe=timeframe,
            timezone=timezone,
            max_age=max_age,
        )

        return self.api.query("funnel", params, all_keys=all_keys)

Response: This method performs a Funnel query on the object that contains the results for each step of the funnel.


Instruction:
Can you tell what is the following Python 3 function doing
def version():
    OPENJPEG.opj_version.restype = ctypes.c_char_p
    library_version = OPENJPEG.opj_version()
    if sys.hexversion >= 0x03000000:
        return library_version.decode('utf-8')
    else:
        return library_version

Response: Wrapper for opj_version library routine.


Instruction:
Write a Python 3 script for
wrapping for openjpeg library function opj_cio_open.

Response:
def cio_open(cinfo, src=None):
    """Wrapper for openjpeg library function opj_cio_open."""
    argtypes = [ctypes.POINTER(CommonStructType), ctypes.c_char_p,
                ctypes.c_int]
    OPENJPEG.opj_cio_open.argtypes = argtypes
    OPENJPEG.opj_cio_open.restype = ctypes.POINTER(CioType)

    if src is None:
        length = 0
    else:
        length = len(src)

    cio = OPENJPEG.opj_cio_open(ctypes.cast(cinfo,
                                            ctypes.POINTER(CommonStructType)),
                                src,
                                length)
    return cio


Instruction:
Implement a function in Python 3 to
wrap openjpeg library function cio_close.

Response:
def cio_close(cio):
    """Wraps openjpeg library function cio_close.
    """
    OPENJPEG.opj_cio_close.argtypes = [ctypes.POINTER(CioType)]
    OPENJPEG.opj_cio_close(cio)


Instruction:
How would you implement a function in Python 3 that
gets the current position in byte stream.

Response:
def cio_tell(cio):
    """Get position in byte stream."""
    OPENJPEG.cio_tell.argtypes = [ctypes.POINTER(CioType)]
    OPENJPEG.cio_tell.restype = ctypes.c_int
    pos = OPENJPEG.cio_tell(cio)
    return pos


Instruction:
Create a Python 3 function to
wrap for openjpeg library function opj_create_compress.

Response:
def create_compress(fmt):
    """Wrapper for openjpeg library function opj_create_compress.

    Creates a J2K/JPT/JP2 compression structure.
    """
    OPENJPEG.opj_create_compress.argtypes = [ctypes.c_int]
    OPENJPEG.opj_create_compress.restype = ctypes.POINTER(CompressionInfoType)
    cinfo = OPENJPEG.opj_create_compress(fmt)
    return cinfo


Instruction:
How would you code a function in Python 3 to
wrap openjpeg library function opj_create_decompress.

Response:
def create_decompress(fmt):
    """Wraps openjpeg library function opj_create_decompress.
    """
    OPENJPEG.opj_create_decompress.argtypes = [ctypes.c_int]
    restype = ctypes.POINTER(DecompressionInfoType)
    OPENJPEG.opj_create_decompress.restype = restype
    dinfo = OPENJPEG.opj_create_decompress(fmt)
    return dinfo


Instruction:
Write a Python 3 script for
wrapping for openjpeg library function opj_decode.

Response:
def decode(dinfo, cio):
    """Wrapper for opj_decode.
    """
    argtypes = [ctypes.POINTER(DecompressionInfoType), ctypes.POINTER(CioType)]
    OPENJPEG.opj_decode.argtypes = argtypes
    OPENJPEG.opj_decode.restype = ctypes.POINTER(ImageType)
    image = OPENJPEG.opj_decode(dinfo, cio)
    return image


Instruction:
Here you have a function in Python 3, explain what it does
def destroy_compress(cinfo):
    argtypes = [ctypes.POINTER(CompressionInfoType)]
    OPENJPEG.opj_destroy_compress.argtypes = argtypes
    OPENJPEG.opj_destroy_compress(cinfo)

Response: Wrapper for openjpeg library function opj_destroy_compress.


Instruction:
Can you create a Python 3 function that
wraps for openjpeg library function opj_encode.

Response:
def encode(cinfo, cio, image):
    """Wrapper for openjpeg library function opj_encode.

    Encodes an image into a JPEG-2000 codestream.

    Parameters
    ----------
    cinfo : compression handle

    cio : output buffer stream

    image : image to encode
    """
    argtypes = [ctypes.POINTER(CompressionInfoType),
                ctypes.POINTER(CioType),
                ctypes.POINTER(ImageType)]
    OPENJPEG.opj_encode.argtypes = argtypes
    OPENJPEG.opj_encode.restype = ctypes.c_int
    status = OPENJPEG.opj_encode(cinfo, cio, image)
    return status


Instruction:
Here you have a function in Python 3, explain what it does
def destroy_decompress(dinfo):
    argtypes = [ctypes.POINTER(DecompressionInfoType)]
    OPENJPEG.opj_destroy_decompress.argtypes = argtypes
    OPENJPEG.opj_destroy_decompress(dinfo)

Response: Wraps openjpeg library function opj_destroy_decompress.


Instruction:
Can you tell what is the following Python 3 function doing
def image_create(cmptparms, cspace):
    lst = [ctypes.c_int, ctypes.POINTER(ImageComptParmType), ctypes.c_int]
    OPENJPEG.opj_image_create.argtypes = lst
    OPENJPEG.opj_image_create.restype = ctypes.POINTER(ImageType)

    image = OPENJPEG.opj_image_create(len(cmptparms), cmptparms, cspace)
    return(image)

Response: Wrapper for openjpeg library function opj_image_create.


Instruction:
Implement a Python 3 function for
wrapping openjpeg library function opj_image_destroy.

Response:
def image_destroy(image):
    """Wraps openjpeg library function opj_image_destroy."""
    OPENJPEG.opj_image_destroy.argtypes = [ctypes.POINTER(ImageType)]
    OPENJPEG.opj_image_destroy(image)


Instruction:
How would you explain what the following Python 3 function does
def set_default_encoder_parameters():
    cparams = CompressionParametersType()
    argtypes = [ctypes.POINTER(CompressionParametersType)]
    OPENJPEG.opj_set_default_encoder_parameters.argtypes = argtypes
    OPENJPEG.opj_set_default_encoder_parameters(ctypes.byref(cparams))
    return cparams

Response: Wrapper for openjpeg library function opj_set_default_encoder_parameters.


Instruction:
Write a Python 3 function for
wrapping for openjpeg library function opj_set_event_mgr.

Response:
def set_event_mgr(dinfo, event_mgr, context=None):
    """Wrapper for openjpeg library function opj_set_event_mgr.
    """
    argtypes = [ctypes.POINTER(CommonStructType),
                ctypes.POINTER(EventMgrType),
                ctypes.c_void_p]
    OPENJPEG.opj_set_event_mgr.argtypes = argtypes
    OPENJPEG.opj_set_event_mgr(ctypes.cast(dinfo,
                                           ctypes.POINTER(CommonStructType)),
                               event_mgr, context)


Instruction:
Create a Python 3 function for
wrapping for openjpeg library function opj_setup_encoder.

Response:
def setup_encoder(cinfo, cparameters, image):
    """Wrapper for openjpeg library function opj_setup_decoder."""
    argtypes = [ctypes.POINTER(CompressionInfoType),
                ctypes.POINTER(CompressionParametersType),
                ctypes.POINTER(ImageType)]
    OPENJPEG.opj_setup_encoder.argtypes = argtypes
    OPENJPEG.opj_setup_encoder(cinfo, cparameters, image)


Instruction:
Here you have a function in Python 3, explain what it does
def setup_decoder(dinfo, dparams):
    argtypes = [ctypes.POINTER(DecompressionInfoType),
                ctypes.POINTER(DecompressionParametersType)]
    OPENJPEG.opj_setup_decoder.argtypes = argtypes
    OPENJPEG.opj_setup_decoder(dinfo, dparams)

Response: Wrapper for openjpeg library function opj_setup_decoder.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def print_upper_triangular_matrix(matrix):

    # Print column header
    # Assumes first row contains all needed headers
    first = sorted(matrix.keys())[0]
    print('\t', end=' ')
    for i in matrix[first]:
        print('{}\t'.format(i), end=' ')
    print()

    indent_count = 0

    for i in matrix:
        # Print line header
        print('{}\t'.format(i), end=' ')

        if indent_count:
            print('\t' * indent_count, end=' ')

        for j in sorted(matrix[i]): # required because dict doesn't guarantee insertion order
            print('{}\t'.format(matrix[i][j]), end=' ')

        print()

        indent_count = indent_count + 1

Response: Prints a CVRP upper triangular matrix.


Instruction:
Explain what the following Python 3 code does
def print_upper_triangular_matrix_as_complete(matrix):
    for i in sorted(matrix.keys()):
        for j in sorted(matrix.keys()):
            a, b = i, j
            if a > b:
                a, b = b, a

            print(matrix[a][b], end=' ')

        print()

Response: Prints a CVRP upper triangular matrix as a normal matrix.


Instruction:
Write a Python 3 script for
printing a solution to stdout

Response:
def print_solution(solution):
    """Prints a solution

    Arguments
    ---------
    solution : BaseSolution

    Example
    -------
    ::

        [8, 9, 10, 7]: 160
        [5, 6]: 131
        [3, 4, 2]: 154
        Total cost: 445

    """
    total_cost = 0
    for solution in solution.routes():
        cost = solution.length()
        total_cost = total_cost + cost
        print('{}: {}'.format(solution, cost))
        #print('xxx')
    print('Total cost: {}'.format(total_cost))


Instruction:
Can you create a Python 3 function that
validates if total generation of a grid in a pkl file is what expected.

Response:
def validate_generation(session, nw):
    '''Validate if total generation of a grid in a pkl file is what expected.

    Parameters
    ----------
    session : sqlalchemy.orm.session.Session
        Database session
    nw:
        The network

    Returns
    -------
    DataFrame
        compare_by_level
    DataFrame
        compare_by_type
    '''
    #config network intern variables
    nw._config = nw.import_config()
    nw._pf_config = nw.import_pf_config()
    nw._static_data = nw.import_static_data()
    nw._orm = nw.import_orm()

    #rescue generation from input table
    generation_input = nw.list_generators(session)

    #make table of generators that are in the grid
    gen_idx = 0
    gen_dict = {}
    for mv_district in nw.mv_grid_districts():
        #search over MV grid
        for node in mv_district.mv_grid.graph_nodes_sorted():
            if isinstance(node, GeneratorDing0):
                gen_idx+=1
                subtype = node.subtype
                if subtype == None:
                    subtype = 'other'
                type = node.type
                if type == None:
                    type = 'other'
                gen_dict[gen_idx] = {
                    'v_level':node.v_level,
                    'type':type,
                    'subtype':subtype,
                    'GenCap':node.capacity,
                }

        #search over LV grids
        for LA in mv_district.lv_load_areas():
            for lv_district in LA.lv_grid_districts():
                # generation capacity
                for g in lv_district.lv_grid.generators():
                    gen_idx+=1
                    subtype = g.subtype
                    if subtype == None:
                        subtype = 'other'
                    type = g.type
                    if type == None:
                        type = 'other'
                    gen_dict[gen_idx] = {
                        'v_level':g.v_level,
                        'type':type,
                        'subtype':subtype,
                        'GenCap':g.capacity,
                    }

    generation_effective = pd.DataFrame.from_dict(gen_dict, orient='index')

    #compare by voltage level
    input_by_level = generation_input.groupby('v_level').sum()['GenCap'].apply(lambda x: np.round(x,3))
    effective_by_level = generation_effective.groupby('v_level').sum()['GenCap'].apply(lambda x: np.round(x,3))

    compare_by_level = pd.concat([input_by_level,effective_by_level,input_by_level==effective_by_level],axis=1)
    compare_by_level.columns = ['table','ding0','equal?']

    #compare by type/subtype
    generation_input['type'] =generation_input['type']+'/'+generation_input['subtype']
    generation_effective['type'] =generation_effective['type']+'/'+generation_effective['subtype']

    input_by_type = generation_input.groupby('type').sum()['GenCap'].apply(lambda x: np.round(x,3))
    effective_by_type = generation_effective.groupby('type').sum()['GenCap'].apply(lambda x: np.round(x,3))

    compare_by_type = pd.concat([input_by_type,effective_by_type,input_by_type==effective_by_type],axis=1)
    compare_by_type.columns = ['table','ding0','equal?']
    compare_by_type.index.names = ['type/subtype']

    return compare_by_level, compare_by_type


Instruction:
Can you tell what is the following Python 3 function doing
def validate_load_areas(session, nw):
    '''Validate if total load of a grid in a pkl file is what expected from load areas

    Parameters
    ----------
    session : sqlalchemy.orm.session.Session
        Database session
    nw
        The network

    Returns
    -------
    DataFrame
        compare_by_la
    Bool
        True if data base IDs of LAs are the same as the IDs in the grid
    '''
    #config network intern variables
    nw._config = nw.import_config()
    nw._pf_config = nw.import_pf_config()
    nw._static_data = nw.import_static_data()
    nw._orm = nw.import_orm()

    #rescue peak load from input table
    load_input = nw.list_load_areas(session, nw.mv_grid_districts())
    la_input = sorted(load_input.index)
    load_input = load_input.sum(axis=0).apply(lambda x: np.round(x,3))
    load_input.sort_index(inplace=True)

    #search for LA in the grid
    la_idx = 0
    la_dict = {}
    for mv_district in nw.mv_grid_districts():
        for LA in mv_district.lv_load_areas():
            la_idx +=1
            la_dict[la_idx] = {
                'id_db':LA.id_db,
                'peak_load_residential':LA.peak_load_residential,
                'peak_load_retail':LA.peak_load_retail,
                'peak_load_industrial':LA.peak_load_industrial,
                'peak_load_agricultural':LA.peak_load_agricultural,
            }

    #compare by LA
    load_effective = pd.DataFrame.from_dict(la_dict,orient='index').set_index('id_db')
    la_effective = sorted(load_effective.index)
    load_effective = load_effective.sum(axis=0).apply(lambda x: np.round(x,3))
    load_effective.sort_index(inplace=True)

    compare_by_la = pd.concat([load_input,load_effective,load_input==load_effective],axis=1)
    compare_by_la.columns = ['table','ding0','equal?']
    compare_by_la.index.names = ['sector']

    return compare_by_la, la_input==la_effective

Response: Validate if total load of a grid in a pkl file is what expected from load areas in a network.


Instruction:
Write a Python 3 function that can
validate if total load of a grid in a pkl file is what expected from LV districts.

Response:
def validate_lv_districts(session, nw):
    '''Validate if total load of a grid in a pkl file is what expected from LV districts

    Parameters
    ----------
    session : sqlalchemy.orm.session.Session
            Database session
    nw:
        The network

    Returns
    -------
    DataFrame
        compare_by_district
    DataFrame
        compare_by_loads
    '''
    # config network intern variables
    nw._config = nw.import_config()
    nw._pf_config = nw.import_pf_config()
    nw._static_data = nw.import_static_data()
    nw._orm = nw.import_orm()

    # rescue peak load from input table
    lv_ditricts = [dist.id_db for mv in nw.mv_grid_districts()
                              for la in mv.lv_load_areas()
                              for dist in la.lv_grid_districts()]
    load_input = nw.list_lv_grid_districts(session, lv_ditricts)
    load_input = load_input.sum(axis=0).apply(lambda x: np.round(x, 3))
    load_input.sort_index(inplace=True)
    load_input.index.names = ['id_db']
    load_input['peak_load_retind']=load_input['peak_load_retail']+load_input['peak_load_industrial']

    # search for lv_district in the grid
    lv_dist_idx = 0
    lv_dist_dict = {}
    lv_load_idx = 0
    lv_load_dict = {}
    for mv_district in nw.mv_grid_districts():
        for LA in mv_district.lv_load_areas():
            for lv_district in LA.lv_grid_districts():
                lv_dist_idx += 1
                lv_dist_dict[lv_dist_idx] = {
                    'id_db':lv_district.id_db,
                    'peak_load_residential':lv_district.peak_load_residential,
                    'peak_load_retail':lv_district.peak_load_retail,
                    'peak_load_industrial':lv_district.peak_load_industrial,
                    'peak_load_agricultural':lv_district.peak_load_agricultural,
                    'peak_load_retind': lv_district.peak_load_industrial + lv_district.peak_load_retail,
                }
                for node in lv_district.lv_grid.graph_nodes_sorted():
                    if isinstance(node,LVLoadDing0):
                        lv_load_idx +=1
                        peak_load_agricultural = 0
                        peak_load_residential = 0
                        peak_load_retail = 0
                        peak_load_industrial = 0
                        peak_load_retind = 0

                        if 'agricultural' in node.consumption:
                            tipo = 'agricultural'
                            peak_load_agricultural = node.peak_load
                        elif 'industrial' in node.consumption:
                            if node.consumption['retail']==0:
                                tipo = 'industrial'
                                peak_load_industrial = node.peak_load
                            elif node.consumption['industrial']==0:
                                tipo = 'retail'
                                peak_load_retail = node.peak_load
                            else:
                                tipo = 'ret_ind'
                                peak_load_retind = node.peak_load
                        elif 'residential' in node.consumption:
                            tipo = 'residential'
                            peak_load_residential = node.peak_load
                        else:
                            tipo = 'none'
                            print(node.consumption)
                        lv_load_dict[lv_load_idx] = {
                            'id_db':node.id_db,
                            'peak_load_residential':peak_load_residential,
                            'peak_load_retail':peak_load_retail,
                            'peak_load_industrial':peak_load_industrial,
                            'peak_load_agricultural':peak_load_agricultural,
                            'peak_load_retind':peak_load_retind,
                        }

        for node in mv_district.mv_grid.graph_nodes_sorted():
            if isinstance(node,LVLoadAreaCentreDing0):
                lv_load_idx +=1
                lv_load_dict[lv_load_idx] = {
                    'id_db': node.id_db,
                    'peak_load_residential': node.lv_load_area.peak_load_residential,
                    'peak_load_retail': node.lv_load_area.peak_load_retail,
                    'peak_load_industrial': node.lv_load_area.peak_load_industrial,
                    'peak_load_agricultural': node.lv_load_area.peak_load_agricultural,
                    'peak_load_retind':0,
                }

    #compare by LV district
    load_effective_lv_distr = pd.DataFrame.from_dict(lv_dist_dict,orient='index').set_index('id_db').sum(axis=0).apply(lambda x: np.round(x,3))
    load_effective_lv_distr.sort_index(inplace=True)

    compare_by_district = pd.concat([load_input,load_effective_lv_distr,load_input==load_effective_lv_distr],axis=1)
    compare_by_district.columns = ['table','ding0','equal?']
    compare_by_district.index.names = ['sector']

    #compare by LV Loads
    load_effective_lv_load = pd.DataFrame.from_dict(lv_load_dict,orient='index').set_index('id_db')
    load_effective_lv_load = load_effective_lv_load.sum(axis=0).apply(lambda x: np.round(x,3))
    load_effective_lv_load.sort_index(inplace=True)

    load_effective_lv_load['peak_load_retind'] = load_effective_lv_load['peak_load_retail'] + \
                                                 load_effective_lv_load['peak_load_industrial'] + \
                                                 load_effective_lv_load['peak_load_retind']

    compare_by_load = pd.concat([load_input,load_effective_lv_load,load_input==load_effective_lv_load],axis=1)
    compare_by_load.columns = ['table','ding0','equal?']
    compare_by_load.index.names = ['sector']

    return compare_by_district, compare_by_load


Instruction:
Can you write a function in Python 3 where it
checks for over - loading of branches and transformers for MV or LV grid.

Response:
def check_load(grid, mode):
    """ Checks for over-loading of branches and transformers for MV or LV grid.

    Parameters
    ----------
    grid : GridDing0
        Grid identifier.
    mode : str
        Kind of grid ('MV' or 'LV').

    Returns
    -------
    :obj:`dict`
        Dict of critical branches with max. relative overloading, and the
        following format::

            {
            branch_1: rel_overloading_1,
            ...,
            branch_n: rel_overloading_n
            }

    :any:`list` of :obj:`GridDing0`
        List of critical transformers with the following format::

        [trafo_1, ..., trafo_m]

    Notes
    -----
        Lines'/cables' max. capacity (load case and feed-in case) are taken from [#]_.

    References
    ----------
    .. [#] dena VNS

    See Also
    --------
    ding0.flexopt.reinforce_measures.reinforce_branches_current :
    ding0.flexopt.reinforce_measures.reinforce_branches_voltage :

    """

    crit_branches = {}
    crit_stations = []

    if mode == 'MV':
        # load load factors (conditions) for cables, lines and trafos for load- and feedin case

        # load_factor_mv_trans_lc_normal = float(cfg_ding0.get('assumptions',
        #                                                      'load_factor_mv_trans_lc_normal'))
        load_factor_mv_line_lc_normal = float(cfg_ding0.get('assumptions',
                                                             'load_factor_mv_line_lc_normal'))
        load_factor_mv_cable_lc_normal = float(cfg_ding0.get('assumptions',
                                                             'load_factor_mv_cable_lc_normal'))
        #load_factor_mv_trans_fc_normal = float(cfg_ding0.get('assumptions',
        #                                                     'load_factor_mv_trans_fc_normal'))
        load_factor_mv_line_fc_normal = float(cfg_ding0.get('assumptions',
                                                             'load_factor_mv_line_fc_normal'))
        load_factor_mv_cable_fc_normal = float(cfg_ding0.get('assumptions',
                                                             'load_factor_mv_cable_fc_normal'))

        mw2kw = 1e3
        kw2mw = 1e-3

        # STEP 1: check branches' loads
        for branch in grid.graph_edges():
            s_max_th = 3**0.5 * branch['branch'].type['U_n'] * branch['branch'].type['I_max_th']

            if branch['branch'].kind == 'line':
                s_max_th_lcfc = [s_max_th * load_factor_mv_line_lc_normal,
                                 s_max_th * load_factor_mv_line_fc_normal]
            elif branch['branch'].kind == 'cable':
                s_max_th_lcfc = [s_max_th * load_factor_mv_cable_lc_normal,
                                 s_max_th * load_factor_mv_cable_fc_normal]
            else:
                raise ValueError('Branch kind is invalid!')

            # check loads only for non-aggregated Load Areas (aggregated ones are skipped raising except)
            try:
                # check if s_res exceeds allowed values for laod and feedin case
                # CAUTION: The order of values is fix! (1. load case, 2. feedin case)
                if any([s_res * mw2kw > _ for s_res, _ in zip(branch['branch'].s_res, s_max_th_lcfc)]):
                    # save max. relative overloading
                    crit_branches[branch] = max(branch['branch'].s_res) * mw2kw / s_max_th
            except:
                pass

        # STEP 2: check HV-MV station's load

        # NOTE: HV-MV station reinforcement is not required for status-quo
        # scenario since HV-MV trafos already sufficient for load+generation
        # case as done in MVStationDing0.choose_transformers()

        # OLD snippet:
        # cum_peak_load = grid.grid_district.peak_load
        # cum_peak_generation = grid.station().peak_generation(mode='MVLV')
        #
        # # reinforcement necessary only if generation > load
        # if cum_peak_generation > cum_peak_load:
        #     grid.station().choose_transformers
        #
        # cum_trafo_capacity = sum((_.s_max_a for _ in grid.station().transformers()))
        #
        # max_trafo = max((_.s_max_a for _ in grid.station().transformers()))
        #
        # # determine number and size of required transformers
        # kw2mw = 1e-3
        # residual_apparent_power = cum_generation_sum * kw2mw - \
        #                           cum_trafo_capacity

    elif mode == 'LV':
        raise NotImplementedError

    if crit_branches:
        logger.info('==> {} branches have load issues.'.format(
            len(crit_branches)))
    if crit_stations:
        logger.info('==> {} stations have load issues.'.format(
            len(crit_stations)))

    return crit_branches, crit_stations


Instruction:
Implement a Python 3 function for
checking for voltage stability issues at all nodes for MV or LV grid.

Response:
def check_voltage(grid, mode):
    """ Checks for voltage stability issues at all nodes for MV or LV grid

    Parameters
    ----------
    grid : GridDing0
        Grid identifier.
    mode : str
        Kind of grid ('MV' or 'LV').

    Returns
    -------
    :any:`list` of :any:`GridDing0`
        List of critical nodes, sorted descending by voltage difference.

    Notes
    -----
        The examination is done in two steps, according to [#]_ :

        1. It is checked #TODO: what?

        2. #TODO: what's next?

    References
    ----------
    .. [#] dena VNS
    """

    crit_nodes = {}

    if mode == 'MV':
        # load max. voltage difference for load and feedin case
        mv_max_v_level_lc_diff_normal = float(cfg_ding0.get('mv_routing_tech_constraints',
                                                            'mv_max_v_level_lc_diff_normal'))
        mv_max_v_level_fc_diff_normal = float(cfg_ding0.get('mv_routing_tech_constraints',
                                                            'mv_max_v_level_fc_diff_normal'))

        # check nodes' voltages
        voltage_station = grid._station.voltage_res
        for node in grid.graph_nodes_sorted():
            try:
                # compare node's voltage with max. allowed voltage difference for load and feedin case
                if (abs(voltage_station[0] - node.voltage_res[0]) > mv_max_v_level_lc_diff_normal) or\
                   (abs(voltage_station[1] - node.voltage_res[1]) > mv_max_v_level_fc_diff_normal):

                    crit_nodes[node] = {'node': node,
                                        'v_diff': max([abs(v2-v1) for v1, v2 in zip(node.voltage_res, voltage_station)])}
            except:
                pass

    elif mode == 'LV':
        raise NotImplementedError

    if crit_nodes:
        logger.info('==> {} nodes have voltage issues.'.format(len(crit_nodes)))

    return [_['node'] for _ in sorted(crit_nodes.values(), key=lambda _: _['v_diff'], reverse=True)]


Instruction:
Here you have a function in Python 3, explain what it does
def get_critical_line_loading(grid):
    cos_phi_load = cfg_ding0.get('assumptions', 'cos_phi_load')
    cos_phi_feedin = cfg_ding0.get('assumptions', 'cos_phi_gen')
    lf_trafo_load = cfg_ding0.get('assumptions',
                                  "load_factor_lv_trans_lc_normal")
    lf_trafo_gen = cfg_ding0.get('assumptions',
                                  "load_factor_lv_trans_fc_normal")

    critical_branches = []
    critical_stations = []

    # Convert grid to a tree (is a directed graph)
    # based on this tree, descendants of each node are accessible
    station = grid._station

    tree = nx.dfs_tree(grid._graph, station)

    for node in tree.nodes():

        # list of descendant nodes including the node itself
        descendants = list(nx.descendants(tree, node))
        descendants.append(node)

        if isinstance(node, LVStationDing0):
            # determine cumulative peak load at node and assign to branch
            peak_load, peak_gen = peak_load_generation_at_node(descendants)

            if grid.id_db == 61107:
                if isinstance(node, LVStationDing0):
                    print(node)
            # get trafos cumulative apparent power
            s_max_trafos = sum([_.s_max_a for _ in node._transformers])

            # compare with load and generation connected to
            if (((peak_load / cos_phi_load) > s_max_trafos * lf_trafo_load) or
                    ((peak_gen / cos_phi_feedin) > s_max_trafos * lf_trafo_gen)):
                critical_stations.append(
                    {'station': node,
                     's_max': [
                         peak_load / cos_phi_load,
                         peak_gen / cos_phi_feedin]})

        else:
            # preceeding node of node
            predecessors = list(tree.predecessors(node))

            # a non-meshed grid topology returns a list with only 1 item
            predecessor = predecessors[0]

            # get preceeding
            branches = grid.graph_branches_from_node(node)
            preceeding_branch = [branch for branch in branches
                                 if branch[0] is predecessor][0]

            # determine cumulative peak load at node and assign to branch
            peak_load, peak_gen = peak_load_generation_at_node(descendants)

            s_max_th = 3 ** 0.5 * preceeding_branch[1]['branch'].type['U_n'] * \
                       preceeding_branch[1]['branch'].type['I_max_th'] / 1e3

            if (((peak_load / cos_phi_load) > s_max_th) or
                    ((peak_gen / cos_phi_feedin) > s_max_th)):
                critical_branches.append(
                    {'branch': preceeding_branch[1]['branch'],
                     's_max': [
                         peak_load / cos_phi_load,
                         peak_gen / cos_phi_feedin]})

    return critical_branches, critical_stations

Response: Returns a list of critical line loading for each LV station and branch.


Instruction:
How would you implement a function in Python 3 that
returns the maximum occuring load and generation at a certain node

Response:
def peak_load_generation_at_node(nodes):
    """
    Get maximum occuring load and generation at a certain node

    Summarizes peak loads and nominal generation power of descendant nodes
    of a branch

    Parameters
    ----------
    nodes : :any:`list`
        Any LV grid Ding0 node object that is part of the grid topology

    Return
    ------
    :any:`float`
        peak_load : Sum of peak loads of descendant nodes
    :any:`float`
        peak_generation : Sum of nominal power of generation at descendant nodes
    """

    loads = [node.peak_load for node in nodes
             if isinstance(node, LVLoadDing0)]
    peak_load = sum(loads)

    generation = [node.capacity for node in nodes
             if isinstance(node, GeneratorDing0)]
    peak_generation = sum(generation)

    return peak_load, peak_generation


Instruction:
Make a summary of the following Python 3 code
def get_critical_voltage_at_nodes(grid):

    v_delta_tolerable_fc = cfg_ding0.get('assumptions',
                                      'lv_max_v_level_fc_diff_normal')
    v_delta_tolerable_lc = cfg_ding0.get('assumptions',
                                      'lv_max_v_level_lc_diff_normal')

    omega = 2 * math.pi * 50

    crit_nodes = []

    # get list of nodes of main branch in right order
    tree = nx.dfs_tree(grid._graph, grid._station)

    # list for nodes of main branch
    main_branch = []

    # list of stub cable distributors branching from main branch
    grid_conn_points = []

    # fill two above lists
    for node in list(nx.descendants(tree, grid._station)):
        successors = list(tree.successors(node))
        if successors and all(isinstance(successor, LVCableDistributorDing0)
               for successor in successors):
            main_branch.append(node)
        elif (isinstance(node, LVCableDistributorDing0) and
            all(isinstance(successor, (GeneratorDing0, LVLoadDing0))
               for successor in successors)):
            grid_conn_points.append(node)

    # voltage at substation bus bar
    r_mv_grid, x_mv_grid = get_mv_impedance(grid)

    r_trafo = sum([tr.r for tr in grid._station._transformers])
    x_trafo = sum([tr.x for tr in grid._station._transformers])

    v_delta_load_case_bus_bar, \
    v_delta_gen_case_bus_bar = get_voltage_at_bus_bar(grid, tree)

    if (abs(v_delta_gen_case_bus_bar) > v_delta_tolerable_fc
        or abs(v_delta_load_case_bus_bar) > v_delta_tolerable_lc):
        crit_nodes.append({'node': grid._station,
                           'v_diff': [v_delta_load_case_bus_bar,
                                      v_delta_gen_case_bus_bar]})

    # voltage at main route nodes
    for first_node in [b for b in tree.successors(grid._station)
                   if b in main_branch]:

        # cumulative resistance/reactance at bus bar
        r = r_mv_grid + r_trafo
        x = x_mv_grid + x_trafo

        # roughly estimate transverse voltage drop
        stub_node = [_ for _ in list(tree.successors(first_node)) if
                     _ not in main_branch][0]
        v_delta_load_stub, v_delta_gen_stub = voltage_delta_stub(
            grid,
            tree,
            first_node,
            stub_node,
            r,
            x)

        # cumulative voltage drop/increase at substation bus bar
        v_delta_load_cum = v_delta_load_case_bus_bar
        v_delta_gen_cum = v_delta_gen_case_bus_bar

        # calculate voltage at first node of branch
        voltage_delta_load, voltage_delta_gen, r, x = \
            get_voltage_delta_branch(grid, tree, first_node, r, x)

        v_delta_load_cum += voltage_delta_load
        v_delta_gen_cum += voltage_delta_gen

        if (abs(v_delta_gen_cum) > (v_delta_tolerable_fc - v_delta_gen_stub)
            or abs(v_delta_load_cum) > (v_delta_tolerable_lc - v_delta_load_stub)):
            crit_nodes.append({'node': first_node,
                               'v_diff': [v_delta_load_cum,
                                          v_delta_gen_cum]})
            crit_nodes.append({'node': stub_node,
                               'v_diff': [
                                   v_delta_load_cum + v_delta_load_stub,
                                   v_delta_gen_cum + v_delta_gen_stub]})

        # get next neighboring nodes down the tree
        successor = [x for x in tree.successors(first_node)
                      if x in main_branch]
        if successor:
            successor = successor[0] # simply unpack

        # successively determine voltage levels for succeeding nodes
        while successor:
            voltage_delta_load, voltage_delta_gen, r, x = \
                get_voltage_delta_branch(grid, tree, successor, r, x)

            v_delta_load_cum += voltage_delta_load
            v_delta_gen_cum += voltage_delta_gen

            # roughly estimate transverse voltage drop
            stub_node = [_ for _ in tree.successors(successor) if
                         _ not in main_branch][0]
            v_delta_load_stub, v_delta_gen_stub = voltage_delta_stub(
                grid,
                tree,
                successor,
                stub_node,
                r,
                x)

            if (abs(v_delta_gen_cum) > (v_delta_tolerable_fc - v_delta_gen_stub)
                or abs(v_delta_load_cum) > (
                            v_delta_tolerable_lc - v_delta_load_stub)):
                crit_nodes.append({'node': successor,
                                   'v_diff': [v_delta_load_cum,
                                              v_delta_gen_cum]})
                crit_nodes.append({'node': stub_node,
                                   'v_diff': [
                                       v_delta_load_cum + v_delta_load_stub,
                                       v_delta_gen_cum + v_delta_gen_stub]})

            successor = [_ for _ in tree.successors(successor)
                         if _ in main_branch]
            if successor:
                successor = successor[0]

    return crit_nodes

Response: r Returns the critical voltage at each node of the LV grid.


Instruction:
Given the following Python 3 function, write the documentation
def voltage_delta_vde(v_nom, s_max, r, x, cos_phi):
    delta_v = (s_max * (
        r * cos_phi + x * math.sin(math.acos(cos_phi)))) / v_nom ** 2
    return delta_v

Response: Estimate the voltage drop or increase in radial grids of a given voltage.


Instruction:
Write a Python 3 script for
returning the total generation and peak load of neighboring house connected to main branch.

Response:
def get_house_conn_gen_load(graph, node):
    """
    Get generation capacity/ peak load of neighboring house connected to main
    branch

    Parameters
    ----------
    graph : :networkx:`NetworkX Graph Obj< >`
        Directed graph
    node : graph node
        Node of the main branch of LV grid

    Returns
    -------
    :any:`list`
        A list containing two items

        # peak load of connected house branch
        # generation capacity of connected generators
    """
    generation = 0
    peak_load = 0

    for cus_1 in graph.successors(node):
        for cus_2 in graph.successors(cus_1):
            if not isinstance(cus_2, list):
                cus_2 = [cus_2]
            generation += sum([gen.capacity for gen in cus_2
                          if isinstance(gen, GeneratorDing0)])
            peak_load += sum([load.peak_load for load in cus_2
                          if isinstance(load, LVLoadDing0)])

    return [peak_load, generation]


Instruction:
Explain what the following Python 3 code does
def get_voltage_delta_branch(grid, tree, node, r_preceeding, x_preceeding):
    cos_phi_load = cfg_ding0.get('assumptions', 'cos_phi_load')
    cos_phi_feedin = cfg_ding0.get('assumptions', 'cos_phi_gen')
    v_nom = cfg_ding0.get('assumptions', 'lv_nominal_voltage')
    omega = 2 * math.pi * 50

    # add resitance/ reactance to preceeding
    in_edge = [_ for _ in grid.graph_branches_from_node(node) if
               _[0] in list(tree.predecessors(node))][0][1]
    r = r_preceeding + (in_edge['branch'].type['R'] *
                     in_edge['branch'].length)
    x = x_preceeding + (in_edge['branch'].type['L'] / 1e3 * omega *
                     in_edge['branch'].length)

    # get apparent power for load and generation case
    peak_load, gen_capacity = get_house_conn_gen_load(tree, node)
    s_max_load = peak_load / cos_phi_load
    s_max_feedin = gen_capacity / cos_phi_feedin

    # determine voltage increase/ drop a node
    voltage_delta_load = voltage_delta_vde(v_nom, s_max_load, r, x,
                                           cos_phi_load)
    voltage_delta_gen = voltage_delta_vde(v_nom, s_max_feedin, r, -x,
                                          cos_phi_feedin)

    return [voltage_delta_load, voltage_delta_gen, r, x]

Response: Returns the voltage delta for a preceeding branch of node at a given voltage level.


Instruction:
Write a Python 3 script to
determine the impedance of MV grid

Response:
def get_mv_impedance(grid):
    """
    Determine MV grid impedance (resistance and reactance separately)

    Parameters
    ----------
    grid : LVGridDing0

    Returns
    -------
    :any:`list`
        List containing resistance and reactance of MV grid
    """

    omega = 2 * math.pi * 50

    mv_grid = grid.grid_district.lv_load_area.mv_grid_district.mv_grid
    edges = mv_grid.find_path(grid._station, mv_grid._station, type='edges')
    r_mv_grid = sum([e[2]['branch'].type['R'] * e[2]['branch'].length / 1e3
                     for e in edges])
    x_mv_grid = sum([e[2]['branch'].type['L'] / 1e3 * omega * e[2][
        'branch'].length / 1e3 for e in edges])

    return [r_mv_grid, x_mv_grid]